@erclx/canon 4.6.1 โ 4.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/canon-feedback-file/SKILL.md +3 -3
- package/claude/skills/canon-feedback-triage/SKILL.md +1 -1
- package/claude/skills/canon-rollout/SKILL.md +1 -1
- package/claude/skills/canon-screencast/SKILL.md +5 -5
- package/claude/skills/canon-slides-draft/SKILL.md +1 -1
- package/claude/skills/claude-address-review/SKILL.md +4 -4
- package/claude/skills/claude-autoship/SKILL.md +17 -17
- package/claude/skills/claude-design-extract/SKILL.md +2 -2
- package/claude/skills/claude-diagram/SKILL.md +13 -13
- package/claude/skills/claude-docs/SKILL.md +23 -23
- package/claude/skills/claude-feature/SKILL.md +6 -6
- package/claude/skills/claude-groundwork/SKILL.md +16 -16
- package/claude/skills/claude-intake/SKILL.md +8 -8
- package/claude/skills/claude-intake-answer/SKILL.md +1 -1
- package/claude/skills/claude-markdown-propose/REQUIREMENT.md +2 -2
- package/claude/skills/claude-markdown-propose/SKILL.md +8 -8
- package/claude/skills/claude-markdown-propose/references/format.md +3 -3
- package/claude/skills/claude-memory-capture/SKILL.md +13 -13
- package/claude/skills/claude-memory-review/SKILL.md +28 -28
- package/claude/skills/claude-memory-review/references/receipt-format.md +1 -1
- package/claude/skills/claude-orchestrate/SKILL.md +9 -9
- package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md +1 -1
- package/claude/skills/claude-orchestrate/references/orchestrator-parked.md +1 -1
- package/claude/skills/claude-orchestrate/references/orchestrator-poll.md +1 -1
- package/claude/skills/claude-orchestrate/references/orchestrator-resume.md +1 -1
- package/claude/skills/claude-orchestrate/scripts/poll.sh +1 -1
- package/claude/skills/claude-planner/REQUIREMENT.md +1 -1
- package/claude/skills/claude-planner/SKILL.md +6 -6
- package/claude/skills/claude-pr-review/SKILL.md +5 -5
- package/claude/skills/claude-review/SKILL.md +4 -4
- package/claude/skills/claude-seed-sync/SKILL.md +2 -2
- package/claude/skills/claude-tasks/SKILL.md +16 -16
- package/claude/skills/claude-teach/SKILL.md +9 -9
- package/claude/skills/claude-ui-test/SKILL.md +3 -3
- package/claude/skills/claude-ux-audit/SKILL.md +5 -5
- package/claude/skills/claude-ux-measure/SKILL.md +3 -3
- package/claude/skills/claude-worker/SKILL.md +2 -2
- package/claude/skills/claude-worktree/SKILL.md +3 -3
- package/claude/skills/git-issue/SKILL.md +4 -4
- package/claude/skills/git-pr/SKILL.md +6 -6
- package/claude/skills/git-ship/SKILL.md +3 -3
- package/claude/skills/git-split/REQUIREMENT.md +1 -1
- package/claude/skills/git-split/SKILL.md +20 -20
- package/claude/skills/migration-superseded/SKILL.md +4 -4
- package/claude/skills/session-map/SKILL.md +2 -2
- package/claude/skills/session-resume/SKILL.md +8 -8
- package/docs/agents/capture.md +1 -1
- package/docs/agents/commands.md +5 -2
- package/docs/agents/demo.md +1 -1
- package/docs/agents/indexes.md +1 -1
- package/docs/agents/install-and-sync.md +1 -1
- package/docs/agents/intake.md +1 -1
- package/docs/agents/key-changes.md +1 -1
- package/docs/agents/records.md +12 -9
- package/docs/agents/restated.md +2 -2
- package/docs/agents/rule-citations.md +1 -1
- package/docs/agents/sandbox.md +1 -1
- package/docs/agents/tasks.md +6 -6
- package/docs/agents/teach.md +4 -4
- package/docs/ai-workflow.md +26 -19
- package/docs/operating-model.md +3 -3
- package/docs/target-projects.md +22 -2
- package/docs/visual-design-workflow.md +1 -1
- package/governance/rules/claude/555-tasks.md +3 -3
- package/governance/rules/claude/556-groundwork.md +2 -2
- package/governance/rules/claude/557-intake.md +2 -2
- package/governance/rules/claude/558-plan.md +3 -3
- package/governance/rules/claude/559-memory.md +2 -2
- package/governance/rules/claude/560-diagrams.md +3 -3
- package/governance/rules/claude/561-teach.md +2 -2
- package/governance/rules/claude/562-session.md +2 -2
- package/governance/rules/core/035-tasks.md +2 -2
- package/governance/rules/core/045-memory.md +3 -3
- package/governance/rules/core/055-scratch.md +2 -1
- package/governance/rules/core/085-worktrees.md +1 -1
- package/package.json +1 -1
- package/scripts/core/check-ignore-parity.sh +24 -51
- package/scripts/core/install-check.sh +4 -4
- package/scripts/core/snapshot.sh +1 -1
- package/scripts/manage-sandbox.sh +1 -1
- package/scripts/tooling/verify.sh +2 -2
- package/snippets/claude/decision-memo.md +1 -1
- package/snippets/claude/feature-recap.md +1 -1
- package/src/audits/catalog.ts +1 -1
- package/src/claude/cases/all.ts +1 -1
- package/src/claude/seeds.ts +13 -2
- package/src/claude/skills-rank.ts +1 -1
- package/src/cli.ts +4 -4
- package/src/commands/demo.ts +1 -1
- package/src/commands/design.ts +1 -1
- package/src/commands/feedback.ts +5 -5
- package/src/commands/gov.ts +17 -6
- package/src/commands/intake.ts +1 -1
- package/src/commands/migrate.ts +173 -2
- package/src/commands/pr.ts +1 -1
- package/src/commands/records.ts +1 -1
- package/src/commands/serve.ts +2 -2
- package/src/commands/slides.ts +1 -1
- package/src/commands/tasks.ts +5 -5
- package/src/commands/teach.ts +1 -1
- package/src/context/audit.ts +1 -1
- package/src/demo/compile.ts +1 -1
- package/src/gov/citations.ts +1 -1
- package/src/gov/restated.ts +3 -3
- package/src/migrate/apply.ts +67 -1
- package/src/migrate/records.ts +276 -0
- package/src/paths.ts +1 -1
- package/src/pr/paths.ts +1 -1
- package/src/record-root.ts +77 -27
- package/src/records/backup.ts +71 -17
- package/src/records/validate.ts +1 -1
- package/src/sync/layout.ts +11 -2
- package/src/tasks/answers.ts +1 -1
- package/src/tasks/archive.ts +20 -3
- package/standards/diagrams.md +4 -4
- package/standards/glossary.md +1 -1
- package/standards/groundwork.md +3 -3
- package/standards/index.md +2 -2
- package/standards/intake.md +3 -3
- package/standards/memory.md +2 -2
- package/standards/plan.md +3 -3
- package/standards/session.md +2 -2
- package/standards/standard.md +1 -1
- package/standards/tasks.md +9 -9
- package/standards/teach.md +2 -2
- package/standards/versioning.md +1 -1
- package/tooling/base/configs/.husky/post-merge +1 -1
- package/tooling/base/reference.md +1 -1
- package/tooling/claude/manifest.toml +13 -3
- package/tooling/claude/reference.md +28 -15
- package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh +8 -8
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: canon-feedback-file
|
|
3
|
-
description: Format a paste-back report about something broken, missing, or off in canon and write it directly to the toolkit's `.
|
|
3
|
+
description: Format a paste-back report about something broken, missing, or off in canon and write it directly to the toolkit's `.canon/review/feedback/` folder via `canon feedback`. Use when asked to "send this to the toolkit", "report this to canon", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate canon surfaces.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Canon feedback file
|
|
@@ -48,7 +48,7 @@ Detect whether `canon` is on PATH:
|
|
|
48
48
|
command -v canon >/dev/null 2>&1
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
If present, pipe the block to `canon feedback`. The CLI writes to its own repo's `.
|
|
51
|
+
If present, pipe the block to `canon feedback`. The CLI writes to its own repo's `.canon/review/feedback/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
54
|
cat <<'EOF' | canon feedback
|
|
@@ -77,4 +77,4 @@ If `canon` is not on PATH, fall back: print the block in chat and tell the user
|
|
|
77
77
|
## Notes
|
|
78
78
|
|
|
79
79
|
- `canon feedback` resolves the toolkit root from the running `canon` binary's source location. If multiple toolkit clones exist on the machine, the first `canon` on PATH wins.
|
|
80
|
-
- The destination `.
|
|
80
|
+
- The destination `.canon/review/` is gitignored in the toolkit repo. Feedback lives as session scratch for the next toolkit-side triage, not as a durable archive.
|
|
@@ -7,7 +7,7 @@ description: Triage open GitHub issues labeled `feedback` in the toolkit repo. L
|
|
|
7
7
|
|
|
8
8
|
Consume the feedback queue that `canon feedback --github` fills. Turn an open `feedback` issue into a scoped fix or a plan, then link the issue so merge closes it.
|
|
9
9
|
|
|
10
|
-
Run from the toolkit repo root. This skill reads GitHub issues, not local `.
|
|
10
|
+
Run from the toolkit repo root. This skill reads GitHub issues, not local `.canon/review/` files. Those are ephemeral session scratch. The durable, cross-project queue is GitHub.
|
|
11
11
|
|
|
12
12
|
## Guards
|
|
13
13
|
|
|
@@ -10,7 +10,7 @@ This skill runs outward. Every other skill for operating on a target assumes the
|
|
|
10
10
|
|
|
11
11
|
One wave takes one toolkit change to every target and ends with a pull request per target for a person to merge. Two roles carry three phases over one target list. The orchestrator enumerates, dispatches, reviews, and routes. The worker holds one target from the worktree entry to the merge of the branch it opened.
|
|
12
12
|
|
|
13
|
-
`claude-orchestrate` owns this repository's own board and is a different subject. Read nothing from `.
|
|
13
|
+
`claude-orchestrate` owns this repository's own board and is a different subject. Read nothing from `.canon/tasks/` here and write nothing to it.
|
|
14
14
|
|
|
15
15
|
## Take a role before anything else
|
|
16
16
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: canon-screencast
|
|
3
|
-
description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `.
|
|
3
|
+
description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `.canon/tmp/screencast/<slug>.md`. Reads project context, asks four discovery questions with proposed defaults, then writes a shippable draft. Use when asked to "draft a screencast", "write a recording script", "plan a demo video", or "scaffold a screencast for X". Do NOT re-invoke to refine an existing draft. Re-running overwrites. Edit the draft file directly.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Canon screencast
|
|
@@ -17,7 +17,7 @@ Read these in parallel from the project root, skipping any that do not exist:
|
|
|
17
17
|
|
|
18
18
|
- `CLAUDE.md`: behavior rules and project pitch
|
|
19
19
|
- `.claude/REQUIREMENTS.md`: feature scope, non-goals, audience hints
|
|
20
|
-
- `.
|
|
20
|
+
- `.canon/tasks/index.md`: current scope
|
|
21
21
|
- Recent commits via `git log --oneline -20 2>/dev/null || echo "FALLBACK"`: what shipped recently is usually the recording subject.
|
|
22
22
|
|
|
23
23
|
## Step 2: discovery with proposed defaults
|
|
@@ -41,7 +41,7 @@ Build a 2-to-4-word kebab-case slug from the topic and discovery answers. Exampl
|
|
|
41
41
|
|
|
42
42
|
## Step 4: write the draft
|
|
43
43
|
|
|
44
|
-
Create `.
|
|
44
|
+
Create `.canon/tmp/screencast/<slug>.md` at the main worktree root. Create the directory if it does not exist. The file is gitignored.
|
|
45
45
|
|
|
46
46
|
From a linked worktree the file-editing tools refuse that path, so the draft goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
|
|
47
47
|
|
|
@@ -154,12 +154,12 @@ Pre-seeded with the common picks. Strike or rewrite as needed.
|
|
|
154
154
|
Print the file path on its own line and a one-line summary. Do not paraphrase the path into prose.
|
|
155
155
|
|
|
156
156
|
```markdown
|
|
157
|
-
๐ Wrote .
|
|
157
|
+
๐ Wrote .canon/tmp/screencast/<slug>.md
|
|
158
158
|
|
|
159
159
|
Draft has 5 beats and pre-seeded defaults. Edit the beats and the resolved decisions.
|
|
160
160
|
|
|
161
161
|
To record it rather than shoot it by hand:
|
|
162
|
-
canon demo compile .
|
|
162
|
+
canon demo compile .canon/tmp/screencast/<slug>.md
|
|
163
163
|
```
|
|
164
164
|
|
|
165
165
|
Name the command and stop there. Do not compile the draft, do not run it, and do not generate captions. The operator edits the beats first, and the compiler reports which selectors and URLs they still owe it.
|
|
@@ -40,7 +40,7 @@ The palette and type scale live in the CLI. Own the choices the source controls.
|
|
|
40
40
|
Shell out to the CLI. It writes the deck and reports the path.
|
|
41
41
|
|
|
42
42
|
```bash
|
|
43
|
-
canon slides render --source .claude/SLIDES.md --out .
|
|
43
|
+
canon slides render --source .claude/SLIDES.md --out .canon/review/slides
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
Pass `--variant light` or `--variant dark` to override the source variant for a one-off render. Pass `--open` to open the deck, and `--mirror <dir>` (or set `CANON_SLIDES_MIRROR`) to copy it into a synced folder.
|
|
@@ -99,7 +99,7 @@ moved, which the earlier test could not see. Rebase again under
|
|
|
99
99
|
continue. The second push costs one extra force-push in a
|
|
100
100
|
case that needs the fix and the sibling to touch the same lines.
|
|
101
101
|
|
|
102
|
-
Then write a summary reply to `.
|
|
102
|
+
Then write a summary reply to `.canon/tmp/address-review/reply-<number>.md`
|
|
103
103
|
mapping each finding to what changed, or to a one-line reason when it is a
|
|
104
104
|
conscious-accept rather than a defect. Key the filename on the PR number so two
|
|
105
105
|
sessions addressing different pull requests never overwrite each other between
|
|
@@ -152,11 +152,11 @@ matches it.
|
|
|
152
152
|
|
|
153
153
|
Before posting, run the scan in
|
|
154
154
|
`${CLAUDE_SKILL_DIR}/../../standards/publish.md`
|
|
155
|
-
against the reply. The hook skips `.
|
|
155
|
+
against the reply. The hook skips `.canon/tmp/`, so this scan is the
|
|
156
156
|
only gate on the published reply. Post it to the PR:
|
|
157
157
|
|
|
158
158
|
```bash
|
|
159
|
-
gh pr comment <number> --body-file .
|
|
159
|
+
gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md
|
|
160
160
|
```
|
|
161
161
|
|
|
162
162
|
## Step 7: confirm resolution
|
|
@@ -208,5 +208,5 @@ Not everything worth reaching the reviewing session surfaces inside the numbered
|
|
|
208
208
|
Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered. `claude-pr-review` states the full heading set this belongs to and routes it the same as a response: `claude-orchestrate`'s poll picks it up and sends the reviewing session back for a pass. Close the body with `๐ค Addressed by Claude Code` on its own line, matching the reply's footer.
|
|
209
209
|
|
|
210
210
|
```bash
|
|
211
|
-
gh pr comment <number> --body-file .
|
|
211
|
+
gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md
|
|
212
212
|
```
|
|
@@ -10,7 +10,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
|
|
|
10
10
|
|
|
11
11
|
## Guards
|
|
12
12
|
|
|
13
|
-
- All `.
|
|
13
|
+
- All `.canon/plans/` and `.canon/review/` reads resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
|
|
14
14
|
- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `โ Detached HEAD. Checkout the feature branch first.` Every later step keys its output on this slug, being the worktree, the review receipt, the branch, and the memory proposal, regardless of which plan Step 1 reads.
|
|
15
15
|
- Resolve `<plan>` in Step 1, ahead of any other read.
|
|
16
16
|
- If the working tree has uncommitted changes unrelated to the plan, stop: `โ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
|
|
@@ -45,13 +45,13 @@ If the two commands differ, the session is already in a linked worktree. Continu
|
|
|
45
45
|
|
|
46
46
|
Resolve `<plan>` in this order, stopping at the first match:
|
|
47
47
|
|
|
48
|
-
1. **Caller-supplied task.** The invocation carried a path under `.
|
|
49
|
-
2. **Caller-supplied plan.** The invocation carried something else. Accept it as a plan path or a bare slug, in the same position `claude-worktree` tier 0 accepts its name. A bare slug resolves to `.
|
|
50
|
-
3. **Derived.** `.
|
|
48
|
+
1. **Caller-supplied task.** The invocation carried a path under `.canon/tasks/`. If it does not resolve to a file, stop: `โ No task at <path>. Path was supplied, not derived, so check it and re-run.` Read that task's first `Plan:` line and take what it names as `<plan>`, per `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`.
|
|
49
|
+
2. **Caller-supplied plan.** The invocation carried something else. Accept it as a plan path or a bare slug, in the same position `claude-worktree` tier 0 accepts its name. A bare slug resolves to `.canon/plans/feature-<slug>.md`, and a path is taken as given from the main worktree root. If it does not resolve to a file, stop: `โ No plan at <path>. Path was supplied, not derived, so check it and re-run.`
|
|
50
|
+
3. **Derived.** `.canon/plans/feature-<slug>.md`, from the `<slug>` the Guards derived. If it does not exist, stop: `โ No approved plan at .canon/plans/feature-<slug>.md. Run /claude-feature first.`
|
|
51
51
|
|
|
52
52
|
Only a path reaches tier 1, and a bare slug is read as a plan's throughout. The two would collide on any similar name, and a caller who means the task holds its path already, having read it off the board. One plan per task is what makes the tier 1 read unambiguous, so it takes the first `Plan:` line and never scans for a second.
|
|
53
53
|
|
|
54
|
-
Read the target out of the link's parentheses, and take the rest of the line when the line carries no link, since an older task writes the target as a plain path with nothing around it. Resolve a relative target against the directory holding the task file rather than against `.
|
|
54
|
+
Read the target out of the link's parentheses, and take the rest of the line when the line carries no link, since an older task writes the target as a plain path with nothing around it. Resolve a relative target against the directory holding the task file rather than against `.canon/tasks/`, and take a project-root target from the root. The archived task is what makes that base matter, since the standard points its line at `../../plans/archive/feature-<slug>.md` once the task sits a folder deeper, and reading that from `.canon/tasks/` lands on a repository-root `plans/archive/` that never exists.
|
|
55
55
|
|
|
56
56
|
### When a tier fails
|
|
57
57
|
|
|
@@ -61,13 +61,13 @@ Tier 1 stops on three failures, and each names a different repair:
|
|
|
61
61
|
- The pointer resolves into a plans archive. Stop: `โ <path> points at an archived plan, which describes work that already shipped. Reopen the task against a live plan, or pass that plan directly.` Test the resolved path rather than the task's outcomes or its `Pull request:` line, since a stale board gets its ticks wrong and the standard fixes where a shipped pointer lands.
|
|
62
62
|
- The pointer resolves to no file. Stop: `โ <path> points at <target>, which does not exist. The citation is stale, so repoint the task or pass the plan path directly.`
|
|
63
63
|
|
|
64
|
-
An archive is `.
|
|
64
|
+
An archive is `.canon/plans/archive/` and also the two older spellings `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` leaves in place for a project that archived plans before the folder nested, written from a task as `../plans-archive/` and `../.tmp/plans-archive/`. Test all three, since a shipped pointer in a project nobody migrated lands on the older two. Run the archive test ahead of the existence test, so a pointer into an archive that no longer holds the file still refuses as shipped work rather than as a stale citation.
|
|
65
65
|
|
|
66
66
|
Each tier fails for a different reason and says so. A supplied path resolving to nothing is a typo, a derived path resolving to nothing is a plan nobody wrote, and a task pointer resolving to nothing is a stale citation the board should have caught.
|
|
67
67
|
|
|
68
68
|
Test the shape of whatever `<plan>` resolved to before reading it as one. A file resolving under any tier can still be the wrong document, and tier 1 resolves through a pointer rather than from the caller, so the test runs after all three rather than guarding a supplied path alone.
|
|
69
69
|
|
|
70
|
-
Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SKILL_DIR}/../../standards/plan.md`, the one section every plan carries structurally and a task never does, where `## Outcomes` and `## Findings` are the task's own. If neither form is present, stop: `โ <path> carries no plan sections. A plan lives at .
|
|
70
|
+
Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SKILL_DIR}/../../standards/plan.md`, the one section every plan carries structurally and a task never does, where `## Outcomes` and `## Findings` are the task's own. If neither form is present, stop: `โ <path> carries no plan sections. A plan lives at .canon/plans/feature-<slug>.md, and a task reaches one through its Plan: line only from .canon/tasks/. Point autoship at either and re-run.`
|
|
71
71
|
|
|
72
72
|
Read `<plan>` at the main worktree root. This file is the scope for this run.
|
|
73
73
|
|
|
@@ -91,7 +91,7 @@ Do not loop. Do not bypass hooks.
|
|
|
91
91
|
|
|
92
92
|
If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:claude-ui-test`.
|
|
93
93
|
|
|
94
|
-
If `claude-ui-test` produces a manual checklist, stop: `โ UI requires visual verification. Checklist at .
|
|
94
|
+
If `claude-ui-test` produces a manual checklist, stop: `โ UI requires visual verification. Checklist at .canon/review/ui-checklist-<slug>.md. Verify manually, then run /git-ship.`
|
|
95
95
|
|
|
96
96
|
If all UI changes are covered by e2e tests, continue.
|
|
97
97
|
|
|
@@ -113,7 +113,7 @@ Say in the run which of the two decided, the verb or the written fallback, since
|
|
|
113
113
|
|
|
114
114
|
An empty list stops the chain: `โ No changed files to classify. Re-run when the plan has yet to produce its output. When the output is gitignored by design, autoship cannot ship it, so take the work out of the chain.` An empty list satisfies the prose-only test vacuously, so reading it as prose-only routes the branch past review instead of through it.
|
|
115
115
|
|
|
116
|
-
The two causes want different responses. A plan that has yet to produce its output is a re-run once it has. A plan whose output is gitignored by design, such as a read pass writing to `.
|
|
116
|
+
The two causes want different responses. A plan that has yet to produce its output is a re-run once it has. A plan whose output is gitignored by design, such as a read pass writing to `.canon/tmp/`, is work the chain cannot carry at all, since `git-stage` finds nothing to commit six steps later. Never advise removing the output from `.gitignore`, which trades a stopped run for scratch committed into the repository.
|
|
117
117
|
|
|
118
118
|
### When the verb is absent
|
|
119
119
|
|
|
@@ -142,17 +142,17 @@ The verb reads the same set from `src/autoship/paths.ts`, so a path added here b
|
|
|
142
142
|
|
|
143
143
|
## Step 6: evaluate findings
|
|
144
144
|
|
|
145
|
-
Skip this step when Step 5 skipped review. Otherwise read `.
|
|
145
|
+
Skip this step when Step 5 skipped review. Otherwise read `.canon/review/branch/review-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited rather than for one this run introduced.
|
|
146
146
|
|
|
147
147
|
- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop and do not offer the fix as a choice, which is the same stop wearing a proposal.
|
|
148
|
-
- **It predates this run, critical or should-fix.** Stop: `โ Review found non-minor issues that predate this run. See .
|
|
148
|
+
- **It predates this run, critical or should-fix.** Stop: `โ Review found non-minor issues that predate this run. See .canon/review/branch/review-<slug>.md. Fix and run /git-ship.`
|
|
149
149
|
- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
|
|
150
150
|
|
|
151
151
|
Read origin as causation rather than authorship. Staleness this run induced in a file it never opened is a finding it caused, and the plan's "Files to touch" list scopes what the run builds rather than what it may repair.
|
|
152
152
|
|
|
153
|
-
Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `โ A self-introduced finding survived one fix pass. See .
|
|
153
|
+
Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `โ A self-introduced finding survived one fix pass. See .canon/review/branch/review-<slug>.md. Fix and run /git-ship.`
|
|
154
154
|
|
|
155
|
-
This chain owns the receipt's lifetime, which is what makes the Output block's citation resolve on a run that reaches it. `claude-docs` used to delete the current slug's receipt while running under Step 7 below, so the closing line named a file the same run had already removed. That sweep now reaches only reports whose branch is gone, which collects this one a branch later rather than during the run that wrote it. The cost is one receipt per live branch left in `.
|
|
155
|
+
This chain owns the receipt's lifetime, which is what makes the Output block's citation resolve on a run that reaches it. `claude-docs` used to delete the current slug's receipt while running under Step 7 below, so the closing line named a file the same run had already removed. That sweep now reaches only reports whose branch is gone, which collects this one a branch later rather than during the run that wrote it. The cost is one receipt per live branch left in `.canon/review/branch/`, bounded by the branch count rather than by the lifetime of the checkout.
|
|
156
156
|
|
|
157
157
|
## Step 7: ship
|
|
158
158
|
|
|
@@ -174,10 +174,10 @@ Respond with up to five lines:
|
|
|
174
174
|
|
|
175
175
|
```plaintext
|
|
176
176
|
โ
Autoshipped (draft): <PR url>
|
|
177
|
-
<N minor findings kept in .
|
|
177
|
+
<N minor findings kept in .canon/review/branch/review-<slug>.md>
|
|
178
178
|
<N facts routed to context entries>
|
|
179
|
-
<N memories captured in .
|
|
180
|
-
<Memory proposal at .
|
|
179
|
+
<N memories captured in .canon/memory/>
|
|
180
|
+
<Memory proposal at .canon/review/memory/memory-review-<slug>.md>
|
|
181
181
|
```
|
|
182
182
|
|
|
183
183
|
Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
|
|
@@ -196,7 +196,7 @@ Every stop point leaves recoverable state. The user resumes manually from the ap
|
|
|
196
196
|
| Task carries no `Plan:` line | Write the plan, point the task's `Plan:` line at it, then re-run |
|
|
197
197
|
| Task points at an archived plan | The work already shipped. Reopen the task against a live plan, or pass that plan's path directly. |
|
|
198
198
|
| Task's `Plan:` pointer resolves to nothing | Repoint the task's `Plan:` line at the plan that exists, then re-run |
|
|
199
|
-
| Resolved file carries no plan shape | Point autoship at a plan under `.
|
|
199
|
+
| Resolved file carries no plan shape | Point autoship at a plan under `.canon/plans/feature-<slug>.md` or at a task under `.canon/tasks/`, then re-run |
|
|
200
200
|
| No diff baseline | Fetch origin so a merge base resolves against `main`, then re-run autoship |
|
|
201
201
|
| Empty changed-file list | Re-run once the plan produces tracked output. Ship gitignored output outside the chain, never by tracking it. |
|
|
202
202
|
| Branch collision on worktree entry | `claude-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship. |
|
|
@@ -90,13 +90,13 @@ Write the filled template to `.claude/DESIGN.md` from the project root. Then run
|
|
|
90
90
|
canon design render
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
-
The command writes an HTML plus CSS preview to `.
|
|
93
|
+
The command writes an HTML plus CSS preview to `.canon/review/design/`. Output the path in chat so the user can open it.
|
|
94
94
|
|
|
95
95
|
## Response format
|
|
96
96
|
|
|
97
97
|
```plaintext
|
|
98
98
|
๐ Wrote .claude/DESIGN.md
|
|
99
|
-
๐ Wrote .
|
|
99
|
+
๐ Wrote .canon/review/design/index.html
|
|
100
100
|
|
|
101
101
|
Ran the <source|greenfield> path. N cells marked `? verify`. Open the preview and confirm before committing.
|
|
102
102
|
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claude-diagram
|
|
3
|
-
description: Writes per-kind Mermaid diagram entries into `.
|
|
3
|
+
description: Writes per-kind Mermaid diagram entries into `.canon/diagrams/`, covering system context, components, request flow, data pipeline, and deployment. Reads `.claude/ARCHITECTURE.md` and `REQUIREMENTS.md` when present, falls back to a code-structure scan. Use when asked to "draw the architecture", "diagram the system", "show the components", "give me a flow chart", "refresh the deploy diagram", or "visualize the project". Do NOT use for design tokens (use `claude-design-extract`) or UI audits (use `claude-ux-audit`).
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Claude diagram
|
|
@@ -15,7 +15,7 @@ Write one entry per diagram kind. Never rewrite the folder wholesale. A pass tha
|
|
|
15
15
|
|
|
16
16
|
Read these from the project root in parallel, skipping any that do not exist:
|
|
17
17
|
|
|
18
|
-
- `.
|
|
18
|
+
- `.canon/diagrams/index.md` and every `.canon/diagrams/*.md`: which entries exist and what they already say
|
|
19
19
|
- `.claude/REQUIREMENTS.md`: users, external dependencies, tech stack, MVP feature list
|
|
20
20
|
- `.claude/ARCHITECTURE.md`: layered components, key technical decisions
|
|
21
21
|
- `CLAUDE.md`: project type, conventions
|
|
@@ -28,7 +28,7 @@ Follow `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` for frontmatter, entry
|
|
|
28
28
|
|
|
29
29
|
### Migrating a pre-split flat file
|
|
30
30
|
|
|
31
|
-
When `.
|
|
31
|
+
When `.canon/diagrams/` holds no entry and `.claude/DIAGRAMS.md` exists, this pass converts it. An entry is any `*.md` in the folder other than `index.md`. The seed ships `index.md` alone, so a folder holding only the catalog is an empty set and still converts.
|
|
32
32
|
|
|
33
33
|
Split each H2 section into the entry whose kind it matches, carry its mermaid body and explanation prose across unchanged, and add the frontmatter the standard requires. Leave `.claude/DIAGRAMS.md` on disk so the split can be compared against its source, and say in Step 7 that deleting it is the user's call.
|
|
34
34
|
|
|
@@ -50,7 +50,7 @@ Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams
|
|
|
50
50
|
|
|
51
51
|
## Step 3: write the entries
|
|
52
52
|
|
|
53
|
-
One file per kind at `.
|
|
53
|
+
One file per kind at `.canon/diagrams/<kind>.md`. Write only the files Step 2 selected.
|
|
54
54
|
|
|
55
55
|
````markdown
|
|
56
56
|
---
|
|
@@ -92,11 +92,11 @@ Nothing enforces the ban inside the diagram. The standards-audit hook toggles on
|
|
|
92
92
|
canon indexes regen
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
-
Run it after the last entry is written. It rebuilds `.
|
|
95
|
+
Run it after the last entry is written. It rebuilds `.canon/diagrams/index.md` from sibling frontmatter and groups entries under their `category`. Never hand-edit that file.
|
|
96
96
|
|
|
97
|
-
When `canon` is not on PATH, say so in Step 7 and name `.
|
|
97
|
+
When `canon` is not on PATH, say so in Step 7 and name `.canon/diagrams/index.md` as stale rather than writing it by hand.
|
|
98
98
|
|
|
99
|
-
Scaffold `.
|
|
99
|
+
Scaffold `.canon/diagrams/index.md` with `title` and `subtitle` frontmatter before the first regen when the folder is new and the seed did not provide one. The subtitle routes a first-time reader to the system context entry, since the catalog sorts categories alphabetically rather than in narrative order.
|
|
100
100
|
|
|
101
101
|
## Step 5: render what this pass changed
|
|
102
102
|
|
|
@@ -113,12 +113,12 @@ Rendering to verify layout. The first run downloads the Mermaid CLI and takes ab
|
|
|
113
113
|
Write each diagram's mermaid body to its own scratch file, then render it:
|
|
114
114
|
|
|
115
115
|
```bash
|
|
116
|
-
mkdir -p .
|
|
116
|
+
mkdir -p .canon/tmp/diagrams && bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/diagrams/<kind>.mmd -o .canon/tmp/diagrams/<kind>.png
|
|
117
117
|
```
|
|
118
118
|
|
|
119
119
|
Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning, so it cannot be verified. Use `bunx` when bun is available. Fall back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
|
|
120
120
|
|
|
121
|
-
Renders are verification artifacts, not deliverables. They stay in `.
|
|
121
|
+
Renders are verification artifacts, not deliverables. They stay in `.canon/tmp/diagrams/` and are never committed.
|
|
122
122
|
|
|
123
123
|
When the render fails for any reason (no browser engine, no network, no package manager), continue to Step 7 and name the skipped check in the chat output. A missing renderer degrades the loop, it does not fail it.
|
|
124
124
|
|
|
@@ -147,8 +147,8 @@ A migration pass stamps on the same rule. Conversion writes entries, Step 5 rend
|
|
|
147
147
|
## Step 7: chat output
|
|
148
148
|
|
|
149
149
|
```plaintext
|
|
150
|
-
๐ Wrote N entries to .
|
|
151
|
-
.
|
|
150
|
+
๐ Wrote N entries to .canon/diagrams/
|
|
151
|
+
.canon/diagrams/<kind>.md
|
|
152
152
|
<one line per entry written>
|
|
153
153
|
|
|
154
154
|
Left untouched: <kind, kind> <omitted when the folder was empty>
|
|
@@ -167,11 +167,11 @@ After a migration pass, add: `Converted .claude/DIAGRAMS.md into N entries. The
|
|
|
167
167
|
If the user asks to export the diagrams (`export to svg`, `give me images`, `render to png`), run:
|
|
168
168
|
|
|
169
169
|
```bash
|
|
170
|
-
mkdir -p .
|
|
170
|
+
mkdir -p .canon/review/diagrams && bunx -y @mermaid-js/mermaid-cli -i .canon/diagrams/<kind>.md -o .canon/review/diagrams/<kind>.png
|
|
171
171
|
```
|
|
172
172
|
|
|
173
173
|
Export PNG by default. Swap the extension for `.svg` only when the user asks for vector, and never for the Step 5 verification path. The CLI writes one file per `mermaid` block, suffixing when an entry holds more than one. Export every entry when the user names no kind. Output line:
|
|
174
174
|
|
|
175
175
|
```plaintext
|
|
176
|
-
๐ Wrote N files to .
|
|
176
|
+
๐ Wrote N files to .canon/review/diagrams/
|
|
177
177
|
```
|
|
@@ -51,7 +51,7 @@ Read these in parallel from the current worktree root (`pwd`), not the main work
|
|
|
51
51
|
|
|
52
52
|
Read the task board from the main worktree root instead, per Worktrees in `CLAUDE.md`. It is gitignored scratch and never commits with the branch:
|
|
53
53
|
|
|
54
|
-
- `.
|
|
54
|
+
- `.canon/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step. The scratch sweep reads every file in the folder for its plans sweep and states that where it gives the instruction.
|
|
55
55
|
|
|
56
56
|
## Step 2: identify what changed
|
|
57
57
|
|
|
@@ -64,7 +64,7 @@ Review the session for decisions that diverged from the original plan:
|
|
|
64
64
|
- Design or UX decisions that differ from DESIGN.md or any `.claude/wireframes/<surface>.md`
|
|
65
65
|
- Tasks blocked or newly identified
|
|
66
66
|
|
|
67
|
-
Then resolve the diff baseline and match it against the board. From `.
|
|
67
|
+
Then resolve the diff baseline and match it against the board. From `.canon/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths and read the ones Step 1 skipped.
|
|
68
68
|
|
|
69
69
|
Path matching only chooses which files to open. Behavior decides each outcome. For each unchecked outcome, decide whether the diff shipped the behavior that outcome names.
|
|
70
70
|
|
|
@@ -93,12 +93,12 @@ This changes which steps the skill reaches. It does not widen what any of them r
|
|
|
93
93
|
|
|
94
94
|
For each doc with relevant changes, apply updates following these rules. Read a standard this skill names, here or in a later step, from `${CLAUDE_SKILL_DIR}/../../standards/` when the project does not have it.
|
|
95
95
|
|
|
96
|
-
**`.
|
|
96
|
+
**`.canon/tasks/`**
|
|
97
97
|
|
|
98
98
|
- Mark completed outcomes `[x]` in the task's own file through `canon tasks outcome <stem> --close <n> --json`, repeating `--close` for each. Positions count every outcome checkbox in file order from 1, which the read above already gives. Do not move or archive the file.
|
|
99
99
|
- Write a newly identified task as its own file, following `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter.
|
|
100
100
|
- Do not touch task files this session did not change.
|
|
101
|
-
- Never hand-edit `.
|
|
101
|
+
- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it.
|
|
102
102
|
|
|
103
103
|
The verb resolves the board at the main worktree root in-process, which is the route because this is an edit inside an existing file and the file-editing tools refuse that path from a linked worktree.
|
|
104
104
|
|
|
@@ -148,7 +148,7 @@ Read `.claude/context/index.md` at `pwd` to see which domain entries exist. Skip
|
|
|
148
148
|
|
|
149
149
|
Two sources feed this step, the same split Step 2 runs on. The diff carries what the repository changed. The routed facts carry what the session learned, which a diff cannot show.
|
|
150
150
|
|
|
151
|
-
**Routed facts.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.
|
|
151
|
+
**Routed facts.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/memory-routing/<slug>.md` at the main worktree root. `claude-memory-capture` writes it, one H2 per target entry naming the path, with the fact underneath. Fold each fact into the entry its heading names, then delete the handoff file so a later run does not fold it twice.
|
|
152
152
|
|
|
153
153
|
This half is not diff-scoped and must not be. A gotcha a session hit while working is exactly the fact the diff never shows, and scoping it to changed files would drop the entries worth keeping. The handoff is a named input rather than a scan, so the reach stays bounded to what capture decided.
|
|
154
154
|
|
|
@@ -181,13 +181,13 @@ Write each updated entry immediately. Output one line per file:
|
|
|
181
181
|
|
|
182
182
|
Add a line naming the handoff when one was consumed:
|
|
183
183
|
|
|
184
|
-
`๐งน Folded: .
|
|
184
|
+
`๐งน Folded: .canon/tmp/memory-routing/<slug>.md`
|
|
185
185
|
|
|
186
186
|
The base lint-staged config runs `canon indexes regen` on every committed `*.md`, so `.claude/context/index.md` refreshes automatically on commit. No manual step needed.
|
|
187
187
|
|
|
188
188
|
## Step 8: fold promoted pages
|
|
189
189
|
|
|
190
|
-
Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.
|
|
190
|
+
Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/teach-promotion/<slug>.md` at the main worktree root. `claude-teach` writes it, one H2 per destination naming the path, with a source line under the heading and the page body in a fenced block below that. Read the body out of the fence rather than off the heading level, since a reference page carries headings of its own and only the fence separates them from the next destination. Skip this step silently when the file is absent, which is every run where nothing was promoted.
|
|
191
191
|
|
|
192
192
|
Each block is a page an operator already confirmed a destination for, so this step lands it rather than judging it again. Write to the destination the heading names, at `pwd` rather than at the main root, since every destination here is a tracked file that commits with the branch:
|
|
193
193
|
|
|
@@ -202,7 +202,7 @@ Output one line per page landed:
|
|
|
202
202
|
|
|
203
203
|
Add a line naming the handoff when one was consumed:
|
|
204
204
|
|
|
205
|
-
`๐งน Folded: .
|
|
205
|
+
`๐งน Folded: .canon/tmp/teach-promotion/<slug>.md`
|
|
206
206
|
|
|
207
207
|
Report a block left unfolded rather than dropping it:
|
|
208
208
|
|
|
@@ -216,44 +216,44 @@ Every move and delete below is a shell operation, so send each as a plain single
|
|
|
216
216
|
|
|
217
217
|
### Plans
|
|
218
218
|
|
|
219
|
-
Scan every file in `.
|
|
219
|
+
Scan every file in `.canon/tasks/`, not only the ones this session touched. For each task file whose outcomes are now all `[x]`, check for a `Plan:` line directly under the title and parse the target.
|
|
220
220
|
|
|
221
|
-
The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.
|
|
221
|
+
The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.canon/tasks/` before routing on it, which lands `../plans/x.md` and `.canon/plans/x.md` on the same file.
|
|
222
222
|
|
|
223
223
|
The bullets below name resolved locations, so an unresolved target falls to the last one and no plan is ever archived. Never delete a plan. `${CLAUDE_SKILL_DIR}/../../standards/plan.md` owns the archive destination and why a shipped plan is moved rather than removed.
|
|
224
224
|
|
|
225
225
|
Board-wide scope is the one place this sweep reaches past Step 3's rule against touching task files the session did not change. A board carrying a task that closed while an earlier run missed its archive is the defect this exists to clear, and skipping those tasks would preserve it. Reaching them is safe because the archive moves the plan and points the task at the new path, so a task from unrelated work ends up with a working pointer rather than a broken one.
|
|
226
226
|
|
|
227
|
-
Before moving anything, count the other citations. Scan every `.
|
|
227
|
+
Before moving anything, count the other citations. Scan every `.canon/tasks/*.md` file except the one being processed for a `Plan:` line naming the same plan. Compare the resolved target from the parse above, never the raw target string and never the filename alone.
|
|
228
228
|
|
|
229
|
-
A board carrying one task written `../plans/x.md` and another written `.
|
|
229
|
+
A board carrying one task written `../plans/x.md` and another written `.canon/plans/x.md` cites one plan, and a raw string comparison reads two, counts zero, and archives the file out from under a live task. Comparing filenames swaps that for the opposite error, since a live plan and an archived one share a basename whenever a closed task still points into `.canon/plans/archive/`, and the count then reads a citation that does not exist and archives nothing.
|
|
230
230
|
|
|
231
231
|
Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
|
|
232
232
|
|
|
233
|
-
`canon tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `canon` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.
|
|
233
|
+
`canon tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `canon` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.canon/plans/archive/`.
|
|
234
234
|
|
|
235
235
|
Nothing in the exit code reports that. Branch on the record's `ok` and `reason` fields and never on the exit, which is the rule every task verb already carries: an operator's shell profile may wrap `canon` in a function that runs the binary and then another command, taking its status from the second, and one measured here masks every non-zero exit rather than only an absent verb. The binary itself exits 1 for an unknown subcommand and 1 for an ordinary refusal alike. Switching this body to the verb needs a release that carries it and a read of the record rather than the exit, which together retire the duplication.
|
|
236
236
|
|
|
237
|
-
A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.
|
|
237
|
+
A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.canon/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
|
|
238
238
|
|
|
239
|
-
- Target resolves inside `.
|
|
240
|
-
- Target resolves inside `.
|
|
241
|
-
- Target resolves inside `.
|
|
242
|
-
- Any other resolved target outside `.
|
|
239
|
+
- Target resolves inside `.canon/plans/`, the file exists, and no other task file cites it: create `.canon/plans/archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.
|
|
240
|
+
- Target resolves inside `.canon/plans/` and at least one other task file cites it: leave the plan where it is and retarget nothing. Report the shared citation.
|
|
241
|
+
- Target resolves inside `.canon/plans/archive/`: skip silently. The plan was archived by an earlier pass and the task file is already correct.
|
|
242
|
+
- Any other resolved target outside `.canon/plans/`: warn and skip.
|
|
243
243
|
|
|
244
244
|
Write the retarget as a markdown link, `Plan: [feature-<slug>](../plans/archive/feature-<slug>.md)`, updating both halves so the text and the target stay in step. This branch is the only writer that produces a `Plan:` line nobody authored by hand, so a retarget that emits a bare path converts every task to the old form as it closes and drifts the board back to two shapes on its own.
|
|
245
245
|
|
|
246
246
|
### Reviews
|
|
247
247
|
|
|
248
|
-
Leave the current branch's review receipt where it is. `claude-autoship` Step 6 keeps minor findings in `.
|
|
248
|
+
Leave the current branch's review receipt where it is. `claude-autoship` Step 6 keeps minor findings in `.canon/review/branch/review-<slug>.md` and its closing block hands the reader that path, so deleting it here removes the file the chain that invoked this skill is still citing. Seven runs recorded that collision across two days before a sandbox fixture asserted the receipt and could pass only on a run the chain stopped early.
|
|
249
249
|
|
|
250
250
|
The body that writes a receipt owns its lifetime. This skill sweeps on behalf of whatever called it and has no way to read whether a file is still in use, where the chain that wrote this one cites it in its own output and knows. What reaps it is the branch sweep below, one branch later, once the branch it names is gone.
|
|
251
251
|
|
|
252
|
-
Sweep the branch reports this session never opened. List `.
|
|
252
|
+
Sweep the branch reports this session never opened. List `.canon/review/branch/review-*.md`, run the slug transform in `${CLAUDE_SKILL_DIR}/../../standards/slug.md` over every name `git branch --format='%(refname:short)'` prints, and delete a report whose slug matches none of them. Take the names from that format rather than from `git branch --list`, which marks the current branch with `* ` and a branch checked out in another worktree with `+ `, so a transform reading the marked lines as written turns a live branch into a slug nothing matches and sweeps a report a sibling worktree is still working from. A branch report is read once, by the session addressing it, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so a report outliving its branch is holding nothing. Skipping this leaves them accumulating for the life of the checkout, since a slug is unique per feature and no later branch ever looks for one.
|
|
253
253
|
|
|
254
254
|
What that removes is a local-only review on a branch deleted before it opened a pull request. `claude-review` says so where a reader meets the report, and the sweep runs anyway rather than keeping every report against the one case, since nothing else ever clears them.
|
|
255
255
|
|
|
256
|
-
Memory receipts sweep board-wide, like both halves of this step above them. Scan every `.
|
|
256
|
+
Memory receipts sweep board-wide, like both halves of this step above them. Scan every `.canon/review/memory/memory-review-*.md`, not only the one matching this slug. `claude-memory-review` writes its receipt after this skill has run in every ship chain, so a sweep keyed on the current slug looks for a file that does not exist yet, and no later branch looks for it either because a slug is unique per feature. Scanning the folder is what makes the sweep fire at all.
|
|
257
257
|
|
|
258
258
|
For each receipt, count the H2 items still marked ๐ pending:
|
|
259
259
|
|
|
@@ -262,11 +262,11 @@ For each receipt, count the H2 items still marked ๐ pending:
|
|
|
262
262
|
|
|
263
263
|
That standard owns what a fold writes and which entry types take one. `claude-memory-review` collects a receipt on the same rule, so neither body restates it.
|
|
264
264
|
|
|
265
|
-
Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables). Those sit at `.
|
|
265
|
+
Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables). Those sit at `.canon/review/` itself rather than under a producer folder, so the two globs above never reach them.
|
|
266
266
|
|
|
267
267
|
Output one line per file swept:
|
|
268
268
|
|
|
269
|
-
- `๐ฆ Archived: <path>` for a plan moved into `.
|
|
269
|
+
- `๐ฆ Archived: <path>` for a plan moved into `.canon/plans/archive/`
|
|
270
270
|
- `โญ Kept: <path>, still cited by <task-file>` for a plan another live task shares
|
|
271
271
|
- `๐งน Deleted: <path>, branch gone` for a branch report whose branch no longer exists
|
|
272
272
|
- `๐งน Deleted: <path>, folded <n> skips` for a swept memory receipt
|
|
@@ -18,7 +18,7 @@ Read these in parallel from the project root, skipping any that do not exist:
|
|
|
18
18
|
- `CLAUDE.md`: behavior rules, conventions, commands
|
|
19
19
|
- `.claude/REQUIREMENTS.md`: feature scope and non-goals
|
|
20
20
|
- `.claude/ARCHITECTURE.md`: decisions already made
|
|
21
|
-
- `.
|
|
21
|
+
- `.canon/tasks/index.md`: current scope and status, then any task file the feature relates to
|
|
22
22
|
|
|
23
23
|
Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
|
|
24
24
|
|
|
@@ -81,7 +81,7 @@ Omit empty sections. Do not print `None identified.` in chat.
|
|
|
81
81
|
|
|
82
82
|
### Full mode
|
|
83
83
|
|
|
84
|
-
Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.
|
|
84
|
+
Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.canon/plans/feature-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist.
|
|
85
85
|
|
|
86
86
|
From a linked worktree the file-editing tools refuse that path, so the plan goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
|
|
87
87
|
|
|
@@ -89,12 +89,12 @@ The file follows the template in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`.
|
|
|
89
89
|
|
|
90
90
|
Run `canon records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
|
|
91
91
|
|
|
92
|
-
Run `canon markdown audit .
|
|
92
|
+
Run `canon markdown audit .canon/plans/feature-<slug>.md` beside it, naming the file. `.canon/plans/` is gitignored and the audit's default path set is what git lists, so no other gate ever opens a plan, and six ban hits landed across four plans written without this call. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
|
|
93
93
|
|
|
94
94
|
Then output in chat:
|
|
95
95
|
|
|
96
96
|
```markdown
|
|
97
|
-
๐ Wrote .
|
|
97
|
+
๐ Wrote .canon/plans/feature-<slug>.md
|
|
98
98
|
|
|
99
99
|
**Questions:**
|
|
100
100
|
|
|
@@ -104,7 +104,7 @@ Then output in chat:
|
|
|
104
104
|
Next: /claude-worktree
|
|
105
105
|
```
|
|
106
106
|
|
|
107
|
-
Show only the path line and the `Next:` line when there are no questions. The `.
|
|
107
|
+
Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored. Do not stage or commit the file.
|
|
108
108
|
|
|
109
109
|
Do not proceed to implementation until the user explicitly says to continue.
|
|
110
110
|
|
|
@@ -114,4 +114,4 @@ After the plan is written, the user may re-ping with follow-up questions or push
|
|
|
114
114
|
|
|
115
115
|
- State each pick as one-line pick plus one-line reason. Do not use section headers, context blocks, or multi-section breakdowns in chat. Those belong in the plan file.
|
|
116
116
|
- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings.
|
|
117
|
-
- When a finding needs more than two lines to explain, update `.
|
|
117
|
+
- When a finding needs more than two lines to explain, update `.canon/plans/feature-<slug>.md` in place with the detail and point the user at the file instead.
|