agentleFS
tstraub89tstraub89/canon-ai/.claude/skills/canon-spec/SKILL.md

canon-spec

Skill3 starsChanged 9 days agoMITView on GitHub

Use when the human describes a new feature, bug fix, or refactor that doesn't yet have a canon task — phrases like "let's add X", "I want to fix Y", "we should refactor Z", "start a task for...", or explicit `/canon-spec` invocation. Also triggers on "full send" / "full-send" / "yolo it" which carries through to pipeline launch without further interrupts (a delicate task asks once for confirmation before launch). Don't use for existing in-progress tasks (use `/canon-pipeline`) or status checks (use `/canon-status`).

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 12 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow these phases in order.

    line 26
  2. Distinctive:

    Stop points marked ⛔ STOP require explicit approval before continuing.

    line 27
  3. Distinctive:

    Read before doing anything else:

    line 33
  4. Very specific:

    Before grilling, detect full-send intent from $ARGUMENTS: if it contains an explicit --full-send flag or the phrase full send / full-send …

    line 67
  5. Distinctive:

    For XS tasks: Ask at most 2–3 clarifying questions in one round if scope is genuinely ambiguous.

    line 82
  6. Distinctive:

    Ask one question at a time — never a batch

    line 87
  7. Distinctive:

    Always state your recommended answer so the user can confirm, redirect, or override

    line 88
  8. Distinctive:

    If a question can be answered by exploring the codebase, explore instead of asking

    line 90
  9. Distinctive:

    Wait for approval before proceeding.

    line 120
  10. Distinctive:

    After scope is approved:

    line 126
  11. Distinctive:

    Create the task directory:

    line 128
  12. Very specific:

    If full-send mode is active, prepend this line immediately after the title block and before ## Problem: > Full-send mode: This spec was …

    line 136
  13. Distinctive:

    Callers: every caller of each function whose behavior or error contract changes, found and accounted for.

    line 178
  14. Distinctive:

    Scope: every file the steps change is inside the spec's Affected Files.

    line 181

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Spec Authorship

Task: $ARGUMENTS

Session context

In-progress tasks:

canon task list 2>/dev/null || echo "(none)"

Current branch: !git branch --show-current 2>/dev/null


Workflow

Follow these phases in order. Do not skip ahead or combine phases. Stop points marked ⛔ STOP require explicit approval before continuing.


Phase 1 — Load context

Read before doing anything else:

  • docs/product-context.md — project context, user flows, delicate surfaces
  • docs/decisions.md — settled decisions (check for conflicts)
  • docs/patterns.md — implementation patterns and known pitfalls
  • docs/lessons-learned.md — insights from past tasks
  • If the project has a docs-freshness config (config.json in the .canon directory), read its docs_freshness.paths map. For any path you put in Affected Files that matches a glob, name the mapped docs in Docs Impact. List a mapped doc in Affected Files only if the implementer should edit it.

The Validation Matrix is inline in .canon/templates/spec.md (the sizing table lives in docs/pipeline-orchestrator.md).

For the task's area, also read the relevant section of docs/codebase-map.md.


Phase 2 — Explore the codebase

Delegate entirely to an Explore sub-agent. Do not read source files directly in this conversation.

Spawn an Explore sub-agent via the Agent tool with a prompt covering:

  • The task: $ARGUMENTS
  • Which systems and files are likely affected (infer from the task and docs/codebase-map.md)
  • What to return:
    • Relevant files with a brief description of their current behavior
    • Patterns from docs/patterns.md that apply
    • Pitfalls from docs/patterns.md that are relevant
    • Conflicts with settled decisions in docs/decisions.md
    • Surprising or non-obvious constraints the implementer will need to know

Synthesize the sub-agent's findings before proceeding.


Phase 3 — Scope alignment

Before grilling, detect full-send intent from $ARGUMENTS: if it contains an explicit --full-send flag or the phrase full send / full-send (case-insensitive), enter full-send mode, print the acknowledgment line below, and carry that mode through the rest of the workflow.

Full-send mode detected. I'll grill, write and review the spec, and run the pipeline through to a draft PR without further interrupts unless the review raises a scope question (a delicate task asks once for "go" before launch).

Assess task size from the description and exploration findings:

  • XS: more than a trivial one-file inline change (>1 file, or real logic), but little-to-no spec premise worth reviewing. This is the smallest way into the pipeline: choosing it over inline buys the pipeline's cross-review direction (the implementer works against written ACs and a separate reviewer checks the code), a plan, and a real code_review.
  • S: the first full-tier size; small and bounded, but the spec carries enough logic/risk that a spec_review pass earns its keep.
  • M: several files, well-understood approach, < 1 day
  • L: cross-cutting, significant refactor, or meaningful uncertainty
  • XL: architecture change, high uncertainty, multiple systems

Also assess: is this delicate? Check docs/product-context.md for the project's defined delicate surfaces. The bar is: an undetected bug here is materially harder to recover from than a normal bug.

Inline remains below the pipeline: Claude implements directly and asks Codex for review at intervals, with no task, written ACs, or plan. XS is the pipeline floor; spec_review is the XS→S dividing line. The cross-review flip is a property of running the pipeline at all, and XS is simply the cheapest tier that has it.

For XS tasks: Ask at most 2–3 clarifying questions in one round if scope is genuinely ambiguous. Resolve them, then move to Phase 4.

For S / M / L / XL / delicate tasks — grill mode:

Walk the decision tree one branch at a time until you have full shared understanding:

  • Ask one question at a time — never a batch
  • Always state your recommended answer so the user can confirm, redirect, or override
  • On a judgment call, also state the strongest case for the runner-up and what would flip the call, so the user decides between two argued options rather than adopting your lean
  • If a question can be answered by exploring the codebase, explore instead of asking
  • Resolve parent decisions before descending to child decisions
  • Continue until the user signals shared understanding ("ok", "yep", "let's write it")

Always take a position. A question without a recommended answer offloads design work onto the user.

Topics to work through for full-tier tasks (apply judgment — not all will apply):

  • What exact behavior changes? What does the user see/do differently?
  • What's explicitly out of scope?
  • Does this conflict with an existing pattern or settled decision?
  • What's the riskiest AC? What can go wrong?
  • Which files are likely affected?
  • Does this touch a delicate surface?

Phase 4 — Propose scope

⛔ STOP — present this and wait for approval before creating any files.

Summarize concisely:

  • Task slug — kebab-case, descriptive (e.g. add-search-sidebar, fix-auth-timeout)
  • Title — short phrase
  • Size — XS / S / M / L / XL with one-line justification
  • Delicate? — yes/no, citing the relevant surface
  • Affected areas — 2–4 bullets: which files/systems change
  • Approach — 1–2 sentences: what we're building
  • Non-goals — what we're explicitly NOT doing

Wait for approval before proceeding.


Phase 5 — Create task and write spec

After scope is approved:

  1. Create the task directory:
    canon task new TASK-ID "Title"
  2. Set metadata with canon task set TASK-ID task_size <XS|S|M|L|XL> and canon task set TASK-ID delicate <true|false>. The spec gate defaults to armed for new tasks.
  3. Fill in tasks/TASK-ID/spec.md, the scaffold canon task new created (it uses the project's task-template override for spec.md when present, else .canon/templates/spec.md). Fill every section — no placeholders, no "TBD".
    • If full-send mode is active, prepend this line immediately after the title block and before ## Problem: > **Full-send mode**: This spec was produced in full-send mode.
  4. Run canon task phase TASK-ID spec done.

Spec quality checklist before presenting:

  • Every AC states exactly how to verify it (not just "it works")
  • Affected Files uses exactly one ### Affected Files heading under ## Design and at most one per ## Amendment… section (a behavior-only amendment needs none), with one file per row: comma-join extra paths for the same change in the first column, put notes in the Change column, and never put a second backticked token in a first-column note (directory entries ending in / are fine). Marking the spec done enforces this format, and canon re-checks it before planning and implementation. Each row has a specific change description.
  • If this spec replaces existing behavior: frame it as one replacement ("replace X with Y; X must not exist after") and add a structural/grep AC when practical; use paired add/remove bullets only when true replacement framing doesn't fit
  • Known Risks covers failure modes for the trickiest ACs
  • Human Test Plan uses product language only — no code, no file paths
  • Validation Required has at least one entry marked - [x] (or a single checked - [x] None - <reason>); unchecked - [ ] placeholders block the code_review pre-flight
  • Non-Goals rules out the most tempting scope expansions — back load-bearing exclusions with a positive scope-bound or grep AC, not prose "NOT" alone
  • Symbols named in ACs actually exist in the codebase — grep-verify before presenting
  • (Bug/flake fixes; N/A for features/refactors) Problem states the confirmed mechanism and how it was confirmed, with evidence matching the mechanism class (runtime-dependent mechanisms need executed confirmation), not merely a plausible cause; Acceptance Criteria includes a red-first regression-test AC or an explicit environment-bound and faithful-repro-impractical escape with a deterministic alternative
  • (Refactors; N/A for features/bug fixes) Problem records the correctness audit of each behavior declared preserved, with one outcome each (correct as-is, fixed deliberately (with its own AC), split into a separate task, or kept as a named quirk) stated before any "preserve" AC
  • Judgment Calls lists every judgment call the spec makes, each with its strongest alternative and a Decided by value (Human or Author), or says None — <reason>

Spec-writing rules of thumb (apply when writing ACs and structure):

  • Name effects to DELETE: frame supersession as replacement ("replace oldFn with newFn; oldFn must not exist after"), not separate add/remove bullets.
  • Prefer positive or structural assertions over prose negations for load-bearing constraints. Back a "must not" with a grep AC or positive reframe.
  • Symbols in ACs must exist — grep for every named function or symbol; verify return shape matches the spec's assumed data contract.
  • Enumerate every caller and classify its execution context before asserting how a mechanism works. "Counter X only increments on event Y" or "this writer can only be invoked from surface Z" is a control-flow claim, and control-flow claims need every caller traced — a helper named for one trigger routinely serves several, and whether a call site runs inside an agent's own session or in the orchestrator's process is invisible from the function body. Grep every caller of the function or counter (including skills and docs, not just source) and classify each site as in-agent-session or orchestrator-context before the spec asserts anything about it.
  • Find sibling implementations, not just callers — before settling Affected Files, search for every other place that implements the behavior the spec changes: a second listener or entry path, a parallel component, or a test or doc that asserts the current behavior. A change that reaches one of two implementations ships half-done, and the gap usually surfaces only at code review.
  • Behavioral contracts, not mechanics — ACs describe observable behavior; defer implementation mechanics to plan/implement. If review rounds start re-litigating literal regexes, exact file layouts, or verbatim command strings, the spec has dropped to code altitude and each round's "underspecified" finding just adds more reviewable surface: move the mechanics into a clearly-labeled non-binding Implementation Notes subsection owned by plan/implement, rather than wording the same mechanism more precisely. The recurring form of this trap is an AC that pins exact operation counts over a fixture in which an unchanged async subsystem (a generation queue, a worker pool) performs its own reads inside the measurement window — an adopter spec took five review rounds on one such AC because each revision worded the same brittle count more precisely instead of removing the dependency; make the side effects inert or assert the discriminating deltas, do not itemize the subsystem's arithmetic.
  • List every judgment call in Judgment Calls. A judgment call is a choice between two or more defensible options where the choice changes behavior or scope. A choice a project doc already settles is not a judgment call: follow the doc and cite it. For each call record the chosen option, the strongest alternative, why the choice fits, and Decided by: Human only when the human explicitly chose it, otherwise Author. Listing them is your own obligation as author: on fast-tier (XS, non-delicate) tasks the spec_review checkpoint is skipped, so the author's list is the only check.
  • Bug and flake-fix specs need a confirmed mechanism and red-first test: For a bug or flake fix, the spec author must state, in Problem, both the confirmed mechanism and how it was confirmed — not merely a plausible cause. Evidence must match the mechanism class: a deterministic mechanism (fixed inputs hit the same wrong branch every run) may cite a trace with the verified trigger values; a runtime-dependent mechanism (race, timing, environment/config interaction) needs executed confirmation — a throwaway prototype-fix spike that makes the symptom vanish, or a deterministic forced repro. The author must satisfy that checkpoint before the spec is marked done; on fast-tier (XS, non-delicate) tasks the spec_review checkpoint is skipped, so no reviewer will catch an unverified mechanism. The Acceptance Criteria must include a red-first regression-test AC: a test that fails on the pre-fix code for the stated reason and passes after the fix. If the mechanism is environment-bound and a faithful repro is impractical, Problem must say so and name a deterministic alternative (integration fixture or documented manual repro) instead of skipping verification silently.
  • At ≥3 spec_review iterations, read the rounds' content, not the count. Label each round edge-fine-tune (it narrows an already-identified case — converging, safe to finish once the findings are addressed) or scope-expansion (it names a new structural case the spec hadn't covered — a real design gap). Round count alone is not the signal; a 6-round run of successive fine-tunes is convergence. On genuine scope-expansion, don't refine again: check whether the last two rejections share one structural root, and whether an existing layer already owns the concern. Dropping the whole mechanism class — or deleting the mechanism in favor of the layer that already owns it — is usually cheaper than another round of hardening.
  • Refactor specs need hard structural caps: size cap, explicit deletion expectations per symbol, grep AC for disappeared symbols.
  • Refactor specs need a correctness audit before "preserve behavior": For each behavior a refactor declares preserved, record in Problem whether it is correct today, and state one outcome: correct as-is, fixed deliberately (with its own AC), split into a separate task, or kept as a named quirk. A behavior confirmed correct needs only a one-line record. N/A for features and bug fixes.
  • Codebase-wide term renames: gate per string family, not per enumerated hit. Hand-enumerated grep lists cause round-over-round scope expansion — each review round surfaces a new label family, not a missed instance. Decompose the stale term into its distinct string families up front via a structural sweep, then express each family's post-change invariant as a zero-result grep AC with a word-bounded pattern that catches all separator variants and cannot match the new term. Where the old string is a substring of the new one, zero-result gating is structurally impossible — verify those surfaces with positive targeted ACs instead, and document the asymmetry in the spec so reviewers don't read it as a gap. Two checks before finalizing any zero-result grep AC: (1) on prose surfaces (docs/, templates, backlog), read every affected file for paraphrases of the retired claim — an exact-string grep proves only that the literal phrase is gone, not that the retired behavior is undocumented everywhere; (2) scan the spec's own other ACs, Docs Impact, and Non-Goals for hits they already tolerate (historical docs, a release-time step, incidental test fixtures) and fold those into an explicit permitted-to-remain bucket inside the same AC, so a later section doesn't quietly contradict the gate.

⛔ STOP — present the spec, list its Judgment Calls rows marked Author (calls you made that the human did not explicitly choose), or say there are none; strongly recommend running /canon-spec-review on it before approving, and wait for approval. The recommendation applies at every size except an XS change with no logic to vet (a typo fix or version bump), which /canon-spec-review itself skips: on full tier it catches what the spec_review phase tends to miss, such as an unnamed second implementation of the changed behavior, and on fast tier (XS, non-delicate) it is the only automated spec review. If the human runs it, fold the findings they accept into the spec and re-present it. In full-send mode there is no approval stop, so run /canon-spec-review on the spec yourself instead, under the same exception. Apply every BLOCKING finding. For each STRONG or NIT finding, use your judgment as the spec author: apply it if it improves the spec, otherwise leave it. If a fix would change the scope the human approved during grilling, such as adding a surface or dropping a Non-Goal, stop and ask the human before applying it. That is the only spec-time interrupt full-send keeps; a delicate task also stops once for "go" before launch (Phase 6). Then continue to Phase 6.


Phase 6 — After spec approval

XS tasks:

  1. Fill in tasks/TASK-ID/plan.md, the scaffold canon task new created (it uses the project's task-template override for plan.md when present, else .canon/templates/plan.md). Before writing steps, run the same feasibility check the pipeline's planner runs, and record the results in a few lines in the plan's Approach section. Mark an item that doesn't apply N/A in a word:

    • Exists: the functions, files, and patterns the plan relies on exist — found by searching the code, not recalled.
    • Real path: the actual runtime call path the change sits on, including any existing code on it that already does part of the work.
    • Callers: every caller of each function whose behavior or error contract changes, found and accounted for.
    • Tests that can fail: for each regression test the plan prescribes, the input or state that sends it through the changed path, so it fails without the change.
    • Predicates: for each condition or state check the plan writes out, its boundary values (for example zero, empty, or non-numeric) and every state it must handle.
    • Scope: every file the steps change is inside the spec's Affected Files.
    • Async/stateful: for async or stateful changes — re-entry, cancellation or unmount, stale state, and ownership.

    A finding that changes a step goes in that step. If the check contradicts the spec, don't work around it in the plan — on the fast tier the spec_review checkpoint is skipped, so no reviewer will catch the mismatch. Amend the spec, re-present the change to the human, and wait for renewed approval. The earlier Phase 5 approval does not cover a spec changed after it, so don't record approval in step 2 until the human has approved the amended spec.

  2. Record the human's approval in tasks/TASK-ID/spec-review.md: check the Approved box and add a one-line note ("Fast tier — human conversational spec approval; spec review skipped"). In full-send mode no human approved the spec, so the note says that instead ("Fast tier full-send — no human spec approval; /canon-spec-review run before launch; spec review skipped"), or "review skipped" when the no-logic exception applied. The phase gate reads this artifact before letting spec_review advance.
  3. Advance the phases with the helpers (they rederive the top-level status pointer):
    canon task phase TASK-ID spec done
    canon task phase TASK-ID spec_review done approved
    canon task phase TASK-ID plan done
    Then run canon task set TASK-ID human_spec_gate false (already cleared by the human's conversational approval).
  4. Invoke the pipeline:
    canon run TASK-ID

Full-tier tasks (S, M, L, XL, or any delicate task):

  1. Invoke the pipeline — the spec reviewer reviews the spec, then pipeline Claude writes the plan, the implementer implements, and pipeline Claude reviews and QA's (in mixed mode Codex holds spec review and implementation; in claude mode every role runs on Claude Code):
    canon run TASK-ID

Full-send tasks: if the task was detected as full-send, invoke the pipeline with --full-send instead of the plain run. If the task is delicate, canon refuses --full-send without --force, so stop and ask before launching: "Delicate + full-send needs your confirmation before I launch with --force: canon's review chains still run with the upgraded model, but no human checkpoint exists before the PR opens. Reply 'go'." Launch with --force only after an explicit "go". A non-delicate full-send launches without this stop. Launch:

canon run --full-send [--force] TASK-ID

Related

  • /canon-spec-review — adversarial pre-pipeline review of the spec. Strongly recommended after authoring any spec with logic to vet, before approving it and invoking the pipeline.
  • /canon-pipeline — drive the pipeline after spec approval.
  • /canon-status — check what other canon tasks are in flight before committing to scope.
  • docs/pipeline-orchestrator.md — pipeline internals, sizing guide, model/effort matrix. The Validation Matrix is now inline in .canon/templates/spec.md.

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.