task-session

---
name: task-session
description: Runs one task of a lead-flow wave end to end. Reads the rules, checks its model, sends a numbered brief and waits for the lead, re-checks decisions, builds with subagents, and finishes ready to close. Use when a session is started for a task id, or the session-start note says "You are task <id>".
---

# Task session

The hub's `CLAUDE.md` holds the full rules; this is the order to apply them in.

## Size

Your status block's `size` picks the path (none means `medium`):

- `small`, a bounded edit of a few lines: a 1–3 line brief; build it inline, without subagents;
  no test to write (the repo's gate still runs once); one `task-reviewer` in 7. Finish.
- `medium`: the steps below as written.
- `big`: after the go-ahead, `lead-flow:writing-plans` writes the plan to `notes/<id>-plan.md` in
  the hub (not `docs/superpowers/plans/`; the execution method is already chosen, so ask for
  none). Commit it, tell the lead its path, and run it with
  `lead-flow:subagent-driven-development` under the overrides in 5. Build. A plan that differs
  from the approved brief goes back to the lead first.

## A hub task

A task whose status block says `repo: hub` changes the hub itself (its handoff doc, its
`callmap/flows/<group>.json` and new `callmap/shots/` files), not a repo. The rest of this skill
applies, with these changes:

- **The hub branch** is the branch the hub's own checkout is on:
  `git -C "<hub>" symbolic-ref --short HEAD`, run in `<hub>`, never in the worktree (there it
  names your task branch). A detached hub checkout has no hub branch: tell the lead and stop.
- **Where it runs:** the worktree `"<hub>/.worktrees/<id>"` on your task branch
  (`git.task_branch`), cut from the hub branch. The hub has no wave branch.
- **What goes where:** the task branch holds only the files you own. Your status block's
  `state:` edits, `notes/<id>.md`, your wave log entry and your messages go in `<hub>`, the hub's
  own checkout, committed on the hub branch, never on the task branch. The worktree holds its own
  copies of `tasks/`, `notes/`, `waves/` and the rest: read and edit every hub file you do not own
  by its `<hub>` path (your task file is `<hub>/tasks/W<n>-<k>-<slug>.md`), never the worktree's
  copy, and commit it with `git -C "<hub>"`.
- **The gate**, in place of a repo's gate. Commit your files first: the doc list below reads the
  task branch.

  ```bash
  python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" callmap-check "<hub>" --tree "<hub>/.worktrees/<id>"
  python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" check-examples "<hub>" "<doc>" --tree "<hub>/.worktrees/<id>"
  ```

  `callmap-check` runs unless `python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" shape "<hub>"`
  prints `call-map: off`; then record `call map is off (L-063): skipped` in its place. It runs
  on `call-map: on`, and a missing `call-map:` line reads `on` (K7); a non-zero `shape` fails
  the gate. With it on, check the worktree's `callmap/groups.json` first: a missing file records
  `not run (no groups.json yet)`; otherwise `callmap-check` must print a line starting `OK:`,
  and any other exit 2 fails the gate. `check-examples` runs once per doc the task branch
  changed, deleted docs left out
  (`git -C "<hub>" diff --name-only --diff-filter=d "<hub branch>...<task branch>" -- docs/`, and
  not `docs/changes/`), and each run must exit 0.
- **Review** (7. Finish) diffs `<hub branch>...<task branch>` in the hub.

## 1. Read, in order

On start, set `state: briefing` with the Edit tool (see 6. Status). Then read:

1. Hub `CLAUDE.md`.
2. `decisions/LOG.md`: every `active` entry. The setup record is the one
   `python3 "${CLAUDE_PLUGIN_ROOT}/lib/leadflow/cli.py" shape "<hub>"` names; its switches gate
   steps below (a missing `call-map:` line reads `on`, K7). A `shape` that exits non-zero has
   no switches: stop and report its output. When its `Design:` line names a source (not
   `none`, `not asked` or `we make it in tasks`), also read `callmap/figma-inventory.md` and
   `callmap/shots/`, those that exist (design import writes them).
3. `pending/README.md`, then every open note in `pending/`.
4. `context/<repo>.md` (none for a hub task).
5. Your wave log, `waves/W<n>.md`.
6. Your task file, `tasks/W<n>-<k>-<slug>.md`, and everything under its "Read first".
7. Your messages (the `messages` skill).

Then run `lead-flow:router` (it picks from your task file and the code it touches), before the
brief and any build.

## 2. Model check

Before the brief, compare your model with the status block's `model`; if they differ, ask the lead
to switch. You cannot see your own effort, so name the block's `effort` and ask the lead to
confirm the session runs at it. The lead may keep you as you are; carry on then.

## 3. Brief, then wait

Before you touch the repo, send the brief (format: hub `CLAUDE.md`, "Brief first"): 10–20
numbered lines (1–3 for a `small` task) in the groups Loaded (the router's report line, as
`Loaded:`), Builds, Parts, Questions, Differs from the plan, Blocked. Each Part names its
ponytail ladder rung (`lead-flow:ponytail`): does it need to exist → already in the codebase →
standard library → platform → an installed dependency → one line → the minimum new code. Pending notes you can resolve are listed as a Part; resolve them only after the
go-ahead.

Send it with the `messages` skill, set `state: waiting_lead`, and **wait for the lead's explicit
go-ahead**. It arrives in this chat (from the lead, or relayed by the coordinator) or as a
message from the `lead` named in `lead-flow.json`; when told to check, read your messages.
Answer numbered replies line by line. On the go-ahead, set `state: building`.

## 4. Decision checkpoint

Check each "Decisions to re-check" item against the code before building on it. A mismatch stops
that part only: tell the lead the decision, what you found (verified names), the options with
costs, your recommendation, and write a pending note. A check that holds gets one line in your
notes file.

## 5. Build

- **Subagents by default.** Split independent parts into parallel subagents: Sonnet for clearly
  specified pieces, Opus for judgment, the model set explicitly on every dispatch. Parallel only
  where files don't overlap; never two on one file. Inline when splitting costs more than it saves
  (a small or single-file change). You keep the judgment and join the results.
- **Our rules, not `lead-flow:subagent-driven-development`'s.** If you use it, these override it:
  implementers run in parallel on files that don't overlap; there is no plan file unless your
  task is `big` (Size), and then only `notes/<id>-plan.md` with its ledger in the skill's
  git-ignored workspace; otherwise the brief and your task file are the plan, with no sdd ledger;
  a decision mismatch stops that part and
  goes to the lead (4. Decision checkpoint), never decided alone; never invoke
  `lead-flow:finishing-a-development-branch`, and never merge, push or open a merge request
  yourself: the task ends at `ready_to_close` (7. Finish) and the coordinator closes it.
- **Tests sized to the change:** failing tests first for logic, money, auth and security
  (`lead-flow:test-driven-development`); none for a trivial edit. Run the repo's gate once
  before your last commit (a hub task: its gate in A hub task). A bug or red test:
  `lead-flow:systematic-debugging`.
- A deliberate shortcut gets a `shortcut:` comment in the code and a note in `pending/` (the
  `pending` skill).

## 6. Status

Change `state:` in your task file's status block with the Edit tool, the `state:` line in both the
old and the new text. That edit fires `/lead-flow:progress`; a shell or script edit does not. Order:
`briefing` → `waiting_lead` → `building` → `in_review` → `ready_to_close`.

## 7. Finish

1. Set `state: in_review`. Dispatch two independent `task-reviewer` agents in parallel (one for a
   `small` task) with the hub path, your task file, the repo and `<wave branch>...<task branch>`
   (a `repo: hub` task: the hub as the repo and `<hub branch>...<task branch>`).
   A `medium` or `big` task also gets one language reviewer per language in
   `git -C "<repo>" diff --name-only <range>`, `<range>` and `<repo>` being the ones just given to
   the `task-reviewer`s: `csharp-reviewer` for `.cs`, `go-reviewer` for `.go`, `python-reviewer`
   for `.py`. Dispatch them in the same parallel batch with `model: "opus"`, the repo path and the
   range, told to review `git diff <range>` in that repo, not their default `git diff -- '*.<ext>'`
   (that shows only uncommitted work). Their CRITICAL and HIGH findings are BLOCKING; MEDIUM and
   LOW are NOTEs. They run again with the `task-reviewer`s every round, and the review is clean
   only when they report no CRITICAL or HIGH finding too.
   One result with `Second opinion: advisor` and no BLOCKING finding is enough. Two
   `incomplete (second review not run)` results with no BLOCKING finding are each other's second
   review: clean. A `small` task's single reviewer returning `incomplete` gets a second one. Fix
   every finding and review again until clean.
2. Write your wave log entry (contract changes, deploy notes as prose for the close to turn into
   `Deploy:` lines, e.g. `Deploy notes: migration: add products.price_cents index`; never start a
   line with `Deploy:` yourself, or the board lists the note twice) and your notes file
   `notes/<task-id>.md`, with the clean review's `Reviewed sha: <sha>` line. With `call-map: on`
   (1. Read), add "For the consumer docs" lines for what a doc reader needs (a route, a field, an
   error code); with `call-map: off`, write none and say `call map is off (L-063): skipped`. What
   a never-touch repo's owners must know goes under `## For the owners of never-touch repos`,
   whatever the switch.
3. Set `state: ready_to_close`. In the same edit, add `tokens: <total>` (e.g. `tokens: 1.2M`) to
   the status block when you know this session's real token usage from the app's or the CLI's
   own usage report; never a guess or an estimate: unknown usage means no line. Commit in the
   hub, and message the lead "ready to close".