Phased Implement

Coordinate multi-phase implementation across workmux worktrees. The coordinator owns the master plan, phase dispatch, merge order, ancestry checks, final integration validation, and final summary. The coordinator does not edit source files for feature work.

Do not use Claude Code built-in worktree features. Use workmux for worktree orchestration.

Operating principles

• Coordinator never writes source. All implementation happens inside spawned worktree agents through /implement.
• workmux done is not success. A phase succeeds only when its result sentinel reports status: success and the coordinator verifies it.
• Merges are serialized. At most one /merge --keep runs at a time.
• Dependents spawn only after every dependency is merged. No exceptions.
• Drain completed handles before dispatching dependents. workmux wait --any can return after one transition while sibling phases also finished.
• Use bounded waits. Avoid tight polling and inspect workmux status on timeouts.
• Preserve failed and blocked worktrees for inspection. Remove worktrees only after merge and ancestry verification succeed.
• Treat merge conflicts as merge failures for that phase, not as reasons to destroy the worktree.
• Read the master plan YAML semantically. Do not write shell parsers for YAML.
• Keep all coordinator artifacts in one shared history/<date>-phased-<slug>/ run directory so worktrees can read prompts and write sentinels.

Argument handling

Arguments are $ARGUMENTS.

Parse these flags before starting:

• --plan <path>: load an existing master plan instead of generating one.
• --integration-branch <branch>: branch that receives phase merges. Default: current branch.
• --preset light|standard|design|strict: default preset for generated phases.
• --validation <command>: final integration validation command.
• --reviewer <selector>: consult-llm selector for optional integration review. Repeatable.
• --reviewers <selector,selector>: comma-separated reviewer selectors.
• --integration-review none|auto|full: final integration review policy. Default: auto.

Everything else is the requested multi-phase implementation.

Preset semantics:

• light: established local pattern, focused validation, no external review
• standard: bounded implementation with acceptance evidence and applicable runtime exercise
• design: meaningful ownership, API, or architecture choice, with one source-grounded technical-shape review
• strict: real trust, persistence, protocol, migration, destructive, concurrency, or FFI boundary, with boundary evidence and one final diff review

Presets increase evidence, not planning or architecture.

Required artifacts

Write coordinator artifacts under history/ using a dated run directory:

history/<YYYY-MM-DD>-phased-<slug>/
  plan.md
  prompts/
  captures/
  summary.md

Required:

• master phased plan at history/<run>/plan.md
• per-phase result sentinel at history/<run>/captures/<phase-id>.result.md
• final summary at history/<run>/summary.md

Optional:

• external review capture
• debug notes

Do not require ADRs or feedback ledgers.

Phase A: snapshot and plan

1. Record the integration branch and start commit:

   START_HEAD=$(git rev-parse HEAD)
   INTEGRATION_BRANCH=<integration-branch or current branch>
   git branch --show-current
   git rev-parse --verify "$INTEGRATION_BRANCH"
   git status --short

2. Stop if unrelated uncommitted changes make orchestration unsafe. The integration branch must exist and must not be a detached HEAD.

3. Pick a topic slug and create the shared run directory:

   PLAN_DIR="history/<YYYY-MM-DD>-phased-<slug>"
   mkdir -p "$PLAN_DIR/prompts" "$PLAN_DIR/captures"

   history/ is gitignored and shared across workmux worktrees in this repo style. Do not commit files from this directory.

4. Track phase state in coordinator memory with these statuses: pending, working, done-unverified, merging, merged, failed, blocked.

5. If --plan <path> is provided, copy or write it to $PLAN_DIR/plan.md, read it, and validate it.

6. If no plan is provided, generate a master phased plan at $PLAN_DIR/plan.md. Gather source context first with Glob, Grep, and Read. The master plan should be scheduling-focused, not code-heavy. Assign phase presets by risk:

   • light for routine mechanical phases from a clear master plan
   • standard for non-trivial phases with known approach
   • design for uncertain, cross-module, or approach-heavy phases
   • strict for public contracts, data formats, security-sensitive work, migrations, or high regression risk

Generated plans should mark non-trivial phases as at least standard.

Master plan schema

The master plan must contain one YAML block and one brief per phase.

# <Feature> Master Plan

**Goal:** <one sentence>
**Integration branch:** <branch>
**Start commit:** <sha>
**Final validation:** `<command>`

```yaml
phases:
  - id: api-contract
    description: Define the public API contract for X.
    depends_on: []
    paths:
      - "src/api/**"
      - "tests/api/**"
    preset: design
    acceptance:
      - "Given a valid request, when the API is called, then it returns the new response shape."
    validation: npm test -- tests/api
```

## Phase briefs

### api-contract

**Intent:** why this phase exists
**Current problem:** what is wrong now
**Desired shape:** target behavior and boundaries
**Preserve:** behavior that must not change
**Avoid:** overreach and later-phase ownership
**Dependencies:** previous phase outputs

Required YAML fields per phase:

• id: stable slug, unique across phases
• description: one sentence
• depends_on: list of phase ids
• paths: expected owned paths or globs
• preset: light, standard, design, or strict
• acceptance: list of acceptance criteria

Optional field:

• validation: phase-specific validation command

DAG validation

Before dispatch, validate the plan:

• Every phase id is unique.
• Every dependency names an existing phase.
• The graph has no cycles.
• Every phase has a valid preset.
• Every phase has acceptance criteria.
• Phase briefs exist for every phase.
• Phase path ownership is specific enough to detect obvious overlap.
• Overlapping paths are allowed only when dependencies serialize those phases or the brief explains the boundary.
• A final validation command exists or can be inferred.

If validation fails, update the master plan directly and rerun validation.

Phase B: dispatch loop

Dispatch phases whose dependencies have succeeded and merged. Parallel phases may run at the same time when dependencies are satisfied and path ownership is safe.

Use the exact local workmux command syntax when running commands in this repo. Do not switch to Claude Code worktrees.

Loop:

1. Drain completed handles before spawning new work. Run Phase C and Phase D for every tracked handle that is already done before recomputing the ready set.

2. Compute the ready set: phases with status pending whose every dependency has status merged.

3. If the ready set is empty and no phase is working, done-unverified, or merging, proceed to final integration validation.

4. For each ready phase:

   • Resolve the preset and phase validation command.
   • Write $PLAN_DIR/prompts/<phase-id>.md.
   • Spawn a workmux worktree from the integration branch.
   • Track the workmux handle and set phase status to working.

   workmux add <phase-id> -b --base "$INTEGRATION_BRANCH" -P "$PLAN_DIR/prompts/<phase-id>.md"

5. Confirm newly spawned handles started with a bounded wait:

   workmux wait <handles> --status working --timeout 120

   On timeout, inspect workmux status. A fast phase may have moved straight to done; treat done as valid. Mark a handle failed only if it is missing, exited unexpectedly, or is stuck before it starts.

6. Recompute the live working handle set before every wait. Exclude phases that are already done-unverified, merging, merged, failed, or blocked.

7. Wait for the next transition in bounded chunks:

   workmux wait <working-handles> --any --timeout 300
   workmux status <working-handles>

   If timeout occurs, inspect workmux status. If any handle is waiting, capture it, mark it blocked, and halt its dependents. Otherwise continue waiting. If a handle exited unexpectedly, mark it failed.

8. Treat done as unverified completion, not success. Set status to done-unverified, capture output, and run Phase C.

9. After every done handle has been verified and merged or marked failed, recompute the ready set. Skipping this drain can spawn dependents against a stale integration branch.

Halt logic:

• When a phase becomes failed or blocked, stop spawning new dependent phases.
• Mark every transitive dependent as blocked with the blocker phase id.
• Let currently working phases that are not transitive dependents finish when their paths and dependencies are unaffected.
• Preserve failed and blocked worktrees for inspection.
• Continue to final summary after the loop drains or no safe progress remains.