orchestrate

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

Template	Purpose
./implementer-prompt.md	Invocation template for claude-caliper:task-implementer
./task-reviewer-prompt.md	Invocation template for claude-caliper:task-reviewer
skills/implementation-review/reviewer-prompt.md	Invocation template for claude-caliper:implementation-reviewer
./dispatch-subagents.md	Subagents dispatch protocol
./dispatch-agent-teams.md	Agent teams dispatch protocol

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.

  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 and continue with the remaining numbered steps below (validate-plan --check-base, etc.).
2. Re-validate base branch: validate-plan --check-base "$PLAN_JSON" (multi-phase only — ensures dispatch happens from integration worktree, not main)
3. PHASE_BASE_SHA=$(git rev-parse HEAD) in worktree
4. Bootstrap dependencies in the worktree. See: skills/design/dependency-bootstrap.md
5. 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)
6. 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:

   # 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.

7. (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: poll gh pr checks then invoke pr-review --automated-merge (which invokes pr-merge on pass) 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)
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), poll checks + 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, poll checks, pr-review --automated-merge, 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

Constraint	Why
Resolve PLAN_JSON as absolute path at setup	Plan artifacts are gitignored — phase worktrees won't have them. Absolute path ensures all agents access the same file.
Read execution_mode from plan.json at setup	Determines which dispatch protocol to follow
Validate schema before execution	Catches file-set overlap and structural issues early
Record PLAN_BASE_SHA before first phase	Final cross-phase review needs total diff
Record PHASE_BASE_SHA per phase	Per-phase review needs exact phase start
Use validate-plan for all status updates	Keeps plan.json and plan.md in sync
All tasks complete before advancing phase	Phase completion gate prevents unresolved work
Run gate checks at startup and after status changes	Entry gates prevent wasted work, base-branch checks prevent wrong-worktree dispatch, consistency checks catch state drift

Integration

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