agentleFS
sentasitysentasity/cadence/skills/c-execute/SKILL.md

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.

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
  1. Distinctive:

    Before scheduling, detect the plan format per-plan:

    line 18
  2. Distinctive:

    No worktree machinery: no lane branches, no git worktree add, no merge-on-land, and no merge-lock acquisition (commits land directly on the …

    line 107
  3. Very specific:

    Use the Task tool with one of these named agents:

    line 138
  4. Distinctive:

    Every sub-agent return leads with one plain-English sentence stating what's done/broken and why it matters, before any file:line citations:

    line 152
  5. Distinctive:

    When a lane's implementer returns DONE, dispatch both reviewers concurrently against the cumulative lane diff:

    line 188
  6. Distinctive:

    Before marking any task complete, grep the task's diff:

    line 218
  7. Distinctive:

    If pre-existing comment untouched by this task → note and proceed.

    line 224
  8. Distinctive:

    If new deferral → STOP:

    line 225
  9. Distinctive:

    Ask user to confirm.

    line 226
  10. Very specific:

    Add entry to plan-side 99-out-of-scope.md with rationale + wikilink to task.

    line 227
  11. Distinctive:

    Only then mark task complete.

    line 229
  12. Very specific:

    Out of scope: write a plan-side 99-out-of-scope entry (rationale plus a wikilink to the task).

    line 290
  13. Distinctive:

    Re-audit: When any row was fixed, re-run the completion audit once, passing the Review decisions table so the branch review skips decided …

    line 297
  14. Very specific:

    Verify: every step - [x] + both reviews ✓ + commit visible in git log.

    line 305
  15. Distinctive:

    Read the agent's report.

    line 308

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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 selects inline.
  • Legacy format (tasks carry Files:/Parallel:, no Touches:) → 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-plan to 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 over execute.mode; the execution-mode gate is skipped.

Pre-flight checks (in order; any failure surfaces — no auto-resolution)

  1. Resolve config by running node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.js" and use its JSON config for every execute.* and worktree.* read this run; follow the notice/gitignore/hard-stop contract in skills/_shared/config-resolution.md; never read config files directly.
  2. Path resolves to a plan folder with 00-overview.md.
  3. Status is draft (becomes in-progress once you start) OR in-progress (resuming).
  4. Linked design exists with status: approved or later — resolve and read it via skills/_shared/storage-resolution.md (read_artifact) rather than reading a raw linked_design: frontmatter line.
  5. Plan style is valid: the plan overview's **Plan style:** line is absent (meaning full-code) or reads full-code or decisions. Any other value is a malformed plan: stop and surface it here, before the execution-mode gate and before any status or base_sha write.
  6. Working tree is clean (no unstaged or uncommitted changes).
  7. Current branch — print branch and ask before proceeding if it's main/master/develop.
  8. Execution-mode gate (new-format plans only). Resolve execute.mode:
    • parallel — run the lane engine. Keep today's worktree confirmation: unless execute.worktree_confirm: false, print the worktree plan and ask once via AskUserQuestion: "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 via AskUserQuestion (this mode question subsumes the worktree confirmation; execute.worktree_confirm: false does 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-execute when ready. Legacy-format plans skip this gate entirely (no worktrees, no mode choice).

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

  1. 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 means full-code; pre-flight check 5 already rejected any other value), the ## Global Constraints section, and the ## Review Focus section (both absent on plans written before they existed; then pass nothing). Never read plan.style from config during execution.
  2. Build an internal task list — every ### Task N.M becomes a tracked item with its Depends: edges, Reads: block, Touches: list, and full step block extracted.
  3. Build the dependency DAG from each task's Depends: edges and form lanes per the scheduling loop in "Lane model and DAG scheduling".
  4. Dispatch lanes concurrently up to execute.max_parallel, respecting Touches: disjointness.
  5. After each task lands (spec ✓ + code ✓ + Invariant 3 clean), record the lane's progress by ticking every - [ ] step under ### Task N.M per skills/_shared/storage-resolution.md (tick). See Marking task complete.
  6. Surface blockers to user — never work around silently.
  7. Run audit gate at the end, then the end-of-run walk over the Review decisions table; set status to implemented per skills/_shared/storage-resolution.md (set_status) only when the audit passes and no row is pending. 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 one cadence-implementer in one worktree, committing per-task internally. Lane boundaries are author-visible (the 0X-*.md filename); they are NOT a runtime-derived chain.
  • Lane formation (per phase file): for every phase file F with at least one ready task, compute eligible(F) = tasks of F whose cross-file Depends: are merged AND whose Touches: are disjoint from every in-flight lane. If eligible(F) is non-empty, dispatch it as one lane. Internal Depends: (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. Internal Depends: 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) = ∅. A Touches: 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_parallel lanes (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 or Touches: 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's Tests: 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 a pending Review decisions row with source inline self-review when 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 AskUserQuestion table 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-auditor dispatch 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 add from the current working tip).
  • Acquire the merge lock before integrating (gated by worktree.merge_lock, default true): when a lane is ready to land, run bash ${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-worktree merge or hand merge in another session serializes with lane landings regardless of target branch. With worktree.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, then bash ${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-invoking acquire (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 per skills/_shared/progress-checkpoint.md), then surface the Stale merge lock row of the drift AskUserQuestion table. Read holder.json inside <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-worktree merge 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 legacy execute.integrate when the new key is absent) — default rebase-ff (rebase the lane branch onto the current working tip and fast-forward; linear history, per-task commits preserved), or merge-commit (--no-ff per 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 an in-progress plan resumes; does not restart.
  • All tasks ticked: go straight to the completion gate (audit, then the end-of-run walk), so pending Review decisions rows left by Stop here or a lost session are picked up where they were.
  • On resume, rebuild the DAG from Depends: edges, run git worktree prune and remove any leftover cadence/lane-* worktrees and branches (per skills/_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:

AgentWhenWhat PM passes
cadence-implementerPer taskTask 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-reviewerAfter implementer DONETask spec + diff + plan style + Global Constraints + the Review Focus entries pinned in this lane's tasks + the implementer's Tests: evidence
cadence-code-reviewerAfter 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

StatusPM response
DONEProceed to spec review.
DONE_WITH_CONCERNSRead concerns. If correctness/scope, fix before review. If observational, note and proceed.
NEEDS_CONTEXTRoute per scope (see below).
BLOCKEDAssess: 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 scopePM action
Narrow — one or two specific filesFetch 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:

  1. cadence-spec-reviewer — does the diff match the task specs? Anything missing/extra?
  2. 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 as pending rows 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:

  1. For each ### Task N.M in the just-landed lane, tick every - [ ] step per skills/_shared/storage-resolution.md (tick). All of the lane's task checkboxes tick together on land.
  2. 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:
    1. Ask user to confirm.
    2. Add entry to plan-side 99-out-of-scope.md with rationale + wikilink to task.
    3. 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).
    4. 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-progress to implemented + 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 every set_status and tick already wrote live through storage-resolution, so there is no plan file and this commit is skipped.
  • No --amend unless user explicitly asks.
  • No --no-verify, no --no-gpg-sign unless 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) the question opens 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's description gives 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).
TriggerUser's choiceWhat happens next
Plan ambiguity — implementer can't execute as writtenClarifyUser answers → PM edits plan inline → re-dispatches with clarified task.
AbortStatus stays in-progress. User resumes later.
Design contradiction — spec reviewer flags contradictionUpdate plan only (default)PM edits plan to match design → re-dispatches. Design untouched.
Update plan + designPM offers both edits; user reviews. Both docs internally consistent before re-dispatch.
AbortPlan stays in-progress.
Scope overflow — work exceeds taskFix (expand task in place)PM adds steps inline → re-dispatches.
Split into new taskPM appends new task to same phase file with Depends: [<current>]. Current task marked complete.
Mark out of scopePM writes entry to plan-side 99-out-of-scope.md with rationale + wikilink. Current task marked complete.
AbortPlan 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)WaitPM re-invokes acquire and keeps polling; integration proceeds when the holder releases.
StealPM runs ${CLAUDE_PLUGIN_ROOT}/scripts/merge-lock.sh steal --target <working-branch>, then integrates and releases. Safe only when the holder is verified dead.
AbortPlan 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:

IDSourceWhereItemDecision
R1spec reviewerTask 1.3, app/auth.py:42An 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 pending until its fix commits.
  • Out of scope: write a plan-side 99-out-of-scope entry (rationale plus a wikilink to the task); the row becomes out of scope.
  • Stop here: the walk pauses with the remaining rows pending; the plan stays in-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:

  1. Verify: every step - [x] + both reviews ✓ + commit visible in git log.
  2. Worktree-cleanup sweep (pre-dispatch): run git worktree list and confirm no cadence/lane-* worktrees remain; run git branch --list 'cadence/lane-*' and confirm no lane branches remain. If any do, remove them (git worktree remove <path>, then git branch -d <branch>) before dispatching the auditor. Never pass --force or -D here: a leftover lane that still holds work is a plan-execution defect, and deleting that work silently hides it. If git worktree remove refuses, show the user git -C <path> status --porcelain -uall; if git branch -d refuses, show git log --oneline HEAD..<branch>. Ask whether to keep, commit, or discard that work before retrying.
  3. Dispatch the cadence-completion-auditor agent directly (via the Task tool) — same agent the standalone /c-audit skill dispatches, same parameters: plan path, linked design folder (from linked_design: frontmatter), resolved config content (the resolver's JSON output; see skills/_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 with scripts/notion-read.js), and the plan's Review decisions table when it has one (the branch review skips decided rows). The default audit roster includes merge-integrity (verifies each task's commit landed cleanly and the lane history is linear). Do NOT route through the /c-audit skill — 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.
  4. 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 failureLeave 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-auditor agent. /c-execute dispatches that agent at completion; the /c-audit skill 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 around cadence-completion-auditor).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.