c-plan
Skill1 starsChanged 3 months agoMITView on GitHub
Use when a Cadence design is approved and the user wants the implementation plan written from it.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs-siteSkill
- c-auditSkill
- c-brainstormSkill
- c-checkSkill
- c-designSkill
- c-executeSkill
- c-explainSkill
- c-find-bugsSkill
- c-validateSkill
- c-worktreeSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 132
Every run-command step shows the exact command and expected output/status.
- Very specific: line 133
Every task ends with a commit step (cadence: per task).
- Very specific: line 195
Every plan, whatever its style, carries a ## Global Constraints section in the overview: the rules that bind every task, one per line, with …
- Distinctive: line 213
Pinning: add a check for each entry to the task that owns the code, in that task's own step style:
- Very specific: line 252
Every entry gets - [ ]. /c-validate checks them off as it walks.
- Very specific: line 267
Create the plan artifact first via skills/_shared/storage-resolution.md (create_artifact), writing the 00-overview (frontmatter + Plan …
- Distinctive: line 270
Invariant 2 in reverse: If a phase reveals a gap or inconsistency in the design, surface it.
- Very specific: line 280
Write 00-overview.md first (frontmatter + Plan style line + Global Constraints + phase index + File Map — generators need them).
≈ “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-plan
You translate an approved design into an execution-ordered plan folder. Plans are written for AI, not humans — terse, exact, no padding.
Entry contract
Requires: the design artifact for {yyyy-mm-dd-slug} with status: approved. Read the entire design (overview + every child + 99-OOS) via skills/_shared/storage-resolution.md (read_artifact) before drafting; do not assume a <paths.designs>/… folder path. When the design carries a 95-visual-contract slot, the read includes it, and the planner also fetches the frozen mockup via skills/_shared/storage-resolution.md (read_mockup).
Refuses when: design status is draft or in-review (tell user to finish/approve the design first); or when the design's 95-visual-contract freeze record still reads frozen: none (malformed approved design; point the user back to /c-design's approval step); or when a plan artifact with the same slug already exists at non-draft status — check via skills/_shared/storage-resolution.md (artifact_exists) — which would overwrite.
One design → one plan
A design always becomes exactly one plan folder. Work that would once have been separate plans becomes phase docs (01-<phase>.md, 02-<phase>.md, …) inside that one plan. There is no split question and no linked_plans: array. After reading the design, confirm the phase decomposition with the user (writing-flow step 2); do not ask about splitting into multiple plans.
Size is handled by phase decomposition, not by spawning sibling plans — /c-execute's DAG engine already parallelizes across phase docs.
Phase file sizing — fewer, coherent files
Each phase file becomes the unit of worktree dispatch and the unit of per-lane review under /c-execute's lane = phase file rule (skills/c-execute/SKILL.md, Lane model and DAG scheduling). Consolidate related work into fewer, larger phase files:
- One substantive topic per file. A topic is a coherent slice the reviewer can hold in their head — closely-related codebase slice (one skill, one service, one feature surface), shared
Reads:core across tasks, a one-sentence reviewer headline with no "and also" clauses, and an internal DAG shape (chain, fan-out, fan-in — not fully disconnected). - Target 5–10+ tasks per file. Below 5 is too thin to amortize worktree spin-up + per-lane review. 10+ is fine as long as topical coherence holds. The 5–10+ figure is a target, not a threshold — a genuinely 3-task plan still ships as a 3-task phase file.
- Task size inside a phase file is unchanged. The per-task contract (
Reads:/Touches:/Depends:/Steps, every step one action, step content per the plan's style) is unchanged. Consolidation is at the file level, not the task level.
Doc size is not a storage concern on any backend. The notion backend writes a doc of any size in one script call (skills/_shared/storage-resolution.md, "Content write path"), so topical coherence and the 5–10+ task target alone decide the file boundaries; never split a coherent lane on size.
Worked example (positive exemplar). docs/plans/2026-05-26-c-validate-browser-automation/01-browser-validation.md is the canonical good shape: 5 tasks (1.1 config keys → 1.2 shared spec → {1.3, 1.4, 1.5} per-skill integration), one substantive topic (browser validation), shared Reads: core across all five (the 2026-05-26-c-validate-browser-automation design docs), classic setup-then-fan-out DAG. Under the new rule this file is one warm lane.
Three anti-patterns to detect. Each is a way the new stance can fail in the wild. Flag candidates to the user via AskUserQuestion; never auto-merge or auto-split silently.
- Mixed-topic file. One phase file whose tasks span more than one coherent topic. Symptoms: tasks touch unrelated codebase slices; pairwise
Reads:overlap is zero; the reviewer's one-sentence headline requires "and" to cover the file's diff; the file's name is generic ("foundation", "miscellaneous setup"). Correct response: split at the topic boundary. Do not pad the title to umbrella both topics; do not manufactureDepends:between unrelated tasks to fake cohesion. - Sprawling monolith. One phase file with 20+ tasks where coherence is loose — several distinct sub-topics are visible inside (e.g. "Refactor the auth service" covering schema migration, middleware rewrite, and provider-integration tests). The internal DAG often shows near-disconnected subgraphs. Correct response: split at the strongest internal topic boundary — usually the one that produces the cleanest combined diff per resulting file.
- Fragmented file. A phase file with 1–2 tasks where related tasks live in sibling phase files that share its topic. Symptoms:
Reads:overlaps heavily with a sibling's (>50% by either side's union); the headlines are near-duplicates; a reviewer would pull up both files together; the internal DAG is trivially short. Correct response: consolidate — merge into the sibling, or merge several fragments into one new file. This is the most common failure mode the new stance directly targets. A "setup-only" phase file (one or two tasks whose only purpose is to scaffold for the next file) is a subtler form of this anti-pattern: the setup belongs in the consuming file as the foundation tasks of its internal DAG.
Bidirectional linkage
- Establish the design↔plan link with a single call to
skills/_shared/storage-resolution.md(link): it is bidirectional and idempotent, settinglinked_designon the plan andlinked_plan(singular) on the design in one step and bumping the design'supdated:. Do not write the twolinked_*frontmatter keys by hand. - The design flips to
completedonly when itslinked_planreaches statuscompleted:/c-validateflips both in one step on a full validation pass.
Plan style
plan.style (resolved config) picks what a plan's steps contain:
full-code(default): every code step shows the full code. "Task structure" and "Plan content rules" below describe this style.decisions: steps record the decisions the implementer can't make alone and leave the code to them. See "Decision plans" below.ask: ask once per plan viaAskUserQuestion, in writing-flow step 3 alongside the generation-mode question, withfull-codemarked(Recommended)(the shipped default).
Every new plan records its style in the overview as a **Plan style:** full-code or **Plan style:** decisions line directly after the Tech Stack line. That line, not config, is the plan's style for its whole life: /c-execute and its agents read it from the plan, so changing plan.style later never changes the rules under a plan already written. A plan with no style line (written before the line existed) is full-code.
The companion sections, "Global Constraints" and "Review Focus" below, apply to every plan whatever its style; plan.style gates only step content and the per-task Interfaces block.
Folder layout
<paths.plans>/
{yyyy-mm-dd-slug}/
00-overview.md
01-<phase>.md, 02-… # execution order
96-validation.md # the three-category doc
97-infrastructure-inventory.md # SHELL — wikilink to design's 97
98-architecture-diagrams.md # SHELL — wikilink to design's 98
99-out-of-scope.md00-overview.md required sections (in this order)
- Frontmatter per
skills/_shared/frontmatter.md. - Agentic worker header:
> For agentic workers: REQUIRED SUB-SKILL: Use /c-execute … - Goal — one sentence.
- Architecture — 2-3 sentences linking back to the design.
- Tech Stack — one line.
- Plan style —
**Plan style:** full-codeor**Plan style:** decisions, directly after Tech Stack (see "Plan style"). - Design link —
[[../../designs/{slug}/00-overview]]. - Global Constraints — a
## Global Constraintssection, every plan (see "Global Constraints"). - Review Focus — a
## Review Focussection, every plan (see "Review Focus"). - Plan Index — one line per child:
[[01-foo]] — Tasks 1.1-1.M: <summary>. - File Map — every file the plan creates or modifies, one line per file, with the change summary.
- Surface map — only when the linked design has a
95-visual-contractslot: one line per surface declared in 95's Surfaces section,<surface name>: <file list>, mapping the surface to the concrete files that implement it, ground-truthed per "Codebase verification". Recording the mapping is what makes the visualReads:attachment below machine-checkable.
No "Background," "Why," or plain-English. Those live in the design.
Task structure (every task, every phase doc)
This is the full-code shape. Decision plans keep the same fields and step sequence, add an **Interfaces:** field, and change what each step contains (see "Decision plans").
### Task N.M: <Name>
**Reads:** [`exact/path/context`] <!-- context files, read not written -->
**Touches:** [`exact/path/written`] <!-- every file this task writes (incl. created files + tests) -->
**Depends:** [N.K] <!-- task ids that must merge first; [] if independent -->
- [ ] **Step 1: Write failing test**
```python
def test_specific_behavior():
...
```
- [ ] **Step 2: Run test, expect FAIL**
`pytest tests/exact/path.py::test_specific_behavior -v`
Expected: FAIL — `<exact message>`
- [ ] **Step 3: Implement**
```python
def function(...):
...
```
- [ ] **Step 4: Run test, expect PASS**
`pytest tests/exact/path.py::test_specific_behavior -v`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add tests/exact/path.py src/exact/path.py
git commit -m "feat: <message>"
```Plan content rules
These rules apply to every plan, except the three marked (full-code), which decision plans replace (see "Decision plans").
- (full-code) Every step is one action (2-5 minutes of work).
- (full-code) Every code step shows the FULL code — no
// implement hereplaceholders. - (full-code) No cross-references like "similar to Task N" — repeat code inline.
- Every run-command step shows the exact command and expected output/status.
- Every task ends with a commit step (cadence: per task).
- Banned phrases:
TBD,TODO,add error handling,fill in details,handle edge cases,write tests for the above. Plan failures; block self-review. Reads:/Touches:/Depends:required on every task.Touches:must name every file the task writes (the/c-executeco-scheduling guard depends on it).Depends:lists task ids that must merge first ([]= independent). The former per-task concurrency marker is superseded by these three fields.
TDD default; opt-out in config. config.plan.tdd: true → test → fail → impl → pass → commit. false → impl → run → commit (test steps omitted).
Decision plans
When the plan's style is decisions, the plan records the decisions the implementer cannot make alone and leaves the code to them. Write for an engineer who has not seen this codebase or this design, who writes idiomatic code in the project's language once they know the exact interface and the exact test, and who makes a reasonable choice wherever the plan leaves one open. What they cannot know is what was decided: which files, which names and signatures, which values from the design, which tests prove each task. Document those.
A step is done when the implementer can write exactly one reasonable thing from it. Unambiguous, not complete. Each kind of step carries what makes it unambiguous and nothing more:
| Step kind | Carries |
| Test step | The test's name and its assertions, as code, with the design's exact values in them. |
| Code step | The exact signature (name, parameters, return type), the file it lives in, and the values the design pins. A body only for an algorithm the signature and tests don't determine, or for exact copy the design fixes. One line on the approach when the signature and tests leave a real choice. |
| Verification step | The command and the output that means it passed (for the RED run, the expected failure). |
| Reference to another task | Through that task's Interfaces block. Never repeat another task's code. |
| Commit step | The files and the message. |
A plan longer than the code it describes has written the code instead. Lines that decide nothing (the banned phrases above, a type or function no task defines) are the opposite failure; self-review catches both.
Step sizing: one action with a checkable result (write the failing test; run it; implement the signature; run the tests; commit), not minutes.
Interfaces block (required in decision plans, omitted in full-code plans). Every task carries **Interfaces:** directly after **Depends:**, with two lines:
Consumes:the exact signatures this task uses from other tasks, each tagged with the producing task id, ornone.Produces:the exact signatures later tasks rely on, ornone.
An implementer sees only its own task block and its Reads: files, so this block is the only place shared names travel. Every Consumes: entry must be produced by a task in the consumer's Depends: closure or already exist in the codebase (ground-truthed per "Codebase verification").
Task shape:
### Task 2.3: Parse retry budget from config
**Reads:** [`src/config/loader.py`, `tests/config/test_loader.py`]
**Touches:** [`src/config/retry.py`, `tests/config/test_retry.py`]
**Depends:** [2.1]
**Interfaces:**
- Consumes: `load_section(name: str) -> dict` (Task 2.1)
- Produces: `retry_budget(cfg: dict) -> RetryBudget` where `RetryBudget(max_attempts: int, backoff_s: float)`
- [ ] **Step 1: Write failing tests** in `tests/config/test_retry.py`
`test_defaults_when_absent`: `retry_budget({})` == `RetryBudget(3, 0.5)`
`test_rejects_zero_attempts`: `retry_budget({"max_attempts": 0})` raises `ValueError("max_attempts must be >= 1")`
- [ ] **Step 2: Run, expect FAIL**
`pytest tests/config/test_retry.py -v` → Expected: FAIL, `ImportError: cannot import name 'retry_budget'`
- [ ] **Step 3: Implement `retry_budget(cfg: dict) -> RetryBudget` and the `RetryBudget` dataclass in `src/config/retry.py`**
Defaults 3 and 0.5 come from the design's retry section.
- [ ] **Step 4: Run, expect PASS**
`pytest tests/config/test_retry.py -v` → Expected: 2 passed
- [ ] **Step 5: Commit**
`git add src/config/retry.py tests/config/test_retry.py && git commit -m "feat(config): parse retry budget"`Global Constraints
Every plan, whatever its style, carries a ## Global Constraints section in the overview: the rules that bind every task, one per line, with exact values copied verbatim from their source.
What qualifies: language and runtime version floors, platform requirements, dependency limits (no new dependencies, or an allowed set), naming and user-facing copy rules, exact values the design pins globally (limits, timeouts, units), and repo rules from CLAUDE.md that bind code. A rule that binds one task belongs in that task's steps, not here.
Sources: while reading the design (writing-flow step 1), collect candidates from the approved design (every doc, including decisions-log entries that state a global rule), the repo's CLAUDE.md, and the repo's manifests where present (package.json engines, .nvmrc, pyproject.toml requires-python, .python-version, go.mod go directive, Cargo.toml rust-version, and the like), ground-truthed like any other cited path. Each line ends with a short source parenthetical: (design 03), (CLAUDE.md), (package.json engines).
Confirmation: show the list in writing-flow step 2, in the same exchange as the phase-decomposition confirmation, via AskUserQuestion with Looks right (Recommended) and Edit the list. An edit loops once through the list and back.
Placement: ## Global Constraints in the overview, after the header lines and before ## Review Focus. An empty list is written as None. (checked, found nothing; never skipped). Constraints are not repeated inside tasks: /c-execute passes the section to every implementer and both reviewers.
Review Focus
Every plan carries a ## Review Focus section in the overview: up to five input classes or failure modes the design implies but no task's tests exercise, the ones most likely to bite a person using the software first. The design's silence on an input is not permission for that input to break the program.
Selection: after the phase docs are drafted (writing-flow step 5a), walk the design's inputs, states, and boundaries with the design in front of you, list the ones no task's tests exercise, and keep the five most likely to hurt a user. Fewer is fine; an empty section is written as None found. (checked, found nothing).
Line format: - <input or condition> → <behavior a reasonable person would expect> (pinned in Task N.M).
Pinning: add a check for each entry to the task that owns the code, in that task's own step style:
plan.tdd | The pin |
true | A test in the owning task's test step (a new test function, or new assertions in its existing test), with the expected behavior as its assertion, run by the task's RED and GREEN steps. |
false | A run step in the owning task with the exact command that exercises the input and the output that means it behaved. |
/c-execute passes the section to the spec reviewer, which checks that each owning task's diff carries its pin.
Codebase verification (mandatory)
Every file path, line range, symbol, and import a plan cites must be ground-truthed against the current code BEFORE it lands in the plan. Imagined APIs are the single biggest cost in /c-execute — implementers burn ~30-40% of each dispatch rediscovering what the planner could have grepped for once. Pay it here.
What to verify, how:
ModifyandTestfile paths —lsor Read each. If a file doesn't exist, fix the path or move the entry toCreate.- Line ranges (
file.py:120-145) — Read that range. Confirm it contains what the task assumes; stale ranges drift fast. - Symbols in code snippets — function names, class names, methods, attributes, properties. Grep for each. If the design says
cost_query_functionbut the real form isself.api_construct.cost_query_function, cite the real form. - Import paths — every
from X import Yresolves to a real module. GrepXto confirm the module exists; checkYis exported. - Codebase conventions — when introducing an import or pattern, check how the codebase already does it (
lambda_vs_lambda,ColumnvsMapped, etc.). Follow the existing convention.
When in doubt, Read the file. A planner guess is worse than a planner question.
What this isn't: type-checking your snippets. You're not verifying the new code compiles — that's the implementer's job. You're verifying that the names, paths, and imports you hand the implementer correspond to things that already exist.
Defense in depth: /c-audit's code-behind-checkbox audit still runs at completion as a backstop. This upstream verification is primary; the audit catches anything that slipped through.
Visual Reads: attachment (95 designs only)
For every task whose Touches: intersects the Surface map's file set, automatically append two entries to that task's Reads:: the design's 95-visual-contract doc (cited the way design docs are cited on the resolved backend: a <paths.designs>/<slug>/95-visual-contract.md path on the filesystem, the design's "95 Visual Contract" sub-page reference on notion), and the frozen mockup version, cited as mockup:NN against the design slug (the implementer resolves it via read_mockup). No new task field exists; Reads: already carries the read-before-writing contract. Every mockup version is a local file, on every backend, so a machine-local caveat travels with the citation: a lane on another machine reports the missing file as a normal missing-Reads: blocker rather than guessing.
96-validation.md — three explicit categories
Walked by /c-validate only after the plan is implemented and the user has deployed. Three required sections:
- A. Automated — Claude runs each:
curl,psql,pytest, etc. Expected value/shape; broken-if signal. - B. Manual workflow — User clicks; Claude verifies after each step via DB/API. Optional
e2e:reference: when you can identify a Playwright spec (and optional grep/tag) that exercises a Category B flow — drawn from the design and the repo's existingtests/e2e/specs — append an indentede2e: <spec> -g "<grep>"sub-line beneath that item's checkbox so/c-validatecan run it headless (grammar inskills/_shared/browser-validation.md). The cited spec path is subject to the "Codebase verification (mandatory)" rule above — ground-truth it against the repo before it lands, the same as anyTouches:/Reads:path. When no relevant spec exists, write a plain manual step (noe2e:line) — attaching a reference is opportunistic, never mandatory, and never breaks the plain-manual path. - C. Prerequisites — User does before Claude can test (deploy, fixtures, keys). Walk blocks until all C confirmed.
Every entry gets - [ ]. /c-validate checks them off as it walks.
97 / 98 shells
Each is a single [!note] Reference shell callout (authored in the backend's form per skills/_shared/obsidian-format.md's backend rule) pointing back to the design's matching doc. Same shape for 97 and 98. If the design omitted 97/98 (opt-in not taken), the shell still creates with a pointer to the design's overview.
99-out-of-scope.md (plan-side)
Initial content is a shell — wikilink to design's 99-OOS and "(No entries yet.)" Entries land when /c-plan Q&A surfaces a cut OR /c-execute mark-out-of-scope is invoked.
Writing flow
- Resolve config by running
node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.js"(plan.tdd,plan.style,authoring.*; contract inskills/_shared/config-resolution.md; never read config files directly). Read approved design end-to-end (overview + every child + 99-OOS), collecting Global Constraints candidates as you read (see "Global Constraints"). - Confirm phase decomposition (no split question — one plan always). Decompose into the minimal coherent grouping that covers the design — prefer one substantive topic per phase file (5–10+ tasks per file), not one phase file per design child-doc. A phase file is the unit of worktree dispatch and per-lane review under
/c-execute's lane = phase file rule; fragmented files create cold-start churn without parallelism gain. Confirm with the user: "Plan files will be01-<topic>,02-<topic>, …. Sound right?" In the same exchange, confirm the Global Constraints list (see "Global Constraints"). - Resolve
authoring.plan_mode; when it names a concrete mode (all-at-once,inline) use it without asking. When it isask, ask viaAskUserQuestion(default(Recommended)= all-at-once): All-at-once — one generator agent per remaining doc in parallel plus thecadence-doc-consistencysweep (today's behavior); Inline (label: "Inline, no sub-agents") — the main session writes every doc itself, sequentially, running the codebase verification pass on each doc before moving on; no generators, no sweep. Whenplan.styleisask, ask the style question in the same exchange (see "Plan style"). - Create the plan artifact first via
skills/_shared/storage-resolution.md(create_artifact), writing the00-overview(frontmatter + Plan style line + Global Constraints + phase index + File Map — generators need them; Review Focus is written in step 5a) withbase_shainitialized empty; do not path-compute<paths.plans>/…/00-overview.md. - (all-at-once mode) Dispatch one fresh generator agent per remaining doc (phase docs,
96-validation,97/98shells,99-out-of-scope) in parallel, up toauthoring.max_parallel; each generated doc is written to its slot perskills/_shared/storage-resolution.md(write_doc), never to a hand-computed<paths.plans>/…file. Before each generator finalizes its doc, run the codebase verification pass (above) on every path, symbol, and import it cites. Fix inline. (inline mode) The main session writes each remaining doc itself, in order, applying the same codebase verification pass per doc. 5a. Review Focus. Once the phase docs are drafted, select the Review Focus entries, add each entry's pin to its owning task, and write the## Review Focussection into the overview via write_doc (see "Review Focus"). - Invariant 2 in reverse. If a phase reveals a gap or inconsistency in the design, surface it. Apply drift policy (default: update plan only; user-elective: update plan + design).
- (all-at-once mode; inline skips the sweep — single author) Dispatch
cadence-doc-consistencyonce over the full set. Reconcile trivial wording; surface substantive contradictions to the user viaAskUserQuestion. Re-dispatch only affected generators on resolution. The plan is not finalized until the sweep is clean. - Bidirectional linkage write. Establish the design↔plan link via
skills/_shared/storage-resolution.md(link) — one idempotent call setslinked_planon the design andlinked_designon the plan and bumps the design'supdated:. - Resolve cross-references. After all plan docs exist and the sweep is clean, call
skills/_shared/storage-resolution.md(resolve_links) once over the plan to turn[[…]]wikilinks into Notion page mentions (sibling plan docs and cross-links to the design's now-existing pages). Backend-neutral: a no-op on the filesystem backend, the mention second pass on notion (seeskills/_shared/notion-translation.md). - Self-review pass (see below).
- Status stays
draft. Print: "Plan written. Run/c-execute <path>when ready."
Generation modes
Plan docs are mechanical, so /c-plan offers all-at-once (default) and inline — never the paused one-by-one mode (review happens on the assembled plan, so a per-doc pause buys nothing). All-at-once:
- Write
00-overview.mdfirst (frontmatter + Plan style line + Global Constraints + phase index + File Map — generators need them). - Dispatch one fresh generator agent per remaining doc (phase docs,
96-validation,97/98shells,99-out-of-scope) in parallel, up toauthoring.max_parallel. Each generator gets the approved design (or relevant slice), the plan overview (whose Plan style line tells the generator which step rules apply), its doc's scope, the resolved storage backend, and the format conventions (skills/_shared/obsidian-format.md; plusskills/_shared/notion-translation.mdwhen the backend is notion, so callouts are authored as native<callout>blocks, never obsidian> [!type]syntax). - Dispatch
cadence-doc-consistencyonce over the full set. Reconcile trivial wording; surface substantive contradictions to the user viaAskUserQuestion. Re-dispatch only affected generators on resolution. - The plan is not finalized until the sweep is clean.
Inline mode replaces items 2-3: the main session writes each remaining doc itself in order, applying the codebase verification pass per doc; the consistency sweep is skipped (single author). Item 4's finalization gate still applies.
Self-review pass
- Placeholder scan — no banned phrases (
TBD,TODO,implement here,similar to Task N,add validation). In decision plans it also flags a code step with no signature ("Implement the parser" decides nothing). - Task shape — every task has
Reads:,Touches:, andDepends:fields, ≥3 steps, and a final commit step; everyTouches:entry is a real path; everyDepends:id references a real task. - Code completeness (full-code plans) — every code step has actual code, not a stub. Step sufficiency (decision plans) — every step lets the implementer write exactly one reasonable thing, and no step carries more: a line that decides nothing is a gap, and a function body the signature and tests already determine is a transcript.
- Command completeness — every run-command step has exact command + expected output.
- Symbol/path/import verification — every cited file path, line range, symbol, and import was ground-truthed against the current code per "Codebase verification" rules. Intra-plan consistency also holds: names referenced across later tasks match earlier ones. (
/c-audit'scode-behind-checkboxaudit remains a backstop at completion.) - File Map honesty — every file in tasks appears in File Map; nothing in File Map is missing from tasks.
- Wikilink integrity — every
[[…]]resolves. - Callout-form check (notion backend only) — scan the read-back for escaped callout remnants (
\[!or a quote block starting> [!): either means a callout reached Notion in obsidian syntax and rendered as literal text. Rewrite that callout as a native<callout>block perskills/_shared/notion-translation.md. - Fragmented-file detector — flag any phase file with 1–2 tasks whose
Reads:core overlaps a sibling phase file's by >50% (candidate for consolidation). Surface to the user viaAskUserQuestion; never auto-merge. - Mixed-topic detector — flag any phase file whose tasks pairwise share zero
Reads:(candidate-multi-topic). Surface to the user viaAskUserQuestion; never auto-split. - Visual-citation check (95 designs only) — every task whose
Touches:intersects the Surface map carries both visual citations inReads:; no task outside the intersection carries amockup:NNcitation (the contract doc may be cited freely where useful). - Proportion (decision plans, advisory) — report the plan's total word count against the design's (overview plus every child doc) and the share of each phase doc's lines inside code blocks. These are signals, not gates: a plan with many tasks can outgrow a terse design while holding no code at all. Act only on what they point to, a step carrying a function body the signature and tests already determine (item 3); replace it with the signature, test names, and assertions.
- Interface closure (decision plans) — every task has an Interfaces block; every
Consumes:entry is produced by a task in the consumer'sDepends:closure or verified to exist in the codebase; everyProduces:name a later task uses matches exactly. - Global Constraints sourced (every plan) — the section exists; every line has a source parenthetical that resolves (a design doc,
CLAUDE.md, or a manifest the plan cites). - Review Focus closure (every plan) — the section exists with at most five entries; every entry names a real task id; that task carries the pin (a test assertion when
plan.tddis true, a run step with expected output when false).
Fix items 1–8, 11, and 13–15 inline. Item 12 is advisory: report its numbers and fix only the transcripts item 3 finds. For items 9 and 10, surface candidates to the user — consolidate / split / leave-as-is is the user's call, not /c-plan's. No re-review needed.
Report the pass in the closing summary as one line per item that applies to this plan's style and backend, by number and name, each with its result: clean, fixed (and what changed), or flagged. An item missing from that list counts as not run, so the user can see that the style-specific checks (3, 12, 13) and the companion checks (14, 15) actually ran.
What /c-plan doesn't do
- Doesn't write code.
- Doesn't modify the design (already approved). Exception: drift handling "update plan + design" path with user opt-in.
- Doesn't run anything.
- Doesn't auto-execute.
/c-executeis separately invoked.
References
- Shared frontmatter:
skills/_shared/frontmatter.md. - Shared format:
skills/_shared/obsidian-format.md.
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.

