Orchestrates execution of implementation plans with independent tasks by dispatching implementers and reviewers, tracking granular progress per task and phase.
npx claudepluginhub nikhilsitaram/claude-caliper --plugin claude-caliper-workflowThis skill uses the workspace's default tool permissions.
Execute plans via the configured execution mode. Phases run sequentially; task dispatch within each phase depends on the mode.
Executes implementation plans from plan.md files via Superpower Loop phases: task creation, batch execution with verification, git commits. Use after plan ready or on 'execute the plan'.
Executes written implementation plans by delegating all code tasks to subagents with dependency-aware dispatch, context preservation, review checkpoints, and lower-cost models.
Orchestrates multi-phase implementation from plan documents using sub-agents with auto-detected parallel/sequential strategies based on dependencies.
Share bugs, ideas, or general feedback.
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.
| 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 |
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.
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
Process phases in order (A, B, C...). For each phase:
git merge-base --is-ancestor unreliable.
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.validate-plan --check-base, etc.).validate-plan --check-base "$PLAN_JSON" (multi-phase only — ensures dispatch happens from integration worktree, not main)PHASE_BASE_SHA=$(git rev-parse HEAD) in worktreevalidate-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")Follow the dispatch protocol from the mode-specific file read during setup. Both modes share these invariants:
validate-plan --check-deps "$PLAN_JSON")./task-reviewer-prompt.md)validate-plan --criteria "$PLAN_JSON" --task {TASK_ID}), merge task branch, check for newly unblocked tasksThe 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).
After all tasks complete and branches merged:
Dispatch implementation-review with PHASE_BASE_SHA..HEAD using model: "$IMPL_REVIEWER_MODEL", run Review Loop Protocol (scope: phase-{letter_lower})
validate-plan --check-review "$PLAN_JSON" --type impl-review --scope phase-{letter_lower}
Append review changes to ${PHASE_DIR}/completion.md
Run phase criteria: validate-plan --criteria "$PLAN_JSON" --phase {LETTER}
Update status: validate-plan --update-status "$PLAN_JSON" --phase {LETTER} --status "Complete (YYYY-MM-DD)"
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.
(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 .claude/worktrees/<feature> && git fetch origin && git reset --hard origin/integrate/<feature>
e. Remove phase worktree if it still exists (pr-merge typically removes it during cleanup; on resumption it may already be gone): git worktree list --porcelain | grep -q "phase-<letter>$" && git worktree remove .claude/worktrees/<feature>-phase-<letter> --force || true
f. Continuity: only Rule 4 deviations stop the loop. Review feedback is auto-fixed by pr-review --automated-merge.
Read the re-review threshold: RE_REVIEW_THRESHOLD=$(caliper-settings get re_review_threshold) (default: 5).
After each impl-review dispatch:
json review-summary fenced block from response. Missing/malformed -> verdict:fail, re-dispatch.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"}
Skip integration branch and phase worktrees. Work directly in the feature worktree:
phase-a)validate-plan --check-review "$PLAN_JSON" --type impl-review --scope phase-avalidate-plan --criteria "$PLAN_JSON" --planvalidate-plan --update-status "$PLAN_JSON" --plan --status Complete"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"validate-plan --criteria "$PLAN_JSON" --plan. If exit 1, do not mark complete.PLAN_BASE_SHA..HEAD, run Review Loop Protocol (scope: final)validate-plan --check-review "$PLAN_JSON" --type impl-review --scope finalvalidate-plan --update-status "$PLAN_JSON" --plan --status Complete"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", stopContinuity: Run continuously. Pause only for Rule 4 violations.
| 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 |
Workflow: design → draft-plan → this skill → pr-create → pr-review → pr-merge
See: tdd.md