execute

Parse the user's input:

• First argument is the task name (matches the docs directory, e.g., offline-sync)

The orchestrator (you) does the thinking. Sub-agents do the mechanical writing. You extract targeted slices of the docs and brief each sub-agent on exactly one step, with explicit upstream/downstream data-flow context. Never hand a sub-agent the full doc dump.

Phase 1 — Read plan and find the target phase

Read docs/{task-name}/plan.md.

If missing: tell the user "No plan found at docs/{task-name}/plan.md. Run /better-plan {task-name} first." and stop.

Scan for checkpoint sections. A phase is complete when every checkpoint item is - [x]. Find the first phase with unchecked checkpoint items — this is the target phase.

If all phases are complete: "All phases in the plan are complete." and stop.

Tell the user: "Executing Phase {N}: {phase name} — {brief one-line summary}."

Phase 2 — Read context docs

Read from docs/{task-name}/:

• structure.md — technical spec (types, signatures, interfaces). Use for: what each step must implement.
• design.md — design decisions and end state. Use for: why each step exists and what outcomes it serves.

Do not read facts.md or research.md. Those are upstream research artifacts — anything relevant from them should already be consolidated into structure.md and design.md. If you feel a step is under-specified, that is a structure/design gap — stop and report it, don't paper over it by re-reading raw research.

Hold structure and design in your working memory. You will extract slices per step — you will not hand the full docs to sub-agents.

Phase 3 — Build a per-step brief for every step in the target phase

For each step in the target phase, assemble a brief from the three docs:

• From plan.md: the step's full Do/Why blocks, verbatim. This is the instruction.
• From structure.md: only the types, signatures, and interface definitions this step implements or consumes. Inline the relevant Python signatures/type hints — do not paste the entire Data & Types or Interfaces & Contracts sections.
• From design.md: only the design decisions whose rationale touches this step's files or behavior. Usually one or two bullets from the Design Decisions table, plus the relevant sentence from End State if it constrains the implementation.

Then add data-flow context:

• Upstream: what earlier steps in this phase produce that this step consumes. Cite concrete signatures and paths: "Step 1.1 adds @dataclass class Foo: x: int in domain/foo.py — import and use it."
• Downstream: what later steps will expect. Cite how this step's output will be called: "Step 1.3 will call bar(foo: Foo) — your function must accept Foo, not Int."

Then the scope fence: the exact files this step may touch. If the sub-agent finds it needs to modify another file, it must stop and report a plan gap rather than silently widening scope.

Phase 4 — Build the dependency graph for the phase

Within the target phase, identify which steps depend on which:

• A step depends on another if it imports a type the other defines, calls a function the other adds, or modifies a file the other creates.
• Steps that touch unrelated files with no cross-references are independent siblings — they may run in parallel.
• Dependency chains run strictly sequentially. Do not overlap dependent steps.

If the phase has only one step, skip the graph and proceed to Phase 5.

Phase 5 — Execute steps in a worktree

Confirm the base branch before creating the worktree. EnterWorktree branches off the current HEAD — if the orchestrator is somehow not on the user's working branch, the worktree will be based on the wrong commit (e.g., main instead of staging) and the merge in Phase 6 will rewind work or produce noise.

1. Run git branch --show-current to capture the current branch as {base-branch}.
2. Run git rev-parse --short HEAD to capture the base SHA.
3. Tell the user verbatim: "Creating worktree based on branch {base-branch} at {base-SHA}."
4. If {base-branch} is main (or whatever the repo's default branch is) and the user has been working on a feature branch in this conversation, stop and ask before proceeding — this is almost always wrong.
5. Call EnterWorktree once for the whole phase.
6. After entering, run git log --oneline -1 and confirm the new worktree's HEAD matches {base-SHA}. If it doesn't, exit the worktree (ExitWorktree with action: "remove") and surface the discrepancy to the user.

All sub-agents write into this shared worktree — do not set isolation: worktree on the sub-agents (that would spawn a fresh worktree off HEAD of the parent process, which may not be {base-branch}).

Walk the dependency graph:

• Launch all independent-sibling steps in parallel via a single message with multiple Agent tool calls.
• For dependency chains, launch step K+1 only after step K has completed and you have verified its output.

Sub-agent prompt template

Use model: sonnet, effort: high, no subagent_type, no isolation. Build each sub-agent's prompt with this structure:

You are implementing Step {X.Y} of Phase {N} for {task-name}.

## Your Task (from plan.md)

{Full Do/Why blocks for this step, verbatim.}

## Types and Signatures (from structure.md)

{Only the types, signatures, and interfaces this step implements or calls. Inline Python signatures/type hints.}

## Design Intent (from design.md)

{Only the decisions whose rationale touches this step. One or two bullets is usually enough.}

## Upstream Context

{What earlier steps in this phase produced, with concrete signatures and file paths. Omit this section if no upstream dependency.}

## Downstream Expectations

{What later steps will call. The signature your work must satisfy. Omit if no downstream step in this phase consumes your output.}

## Scope

You may modify or create only these files:
{list of files from the step's Do block}

If you find you need to modify any other file to complete the step, STOP and return "plan gap: need to modify {file} for {reason}". Do not proceed, do not widen scope.

## Conventions

- Match existing codebase conventions in nearby files.
- Do not refactor code outside this step.
- Do not add comments unless the plan's Do block explicitly calls for them.
- Do not run tests or build commands — the orchestrator runs the checkpoint after all steps complete.

Commit your changes with message: "Step {X.Y}: {step name}".

Verify between dependent steps

After each step in a dependency chain completes, and before launching any step that depends on it:

• Read the file(s) the step produced.
• Confirm the key signatures you briefed match what was written.

If they don't match, stop the chain and report to the user: "Step {X.Y} produced {actual} instead of the briefed {expected}. Stopping before dependent steps — how should I proceed?" Do not guess or auto-adjust downstream briefs.

No per-step checkpointing. The phase checkpoint at the end of Phase 6 is the verification.

Phase 6 — Merge and run the phase checkpoint

After all steps in the phase have completed:

1. Capture the current branch's HEAD SHA before merging (needed for the review diff in Phase 7): git rev-parse HEAD. Save this as {pre-merge-SHA}.
2. Merge the worktree branch into the current working branch: git merge {branch} --no-edit.
3. Run each checkpoint item from the plan in the merged branch. Record pass/fail.

4. Vacuous-filter check. A test runner can return success for two reasons: tests ran and passed, or the filter matched zero tests. The second is not a pass — it is a planning gap (the checkpoint named a test class that does not exist) that fakes coverage.

   For each test command in the checkpoint, after it returns success, verify tests actually ran:

   • Pytest (pytest -k Bar or pytest tests/test_bar.py): exit code 5 ("no tests collected"), "no tests ran", or 0 passed is vacuous. Run with -q and confirm the summary shows N passed with N > 0 for every filter that names a specific test/path (not a bare pytest).
   • Other runners: any "No test files found" / Tests: 0 passed style success is vacuous.

   The plan author may flag a filter as deliberately vacuous (e.g., (vacuous — no pre-existing tests)), but that annotation is itself a signal that a test should be authored now — it is not a license to check the box. Treat it the same way as an undetected zero-match.

   When a vacuous filter is detected, do not check the box. Surface it:

   ⚠ Phase {N}: {phase name} — checkpoint item is vacuous
   
   - Filter: `{exact filter string}`
   - Matched tests: 0 (filter implies a test class/file that does not exist)
   - Convention check: {look for sibling tests in the same folder; if the codebase
     conventionally tests this kind of class and the file is simply missing, say so}
   
   Options:
   - "write" — I'll author the missing test now to make this checkpoint real,
              then re-run.
   - "skip"  — accept the gap; I'll mark the box checked and note in the
              completion report that this checkpoint did not actually verify
              anything. Use only if you've decided the gap is acceptable.
   - "edit"  — adjust the filter (e.g., to a related test that does exist),
              then re-run.

   Default to "write" unless the user steers otherwise. The completion report (Phase 8) must list any vacuous filters even after the user accepts a "skip", so the gap stays visible.

5. After every test command has been validated as non-vacuous (or explicitly skipped by the user), proceed to the pass/fail branches below.

If all checkpoints pass:

• Record the step list and checkpoint results.
• Do not mark the phase complete yet — proceed to Phase 7 (Review) before reporting completion.

If a checkpoint fails:

• Do not check the boxes.
• Report:

  ✗ Phase {N}: {phase name} — checkpoint failed
  
  Checkpoint results:
  - [x] {item 1} — passed
  - [ ] {item 2} — FAILED: {error output}
  
  The phase changes have been merged. Options:
  - "fix"    — I'll diagnose and fix in the current branch.
  - "revert" — I'll revert the merge so we can re-attempt.

If any sub-agent returned a plan gap:

• Do not merge. Leave the worktree intact.
• Report the gap with the step's reason. Options: adjust the plan, provide guidance, or abandon this phase.

If a sub-agent failed outright:

• Do not merge. Report what the agent said. Options: "retry", "fix and retry" (user gives guidance), or "stop".

Phase 7 — Review the phase's changes

Mechanical checkpoints catch build and test failures. The review catches judgment-level issues the checkpoint can't: drift from the plan, inconsistencies, obvious bugs.

Compute the diff of what this phase actually changed:

git diff {pre-merge-SHA}..HEAD

Spawn a review sub-agent (model: fable, effort: max, no subagent_type, no isolation) with this prompt:

You are reviewing the changes made in Phase {N} of {task-name}.

## What was supposed to happen (from plan.md)

{The full target phase section, verbatim — steps, Do/Why, checkpoint.}

## Design intent (from design.md)

{Relevant design decisions for this phase. One or two bullets.}

## Technical spec (from structure.md)

{Relevant types, signatures, interfaces for the files this phase touched.}

## What actually changed

{Paste the output of `git diff {pre-merge-SHA}..HEAD` here, scoped to the files this phase touched.}

## Your task

Review the changes for three things:

1. **Drift from plan** — do implemented signatures match what plan/structure specified? Any files touched outside the phase's scope? Any steps skipped or only partially done?
2. **Inconsistencies** — type mismatches, unused imports, dead code, naming that doesn't match surrounding conventions.
3. **Obvious bugs** — null gaps, missed error cases, off-by-ones, logic that clearly contradicts the documented intent.

You may use Read and Grep to inspect surrounding code when the diff alone isn't enough.

**Ignore:**
- Style nits that don't affect correctness.
- Questioning the design itself — that decision is already made in design.md.
- Missing functionality that belongs to a later phase.

**Do not** run tests or build commands — the checkpoint already did.

Return findings in this format:

**BLOCKERS** (must fix before phase is complete):
- {file:line} — {issue} — {why it's a blocker}

**CONCERNS** (suspicious, surface to user but not fatal):
- {file:line} — {issue} — {why it's suspicious}

If nothing found, return exactly: "Clean — no blockers, no concerns."

Triage the findings:

If there are blockers:

• Do not check the plan's checkpoint boxes.
• Report:

  ⚠ Phase {N}: {phase name} — checkpoints passed, review found {K} blocker(s)
  
  Blockers:
  - {file:line} — {issue}
  - ...
  
  Concerns (informational):
  - {file:line} — {issue}
  
  Options:
  - "fix"    — I'll fix the blockers in the current branch.
  - "accept" — treat the blockers as false positives and mark phase complete.
  - "revert" — revert the merge and re-attempt.

If only concerns (no blockers), or clean:

• Do not mark the phase complete yet — proceed to Phase 8 (Manual verification).
• Hold the review result (clean or the concern list) to report at Phase 8 completion.

Phase 8 — Manual verification (if required)

Automated checkpoints and code review only go so far. Some phases produce behavior only a human on a real environment can confirm — a UI on a device, a staging server's observable behavior, an end-to-end flow across services. Catch these failures now, one phase at a time, not at the very end when they're expensive to diagnose.

Check whether the target phase in plan.md has a ### Manual Verification section.

If there is no manual verification section:

• Update docs/{task-name}/plan.md — check all checkpoint boxes for this phase (- [x]).
• Report completion using the template below and proceed to Phase 9.

If a manual verification section exists:

Present the steps one at a time — never bundle multiple steps into a single message. The user must confirm each step before you move to the next.

For step i of N, output:

Manual verification — Phase {N}: {phase name}
Step {i}/{total}: {step description from the plan}

Expected: {expected observation from the plan}

Reply "pass" or "fail + reason".

Then wait for the user's reply:

• On "pass" → check the box for step i in plan.md. If there are more steps, present step i+1. If this was the last step, proceed to the "All steps passed" branch below.
• On "fail" (or anything else that isn't "pass") → stop the sequence. Do not check remaining boxes. Do not mark the phase complete. Report:

  ✗ Phase {N}: {phase name} — manual verification failed at step {i}
  
  Step {i}: {description}
  Expected: {expected}
  User reported: {user's message}
  
  Options:
  - "fix"    — I'll diagnose and fix in the current branch, then re-run from step {i}.
  - "revert" — revert the merge and re-attempt the phase.

  Go to Phase 9.

All steps passed:

• Update plan.md — check any remaining checkpoint boxes for this phase (manual-step boxes were already checked as we went).
• Report completion using the template below and proceed to Phase 9.

Completion report template

✓ Phase {N}: {phase name} — complete

Steps run: {e.g., X.1, X.2 + X.3 (parallel), X.4}
Checkpoint: all items passed.
Review: {"clean" | "{K} concern(s) surfaced"}
Manual verification: {"not required" | "all {K} steps passed"}
Vacuous filters: {"none" | "{K} skipped by user — coverage gap remains: {filter list}"}

{If concerns: list them with file:line and the issue.}

Next: Phase {N+1}: {next phase name}
Say "continue" to proceed, or review the changes first.

Phase 9 — Wait for user direction

After reporting, wait for:

• "continue" — go back to Phase 1 to find the next incomplete phase.
• "fix" — diagnose the failure (checkpoint failure, review blocker, or manual-verification failure) in the current branch, fix it, then re-run the failed check. For manual-verification failures, re-present starting from the failed step after the fix lands. If the re-run passes, continue where we left off (e.g., resume manual verification, or mark phase complete).
• "accept" — (review blockers only) treat the blockers as false positives, then proceed to Phase 8 (manual verification) or mark the phase complete if none is required.
• "revert" — git revert --no-edit HEAD to undo the merge; the plan phase stays unchecked for re-attempt.
• "retry" — re-run Phases 3–8 for the same phase.
• "stop" — stop execution and report current progress.

Any other input is guidance for fixing (equivalent to "fix" with context).

Invariants

• Orchestrator thinks, sub-agents write. Extract per-step slices. Never dump the full plan/structure/design into a sub-agent prompt.
• Worktree base branch is explicit. Before creating any worktree, state the source branch and SHA out loud. If the current branch looks wrong (e.g., main when the conversation has been on a feature branch), stop and confirm before calling EnterWorktree. Never let sub-agents create their own worktrees with isolation: worktree — that re-bases off the orchestrator's HEAD invisibly.
• One phase at a time. Never auto-advance to the next phase. Always report and wait at Phase 9.
• Phases are fully serialized. Parallelism is permitted only within a phase, only for truly independent sibling steps. Dependency chains run strictly sequentially.
• Do not modify plan instructions. Only check or uncheck checkpoint and manual-verification boxes.
• Checkpoint, review, and manual verification all gate completion. Checkpoints prove the code builds and tests pass. Review catches drift, inconsistencies, and obvious bugs. Manual verification (when present in the plan) catches what only a human on a real environment can see. A phase is not complete until all applicable gates pass — or until the user has explicitly accepted review blockers as false positives.
• A test command that ran zero tests is not a pass. pytest exit code 5 ("no tests collected"), "no tests ran", or 0 passed is a planning gap, not a verification. A plan author marking a filter (vacuous — no pre-existing tests) is flagging the gap, not authorizing the box to be checked. Run the Phase 6 vacuous-filter check; default to authoring the missing test, not skipping.
• Manual steps go one at a time. When presenting manual verification, never bundle multiple steps into one message. Wait for the user's pass/fail on step i before presenting step i+1. The whole point is catching bugs early — don't let the user skim-accept a batch.
• Plan gaps surface, never silently widen scope. If a step needs to touch a file outside its list, stop and report.
• Verify between dependent steps. Read what the prior step produced and confirm it matches the brief before briefing a downstream step. Do not chain briefs on unverified output.
• Merge conflicts surface to the user. Do not auto-resolve — conflicts mean the plan's file-state assumptions were wrong and need human judgment.