canon-pipeline
Skill3 starsChanged 9 days agoMITView on GitHub
Use when an existing canon task needs the pipeline driven forward — invoking `canon run`, advancing a single phase, opening the draft PR, shipping a merged task, or recovering from a snag (auto-block hit, phase mismatch, post-merge branch divergence, agent auth failure). Also for release and shipping operations: finalization, hotfix absorption, and any release model (release-branch, trunk, tag, or no-versioning). Don't use to author a new spec (use `/canon-spec`) or check pipeline status (use `/canon-status`).
- Commits and pushes
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- canon-changelogSkill
- canon-initSkill
- canon-inline-reviewSkill
- canon-spec-reviewSkill
- canon-specSkill
- canon-statusSkill
- canon-sweepSkill
- docs-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 5 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 42
After spec (and, for fast-tier tasks, plan) is approved:
- Very specific: line 48
Add --step --expect <phase> if you want one phase at a time with a guard.
- Very specific: line 66
Use --expect whenever you have a specific next phase in mind — it fails fast on phase mismatch instead of silently running the wrong phase.
- Distinctive: line 84
After the PR is marked ready and approved — do not merge it manually:
- Very specific: line 92
If the task targeted a release branch (base_branch in status.json), --ship merges and archives there — not main.
- Distinctive: line 113
Always check working tree state before branch operations: If git status --porcelain is non-empty, surface it and ask before proceeding.
- Very specific: line 121
Check out release/vX.Y (initialize it per your project's release doc if it doesn't exist yet — this skill does not run initialization …
- Very specific: line 123
Run the pipeline normally.
- Distinctive: line 132
All tasks target the project's default branch (main or master).
- Very specific: line 135
Run the pipeline normally.
- Distinctive: line 145
After the desired set of tasks ships, create a tag from the default branch per your project's tag convention.
- Very specific: line 154
Run the pipeline. --ship merges to the default branch.
- Very specific: line 172
If the amendment review blocks with changes_requested, revise the Amendment section and re-run plain canon run <task-id> — not --reroute …
- Very specific: line 178
When the pipeline gets stuck — auto-block on a review loop, phase mismatch, --ship refusing, branch divergence after squash or rebase …
- Very specific: line 183
All ACs marked Met in handoff.md AC Coverage table.
- Very specific: line 186
Follow-ups are decided (no untracked rows) or deliberately left for --ship to surface.
- Very specific: line 189
If any are missing post-pipeline, manually advance or fix before --pr / --ship.
≈ “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.
Files
Pipeline Operations
This skill drives canon run. It encodes:
- common command patterns (start, advance, ship, open PRs)
- pre-flight checks before invoking the pipeline
- snag-recovery flows (auto-block reset, phase mismatch, post-merge sync)
For orchestrator internals — pipeline tiers, the model/effort matrices, env-var defaults, worktree mechanics, session-resumption, auto-commit guardrails — read docs/pipeline-orchestrator.md on demand.
Command reference
canon run <id> [flags]
canon task <subcommand> [args]Pipeline phases (in order)
spec → spec_review → plan → implement → code_review → qa → human_reviewDo NOT use this skill for
- Authoring a spec (use
/canon-spec) - Reading task status (use
/canon-status) - Drafting changelog entries (use
/canon-changelog)
Standard flows
1. Start a task's pipeline
After spec (and, for fast-tier tasks, plan) is approved:
canon run <task-id>Add --step --expect <phase> if you want one phase at a time with a guard. Add MAX_REVIEW_LOOPS=N when the default loop cap is too low for a complex spec.
In Claude Code canon run detaches after about a second and prints a PID and log path. Run canon watch <task-id> (do not pipe it, do not tail the log) to wait for the run to settle. It prints one summary line and exits 0 on a healthy stop, 3 on an auto-block, 4 on death, 5 on timeout. canon stop <task-id> terminates a detached run. --step, --pr and --ship run in the foreground and need no watch.
What happens after canon run (full-tier, no --full-send): the pipeline runs the spec reviewer first, then halts at the human spec gate after the spec reviewer approves the spec (before plan). In mixed mode Codex is the spec reviewer; in claude mode that role runs on Claude Code. human_spec_gate is a single-use latch that fires after spec_review, never before it — so seeing the run go straight into spec_review with the gate still true is correct, not a skipped gate. Review spec.md + spec-review.md, including the Author rows in the spec's Judgment Calls section (calls the human has not explicitly made, including any the spec reviewer's revisions added), then re-run canon run <id> to pass the gate into plan. Under --full-send there is no halt: the gate is pre-cleared, so the pipeline flows spec_review → plan → … → draft PR uninterrupted (on a delicate task --full-send also needs --force). (Fast-tier without full-send: the gate sits at spec_review entry and is usually pre-cleared during plan-writing. Full mechanics: docs/pipeline-orchestrator.md §"Spec gate is a single-use latch".)
Pre-flight before kicking off:
- Working tree is clean — commit or stash any pending edits. The orchestrator auto-commits task artifacts but will not touch source files outside
handoff.md's Changes table. tasks/<id>/status.json:task_size,delicate,human_spec_gate,worktreeset correctly.- Fast-tier (XS, non-delicate): spec + plan written,
phases.spec_review = { "status": "done", "verdict": "approved" },phases.plan.status = "done",human_spec_gate = false. - Full-tier (S/M/L/XL/delicate): spec written,
phases.spec.status = "done",phases.spec_review.status = "pending".
2. Advance one phase
canon run <task-id> --step --expect <phase>Use --expect whenever you have a specific next phase in mind — it fails fast on phase mismatch instead of silently running the wrong phase.
Valid phases: spec | spec_review | plan | implement | code_review | qa | human_review
2b. Decide follow-ups at human review
Before --pr, read tasks/<id>/done.md → ## Follow-ups. For each untracked row, ask the human to choose one of four options: file it now, write it after merge (post-ship), drop it, or fix it in this task with canon run <id> --reroute and an amendment. Offer all nit rows as one batch. Before filing an item, confirm it is still open in the current tree. File accepted items the project's way (issue tracker, backlog, or its established convention); if no convention is evident, ask the human where to file it. Record each outcome in the row's Tracked cell (dropped, post-ship, a link, #<n>, or task:<id>) before --pr. A row fixed in this task is no longer a follow-up: remove it from the table and note the fix under Decisions Made. In worktree mode, edit the worktree's copy. Full-send skips this human_review stop, so its follow-ups first appear at --ship.
3. Open a draft PR
canon run <task-id> --prPushes the task branch (first pushing canon's own unpushed scaffold commits on base_branch, or creating it on origin if missing when every local-only commit is canon-safe or already published) and opens a draft PR via gh pr create targeting base_branch from status.json. After it runs, read tasks/<id>/handoff.md and verify the auto-generated PR body matches actual scope — rewrite via gh pr edit <num> --body-file ... if code-review iterations expanded scope beyond the initial handoff.
4. Ship an approved task
After the PR is marked ready and approved — do not merge it manually:
canon run <task-id> --ship # merge the PR (squash by default), pull base, tear down worktree, archive, clean up branches--ship merges with the configured method (ship.merge_method, squash by default), deletes the remote task branch, then pulls/fast-forwards the base branch, proves the merge (forge-proof gate) before deleting any local task branch, tears down the worktree, and archives tasks/<id>/. If the PR was already merged externally, --ship detects that and picks up at cleanup — and canon task post-merge-sync exists as a recovery helper if the local base has diverged after an external squash or rebase merge, not as a standard pre-ship step.
If the task targeted a release branch (base_branch in status.json), --ship merges and archives there — not main.
--ship requires the task to be at human_review (or complete). If it refuses with "task is at: code_review" (or similar), the squash or rebase merge captured a pre-progression status.json. Advance the phases manually — artifacts are on disk, so this is paperwork. Use the verdict actually checked in tasks/<task-id>/review.md (approved or approved_with_nits) — the phase gate rejects a verdict that doesn't match the artifact:
canon task phase <task-id> code_review done <verdict-from-review.md>
# Before marking qa done, make sure done.md has a parseable ## Follow-ups section (None. or the table).
canon task phase <task-id> qa done
canon run <task-id> --shipAfter --ship, write the rows in the Post-ship follow-ups block in the post-ship docs commit on the base branch. Put each row in the Untracked follow-ups block to the human for a decision. A Follow-ups … not listed warning means the section is missing or unparseable; inspect the archived done.md by hand.
5. Release and shipping operations
Canon's --pr / --ship / base_branch mechanics are model-neutral. The base_branch field is recorded in status.json per task at creation, so a single repository may use different release models for different task surfaces — pick the model that matches the work at hand.
Hybrid repos are first-class: a project with one surface on versioned release branches and another shipping straight to the main line can use different base_branch values per task with no global setting. Canon supports all shapes because the per-task base_branch is the only release-model knob the orchestrator reads.
Authority pointer: For every recipe below, your project's own decisions.md §Versioning and Release Policy (and/or your project's release doc) is the source of truth for version numbers, changelog policy, branch strategy, and tag conventions. Canon provides mechanics; your project's policy provides decisions.
Always check working tree state before branch operations. If git status --porcelain is non-empty, surface it and ask before proceeding. Never blow away uncommitted work.
Recipe: release-branch-per-version
One release branch per version (release/vX.Y). Tasks land on the release branch; a merge PR ships the whole release to the default branch.
- Check out
release/vX.Y(initialize it per your project's release doc if it doesn't exist yet — this skill does not run initialization commands). canon task new <id> "Title"— auto-detectsbase_branch: release/vX.Y.- Run the pipeline normally.
--shipmerges the task torelease/vX.Y. - Hotfixes during a release cycle: hotfixes go directly to the default branch. After the hotfix lands, offer: "Release branch
release/vX.Ywill need to absorb this — want me to merge the default branch into it?" - Finalize: once all vX.Y tasks are merged, use
/canon-changelog finalizeto stamp the unreleased block with today's date. - Ship the release:
gh pr create --base <default-branch> --head release/vX.Y --title "vX.Y: <theme>". After merge,canon task post-merge-syncon the default branch. Tag and GitHub release steps live in your project's release doc.
Recipe: trunk-from-main
All tasks target the project's default branch (main or master). No separate release branch.
canon task new <id> "Title"while on the default branch — auto-detectsbase_branch: main(ormaster).- Run the pipeline normally.
--shipmerges the task directly to the default branch. - Version bumps, changelog entries, and tags are handled on the default branch per your project's versioning policy — not prescribed by canon.
Recipe: tag-from-main
Tasks land on the default branch; releases are marked with a tag rather than a release branch.
- Same as trunk-from-main for task targeting and pipeline execution.
- After the desired set of tasks ships, create a tag from the default branch per your project's tag convention. Canon does not manage tag creation or GitHub release publication — those belong to your project's release doc.
Recipe: no versioning
Tasks land on the default branch; no version numbers, no CHANGELOG, no tags.
canon task new <id> "Title"on the default branch.- Run the pipeline.
--shipmerges to the default branch. - Skip all versioning, changelog, and tagging steps. Use
/canon-changelogonly if and when your project adopts a CHANGELOG.
6. Reroute once implementation has begun
--reroute is allowed once implementation has begun: current phase code_review, qa, or human_review (any status or verdict), or implement when implement is in progress or blocked, code review is blocked, or code review already ran in the current loop (a review round or a pre-flight rejection). In a bundle, a sibling at implement pending with no current-loop activity is admitted alongside a task that qualifies when both belong to the same non-empty task branch. Name every task of a shared-branch bundle in one reroute; a reroute that names only part of it is refused before any state changes, and the message lists the missing tasks. A task admitted as a sibling still needs its own Amendment section.
Deciding to reroute a task is a human decision, not something an agent driving canon infers on its own — even under --full-send or another autonomous mode, get an explicit human decision before invoking --reroute.
- Write the new requirements into
spec.mdas an Amendment section — required, not optional (unless this is a spec_gap-entry reroute, where only thespec_gaptasks need one; approved siblings ride along): the reroute pre-flight gate aborts unless the heading## Amendment(round 1) or## Amendment Round N(round 2+) exists. A note elsewhere doesn't count. Edit the worktree copy if a worktree exists. - Reroute re-enters at the tier's review altitude:
canon run <task-id> --reroute # Full tier (S/M/L/XL/delicate) re-enters at spec_review — amendment gets reviewed, plan refreshed: canon run <task-id> --step --expect spec_review # Fast tier (XS, non-delicate) re-enters directly at implement: canon run <task-id> --step --expect implement - If the amendment review blocks with
changes_requested, revise the Amendment section and re-run plaincanon run <task-id>— not--reroute(that would start a new reroute round).
Snag recovery
When the pipeline gets stuck — auto-block on a review loop, phase mismatch, --ship refusing, branch divergence after squash or rebase merge, parallel-task artifact conflicts, or agent auth 401 — see recovery.md. Each scenario has a documented diagnosis and fix.
Pre-flight checklist before --pr or --ship
- Working tree clean inside the worktree (no uncommitted source).
- All ACs marked Met in
handoff.mdAC Coverage table. - Validation Outcomes table has no Fail rows except clearly-labeled unrelated-flake rows.
done.mdexists (qa phase wrote it).- Follow-ups are decided (no
untrackedrows) or deliberately left for--shipto surface. review.mdshowsapprovedorapproved_with_nits.
If any are missing post-pipeline, manually advance or fix before --pr / --ship.
Related
docs/pipeline-orchestrator.md— orchestrator internals, model matrix, reroute, ship mechanics (the primary reference for this skill)./canon-status— read task state and get recommended next action./canon-spec— author a new task spec./canon-spec-review— adversarial pre-pipeline spec review before invoking the pipeline./canon-changelog— draft release notes from completed tasks./canon-init— fill canon scaffold docs on a fresh project.
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.

