c-execute
Skill1 starsChanged 3 months agoMITView on GitHub
Use when the user wants to implement a Cadence plan, or resume one that is already in progress.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs-siteSkill
- c-auditSkill
- c-brainstormSkill
- c-checkSkill
- c-designSkill
- c-explainSkill
- c-find-bugsSkill
- c-planSkill
- c-validateSkill
- c-worktreeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Before scheduling, detect the plan format per-plan:
- Distinctive: line 107
No worktree machinery: no lane branches, no git worktree add, no merge-on-land, and no merge-lock acquisition (commits land directly on the …
- Very specific: line 138
Use the Task tool with one of these named agents:
- Distinctive: line 152
Every sub-agent return leads with one plain-English sentence stating what's done/broken and why it matters, before any file:line citations:
- Distinctive: line 188
When a lane's implementer returns DONE, dispatch both reviewers concurrently against the cumulative lane diff:
- Distinctive: line 218
Before marking any task complete, grep the task's diff:
- Distinctive: line 224
If pre-existing comment untouched by this task → note and proceed.
- Distinctive: line 225
If new deferral → STOP:
- Distinctive: line 226
Ask user to confirm.
- Very specific: line 227
Add entry to plan-side 99-out-of-scope.md with rationale + wikilink to task.
- Distinctive: line 229
Only then mark task complete.
- Very specific: line 290
Out of scope: write a plan-side 99-out-of-scope entry (rationale plus a wikilink to the task).
- Distinctive: line 297
Re-audit: When any row was fixed, re-run the completion audit once, passing the Review decisions table so the branch review skips decided …
- Very specific: line 305
Verify: every step - [x] + both reviews ✓ + commit visible in git log.
- Distinctive: line 308
Read the agent's report.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/c-execute
You are the PM. You drive a plan to completion via fresh sub-agents per task, two-stage review, and a completion-time audit gate. You never inherit sub-agent context. You never read the whole repo.
Invocation
/c-execute <path-to-plan-folder>
Optional: /c-execute --restart <plan-path> — wipe checkboxes and start over (NEVER the default).
Plan-format detection
Before scheduling, detect the plan format per-plan:
- New format (tasks carry
Touches:) → run the lane engine below, or the inline path when the execution-mode gate selectsinline. - Legacy format (tasks carry
Files:/Parallel:, noTouches:) → run the legacy sequential path (walk phase files in order, one implementer per task, sequential two-stage review, no worktrees) and print once: "This plan uses the legacy format; running sequentially. Re-plan with/c-planto enable parallel execution." A single plan is never run half-parallel, half-sequential. execute.parallel: false→ run the legacy sequential path regardless of plan format (the user has opted out of worktree parallelism). Takes precedence overexecute.mode; the execution-mode gate is skipped.
Pre-flight checks (in order; any failure surfaces — no auto-resolution)
- Resolve config by running
node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.js"and use its JSONconfigfor everyexecute.*andworktree.*read this run; follow the notice/gitignore/hard-stop contract inskills/_shared/config-resolution.md; never read config files directly. - Path resolves to a plan folder with
00-overview.md. - Status is
draft(becomesin-progressonce you start) ORin-progress(resuming). - Linked design exists with
status: approvedor later — resolve and read it viaskills/_shared/storage-resolution.md(read_artifact) rather than reading a rawlinked_design:frontmatter line. - Plan style is valid: the plan overview's
**Plan style:**line is absent (meaningfull-code) or readsfull-codeordecisions. Any other value is a malformed plan: stop and surface it here, before the execution-mode gate and before any status orbase_shawrite. - Working tree is clean (no unstaged or uncommitted changes).
- Current branch — print branch and ask before proceeding if it's
main/master/develop. - Execution-mode gate (new-format plans only). Resolve
execute.mode:parallel— run the lane engine. Keep today's worktree confirmation: unlessexecute.worktree_confirm: false, print the worktree plan and ask once viaAskUserQuestion: "This plan runs up to<max_parallel>parallel lanes in git worktrees under.cadence/worktrees/(auto-created, auto-removed; the completion gate blocks if any remain). Proceed?" On confirm, worktree management is fully automatic for the rest of the run — no per-lane prompts. On decline, do not start.inline— run the Inline mode path (below). No worktree question; nothing worktree-related happens all run.ask(default) — ask once viaAskUserQuestion(this mode question subsumes the worktree confirmation;execute.worktree_confirm: falsedoes not suppress it):- Parallel lanes in worktrees
(Recommended)— up to<max_parallel>lanes under.cadence/worktrees/(auto-created, auto-removed),Touches:guard, two-stage sub-agent review per lane. - Inline sequential — the PM session implements every task itself in the main worktree, in dependency order; no worktrees, no implementer sub-agents; reviews are performed inline by the PM (reduced independence), and the completion audit still runs as a real sub-agent.
- Don't start — nothing is dispatched; re-run
/c-executewhen ready. Legacy-format plans skip this gate entirely (no worktrees, no mode choice).
- Parallel lanes in worktrees
On first flip from draft to in-progress: record base_sha
Before starting any task, record the current HEAD SHA on the plan overview as base_sha per skills/_shared/storage-resolution.md (set_property). This is the anchor /c-audit will use to compute the diff range (git diff <base_sha>..HEAD). On resume (status already in-progress), read the existing base_sha via read_artifact and preserve it — never re-anchor, even if HEAD has moved.
SHA-based pinning is robust against rebases, merges, and unrelated commits that timestamp-based diffing would miss.
PM responsibilities
- Read the plan once via
skills/_shared/storage-resolution.md(read_artifact): a single pass materializes the overview + every phase doc + 96-validation + 97/98/99 into the in-memory task list. This is the only plan read, and only the PM issues it; do not read phase-file markdown by path. From the overview, take three things here, once: the plan style from the**Plan style:**line (no line meansfull-code; pre-flight check 5 already rejected any other value), the## Global Constraintssection, and the## Review Focussection (both absent on plans written before they existed; then pass nothing). Never readplan.stylefrom config during execution. - Build an internal task list — every
### Task N.Mbecomes a tracked item with itsDepends:edges,Reads:block,Touches:list, and full step block extracted. - Build the dependency DAG from each task's
Depends:edges and form lanes per the scheduling loop in "Lane model and DAG scheduling". - Dispatch lanes concurrently up to
execute.max_parallel, respectingTouches:disjointness. - After each task lands (spec ✓ + code ✓ + Invariant 3 clean), record the lane's progress by ticking every
- [ ]step under### Task N.Mperskills/_shared/storage-resolution.md(tick). See Marking task complete. - Surface blockers to user — never work around silently.
- Run audit gate at the end, then the end-of-run walk over the Review decisions table; set status to
implementedperskills/_shared/storage-resolution.md(set_status) only when the audit passes and no row ispending. Committing accumulated plan-file changes in one commit is the filesystem backend's mechanism only; in Notion mode every tick and status write already landed live, so there is no plan file to commit.
The PM never reads the whole repo, never runs sub-agents on its own session context, never aggregates code commits, never amends commits, never skips hooks. The PM is also the sole caller of skills/_shared/storage-resolution.md: it issues the one read_artifact and every tick/set_status/set_property write. Implementers and reviewers receive their task spec as plain text and touch git only; they stay storage-backend-blind.
Lane model and DAG scheduling
Applies in parallel mode; inline mode replaces this whole engine with the Inline mode section below. The PM builds a dependency DAG from each task's Depends: edges (cross-file allowed), then runs lanes — the ready subset of one phase file's tasks — concurrently in isolated worktrees. The phase file is the lane: the unit of dispatch, the unit of review, and the unit of merge.
- Lane = the ready subset of one phase file
F's tasks, run by onecadence-implementerin one worktree, committing per-task internally. Lane boundaries are author-visible (the0X-*.mdfilename); they are NOT a runtime-derived chain. - Lane formation (per phase file): for every phase file
Fwith at least one ready task, computeeligible(F)= tasks ofFwhose cross-fileDepends:are merged AND whoseTouches:are disjoint from every in-flight lane. Ifeligible(F)is non-empty, dispatch it as one lane. InternalDepends:(both endpoints in the same eligible subset) do NOT gate dispatch — the implementer resolves them inside the lane by running predecessors first. - Ready set: a task is ready when every cross-file
Depends:predecessor has merged to the working branch. InternalDepends:are intra-lane ordering, not ready-set gates. Recompute on every land. - Co-schedule guard (hard): two ready lanes may run concurrently only if
Touches(A) ∩ Touches(B) = ∅. ATouches:overlap serializes the later lane (defer until the other lands) — never error, never override. The guard now operates between phase-file lanes; same semantics as before. - Cap: up to
execute.max_parallellanes (default 4 = concurrent worktrees). Reviewers run on top, uncapped. - Follow-up lanes from the same file: when only part of a phase file is currently ready (cross-file
Depends:pending orTouches:collision), the PM dispatches the ready subset now and the remainder waits in the ready set. When the remainder clears, it forms a second (or third) lane from the same phase file. One file can become 2–3 lanes over a run; each lane reviews independently against its own cumulative diff.
Edge cases (load-bearing). A phase file with a single task = a singleton lane; same as today. A phase file with every task blocked at scheduling time = no lane forms; revisit when the ready set changes. An empty phase file is skipped. An internal-Depends: cycle inside one file is a plan defect — surfaced at DAG construction, never silently re-ordered. Two tasks in F that declare overlapping Touches: are dispatched in the same lane — the implementer runs them in Depends: order with per-task commits; the Touches: overlap inside one lane is not flagged (the guard exists only between distinct lanes).
Scheduling loop
build DAG from Depends edges (once; rebuild on resume)
while unfinished tasks and not quiescing:
ready = tasks whose cross-file Depends predecessors all merged
(internal Depends do not gate; the implementer resolves them in-lane)
while free lane slots > 0:
for each phase file F (numeric order: 01- before 02- …) with ≥ 1 task in ready:
eligible(F) = { T in tasks(F) ∩ ready :
Touches(T) ∩ Touches(in-flight lanes) = ∅ }
if eligible(F) is non-empty
and Touches(eligible(F)) ∩ Touches(in-flight) = ∅:
open worktree
dispatch one implementer with eligible(F) as the lane
mark eligible(F) in-flight
break (one dispatch per slot per inner pass)
else:
defer F to next tick (its ready tasks stay in the ready set)
await next lane to land
on land: integrate (merge-on-land), flip the lane's task checkboxes, free slot
(remainder of F = tasks(F) \ landed \ in-flight \ merged stays in ready set;
re-enters eligible(F) on a later tick when its blockers clear — this is the
follow-up-lane mechanism)The DAG must be acyclic; a cycle is a plan defect — surface it, never guess an order. Internal-Depends: cycles inside one phase file are caught by the same acyclicity check at DAG construction time and never reach this loop.
Inline mode (no worktrees, no implementer sub-agents)
Selected by execute.mode: inline or the ask gate. The PM session implements every task itself, directly in the main worktree. The execution-side analog of the authoring skills' inline generation mode.
- Order: topological over
Depends:edges (the same DAG; acyclicity check unchanged), walking phase files in numeric order and task order within a file as the tie-break.Touches:overlaps are irrelevant — nothing runs concurrently. - Per task, unchanged from the lane engine's per-task contract: follow the task's steps exactly (TDD shape included), commit per task with the task's commit step, run the Invariant 3 grep on the task's diff, and tick the task's checkboxes per
skills/_shared/storage-resolution.md(tick) the moment it lands. The progress-checkpoint rule holds: never carry landed-but-unmarked work through a pause. - Review: the PM self-reviews each task's diff against the task spec and repo conventions before ticking, applying the spec reviewer's style-aware rules (
agents/cadence-spec-reviewer.md: exact match for full-code plans, the decisions for decision plans), the plan's Global Constraints, and any Review Focus pins the task owns. It records the task'sTests:evidence before ticking, and when a run doesn't match its Expected line it follows the implementer's root-cause-first rule (agents/cadence-implementer.md). This is a real trade-off — the author is the reviewer — and is exactly what the user opts into by picking inline; do not silently dispatch reviewer sub-agents anyway. The self-review also applies the spec reviewer's check 9 (spec-silent behavior): a clear violation is fixed before ticking, and a case it would decline, or a repo convention that conflicts with what the task prescribes, is recorded as apendingReview decisions row with sourceinline self-reviewwhen the task is ticked. - No worktree machinery: no lane branches, no
git worktree add, no merge-on-land, and no merge-lock acquisition (commits land directly on the working branch; there is nothing to integrate). The completion-time worktree-cleanup sweep still runs and should trivially find nothing. - Drift and blockers: the drift
AskUserQuestiontable applies unchanged; quiesce is trivial (nothing else is in flight). Implementer status handling and NEEDS_CONTEXT routing don't apply — there is no implementer to route. - Completion gate: unchanged in every mode. The
cadence-completion-auditordispatch stays a real sub-agent — its value is independence from the author, which matters MORE when the author also reviewed. Never run the audit inline. - Resume: identical protocol; checkbox state remains the only source of truth. The worktree prune step is a harmless no-op.
Worktree lifecycle and merge-on-land
Lane isolation and integration follow skills/_shared/worktree-lifecycle.md.
- Open a worktree per lane at lane start (
git worktree addfrom the current working tip). - Acquire the merge lock before integrating (gated by
worktree.merge_lock, default true): when a lane is ready to land, runbash ${CLAUDE_PLUGIN_ROOT}/scripts/merge-lock.sh acquire --target <working-branch> --threshold <worktree.lock_stale_threshold>from the repo root. The lock is repo-global (one lock in the git common dir, not per branch), so a concurrent/c-worktreemerge or hand merge in another session serializes with lane landings regardless of target branch. Withworktree.merge_lock: false, skip acquire/release entirely and integrate exactly as before the lock existed (the single PM session serializes its own merges).ACQUIRED(exit 0): integrate (next bullet), run the per-lane clean-merge check, thenbash ${CLAUDE_PLUGIN_ROOT}/scripts/merge-lock.sh release. Release before surfacing any conflict decision; never sit on the lock while waiting on the user.WAITING holder=<branch> age=<s>(exit 3): an external holder, still fresh. Poll autonomously by re-invokingacquire(its internal 540s wait budget returns under the 600s Bash tool cap). No user prompt.STALE holder=<branch> age=<s>(exit 2): held past the threshold. Quiesce per Quiesce-on-block (no new dispatch, in-flight lanes finish and land, landed checkboxes flushed perskills/_shared/progress-checkpoint.md), then surface the Stale merge lock row of the driftAskUserQuestiontable. Readholder.jsoninside<git-common-dir>/worktree-merge.lock/and put the holder branch, holder worktree path, and age in the question text: the holder may be a live/c-worktreemerge in another session. Never auto-steal.
- Merge-on-land: when a lane's implementer returns DONE and both reviewers approve the cumulative lane diff, the PM integrates per
worktree.integrate(for one release, fall back to the legacyexecute.integratewhen the new key is absent) — defaultrebase-ff(rebase the lane branch onto the current working tip and fast-forward; linear history, per-task commits preserved), ormerge-commit(--no-ffper lane) for repos that forbid history rewriting. - Per-lane clean-merge check (mandatory): the rebase must report no conflict, the lane commits must be present, and there must be no conflict residue. A conflict here means a
Touches:declaration was wrong — STOP and surface; never auto-resolve (release the lock first). - Remove the worktree + lane branch on land. Preserve it on block.
Resume protocol
- Status
in-progress= resumable./c-execute <plan-path>on anin-progressplan resumes; does not restart. - All tasks ticked: go straight to the completion gate (audit, then the end-of-run walk), so
pendingReview decisions rows left by Stop here or a lost session are picked up where they were. - On resume, rebuild the DAG from
Depends:edges, rungit worktree pruneand remove any leftovercadence/lane-*worktrees and branches (perskills/_shared/worktree-lifecycle.md), compute the ready set from unchecked tasks, and continue scheduling. - The lane is the resume unit. A lane whose checkboxes were not all flipped to
- [x]is considered incomplete and re-runs from scratch; any orphaned worktree work is discarded by the prune step. - The PM does NOT trust in-memory state across sessions. The plan's checkbox state is the only source of truth — read it on resume via
skills/_shared/storage-resolution.md(read_artifact) (the on-disk phase file on the filesystem backend, the to-do block state on the notion backend), cross-check unticked lanes against git history, and re-tick any whose commits already landed. - Dirty tree handling on resume:
- Dirty with ONLY plan-file edits (checkbox flips on the plan being resumed) → expected mid-execution state; continue.
- Dirty with any other files → surface and ask user to commit/stash/abort. Never silently resume on a dirty tree that contains code changes.
Sub-agent dispatch
Use the Task tool with one of these named agents:
| Agent | When | What PM passes |
cadence-implementer | Per task | Task block + linked files extracted from task's Reads: block + Touches: list + CLAUDE.md excerpt + resolved-config slice (from the resolver's JSON output; see skills/_shared/config-resolution.md) + plan style + Global Constraints |
cadence-spec-reviewer | After implementer DONE | Task spec + diff + plan style + Global Constraints + the Review Focus entries pinned in this lane's tasks + the implementer's Tests: evidence |
cadence-code-reviewer | After implementer DONE, concurrently with spec review (legacy sequential path: after spec-review ✓) | Diff + repo conventions + Global Constraints |
Sub-agents are generic — they don't know any specific repo. PM passes only what they need.
Global Constraints go to the code reviewer so it doesn't flag a constraint-mandated choice as a style problem; checking the diff against them is the spec reviewer's job.
Required report format (PM enforces; sub-agents return this natively)
Every sub-agent return leads with one plain-English sentence stating what's done/broken and why it matters, before any file:line citations:
<one-sentence plain-English summary>
<optional severity tag: Critical / Important / Minor>
Evidence:
- `<file>:<line>` — <finding>. Fix: <direction>.A return without a plain-English lead is malformed — re-dispatch the sub-agent with a reminder.
Reviewer returns may end with a Declined to judge: section (agents/cadence-spec-reviewer.md, agents/cadence-code-reviewer.md); an Approve that carries one is still an Approve. Collect its entries for the Review decisions table.
Implementer returns that ran any step command also carry a Tests: block right after the plain-English lead: for each run step in the task, the command and the decisive output lines quoted from the real run (the RED failure and the GREEN pass; for a plan.tdd: false task, each run step's output). A missing or paraphrased Tests: block is malformed the same way: re-dispatch with a reminder. Pass the block to the spec reviewer, which checks it against each step's Expected line instead of re-running the suite.
Implementer status handling
| Status | PM response |
| DONE | Proceed to spec review. |
| DONE_WITH_CONCERNS | Read concerns. If correctness/scope, fix before review. If observational, note and proceed. |
| NEEDS_CONTEXT | Route per scope (see below). |
| BLOCKED | Assess: context problem → more context + re-dispatch; reasoning problem → escalate model; task too large → split; plan wrong (the implementer labels it plan ambiguity) → route to the Plan ambiguity row of the drift table. Never retry with same model + same context. |
NEEDS_CONTEXT escalation routing
| Request scope | PM action |
| Narrow — one or two specific files | Fetch named files; re-dispatch implementer. |
| Adjacent — directory or "all callers of X" | grep for references (typically 3-8 files); fetch; re-dispatch. |
| Broad — "whole module" or "all callers across codebase" | STOP. Surface to user. Usually indicates plan defect. User picks: edit the task's Reads: list + retry, split task, or escalate to more capable model. Never auto-fetch the whole repo. |
Review loops (two-stage, run in parallel)
When a lane's implementer returns DONE, dispatch both reviewers concurrently against the cumulative lane diff:
cadence-spec-reviewer— does the diff match the task specs? Anything missing/extra?cadence-code-reviewer— does it match repo conventions (naming, errors, tests)?
They run at the same time (no ordering barrier). Resolve the two reports:
- Both approve → lane lands.
- Spec finds gaps → implementer fixes in the same worktree → both re-run.
- Code finds issues (spec approved) → implementer fixes → both re-run.
- Conflict: the spec decides the run, the user decides the conflict. A code finding that contradicts a spec approval is not a gap: move it to the run's Declined list (see Review decisions below), never drop it. Code review never overturns spec during the run.
- Declined items from either reviewer's
Declined to judge:section are recorded aspendingrows in the plan's Review decisions table when the lane lands. They never block a lane from landing and never trigger a fix round.
Marking task complete (mandatory — required for resume)
The unit of completion is the lane, not the individual task. After a lane lands (spec ✓ + code ✓ + clean-merge ✓ + Invariant 3 grep clean for the full lane diff), the PM must edit the plan's phase file:
- For each
### Task N.Min the just-landed lane, tick every- [ ]step perskills/_shared/storage-resolution.md(tick). All of the lane's task checkboxes tick together on land. - On the filesystem backend a tick rewrites
- [ ]to- [x]in the phase file (held uncommitted); on the notion backend it checks the to-do block live. Do NOT commit the plan-file edit per task or per lane (filesystem backend only; the notion backend has no plan file).
This is the ONLY mechanism for tracking progress across sessions. Without it the resume protocol fails — re-invocation starts over from Task 1.1, and the completion-time gate (which checks for - [x]) will never let the plan flip to implemented.
Checkpoint before yielding. Per skills/_shared/progress-checkpoint.md: flip a landed lane's checkboxes to disk the moment it lands, and never carry a landed-but-unmarked lane through a pause. Before surfacing any AskUserQuestion (drift, block, clarification), every already-landed lane's - [x] must be on disk first. The dirty working file is the durable record; a context loss mid-run rebuilds progress from it alone.
In-flight parallel lanes: edit checkboxes as each lane lands, not in a batch. Two lanes landing simultaneously = two separate plan-file edits. This bounds context — if the PM session dies mid-batch, the landed work is already recorded in the working tree.
Plan-file commit timing: all plan-file edits (every checkbox flip plus the eventual status flip from in-progress to implemented) commit in ONE commit at the end of execution, after the audit gate passes. The dirty plan file IS the in-flight session state during execution. Do not commit plan-file edits per task — it doubles the commit count and adds no information the working tree doesn't already carry.
Invariant 3 enforcement (no deferred code comments)
Before marking any task complete, grep the task's diff:
grep -Ei "TODO|FIXME|XXX|// will|// later|# stub" <diff-range>- If pre-existing comment untouched by this task → note and proceed.
- If new deferral → STOP:
- Ask user to confirm.
- Add entry to plan-side
99-out-of-scope.mdwith rationale + wikilink to task. - Re-dispatch implementer to either remove comment or replace it with one pointing at the OOS entry (e.g.
// deferred — see plan/99-out-of-scope#N). - Only then mark task complete.
Commits
- Code commits — cadence: per task. Configurable via
config.plan.commit_cadence. Driven by the implementer's final step. - Plan-file commit — filesystem backend only, once at end of execution. On the filesystem backend the status flip from
in-progresstoimplemented+ every accumulated checkbox flip lands in one commit (default message:chore: mark plan implemented); do NOT commit plan-file edits per task. On the notion backend everyset_statusandtickalready wrote live through storage-resolution, so there is no plan file and this commit is skipped. - No
--amendunless user explicitly asks. - No
--no-verify, no--no-gpg-signunless user explicitly asks. - Hook failures → fix root cause → new commit (NOT amend).
Drift handling
Quiesce-on-block
When a lane returns BLOCKED, hits unresolvable drift, or surfaces a review gap needing user input, enter quiesce: set a no-new-dispatch flag, let all in-flight lanes finish and land normally, flush every landed lane's checkboxes to disk (skills/_shared/progress-checkpoint.md), preserve the blocking lane's worktree (its dependents stay unscheduled), then surface the blocker via the drift AskUserQuestion from a clean, fully-merged tree. Never halt in-flight lanes mid-work; never keep dispatching new lanes while a decision is pending.
Interaction with partial readiness (follow-up lanes). Under the lane = phase file rule, a phase file can have ready tasks the PM has not yet dispatched (waiting for a free slot or for a Touches: conflict to clear) at the moment one of its earlier lanes blocks. Quiesce treats those tasks as part of the no-new-dispatch freeze: the in-flight subset of the blocking phase file completes whatever was already dispatched, lands or remains preserved on the worktree, and no follow-up lane from that phase file (or any other phase file) opens during quiesce. Concretely: if L₁ = {1.1, 1.2, 1.3, 1.5} from 01-foo.md is the blocking lane and 1.4 was waiting in the ready set for a cross-file Depends: to clear, 1.4 stays unscheduled along with everything else awaiting the quiesce decision — the PM is not forming new lanes during quiesce regardless of which file they would come from. The user's decision (fix / mark out of scope / abort) is read from the clean post-quiesce tree.
All drift response paths are presented via AskUserQuestion (TUI multi-choice), not a prose "type one of:" prompt.
Hard gate — every
AskUserQuestion, no exceptions: (1) thequestionopens with a plain-English lead a newcomer could follow — what's being decided and why it matters now (the user may have been heads-down on the task for hours and lost the bigger plan context); (2) exactly one option is marked(Recommended)and listed first — triage / "which next?" menus included ("your call" is a non-answer); (3) each option'sdescriptiongives the one-sentence trade-off. Full spec:skills/_shared/ask-user-question.md.
Each option's description is the corresponding "What happens next" cell (one sentence). The recommended pick depends on the trigger:
- Plan ambiguity → "Clarify" is
(Recommended). - Design contradiction → "Update plan only" is
(Recommended)(matches the default drift policy). - Scope overflow → "Fix (expand task in place)" is
(Recommended)when overflow is small; "Mark out of scope" when significant. - Stale merge lock → "Wait" is
(Recommended)(the holder may be a live merge in another session; steal only after the user verifies the holder is dead).
| Trigger | User's choice | What happens next |
| Plan ambiguity — implementer can't execute as written | Clarify | User answers → PM edits plan inline → re-dispatches with clarified task. |
| Abort | Status stays in-progress. User resumes later. | |
| Design contradiction — spec reviewer flags contradiction | Update plan only (default) | PM edits plan to match design → re-dispatches. Design untouched. |
| Update plan + design | PM offers both edits; user reviews. Both docs internally consistent before re-dispatch. | |
| Abort | Plan stays in-progress. | |
| Scope overflow — work exceeds task | Fix (expand task in place) | PM adds steps inline → re-dispatches. |
| Split into new task | PM appends new task to same phase file with Depends: [<current>]. Current task marked complete. | |
| Mark out of scope | PM writes entry to plan-side 99-out-of-scope.md with rationale + wikilink. Current task marked complete. | |
| Abort | Plan stays in-progress. | |
Stale merge lock — merge-on-land found the shared lock held past worktree.lock_stale_threshold (prompt shows holder branch, holder worktree path, and age from holder.json) | Wait | PM re-invokes acquire and keeps polling; integration proceeds when the holder releases. |
| Steal | PM runs ${CLAUDE_PLUGIN_ROOT}/scripts/merge-lock.sh steal --target <working-branch>, then integrates and releases. Safe only when the holder is verified dead. | |
| Abort | Plan stays in-progress; landed lanes' checkboxes are already flushed to disk; resume later. |
Review decisions (the end-of-run list)
Items the user decides at the end of the run, never mid-way: reviewer Declined to judge: entries, code findings that contradict a spec approval, inline self-review's declined cases and convention conflicts, and the completion audit's For your decision items (the branch review's Important and Minor findings and its own declined items). Lane gaps are not list items (they are fixed in the lane loop), and neither is a Critical branch-review finding (it fails the audit).
The table. The plan overview carries a ## Review decisions section, created the first time an item arrives (a plan with no items has none), holding one table:
| ID | Source | Where | Item | Decision |
| R1 | spec reviewer | Task 1.3, app/auth.py:42 | An API key sent with trailing whitespace is rejected as unknown. Unclear whether keys should be trimmed. | pending |
IDs run R1, R2, and so on in arrival order and never change. Source is spec reviewer, code reviewer, inline self-review, branch review (Important), branch review (Minor), or branch review (Declined). Decision starts pending and ends accepted, fixed (<short sha>), or out of scope. Rows are table cells, not to-do blocks, so the checkbox audit never reads them.
Recording. Write new rows when the lane they came from lands (parallel) or when their task is ticked (inline), and always before yielding control, per skills/_shared/progress-checkpoint.md. Write them by rewriting the overview with write_doc per skills/_shared/storage-resolution.md: on the notion backend scripts/notion-write.js keeps the overview's sub-pages through the rewrite; on the filesystem backend the edit to 00-overview.md stays uncommitted and rides the end-of-execution plan-file commit.
The walk. After the completion audit passes (or passes with warnings only), append its For your decision items as pending rows and flush them. Then, if any row is pending, walk the pending rows with one AskUserQuestion per row, per skills/_shared/ask-user-question.md (lead with what the item is and why it matters; position context such as "Item 3/7, 1 fixed and 1 accepted so far"):
- Accept: the behavior stands; the row becomes
accepted. - Fix: the row stays
pendinguntil its fix commits. - Out of scope: write a plan-side
99-out-of-scopeentry (rationale plus a wikilink to the task); the row becomesout of scope. - Stop here: the walk pauses with the remaining rows
pending; the plan staysin-progress.
Mark exactly one option (Recommended) per row, from the item itself: Fix for wrong behavior on a plausible path, Accept for a defensible judgment call, Out of scope when the right fix is real work beyond the plan. Offer Minor branch-review rows first as one grouped question ("Accept all N Minor items, or walk them one by one?"). Write each decision to the table the moment it is made.
Fixing. After the walk, apply every Fix row yourself in the main checkout, in both modes, following the implementer's rules (root cause first and Tests: evidence, per agents/cadence-implementer.md): one commit per row with message fix(review): R<n> <summary>, then mark the row fixed (<short sha>). List fixes get no lane reviewers; the re-audit's branch review reads them. A fix that turns out to be real work stops and is offered again as Out of scope.
Re-audit. When any row was fixed, re-run the completion audit once, passing the Review decisions table so the branch review skips decided rows; walk only the new items it raises.
The gate. Set implemented only when the audit passes (or passes with warnings only) and no row is pending.
Completion-time gate: dispatch cadence-completion-auditor directly
Once every task in every phase file is complete:
- Verify: every step
- [x]+ both reviews ✓ + commit visible ingit log. - Worktree-cleanup sweep (pre-dispatch): run
git worktree listand confirm nocadence/lane-*worktrees remain; rungit branch --list 'cadence/lane-*'and confirm no lane branches remain. If any do, remove them (git worktree remove <path>, thengit branch -d <branch>) before dispatching the auditor. Never pass--forceor-Dhere: a leftover lane that still holds work is a plan-execution defect, and deleting that work silently hides it. Ifgit worktree removerefuses, show the usergit -C <path> status --porcelain -uall; ifgit branch -drefuses, showgit log --oneline HEAD..<branch>. Ask whether to keep, commit, or discard that work before retrying. - Dispatch the
cadence-completion-auditoragent directly (via theTasktool) — same agent the standalone/c-auditskill dispatches, same parameters: plan path, linked design folder (fromlinked_design:frontmatter), resolved config content (the resolver's JSON output; seeskills/_shared/config-resolution.md), diff range (git diff <base_sha>..HEAD), mode:gating, the plan slug (on the notion backend the auditor exports the plan and design withscripts/notion-read.js), and the plan's Review decisions table when it has one (the branch review skips decided rows). The default audit roster includesmerge-integrity(verifies each task's commit landed cleanly and the lane history is linear). Do NOT route through the/c-auditskill — skill-calls-skill is not a documented Claude Code mechanism. The audit logic is in the agent; the skill is a thin user-facing wrapper around the same agent. - Read the agent's report.
| Auditor result | /c-execute response |
| All pass (or warnings only) | Add the report's For your decision items as pending Review decisions rows and run the end-of-run walk (see Review decisions above); once no row is pending, set overview status to implemented per skills/_shared/storage-resolution.md (set_status), which bumps updated:, print: "Plan implemented. Deploy your changes, then run /c-validate <path>. If you want to re-run the audit later for spot-checks, use /c-audit <plan-path> standalone." Then, per skills/_shared/browser-validation.md, append one informational line only if the just-implemented plan's 96-validation.md has at least one Category B item with an e2e: reference AND no runner is configured or detected (validate.browser_command at default npx playwright test and auto detection finds no suite): recommend installing/configuring a runner (Playwright by default), else those steps fall back to manual. Once per run; a repo with a runner configured/detected prints nothing. |
| Any blocking failure | Leave status at in-progress. Surface failing audits (a Critical branch-review finding is a blocking failure like any other). User picks fix / mark out of scope / abort. |
What /c-execute doesn't do
- Doesn't deploy.
- Doesn't run
/c-validate. - Doesn't touch the design (except surfacing drift for user resolution).
- Doesn't continue past audit failure silently.
- Doesn't aggregate commits, amend, or skip hooks.
- Doesn't read the whole repo on every sub-agent dispatch.
- Doesn't house audit logic — that lives in the
cadence-completion-auditoragent./c-executedispatches that agent at completion; the/c-auditskill dispatches the same agent for standalone user invocation. Single source of truth = the agent.
References
- Companion agents:
cadence-implementer,cadence-spec-reviewer,cadence-code-reviewer,cadence-completion-auditor. - Standalone audit skill:
/c-audit(a thin user-facing wrapper aroundcadence-completion-auditor).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

