version: "1.0.1" name: orchestrate description: Use when executing implementation plans with independent tasks in the current session

Orchestrate

Execute plans via the configured execution mode. Phases run sequentially; task dispatch within each phase depends on the mode.

Core principle: The lead coordinates — dispatched implementers touch code.

Prompt Templates

Progress Tracking

TaskCreate one entry per task in plan.json (e.g. "Implement A1", "Implement A2", ...) plus per phase "Phase {LETTER}: implementation review", and final "Create PR" / "Mark plan complete". Set addBlockedBy to mirror task depends_on and phase ordering. Mark in_progress when you dispatch a task and completed when its task review passes — granular per-task tracking surfaces stuck tasks immediately rather than hiding them inside a phase-wide "Execute tasks" entry.

Setup

Before first phase:

• Resolve main repo and plan paths. Plan artifacts live in the main repo at $MAIN_ROOT/.claude/claude-caliper/ (gitignored, decoupled from worktree lifetime so they survive cleanup) — they are NOT in the worktree CWD, so realpath plan.json from the worktree will fail.

``bash MAIN_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/\.git$||')" PLAN_JSON="$(realpath -- "<absolute-path-passed-by-caller>")" PLAN_DIR="$(dirname "$PLAN_JSON")" ``

The caller (design skill or user) supplies the absolute plan.json path — typically $MAIN_ROOT/.claude/claude-caliper/<folder>/plan.json. All references downstream must use the absolute $PLAN_JSON / $PLAN_DIR paths since phase worktrees don't have these files.

• Read workflow: WORKFLOW=$(jq -r '.workflow' "$PLAN_JSON")
• Read execution mode: EXEC_MODE=$(jq -r '.execution_mode' "$PLAN_JSON")

Note: workflow and execution_mode are read from plan.json (set by the design skill based on user selection and caliper-settings defaults), not from caliper-settings at runtime. This avoids two sources of truth — the plan is the single source once created.

• Read task implementer model: TASK_IMPLEMENTER_MODEL=$(caliper-settings get task_implementer_model)
• Read task reviewer model: TASK_REVIEWER_MODEL=$(caliper-settings get task_reviewer_model)
• Read implementation reviewer model: IMPL_REVIEWER_MODEL=$(caliper-settings get implementation_reviewer_model)

Note: These model settings are substituted into dispatch template variables {TASK_IMPLEMENTER_MODEL}, {TASK_REVIEWER_MODEL}, and {IMPL_REVIEWER_MODEL} when dispatching implementers, reviewers, and fix-cycle agents.

• Count phases: PHASE_COUNT=$(jq '.phases | length' "$PLAN_JSON")
• Validate schema: validate-plan --schema "$PLAN_JSON"
• Validate entry gate: validate-plan --check-entry "$PLAN_JSON" --stage execution
• Validate base branch: validate-plan --check-base "$PLAN_JSON"
• Validate consistency: validate-plan --consistency "$PLAN_JSON"
• validate-plan --update-status "$PLAN_JSON" --plan --status "In Development"
• PLAN_BASE_SHA=$(git rev-parse HEAD)
• [ -f "$PLAN_DIR/reviews.json" ] || echo '[]' > "$PLAN_DIR/reviews.json"
• Push branch: git push -u origin HEAD
• Read the dispatch protocol for EXEC_MODE: See: ./dispatch-subagents.md (subagents) or ./dispatch-agent-teams.md (agent-teams) — read only the file matching EXEC_MODE

Per-Phase Execution (Sequential)

Process phases in order (A, B, C...). For each phase:

Prepare Phase

1. Determine phase resumption state (multi-phase only — single-phase: use feature worktree, no resumption check needed). Phase status is the primary signal because squash-merge in step 7 typically deletes the phase branch ref, making git merge-base --is-ancestor unreliable.

• If phase status starts with "Complete": run gh pr list --base integrate/<feature> --head phase-<letter> --state merged --json number --jq 'length'. If non-zero, the phase is fully merged — skip to next phase. If zero (status Complete but PR not yet merged), skip directly to Phase Wrap-Up step 7, reusing any open PR or creating one if absent.
• Otherwise (status "Not Started" or "In Progress"): create phase worktree from integration branch (git worktree add "$MAIN_ROOT/.claude/worktrees/<feature>-phase-<letter>" -b phase-<letter>), then link-agent-memory "$MAIN_ROOT/.claude/worktrees/<feature>-phase-<letter>" so the implementation-reviewer dispatched at Phase Wrap-Up persists memory through cleanup. Continue with the remaining numbered steps below (validate-plan --check-base, etc.).

1. Re-validate base branch: validate-plan --check-base "$PLAN_JSON" (multi-phase only — ensures dispatch happens from integration worktree, not main)
2. PHASE_BASE_SHA=$(git rev-parse HEAD) in worktree
3. Bootstrap dependencies in the worktree. See: skills/design/dependency-bootstrap.md
4. Extract context: tasks JSON, plan dir, phase dir, prior completions (from depends_on closure) — prior-phase handoff notes are already inlined in this phase's task .md files (written at prior phase's wrap-up)
5. Set phase to "In Progress": validate-plan --update-status "$PLAN_JSON" --phase {LETTER} --status "In Progress" — required before any task can be marked in_progress (transition gate rejects task advancement when parent phase is "Not Started")

Dispatch, Complete, and Review Tasks

Follow the dispatch protocol from the mode-specific file read during setup. Both modes share these invariants:

• Only dispatch tasks whose dependencies are met (validate-plan --check-deps "$PLAN_JSON")
• Each task gets reviewed after implementation (reviewer always uses ./task-reviewer-prompt.md)
• After review passes: validate criteria (validate-plan --criteria "$PLAN_JSON" --task {TASK_ID}), merge task branch, check for newly unblocked tasks

The dispatch file specifies how tasks are dispatched (teammates vs subagents), how completions are detected (push vs background notification), and how review fixes are communicated (mailbox vs fresh agent).

Phase Wrap-Up

After all tasks complete and branches merged:

1. Dispatch implementation-review with PHASE_BASE_SHA..HEAD using model: "$IMPL_REVIEWER_MODEL", run Review Loop Protocol (scope: phase-{letter_lower})
2. validate-plan --check-review "$PLAN_JSON" --type impl-review --scope phase-{letter_lower}
3. Append review changes to ${PHASE_DIR}/completion.md
4. Run phase criteria: validate-plan --criteria "$PLAN_JSON" --phase {LETTER}
5. Update status: validate-plan --update-status "$PLAN_JSON" --phase {LETTER} --status "Complete (YYYY-MM-DD)"
6. Write cross-phase handoff notes for downstream tasks. For each task in a future phase whose depends_on references a task from this phase, append a handoff section to {PLAN_DIR}/phase-{next_letter}/{target_task_id_lower}.md describing the shipped interface — names, paths, signatures, usage. Writing post-wrap-up (rather than before next-phase dispatch) means notes reflect the shipped reality, including any review-driven interface changes. Insert after the H1, before existing prose:

````markdown # B1: Dashboard page

## Handoff from A2

Auth middleware exports validateToken() from src/auth/middleware.ts. Use as Hono middleware: app.use('/dashboard/*', validateToken()).

Avoid: ... ````

Ad-hoc handoffs (no current `depends_on` link). When implementation surfaces context useful to a future task that wasn't anticipated at design time, register the dependency before writing the note: validate-plan --add-dep "$PLAN_JSON" --task {DOWNSTREAM_ID} --depends-on {SOURCE_ID}. This keeps plan.json the single source of truth for the dependency graph and re-renders plan.md. Then write the ## Handoff from {SOURCE_ID} section as above.

Opt-out. If downstream tasks can derive everything they need from completion.md alone, append a ## Handoff Notes section to {PHASE_DIR}/completion.md whose first content line starts with None (e.g., None — downstream tasks derive context from completion.md.).

Validate: validate-plan --check-handoffs "$PLAN_JSON" --phase {LETTER} — fails if any cross-phase depends_on link into this phase lacks a matching ## Handoff from section AND no opt-out block exists.

1. (Multi-phase) Merge phase PR into integration branch — runs unconditionally for every phase including the last, regardless of workflow setting. The final integrate->main PR is created separately in "After All Phases".

a. Open the phase PR: if one already exists and is open (gh pr list --head phase-<letter> --state open --json url --jq '.[0].url'), reuse it; otherwise run pr-create --base integrate/<feature>. b. REVIEW_WAIT=$(caliper-settings get review_wait_minutes) c. If $REVIEW_WAIT == 0: invoke pr-merge directly. Else: invoke pr-review --automated-merge (which invokes pr-merge). No pre-merge gh pr checks poll — pr-merge enables auto-merge so GitHub gates on CI, then waits (up to merge_wait_minutes) for the MERGED flip before returning. If that wait times out with the PR still open, step d's --ff-only finds no merged tip and stops the loop (handled there) — resume once GitHub completes the merge d. Return to the integration worktree (the orchestrate lead's primary CWD established at Setup) and fast-forward local integrate to the merged tip: cd "$MAIN_ROOT/.claude/worktrees/<feature>" && git pull --ff-only origin integrate/<feature> — uses $MAIN_ROOT from Setup so the path is absolute (relative cd .claude/worktrees/<feature> would fail when called from a phase worktree). --ff-only surfaces unexpected divergent commits, because auto-resolution via hard reset can silently destroy local commits the user may need. If it fails, stop the loop and surface to the user with the worktree path. e. Remove phase worktree if it still exists (pr-merge typically removes it during cleanup; on resumption it may already be gone): if git worktree list --porcelain | grep -q "^branch refs/heads/phase-<letter>$"; then git worktree remove "$MAIN_ROOT/.claude/worktrees/<feature>-phase-<letter>"; fi — anchored on the branch refs/heads/... porcelain line (avoids matching the worktree-path line). No --force; missing worktree is silent-continue, while a failed git worktree remove (uncommitted content) propagates non-zero exit so the orchestrator can stop and surface the path. f. Continuity: only Rule 4 deviations stop the loop. Review feedback is auto-fixed by pr-review --automated-merge.

Review Loop Protocol

Read the re-review threshold: RE_REVIEW_THRESHOLD=$(caliper-settings get re_review_threshold) (default: 5).

After each impl-review dispatch:

1. Extract last json review-summary fenced block from response. Missing/malformed -> verdict:fail, re-dispatch.
2. Triage issues: "fix" (dispatch implementer) or "dismiss" (with reasoning). Issues with `non_dismissible: true` must take the 'fix' branch — dismissing them invalidates the review record and triggers re-dispatch. This rule exists to prevent the dismissal pattern from gh issue #243 (impl-review #1 there dismissed a "kv_launcher↔kv_fetch boundary test missing" finding as low-severity; the seam then leaked 22+ commits of contract-drift bugs).
3. actionable == 0 -> write reviews.json record with verdict:pass, advance
4. actionable 1-$RE_REVIEW_THRESHOLD -> fix all, verify, write record verdict:pass, advance
5. actionable > $RE_REVIEW_THRESHOLD -> fix all, write record verdict:fail, re-dispatch (max 3 iterations, then escalate via AskUserQuestion)

Append record to {PLAN_DIR}/reviews.json: {"type":"impl-review","scope":"{SCOPE}","iteration":N,"issues_found":N,"severity":{...},"actionable":N,"dismissed":N,"dismissals":[...],"fixed":N,"remaining":0,"verdict":"pass|fail","timestamp":"ISO8601"}

Single-Phase Plans

Skip integration branch and phase worktrees. Work directly in the feature worktree:

1. Dispatch tasks, process completions, wrap up (same dispatch protocol as above)
2. Dispatch implementation-review, run Review Loop Protocol (scope: phase-a)
3. validate-plan --check-review "$PLAN_JSON" --type impl-review --scope phase-a
4. Run plan criteria: validate-plan --criteria "$PLAN_JSON" --plan
5. validate-plan --update-status "$PLAN_JSON" --plan --status Complete
6. Route on workflow:

• "orchestrate": validate-plan --check-workflow "$PLAN_JSON", report worktree path, stop
• "pr-create": invoke pr-create (targets main), validate-plan --check-workflow "$PLAN_JSON", stop
• "pr-merge": invoke pr-create, read REVIEW_WAIT=$(caliper-settings get review_wait_minutes), invoke pr-review --automated-merge (skip if $REVIEW_WAIT is 0; if skipped, invoke pr-merge directly), validate-plan --check-workflow "$PLAN_JSON"

After All Phases (Multi-Phase Only)

1. Run plan criteria: validate-plan --criteria "$PLAN_JSON" --plan. If exit 1, do not mark complete.
2. Final review: dispatch implementation-review with PLAN_BASE_SHA..HEAD, run Review Loop Protocol (scope: final)
3. validate-plan --check-review "$PLAN_JSON" --type impl-review --scope final
4. validate-plan --update-status "$PLAN_JSON" --plan --status Complete
5. Route on workflow:

• "orchestrate": validate-plan --check-workflow "$PLAN_JSON", report worktree path, stop
• "pr-merge": create final PR, pr-review --automated-merge (no pre-merge check poll — pr-merge auto-merges and waits for MERGED), validate-plan --check-workflow "$PLAN_JSON", clean up
• "pr-create": create final PR, validate-plan --check-workflow "$PLAN_JSON", stop

Continuity: Run continuously. Pause only for Rule 4 violations.

Key Constraints

Integration

Workflow: design → draft-plan → this skill → pr-create → pr-review → pr-merge See: tdd.md