@erclx/canon 5.31.0 → 5.32.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/README.md +1 -1
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/api-design/references/adopted.md +1 -1
- package/claude/skills/auto-ship/REQUIREMENT.md +4 -16
- package/claude/skills/auto-ship/SKILL.md +13 -58
- package/claude/skills/auto-ship/references/draft-mark.md +2 -2
- package/claude/skills/auto-ship/references/failure-recovery.md +1 -5
- package/claude/skills/auto-ship/references/tier-failures.md +1 -1
- package/claude/skills/auto-ship/references/ui-checklist.md +2 -2
- package/claude/skills/auto-ship/references/verb-absent.md +3 -27
- package/claude/skills/backlog-triage/SKILL.md +1 -1
- package/claude/skills/canon-cli/REQUIREMENT.md +4 -6
- package/claude/skills/canon-cli/SKILL.md +2 -2
- package/claude/skills/canon-feedback/REQUIREMENT.md +1 -1
- package/claude/skills/canon-feedback/SKILL.md +10 -13
- package/claude/skills/canon-feedback-triage/REQUIREMENT.md +13 -14
- package/claude/skills/canon-feedback-triage/SKILL.md +49 -30
- package/claude/skills/canvas/REQUIREMENT.md +3 -4
- package/claude/skills/canvas/SKILL.md +5 -5
- package/{standards → claude/skills/canvas/references}/canvas.md +12 -1
- package/claude/skills/ci-workflow/REQUIREMENT.md +0 -1
- package/claude/skills/context-fold/REQUIREMENT.md +8 -20
- package/claude/skills/context-fold/SKILL.md +20 -44
- package/claude/skills/context-fold/references/classify.md +7 -8
- package/claude/skills/context-fold/references/completion-report.md +2 -6
- package/claude/skills/context-fold/references/context-refresh.md +5 -15
- package/claude/skills/context-fold/references/promoted-pages.md +3 -3
- package/claude/skills/context-fold/references/receipt-sweep.md +6 -17
- package/claude/skills/context-fold/references/unusable-baseline.md +4 -6
- package/claude/skills/create-rule/REQUIREMENT.md +0 -1
- package/claude/skills/create-skill/REQUIREMENT.md +6 -4
- package/claude/skills/create-skill/SKILL.md +8 -7
- package/{standards → claude/skills/create-skill/references}/skill-paths.md +1 -0
- package/claude/skills/decision-escalate/REQUIREMENT.md +1 -1
- package/claude/skills/decision-escalate/SKILL.md +1 -1
- package/claude/skills/design-taste/REQUIREMENT.md +0 -2
- package/claude/skills/design-taste/SKILL.md +1 -3
- package/claude/skills/design-taste/references/vocabulary.md +1 -1
- package/claude/skills/docs-sync/REQUIREMENT.md +3 -3
- package/claude/skills/document-health/REQUIREMENT.md +2 -2
- package/claude/skills/document-health/SKILL.md +4 -5
- package/claude/skills/document-health/references/axes.md +4 -6
- package/claude/skills/draft-and-pick/REQUIREMENT.md +16 -14
- package/claude/skills/draft-and-pick/SKILL.md +40 -32
- package/claude/skills/draft-and-pick/references/live-arms.md +9 -9
- package/claude/skills/draft-doc/REQUIREMENT.md +5 -5
- package/claude/skills/draft-doc/SKILL.md +9 -10
- package/claude/skills/draft-doc/references/requirements.md +61 -0
- package/claude/skills/draft-doc/references/wiki-kind.md +53 -0
- package/claude/skills/draft-doc/references/wiki.md +50 -30
- package/claude/skills/draft-figure/REQUIREMENT.md +2 -2
- package/claude/skills/draft-figure/SKILL.md +4 -4
- package/claude/skills/draft-figure/references/architecture-set.md +4 -4
- package/claude/skills/draft-figure/references/hand-drawn.md +1 -1
- package/claude/skills/draft-figure/references/mermaid-path.md +55 -0
- package/claude/skills/draft-figure/references/mermaid.md +43 -34
- package/claude/skills/draft-identity/REQUIREMENT.md +1 -1
- package/claude/skills/draft-identity/SKILL.md +9 -7
- package/claude/skills/draft-ready/REQUIREMENT.md +1 -1
- package/claude/skills/draft-ready/SKILL.md +6 -6
- package/claude/skills/draft-ready/references/assembly.md +1 -1
- package/{standards → claude/skills/draft-ready/references}/ready.md +13 -5
- package/claude/skills/git-issue/references/issue.md +3 -3
- package/claude/skills/git-ship/REQUIREMENT.md +0 -2
- package/claude/skills/git-ship/SKILL.md +16 -24
- package/claude/skills/plan-feature/SKILL.md +2 -6
- package/{standards → claude/skills/plan-feature/references}/plan.md +9 -10
- package/claude/skills/plan-groundwork/SKILL.md +5 -6
- package/{standards → claude/skills/plan-groundwork/references}/groundwork.md +17 -4
- package/claude/skills/plan-intake/SKILL.md +2 -3
- package/{standards → claude/skills/plan-intake/references}/intake.md +17 -2
- package/claude/skills/plan-intake-answer/REQUIREMENT.md +1 -1
- package/claude/skills/plan-intake-answer/SKILL.md +1 -1
- package/claude/skills/review-address/SKILL.md +1 -1
- package/claude/skills/review-craft/REQUIREMENT.md +3 -3
- package/claude/skills/review-craft/SKILL.md +2 -2
- package/claude/skills/review-craft/references/ui.md +4 -4
- package/claude/skills/review-pr/REQUIREMENT.md +1 -1
- package/claude/skills/review-pr/SKILL.md +5 -7
- package/claude/skills/review-ui/REQUIREMENT.md +0 -1
- package/claude/skills/review-ui/SKILL.md +1 -1
- package/claude/skills/role-orchestrator/REQUIREMENT.md +0 -3
- package/claude/skills/role-orchestrator/SKILL.md +8 -8
- package/claude/skills/role-orchestrator/references/orchestrator-dispatch.md +3 -3
- package/claude/skills/role-orchestrator/references/orchestrator-handoff.md +7 -10
- package/claude/skills/role-orchestrator/references/orchestrator-parked.md +2 -2
- package/claude/skills/role-orchestrator/references/orchestrator-refill.md +0 -3
- package/claude/skills/role-orchestrator/references/orchestrator-resume.md +1 -1
- package/claude/skills/role-planner/SKILL.md +2 -2
- package/claude/skills/role-reviewer/SKILL.md +1 -1
- package/claude/skills/role-worker/SKILL.md +2 -2
- package/claude/skills/session-compact/REQUIREMENT.md +1 -4
- package/claude/skills/session-compact/SKILL.md +3 -13
- package/claude/skills/session-compact/references/handoff-note.md +2 -2
- package/claude/skills/session-map/REQUIREMENT.md +1 -9
- package/claude/skills/session-map/SKILL.md +8 -16
- package/{standards → claude/skills/session-map/references}/session.md +17 -11
- package/claude/skills/session-relay/REQUIREMENT.md +1 -1
- package/claude/skills/session-resume/REQUIREMENT.md +4 -6
- package/claude/skills/session-resume/SKILL.md +3 -9
- package/claude/skills/session-worktree/SKILL.md +1 -1
- package/claude/skills/session-worktree/references/main-root-writes.md +2 -2
- package/claude/skills/systematic-debugging/REQUIREMENT.md +0 -1
- package/claude/skills/target-check/REQUIREMENT.md +3 -3
- package/claude/skills/target-check/SKILL.md +1 -1
- package/claude/skills/target-check/references/domains.md +1 -1
- package/claude/skills/target-setup/REQUIREMENT.md +4 -4
- package/claude/skills/target-setup/SKILL.md +3 -3
- package/claude/skills/target-setup/references/detect.md +1 -1
- package/claude/skills/task-board/SKILL.md +4 -4
- package/claude/skills/task-board/references/archive.md +1 -1
- package/{standards → claude/skills/task-board/references}/board.md +9 -0
- package/claude/skills/task-board/references/decline.md +1 -1
- package/{standards → claude/skills/task-board/references}/tasks.md +13 -8
- package/claude/skills/teach-workspace/SKILL.md +1 -1
- package/claude/skills/teach-workspace/references/revisit.md +1 -1
- package/{standards → claude/skills/teach-workspace/references}/teach.md +17 -5
- package/claude/skills/ux-audit/REQUIREMENT.md +2 -2
- package/claude/skills/ux-audit/SKILL.md +2 -3
- package/claude/skills/write-human/REQUIREMENT.md +0 -1
- package/claude/skills/write-human/SKILL.md +1 -1
- package/docs/agents/audits.md +1 -1
- package/docs/agents/canvas.md +1 -1
- package/docs/agents/commands.md +1 -6
- package/docs/agents/context-audit-checks.md +9 -23
- package/docs/agents/context-audit.md +7 -15
- package/docs/agents/context-classify.md +5 -5
- package/docs/agents/counts.md +5 -5
- package/docs/agents/drift-surfaces.md +2 -2
- package/docs/agents/index.md +3 -5
- package/docs/agents/install-and-sync.md +6 -6
- package/docs/agents/intake.md +1 -1
- package/docs/agents/records-stale.md +5 -5
- package/docs/agents/records-validate.md +1 -1
- package/docs/agents/records.md +2 -2
- package/docs/agents/restated.md +1 -1
- package/docs/agents/rule-citations.md +1 -1
- package/docs/agents/skills-audit.md +2 -2
- package/docs/agents/state-scoped-risk.md +2 -2
- package/docs/agents/superseded.md +2 -2
- package/docs/agents/tasks-plans.md +1 -1
- package/docs/agents/tasks-validate.md +1 -1
- package/docs/agents/tasks.md +1 -1
- package/docs/agents/teach.md +1 -1
- package/docs/agents/upstream.md +26 -2
- package/docs/target/migrations.md +24 -0
- package/docs/target/projects.md +5 -7
- package/docs/target/scenarios.md +2 -2
- package/docs/target/sync.md +3 -3
- package/docs/workflow/ai-workflow.md +7 -38
- package/docs/workflow/index.md +1 -1
- package/docs/workflow/operating-model.md +8 -8
- package/docs/workflow/parallel-features.md +7 -7
- package/docs/workflow/skill-map-on-request.md +12 -15
- package/docs/workflow/skill-map.md +20 -32
- package/docs/workflow/visual-design-workflow.md +11 -14
- package/governance/renames.toml +0 -19
- package/governance/rules/canon/605-worktrees.md +1 -1
- package/governance/rules/{standards → canon}/plan.md +4 -5
- package/governance/rules/canon/tasks.md +18 -0
- package/governance/stacks/base.toml +1 -1
- package/package.json +1 -1
- package/scripts/core/install-check.sh +1 -1
- package/scripts/core/regen-web-previews.ts +1 -1
- package/src/audits/catalog.ts +5 -97
- package/src/claude/cases/authoring.ts +0 -18
- package/src/claude/cases/misc.ts +0 -13
- package/src/claude/cases/setup.ts +3 -20
- package/src/claude/cases/workflow.ts +0 -33
- package/src/claude/seeds.ts +1 -7
- package/src/claude/skills-audit.ts +1 -1
- package/src/cli/help.ts +1 -4
- package/src/cli.ts +0 -4
- package/src/commands/claude.ts +8 -14
- package/src/commands/context.ts +18 -280
- package/src/commands/feedback.ts +22 -91
- package/src/commands/records.ts +5 -5
- package/src/commands/sync.ts +5 -3
- package/src/commands/upstream.ts +135 -0
- package/src/context/audit.ts +5 -14
- package/src/context/classify/extract.ts +6 -13
- package/src/context/classify/patterns.ts +2 -41
- package/src/context/classify/prompts.ts +2 -6
- package/src/context/classify/run.ts +3 -3
- package/src/context/folders.ts +7 -12
- package/src/context/gate.ts +11 -91
- package/src/context/requirements.ts +13 -4
- package/src/counts/scan.ts +3 -3
- package/src/design/components.ts +2 -2
- package/src/feedback/body.ts +0 -12
- package/src/gate/measures.ts +6 -57
- package/src/gov/citations.ts +9 -3
- package/src/gov/restated.ts +3 -3
- package/src/markdown/structure.ts +2 -2
- package/src/migrate/record-layout.ts +3 -3
- package/src/records/ordinal.ts +1 -1
- package/src/records/prune.ts +2 -1
- package/src/records/stale-canonical.ts +2 -2
- package/src/roots/record.ts +1 -1
- package/src/sandbox/scenario.ts +115 -11
- package/src/shipped/references.ts +3 -3
- package/src/standards/read.ts +31 -0
- package/src/sync/seeds-report.ts +1 -1
- package/src/tasks/reach.ts +2 -2
- package/src/tasks/validate.ts +1 -1
- package/src/teach/workspace.ts +1 -1
- package/src/upstream/cursor.ts +1 -1
- package/src/upstream/due.ts +128 -0
- package/src/upstream/releases.ts +2 -1
- package/standards/context.md +3 -5
- package/standards/design.md +2 -3
- package/standards/index.md +0 -22
- package/standards/publish.md +1 -1
- package/standards/skill.md +1 -1
- package/tooling/base/reference.md +1 -1
- package/tooling/claude/reference.md +6 -20
- package/tooling/claude/seeds/.claude/hooks/records-index.sh +8 -20
- package/tooling/claude/seeds/.claude/hooks/standards-audit.sh +3 -3
- package/tooling/claude/seeds/CLAUDE.md +1 -3
- package/tooling/claude/seeds/canon/REQUIREMENTS.md +2 -9
- package/tooling/web/configs/e2e/screenshot.ts +0 -1
- package/claude/skills/auto-ship/references/review-findings.md +0 -20
- package/claude/skills/bash-cli-script/REQUIREMENT.md +0 -43
- package/claude/skills/bash-cli-script/SKILL.md +0 -53
- package/claude/skills/bash-cli-script/references/template.md +0 -19
- package/claude/skills/canon-operator/REQUIREMENT.md +0 -62
- package/claude/skills/canon-operator/SKILL.md +0 -113
- package/claude/skills/canon-rollout/REQUIREMENT.md +0 -59
- package/claude/skills/canon-rollout/SKILL.md +0 -140
- package/claude/skills/canon-rollout/references/failure-recovery.md +0 -20
- package/claude/skills/context-fold/references/anchor-sweep.md +0 -58
- package/claude/skills/context-fold/references/wireframe-sweep.md +0 -45
- package/claude/skills/create-standard/REQUIREMENT.md +0 -33
- package/claude/skills/create-standard/SKILL.md +0 -31
- package/claude/skills/design-extract/REQUIREMENT.md +0 -42
- package/claude/skills/design-extract/SKILL.md +0 -108
- package/claude/skills/draft-and-pick/references/frame.html +0 -118
- package/claude/skills/draft-doc/references/wireframes.md +0 -48
- package/claude/skills/markdown-propose/REQUIREMENT.md +0 -47
- package/claude/skills/markdown-propose/SKILL.md +0 -122
- package/claude/skills/markdown-propose/references/format.md +0 -118
- package/claude/skills/memory-capture/REQUIREMENT.md +0 -50
- package/claude/skills/memory-capture/SKILL.md +0 -117
- package/claude/skills/memory-review/REQUIREMENT.md +0 -52
- package/claude/skills/memory-review/SKILL.md +0 -129
- package/claude/skills/memory-review/references/later-phases.md +0 -118
- package/claude/skills/memory-review/references/receipt-format.md +0 -64
- package/claude/skills/project-commands/REQUIREMENT.md +0 -42
- package/claude/skills/project-commands/SKILL.md +0 -87
- package/claude/skills/repo-metadata/REQUIREMENT.md +0 -37
- package/claude/skills/repo-metadata/SKILL.md +0 -54
- package/claude/skills/restate-plainly/REQUIREMENT.md +0 -41
- package/claude/skills/restate-plainly/SKILL.md +0 -41
- package/claude/skills/review-branch/REQUIREMENT.md +0 -40
- package/claude/skills/review-branch/SKILL.md +0 -137
- package/claude/skills/seed-sync/REQUIREMENT.md +0 -45
- package/claude/skills/seed-sync/SKILL.md +0 -158
- package/claude/skills/sketch-design/REQUIREMENT.md +0 -38
- package/claude/skills/sketch-design/SKILL.md +0 -94
- package/claude/skills/ux-walkthrough/REQUIREMENT.md +0 -56
- package/claude/skills/ux-walkthrough/SKILL.md +0 -53
- package/claude/skills/ux-walkthrough/references/builds.md +0 -15
- package/claude/skills/ux-walkthrough/references/candidate-pages.md +0 -11
- package/claude/skills/ux-walkthrough/references/measuring.md +0 -22
- package/claude/skills/ux-walkthrough/references/record.md +0 -36
- package/claude/skills/ux-walkthrough/references/relay.md +0 -25
- package/docs/agents/architecture-record.md +0 -36
- package/docs/agents/review-classification.md +0 -76
- package/governance/rules/canon/603-memory.md +0 -11
- package/governance/rules/lang/120-bash.md +0 -18
- package/governance/rules/standards/architecture.md +0 -13
- package/governance/rules/standards/groundwork.md +0 -13
- package/governance/rules/standards/intake.md +0 -12
- package/governance/rules/standards/memory.md +0 -12
- package/governance/rules/standards/ready.md +0 -13
- package/governance/rules/standards/requirements.md +0 -12
- package/governance/rules/standards/session.md +0 -13
- package/governance/rules/standards/tasks.md +0 -15
- package/governance/rules/standards/teach.md +0 -14
- package/governance/rules/standards/wiki.md +0 -13
- package/governance/rules/standards/wireframes.md +0 -13
- package/src/autoship/classify.ts +0 -75
- package/src/autoship/paths.ts +0 -50
- package/src/commands/autoship.ts +0 -129
- package/src/commands/repo.ts +0 -393
- package/src/context/architecture.ts +0 -654
- package/src/context/wireframe-states.ts +0 -238
- package/src/repo/metadata.ts +0 -206
- package/standards/architecture.md +0 -127
- package/standards/memory.md +0 -158
- package/standards/mermaid.md +0 -64
- package/standards/requirements.md +0 -79
- package/standards/wiki.md +0 -77
- package/standards/wireframes.md +0 -143
- package/tooling/claude/seeds/.claude/memory/index.md +0 -8
- package/tooling/claude/seeds/canon/ARCHITECTURE.md +0 -23
- package/tooling/claude/seeds/canon/wireframes/index.md +0 -8
- /package/{standards → claude/skills/create-skill/references}/skill-practice.md +0 -0
- /package/{standards → claude/skills/create-skill/references}/skill-requirement.md +0 -0
- /package/{standards → claude/skills/plan-feature/references}/plan-lifecycle.md +0 -0
- /package/{standards → claude/skills/plan-groundwork/references}/groundwork-spikes.md +0 -0
- /package/{standards → claude/skills/task-board/references}/tasks-decline.md +0 -0
- /package/{standards → claude/skills/teach-workspace/references}/glossary.md +0 -0
|
@@ -1,10 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Groundwork reference
|
|
3
3
|
description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
|
|
4
|
-
paths:
|
|
5
|
-
- '.canon/groundwork/**'
|
|
6
|
-
rule:
|
|
7
|
-
- 'Follow the groundwork spikes standard for `08-spikes.md` and the folders holding what a spike produced. Read it with `canon standards groundwork-spikes`.'
|
|
8
4
|
---
|
|
9
5
|
|
|
10
6
|
# Groundwork reference
|
|
@@ -13,6 +9,23 @@ Applies to a groundwork track at `.canon/groundwork/<nn>-<slug>/`. A track measu
|
|
|
13
9
|
|
|
14
10
|
The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs it against a compaction dropping a session's reasoning before a push, so the handoff file has to be self-contained.
|
|
15
11
|
|
|
12
|
+
## Contents
|
|
13
|
+
|
|
14
|
+
- [Scope](#scope)
|
|
15
|
+
- [Folder name](#folder-name)
|
|
16
|
+
- [What a working track looks like](#what-a-working-track-looks-like)
|
|
17
|
+
- [Frontmatter and dating](#frontmatter-and-dating)
|
|
18
|
+
- [Reserved numbers](#reserved-numbers)
|
|
19
|
+
- [README.md](#readmemd)
|
|
20
|
+
- [01-current-state.md](#01-current-statemd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
|
|
21
|
+
- [00-scope.md](#00-scopemd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
|
|
22
|
+
- [06-decision.md](#06-decisionmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
|
|
23
|
+
- [07-next-session.md](#07-next-sessionmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
|
|
24
|
+
- [Open questions](#open-questions)
|
|
25
|
+
- [Conventions](#conventions)
|
|
26
|
+
- [Anti-patterns](#anti-patterns)
|
|
27
|
+
- [Template](#template)
|
|
28
|
+
|
|
16
29
|
## Scope
|
|
17
30
|
|
|
18
31
|
Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout, ordinal naming, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
|
|
@@ -9,7 +9,7 @@ metadata:
|
|
|
9
9
|
|
|
10
10
|
Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
|
|
11
11
|
|
|
12
|
-
Read `${CLAUDE_SKILL_DIR}
|
|
12
|
+
Read `${CLAUDE_SKILL_DIR}/references/intake.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter and dating rules, the item format, and the answer contract. Do not work them from memory.
|
|
13
13
|
|
|
14
14
|
## Routing
|
|
15
15
|
|
|
@@ -44,7 +44,7 @@ List `.canon/intake/` from the project root and match the topic against the slug
|
|
|
44
44
|
|
|
45
45
|
Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
|
|
46
46
|
|
|
47
|
-
With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Claim the ordinal and create the folder in one act with `canon records ordinal intake <slug> --claim`, per `${CLAUDE_SKILL_DIR}
|
|
47
|
+
With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Claim the ordinal and create the folder in one act with `canon records ordinal intake <slug> --claim`, per `${CLAUDE_SKILL_DIR}/references/intake.md`. Where the installed binary carries no such subcommand, fall back to listing both `.canon/intake/` and `.canon/groundwork/` and taking the highest ordinal present across the two, incremented. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
|
|
48
48
|
|
|
49
49
|
## Step 2: orient
|
|
50
50
|
|
|
@@ -52,7 +52,6 @@ Read these in parallel from the project root, skipping any that do not exist:
|
|
|
52
52
|
|
|
53
53
|
- `CLAUDE.md`: behavior rules, conventions, commands
|
|
54
54
|
- `canon/REQUIREMENTS.md`: scope and non-goals
|
|
55
|
-
- `canon/ARCHITECTURE.md`: decisions already made
|
|
56
55
|
- `.canon/tasks/index.md`: what is already tracked. Open a task file whose entry looks related to an item.
|
|
57
56
|
|
|
58
57
|
Then read only what a live item needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
|
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Intake reference
|
|
3
3
|
description: Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
|
|
4
|
-
paths:
|
|
5
|
-
- '.canon/intake/**'
|
|
6
4
|
---
|
|
7
5
|
|
|
8
6
|
# Intake reference
|
|
@@ -11,6 +9,23 @@ Applies to an intake folder at `.canon/intake/<nn>-<slug>/`. One folder holds on
|
|
|
11
9
|
|
|
12
10
|
The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so the shape below survives only by being read.
|
|
13
11
|
|
|
12
|
+
<!-- canon-length-exempt: the folder shape and the item template share one reader, and a split into a second reference is queued as its own change -->
|
|
13
|
+
|
|
14
|
+
## Contents
|
|
15
|
+
|
|
16
|
+
- [Scope](#scope)
|
|
17
|
+
- [Folder name](#folder-name)
|
|
18
|
+
- [What a working intake looks like](#what-a-working-intake-looks-like)
|
|
19
|
+
- [Files](#files)
|
|
20
|
+
- [Frontmatter and dating](#frontmatter-and-dating)
|
|
21
|
+
- [00-overview.md](#00-overviewmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
|
|
22
|
+
- [Item format](#item-format)
|
|
23
|
+
- [The answer contract](#the-answer-contract)
|
|
24
|
+
- [Retrieval](#retrieval)
|
|
25
|
+
- [Conventions](#conventions)
|
|
26
|
+
- [Anti-patterns](#anti-patterns)
|
|
27
|
+
- [Template](#template)
|
|
28
|
+
|
|
14
29
|
## Scope
|
|
15
30
|
|
|
16
31
|
Governs an intake folder under `.canon/intake/<nn>-<slug>/`: folder layout, ordinal naming, the reserved index number, frontmatter and dating, the item format, the answer contract, and retrieval.
|
|
@@ -43,6 +43,6 @@ The batching fails a fifth way. A folder holding thirty unread items put as thir
|
|
|
43
43
|
|
|
44
44
|
- Filing a dump and writing the items, which is `plan-intake` and owns every other write into the folder
|
|
45
45
|
- Promoting an answered item onto the board, which is `task-board` and runs after the answers land
|
|
46
|
-
- The item format, the answer contract, and retrieval, which the
|
|
46
|
+
- The item format, the answer contract, and retrieval, which the `plan-intake` skill's `references/intake.md` owns and this skill cites
|
|
47
47
|
- The comparable answer slots in groundwork and feature plans, which carry their own contracts and are a separate measurement
|
|
48
48
|
- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so answering is the operator's call rather than a description match.
|
|
@@ -12,7 +12,7 @@ Put an intake folder's unread items as batched questions, then land each selecti
|
|
|
12
12
|
|
|
13
13
|
A folder is answered by opening each cluster file and typing under the item, which on a dump spanning six clusters means navigating to each in turn. This walks the same items in chat and writes the answers back, so the file rather than the conversation stays the record.
|
|
14
14
|
|
|
15
|
-
Read `${CLAUDE_SKILL_DIR}
|
|
15
|
+
Read `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` before writing anything. It holds the item format and the answer contract this skill is bound by.
|
|
16
16
|
|
|
17
17
|
## Guards
|
|
18
18
|
|
|
@@ -42,7 +42,7 @@ Do not push a red follow-up.
|
|
|
42
42
|
|
|
43
43
|
## Step 4: refresh stale docs
|
|
44
44
|
|
|
45
|
-
The fixes may have changed or added behavior that `.claude/` context entries
|
|
45
|
+
The fixes may have changed or added behavior that `.claude/` context entries or docs describe. Refresh them with the `context-fold` skill, which maps the changed files to the entries that reference them and rewrites the stale sections. Do not reimplement that mapping here. When a fix adds a new capability with no existing entry, `context-fold` flags it rather than creating one.
|
|
46
46
|
|
|
47
47
|
## Step 5: rebase a stale branch
|
|
48
48
|
|
|
@@ -37,14 +37,14 @@ The axes also said nothing about a change that passes by lowering the bar it has
|
|
|
37
37
|
|
|
38
38
|
## Must not
|
|
39
39
|
|
|
40
|
-
- State a severity or a posting rule. `review-pr`
|
|
40
|
+
- State a severity or a posting rule. `review-pr` owns the ladder.
|
|
41
41
|
- Restate the high-signal filter either procedure carries
|
|
42
|
-
- Name a repository-specific capture layout, width list, or folder. The evidence marker
|
|
42
|
+
- Name a repository-specific capture layout, width list, or folder. The evidence marker is a target contract, and everything else is the project's.
|
|
43
43
|
- Carry a per-surface reference beyond security and rendered output before a measured miss asks for one
|
|
44
44
|
|
|
45
45
|
## Out of scope
|
|
46
46
|
|
|
47
|
-
- Running a review, reading the diff, posting findings, and grading them: `review-
|
|
47
|
+
- Running a review, reading the diff, posting findings, and grading them: `review-pr`
|
|
48
48
|
- The high-signal filter and the severity ladder, which stay in each procedure body
|
|
49
49
|
- Which layer a test belongs at: `test-craft`
|
|
50
50
|
- Capturing screenshots or writing the visual checklist: `canon pr evidence` and `ui-checklist`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: review-craft
|
|
3
|
-
description: Carries what a code review looks for and how much evidence a finding needs, from design and scope through breakage outside the diff, a test or check the change weakens to pass, performance, developer experience, executable prose, stale docs, security classes, and rendered output checked against the screenshots a pull request carries. Use when reviewing a change, when a review procedure loads it for its axes, or when asked "what should a review look for", "what does a good review check", "how sure do I need to be before flagging this", or "did the review look at the screenshots". Do NOT use to run a review, post it, or grade its findings, which is `review-
|
|
3
|
+
description: Carries what a code review looks for and how much evidence a finding needs, from design and scope through breakage outside the diff, a test or check the change weakens to pass, performance, developer experience, executable prose, stale docs, security classes, and rendered output checked against the screenshots a pull request carries. Use when reviewing a change, when a review procedure loads it for its axes, or when asked "what should a review look for", "what does a good review check", "how sure do I need to be before flagging this", or "did the review look at the screenshots". Do NOT use to run a review, post it, or grade its findings, which is `review-pr`, and do NOT use for a deliberate full security audit, which is the built-in `security-review`.
|
|
4
4
|
metadata:
|
|
5
5
|
family: build
|
|
6
6
|
---
|
|
@@ -102,7 +102,7 @@ Three scope checks follow the walk:
|
|
|
102
102
|
|
|
103
103
|
## What this delegates
|
|
104
104
|
|
|
105
|
-
- Which files a pass reads, the high-signal filter, the severity ladder, and where findings go: `review-
|
|
105
|
+
- Which files a pass reads, the high-signal filter, the severity ladder, and where findings go: `review-pr`
|
|
106
106
|
- Which layer a test belongs at and what makes it good: `test-craft`
|
|
107
107
|
- Writing what a reviewer should look at on a rendered change: `ui-checklist`
|
|
108
108
|
- A deliberate full security audit of a codebase: the built-in `security-review`
|
|
@@ -6,7 +6,7 @@ Stills are this pass's evidence. Driving the running app through the checklist b
|
|
|
6
6
|
|
|
7
7
|
## When it applies
|
|
8
8
|
|
|
9
|
-
The diff touches a file that paints: markup, a stylesheet, a component or template, a design token file, a rendered document source
|
|
9
|
+
The diff touches a file that paints: markup, a stylesheet, a component or template, a design token file, or a rendered document source. Or the pull request carries an evidence comment, whatever the diff touches.
|
|
10
10
|
|
|
11
11
|
## First, check that a screenshot exists
|
|
12
12
|
|
|
@@ -59,11 +59,11 @@ A second theme earns a read only when the diff touches a color token. Name the s
|
|
|
59
59
|
|
|
60
60
|
## Comparing
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Check each opened image against the layout its checklist box claims, and check `canon/DESIGN.md` for the tokens the image makes visible: color, type scale, spacing, and component rules.
|
|
63
63
|
|
|
64
|
-
Read the width and theme from whatever the image path carries, and fix no width list, since which widths matter belongs to the project. Skip
|
|
64
|
+
Read the width and theme from whatever the image path carries, and fix no width list, since which widths matter belongs to the project. Skip the design file comparison silently when the project has none.
|
|
65
65
|
|
|
66
|
-
A finding names the
|
|
66
|
+
A finding names the checklist box or design-file line the image breaks, never a taste.
|
|
67
67
|
|
|
68
68
|
## The checklist
|
|
69
69
|
|
|
@@ -49,5 +49,5 @@ Scoping a later pass off GitHub's review stamp skipped real work. On 2026-09-07
|
|
|
49
49
|
## Out of scope
|
|
50
50
|
|
|
51
51
|
- Fixing what it finds, which `review-address` owns. The split is by side of the channel: this one posts findings from an independent session and that one consumes them.
|
|
52
|
-
- Reviewing local uncommitted work
|
|
52
|
+
- Reviewing local uncommitted work. This skill posts to a pull request it did not write.
|
|
53
53
|
- Merging, which stays the human's decision
|
|
@@ -1,16 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: review-pr
|
|
3
|
-
description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes.
|
|
3
|
+
description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes.
|
|
4
4
|
metadata:
|
|
5
5
|
family: after-pr
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Review PR
|
|
9
9
|
|
|
10
|
-
This is the orchestrator's independent review
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
findings to the PR, so the vantage is independent and the output is durable.
|
|
10
|
+
This is the orchestrator's independent review. It reviews an open PR the session
|
|
11
|
+
did not write and posts the findings to the PR, so the vantage is independent
|
|
12
|
+
and the output is durable.
|
|
14
13
|
|
|
15
14
|
It posts at least twice over a pull request's life. A first pass opens the
|
|
16
15
|
review against the whole change, and every later pass reads only the commits
|
|
@@ -32,7 +31,7 @@ reader scanning the thread finds the current verdict where the last one sat.
|
|
|
32
31
|
|
|
33
32
|
## Guards
|
|
34
33
|
|
|
35
|
-
- If no open PR resolves for the target branch via `canon pr head --json`, stop: `❌ No open PR to review. Open one first
|
|
34
|
+
- If no open PR resolves for the target branch via `canon pr head --json`, stop: `❌ No open PR to review. Open one first.`
|
|
36
35
|
- Review and post. Do not merge. Merging is the human's gate.
|
|
37
36
|
|
|
38
37
|
## Step 1: resolve the PR and read context
|
|
@@ -59,7 +58,6 @@ Read these in parallel from the project root, skipping any that do not exist:
|
|
|
59
58
|
|
|
60
59
|
- `CLAUDE.md`: project type, conventions, and commands
|
|
61
60
|
- `canon/REQUIREMENTS.md`: feature scope and non-goals
|
|
62
|
-
- `canon/ARCHITECTURE.md`: technical design decisions
|
|
63
61
|
- `.canon/tasks/priority.md`: where this feature sits on the board and what each neighboring row waits on. Resolve this one at the main worktree root the way `session-worktree` does, since the board is gitignored and a linked worktree holds no copy of it
|
|
64
62
|
- `.canon/plans/feature-<slug>.md` for the branch, when present: the intent the PR should satisfy, and its `**Review focus:**` section as the inputs this pass must confirm the diff handles
|
|
65
63
|
|
|
@@ -53,7 +53,6 @@ A verdict also goes stale without saying so. A push after the pass changes what
|
|
|
53
53
|
## Out of scope
|
|
54
54
|
|
|
55
55
|
- Reviewing the code and the stills, which `review-pr` owns. The two run as separate sessions so each finishes on its own clock and neither hears the other.
|
|
56
|
-
- Inspecting a running app across many findings with the operator present, which `ux-walkthrough` owns
|
|
57
56
|
- Writing the checklist and its drivable format, which `ui-checklist` owns
|
|
58
57
|
- Dispatching the pass, polling its verdict, and lifting the draft mark, which `role-orchestrator` owns
|
|
59
58
|
- A subagent inside the code reviewer, dropped because its cost stays invisible until it returns
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: review-ui
|
|
3
|
-
description: Drives an open pull request's visual checklist in the running app, one box at a time through a pinned agent browser, and posts one verdict per box as its own review comment under `## UI review` while the branch owes a fix, being a failed box, a sweep finding, or a box the page kept from being driven, and `## UI review closed` once it owes none. Never reads the diff, never builds the head, and never judges a box marked as taste. Use when asked to "drive the checklist", "run the UI review", "check the running app against the checklist", "review the PR in the browser", or launched as the UI reviewer beside a code review. Do NOT use to review the code or the screenshots, which is `review-pr`,
|
|
3
|
+
description: Drives an open pull request's visual checklist in the running app, one box at a time through a pinned agent browser, and posts one verdict per box as its own review comment under `## UI review` while the branch owes a fix, being a failed box, a sweep finding, or a box the page kept from being driven, and `## UI review closed` once it owes none. Never reads the diff, never builds the head, and never judges a box marked as taste. Use when asked to "drive the checklist", "run the UI review", "check the running app against the checklist", "review the PR in the browser", or launched as the UI reviewer beside a code review. Do NOT use to review the code or the screenshots, which is `review-pr`, or to write the checklist, which is `ui-checklist`.
|
|
4
4
|
metadata:
|
|
5
5
|
family: after-pr
|
|
6
6
|
---
|
|
@@ -41,8 +41,6 @@ Both halves of that channel are written here and one of them is performed elsewh
|
|
|
41
41
|
|
|
42
42
|
Cost never enters the decision to widen a wave. The rule weighing how many tracks to open measures conflict and review attention, and both describe what a worker writes rather than what the loop spends. Claude Code delivers a message from another session as a fresh turn carrying the whole accumulated context, and a recurring poll bills that same window on its own interval, so a wave's spend tracks this session's context rather than the work coming back. The one setting that bounds it reads as available to whoever finds it, and the two values that would bound it break the handback the loop runs on.
|
|
43
43
|
|
|
44
|
-
The session also records nothing of what it learns. Both other callers of memory capture are ship-chain skills and this one never ships, so the session taking every operator correction is the session with no moment that writes one down. Hanging that moment on the merge sweep answers it and bills the operator a capture pass per batch of merges while nothing is being built, which is a cost paid on the days shipping is fastest.
|
|
45
|
-
|
|
46
44
|
Dispatch parts from what it checked in three ways. The gate and the worker each derive the branch from their own reading of one plan and reach different strings, a launched worker inherits its launcher's model rather than the configured default, and a declared file set does not hold, since a track crosses the set its plan named.
|
|
47
45
|
|
|
48
46
|
## Must
|
|
@@ -65,7 +63,6 @@ Dispatch parts from what it checked in three ways. The gate and the worker each
|
|
|
65
63
|
- Write the pre-compact handoff with what no other file carries, and name the runbook that reads it back
|
|
66
64
|
- Carry the resume invocation and the owed poll restart in the handoff file itself, not in the runbook that writes it alone, since the file is what survives a compaction and the runbook is what a session has to already be holding to read
|
|
67
65
|
- Distinguish this resume from the general-purpose `session-resume`, since the name an operator reaches for first reaches a skill that knows nothing about the board
|
|
68
|
-
- Capture what the session learned at the handoff rather than in the merge sweep, and have the sweep report the debt dated from the last handoff, since a capture per batch of merges bills the operator a wait while nothing ships and an undated row reads the same however long the debt has run
|
|
69
66
|
- Retire the sessions this wave delivered before the map is written and ahead of any reclaim run, reporting a hand-launched one rather than acting on it, since no verb decides a planner or an unmerged worker and a live session holding a worktree is what the reclaim reading refuses on
|
|
70
67
|
- Carry every runbook the session cannot run from memory inside the skill, so each citation resolves for a project holding the plugin and nothing else
|
|
71
68
|
- State which rule wins where the tracked-file ban collides with the root instruction on small edits, and where a correction no open task owns goes
|
|
@@ -20,8 +20,8 @@ that builds something runs an existing skill. The queue rules below decide which
|
|
|
20
20
|
one runs and when.
|
|
21
21
|
|
|
22
22
|
Run `canon docs operating-model` for the model this skill enacts: the two roles
|
|
23
|
-
and what each owns, the loop end to end, why
|
|
24
|
-
|
|
23
|
+
and what each owns, the loop end to end, why this session's review is the first
|
|
24
|
+
one a change gets, and how a feature is sized.
|
|
25
25
|
|
|
26
26
|
## On invocation
|
|
27
27
|
|
|
@@ -37,13 +37,13 @@ Then output the state of play so the human knows what to launch, review, and mer
|
|
|
37
37
|
|
|
38
38
|
`priority.md` is the ordering source. `index.md` sorts by filename and says nothing about order, so read the sequence from the first and never infer it from the second. When `priority.md` is absent, report the queue and say the order is unrecorded.
|
|
39
39
|
|
|
40
|
-
Row position under `## Needs a plan` is what gets planned next, top first, per `${CLAUDE_SKILL_DIR}
|
|
40
|
+
Row position under `## Needs a plan` is what gets planned next, top first, per `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`. `backlog.md` carries what nobody is scheduling and is explicitly unordered, so read it for what exists and never as a queue. Report a backlog count rather than its rows, since listing them puts the length back in front of the reader the cut took it away from. This read reports how many rows exist and nothing about whether each still belongs there. `references/orchestrator-parked.md` is what re-tests a backlog row's currency, on its own trigger below.
|
|
41
41
|
|
|
42
42
|
No surface carries cross-version sequencing, so report none. A row's `Waiting on` cell states why that row sits where it does, and reasoning spanning several rows reaches this session only through whoever remembers it. Say nothing about an active version, since nothing in the tree states one and a version asserted from the board is the unsourced claim this omission exists against.
|
|
43
43
|
|
|
44
44
|
A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
|
|
45
45
|
|
|
46
|
-
On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `canon:session-map`, which
|
|
46
|
+
On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `canon:session-map`, which writes a session map per `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`, then adds the decisions taken under delegated authority as this role's extension. A lesson about how to work goes to the owning task's Findings. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
|
|
47
47
|
|
|
48
48
|
On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
|
|
49
49
|
|
|
@@ -63,12 +63,12 @@ Report the state of play in the invocation block, and open every later sweep rep
|
|
|
63
63
|
2. Decide parallelism and merge order. Note which plans depend on another or change a contract another consumes, since those hold, and which merely share a file, since those build together and the second to merge rebases.
|
|
64
64
|
3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
|
|
65
65
|
4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, run its conflict check against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the branch check refuses or the conflict check holds the row behind something already out.
|
|
66
|
-
5. Review the PR. When a worker opens a PR, its first pass runs through `review-pr` in a reviewer dispatched under `role-reviewer` when `### The review dispatch` below fires, and in this session otherwise. Either is the deep, independent pass. The worker's
|
|
66
|
+
5. Review the PR. When a worker opens a PR, its first pass runs through `review-pr` in a reviewer dispatched under `role-reviewer` when `### The review dispatch` below fires, and in this session otherwise. Either is the deep, independent pass. The worker's chain carries no review step, so this is the first review the change gets.
|
|
67
67
|
- Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and run the poll under the condition it states rather than checking the board by hand. That runbook holds the routing and the trigger, and a summary of it here is a second source that drifts from it.
|
|
68
68
|
6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `review-address`, rather than waiting for a person to relay it. Re-review when the worker's own message says the address pass finished, per the channel `role-worker` states, rather than polling for an answer nothing else marks as landed, and send the re-review back to the dispatched reviewer when one took the first pass. Once a pass posts `## Review closed`, a UI close names the current head wherever the PR carries a checklist, the poll run as `--check <number>` prints `CLEAR`, and `--check` reports `settled`, lift the pull request's draft mark yourself, per Boundaries below. Then the human merges. Tell each trailing worker whose files the merged diff touches to run `review-address`, which rebases it when it no longer merges or when `main` changed a file it writes, after each merge rather than once per wave.
|
|
69
69
|
- Read `${CLAUDE_SKILL_DIR}/references/orchestrator-handback.md` on reaching this step. It holds how the message is addressed and worded, what to do when no live session holds the branch, and where a worker's reply goes.
|
|
70
70
|
|
|
71
|
-
A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}
|
|
71
|
+
A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke. A path the two share forbids an act only where the conflict check in `orchestrator-dispatch.md` holds the pair, and otherwise names what the second branch to merge rebases over.
|
|
72
72
|
|
|
73
73
|
Stamp the block with the commit this session read the tree at, which the same section fixes the form of. A plan written during a refill sits in the ready queue while the wave it names merges, so the constraint is true when written and false when a worker reads it. The stamp is what lets that worker test the difference, and the standard carries the test.
|
|
74
74
|
|
|
@@ -85,9 +85,9 @@ Stamp the block with the commit this session read the tree at, which the same se
|
|
|
85
85
|
|
|
86
86
|
The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately without a task entry, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards and no later session recovers that vantage, which is the separation `review-pr` exists to supply.
|
|
87
87
|
|
|
88
|
-
Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when no such task exists or is expected.
|
|
88
|
+
Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when no such task exists or is expected.
|
|
89
89
|
|
|
90
|
-
Filing a row states the defect and the surface it was seen on, and stops there. The extent and the cause belong to whoever plans it, so a row names neither a count of how far the defect reaches nor the mechanism behind it. Say in a plain sentence in the task file that the count was not taken, where the row's shape invites one, rather than in a marker of any prescribed form. The board's own cell has no room for it, since `${CLAUDE_SKILL_DIR}
|
|
90
|
+
Filing a row states the defect and the surface it was seen on, and stops there. The extent and the cause belong to whoever plans it, so a row names neither a count of how far the defect reaches nor the mechanism behind it. Say in a plain sentence in the task file that the count was not taken, where the row's shape invites one, rather than in a marker of any prescribed form. The board's own cell has no room for it, since `${CLAUDE_SKILL_DIR}/../task-board/references/board.md` caps a `Waiting on` cell at two clauses.
|
|
91
91
|
|
|
92
92
|
A finding placed into another task's `## Findings` is filing under a second name and takes the same rule. An unverified cause costs more than an unverified count, since a count fails loudly at the first re-measurement while a mechanism nobody opened the module to check sends real work in the wrong direction.
|
|
93
93
|
|
|
@@ -50,7 +50,7 @@ This gate runs ahead of the two collision checks because it is the cheapest read
|
|
|
50
50
|
|
|
51
51
|
It also reads the plan rather than a cell describing one, which is the input the gate below it does not have. The conflict check reads the sets a dispatcher wrote into the constraints and the Touches column, so a cell omitting a renamed or relocated path clears a check the tree would fail, and what catches it then is a worker's message rather than any check.
|
|
52
52
|
|
|
53
|
-
A blank `- Answer:` is not an unanswered question. `${CLAUDE_SKILL_DIR}
|
|
53
|
+
A blank `- Answer:` is not an unanswered question. `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` fixes an empty slot as accepting the `- Suggested:` line above it, which is what makes a plan decision-ready in one pass. The narrow case this reads is `- Suggested: needs your call, <why>` and its two demonstrated paraphrases, `needs operator's call` and `needs the operator's call`, over an empty slot, the form that same standard writes where the answer turns on preference rather than on a technical default. A gate reading every blank slot as open would refuse every plan in the folder.
|
|
54
54
|
|
|
55
55
|
What it prevents is a halt nobody is watching for. `role-worker` instructs a session to stop on a question written as needing the operator's call, correctly and by its own body, so a dispatch that never reads the plan lands a worker in a wait for a person who does not know it is waiting. The worker's halt is not the defect, and the dispatch that made it necessary is.
|
|
56
56
|
|
|
@@ -84,7 +84,7 @@ No count binds this, and a shared file does not either. Hold a candidate behind
|
|
|
84
84
|
|
|
85
85
|
1. Dependency. The row or plan cites the track as something it waits on or builds over, including a stacked slice based on the other's branch.
|
|
86
86
|
2. Contract. One plan changes a contract the other consumes, such as an exported signature, a CLI verb's flags or JSON record, a skill step another skill cites, or a config or frontmatter key, read off the changing plan's `**Risks:**`.
|
|
87
|
-
3. Relocation. One plan moves, renames, splits, or deletes a path the other writes or reads, which a rebase cannot settle mechanically. Both sides of a rename sit before the colon of a `**Files to touch:**` entry, per `${CLAUDE_SKILL_DIR}
|
|
87
|
+
3. Relocation. One plan moves, renames, splits, or deletes a path the other writes or reads, which a rebase cannot settle mechanically. Both sides of a rename sit before the colon of a `**Files to touch:**` entry, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
|
|
88
88
|
4. Sweep. One plan rewrites a file or folder wholesale, such as a terminology pass or a `canon/context/` reflow, and the other writes inside it.
|
|
89
89
|
5. A stated reason, written on the hold: a singleton resource, or tracks interacting where no file reading shows, as a row creating a skill does with one counting that catalog. Nothing verifies the reason, so this hold stands only while the dispatcher applies it.
|
|
90
90
|
|
|
@@ -94,7 +94,7 @@ No practitioner source serializes on a shared file. Each builds in parallel and
|
|
|
94
94
|
|
|
95
95
|
Read `canon sessions list --json` for the branches in flight as well as the board, since a track a person launched by hand carries no row, and read the plan of any branch no row names. `canon tasks validate` and `canon tasks plan-reach` report the paths two rows share, which is a candidate list for the five holds and the paths the dispatch names. A shared folder means a Touches cell claimed it bare, so narrow that cell rather than reading the folder as a sweep.
|
|
96
96
|
|
|
97
|
-
A declared set predicts what a branch writes rather than bounding it, since `canon:context-fold`, `canon:docs-sync`, and the regenerated drift stages write past every plan. Such a crossing changes what the second branch rebases over rather than whether a row holds, and `canon tasks plan-reach` at `canon:git-ship` step
|
|
97
|
+
A declared set predicts what a branch writes rather than bounding it, since `canon:context-fold`, `canon:docs-sync`, and the regenerated drift stages write past every plan. Such a crossing changes what the second branch rebases over rather than whether a row holds, and `canon tasks plan-reach` at `canon:git-ship` step 4 names it before the pull request opens. What binds past the five holds is review attention, which `## Parallelism` in the skill body states. The one number this skill carries is the review dispatch's count of three in `orchestrator-review-dispatch.md`, which moves a review rather than binding a track, and this runbook carries none.
|
|
98
98
|
|
|
99
99
|
## Pick the model
|
|
100
100
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Orchestrator handoff runbook
|
|
3
|
-
description: Retirement act the wind-down owes the fleet it dispatched, the two sections an orchestrating session adds over the shared session map,
|
|
3
|
+
description: Retirement act the wind-down owes the fleet it dispatched, the two sections an orchestrating session adds over the shared session map, where a lesson goes from a session that never commits, and the resume invocation the file carries out
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
## Retire what the wave delivered
|
|
@@ -39,11 +39,10 @@ Report the retired sessions as a list, the hand-launched ones under it as a read
|
|
|
39
39
|
|
|
40
40
|
Write the pre-compaction handoff as orchestrator. Invoke `canon:session-map` for the generic half, which is the filename, the three core sections, the write procedure, the drift step and the ref it reads, and the citation rule. Everything in this section is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
|
|
41
41
|
|
|
42
|
-
Settle
|
|
42
|
+
Settle both steps below before the door writes, so one write carries the core and the extension together. The door reports the map as written and knows nothing of this role, so its success line ends the generic half rather than this runbook, and a session that stops there ships a map missing both of the things this section adds to it.
|
|
43
43
|
|
|
44
|
-
1.
|
|
45
|
-
2.
|
|
46
|
-
3. Close the file with the block below, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
|
|
44
|
+
1. Add `## Decisions taken under delegated authority` directly after `## State`, holding each decision and why it went that way, so nobody re-proposes it. It sits there rather than after the core because a decision is read against the state it was taken in.
|
|
45
|
+
2. Close the file with the block below, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
|
|
47
46
|
|
|
48
47
|
```markdown
|
|
49
48
|
Resume by loading the orchestrator skill and asking it to resume after a compaction. This repository spells that `/canon:role-orchestrator` followed by the request. Following <RESUME_RUNBOOK> reaches the same place with no skill loaded at all.
|
|
@@ -53,14 +52,12 @@ That resume reads the board and stops. It restarts nothing, so the review poll i
|
|
|
53
52
|
|
|
54
53
|
The delegated-authority section is the orchestrator's alone because a worker holds no delegation to have exercised, and a section a session cannot fill teaches its reader to skip the file. The closing block is the orchestrator's for the same reason from the other direction: it restarts a review poll no other role runs.
|
|
55
54
|
|
|
56
|
-
The substitution belongs in step
|
|
55
|
+
The substitution belongs in step 2 because that step ends the write. A reader who treats the list as finished elsewhere ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
|
|
57
56
|
|
|
58
57
|
That block sits in this runbook and again in the file this runbook writes, which is the fix rather than a copy for a later pass to collapse. A session has to already be holding this runbook to read it, and a compaction that took the skill body took the routing to it too, so the session that most needs the resume is the one that can no longer find it. The map survives that, so it carries the invocation itself. Each of the two reaches a reader the other cannot.
|
|
59
58
|
|
|
60
59
|
The requirement is a resume request to the orchestrator skill with that skill loaded first. The command the block carries is this repository's spelling rather than the only one, since the skill ships to every target holding the plugin and each runs whatever client it runs. The poll restart is named beside it because the resume performs none.
|
|
61
60
|
|
|
62
|
-
|
|
61
|
+
This runbook varies the door rather than replacing it, which is why the door is invoked first and this runbook states only what differs. The generic half moved out whole, the drift step and its ref recovery with it, so nothing here restates a step the door already carries and the two cannot disagree.
|
|
63
62
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work.
|
|
63
|
+
This session commits nothing, and the orchestrator's boundaries forbid writing a context entry from it. A domain fact belongs to the task that owns the surface and goes in that task's Findings, and so does a lesson about how to work, since nothing reads a lesson left only in the map once the session after it is past it.
|
|
@@ -17,7 +17,7 @@ The sweep's own question stays distinct from this one. It asks which parked row
|
|
|
17
17
|
|
|
18
18
|
Every row under `## Up next` and `## Needs a plan` in `.canon/tasks/priority.md`. A `## Run now` row carries no blocker by definition, so the pass skips it. On the idle trigger, also every row in `.canon/tasks/backlog.md` when the file exists, per the trigger split above. Resolve the board, the backlog, and each task file at the main worktree root, the way `session-worktree` does.
|
|
19
19
|
|
|
20
|
-
Take the board rows in board order and finish one before opening the next. Clearing a row changes what the next row holds behind, so a pass that measures every row first and writes afterwards writes against a board it has already invalidated. On the idle trigger, walk the backlog after the board, in the file's own filename order, since `${CLAUDE_SKILL_DIR}
|
|
20
|
+
Take the board rows in board order and finish one before opening the next. Clearing a row changes what the next row holds behind, so a pass that measures every row first and writes afterwards writes against a board it has already invalidated. On the idle trigger, walk the backlog after the board, in the file's own filename order, since `${CLAUDE_SKILL_DIR}/../task-board/references/board.md` fixes that file as unordered and nothing about a row's position there means anything to preserve mid-pass.
|
|
21
21
|
|
|
22
22
|
## Re-testing a row
|
|
23
23
|
|
|
@@ -35,7 +35,7 @@ Write the result into the row. A re-test reported in chat is lost at the next co
|
|
|
35
35
|
|
|
36
36
|
## Re-testing a backlog row
|
|
37
37
|
|
|
38
|
-
A backlog row carries no blocker cell, since `${CLAUDE_SKILL_DIR}
|
|
38
|
+
A backlog row carries no blocker cell, since `${CLAUDE_SKILL_DIR}/../task-board/references/board.md` fixes `backlog.md` as a flat list of links with no state of its own. The five kinds above test what a blocker names, and a backlog row names none, so this pass asks the board-or-backlog question the standard already states instead: has the work in front of the row landed, or has the world changed under it. Read the answer from the task file's own `## Findings` and its origin line (`Plan:`, `Groundwork:`, `Intake:`, or `Issue:`), which name what the row was filed against and whether the fact behind it still holds.
|
|
39
39
|
|
|
40
40
|
Clearing a row answers yes to that question. It is not a count of how long the row has waited: `## Two results that are not a re-test` below refuses age as evidence for a board row, and it refuses it here on the same ground, since a row untouched for weeks is not more clearable than one added yesterday.
|
|
41
41
|
|
|
@@ -24,7 +24,6 @@ It counts unclaimed plans against workers rather than reading the reserve in ste
|
|
|
24
24
|
7. Write a plan for each newly promoted task with `plan-feature`, carrying the in-flight constraint that `## The loop` in the skill body states, then report:
|
|
25
25
|
|
|
26
26
|
```plaintext
|
|
27
|
-
Capture: owed since <the last handoff, or session start when none has run>
|
|
28
27
|
Findings placed: <finding> → <destination>
|
|
29
28
|
Archived: <task>
|
|
30
29
|
Promoted: <task>, touches <surfaces>, parallel with <task>, sharing <paths or none>
|
|
@@ -33,8 +32,6 @@ Backlogged: <task>, because <what stopped being near-term>
|
|
|
33
32
|
Ready now: <tasks with plans, and what each waits on>
|
|
34
33
|
```
|
|
35
34
|
|
|
36
|
-
The capture row states a standing debt rather than a per-run result. Running capture from here costs the operator a pass between merges while nothing ships, so the row leaves the timing to them and dates the debt, since a capture owed for twenty minutes and one owed all day want different answers and undated text reads the same either way. `orchestrator-handoff.md` holds the step that pays it.
|
|
37
|
-
|
|
38
35
|
That block is the detail. Lead the reply with the three slots under `## Every later turn` in `orchestrator-output.md`, so the human reads what they own before the evidence for it.
|
|
39
36
|
|
|
40
37
|
A task that edits `canon/context/` entries wholesale is a sweep under the conflict check, and holds every other task, because the root instruction file requires each task to update its own domain entry as it lands.
|
|
@@ -6,7 +6,7 @@ description: What to read back after a compaction, and how to treat a groundwork
|
|
|
6
6
|
Resume as orchestrator after a compaction. Read the board and the groundwork behind the live work before answering anything, because a compaction summary keeps conclusions and drops the reasoning that produced them.
|
|
7
7
|
|
|
8
8
|
1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Every path below resolves against it.
|
|
9
|
-
2. Read `.canon/tasks/priority.md` for the ordering and what each task waits on. Read the newest `.canon/tasks/session-*.md` when one exists, per `${CLAUDE_SKILL_DIR}
|
|
9
|
+
2. Read `.canon/tasks/priority.md` for the ordering and what each task waits on. Read the newest `.canon/tasks/session-*.md` when one exists, per `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`, and treat it as the previous session's scratch rather than a source.
|
|
10
10
|
3. Read the task file for every entry under `## Run now`, plus any entry a live pull request names.
|
|
11
11
|
4. Read the groundwork folder each of those tasks cites. Read `README.md` for the file map, then `06-decision.md` when the track is closed, or `07-next-session.md` and the numbered topic files when it is open. A task's Findings section is a lossy summary of its track, so planning against the summary re-derives what the folder already settled.
|
|
12
12
|
5. Run `gh pr list --state open` and `git log --oneline -5` to see what shipped since the folder was written.
|
|
@@ -41,14 +41,14 @@ Each item below is something a record needed and a launch string did not carry.
|
|
|
41
41
|
|
|
42
42
|
- The task file, and its `## Findings` before deciding anything. A row can carry its own disproof under a title that still states the original claim, which is how one trial nearly planned against a premise the file had already recorded as dead.
|
|
43
43
|
- The source files themselves, opened rather than summarized. Never a count quoted from the task file, which was wrong or stale in ten places across four plans.
|
|
44
|
-
- `CLAUDE.md` and
|
|
44
|
+
- `CLAUDE.md` and the context entries the row touches, for the decision and the alternative it was taken against rather than for the decision alone.
|
|
45
45
|
- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch conflict check already reads. Read it for the shared-path lines and the holds of the constraint block, never as a gate a plan must clear.
|
|
46
46
|
|
|
47
47
|
Two reads belong to the `plan-feature` path alone, since neither a groundwork
|
|
48
48
|
track nor an intake pass is sequenced behind another row or validated as a plan:
|
|
49
49
|
|
|
50
50
|
- The plan of any row this one is sequenced behind, including one already moved to `.canon/plans/archive/`. Reading a shipped plan produced the strongest constraint in the first trial and no brief asked for it.
|
|
51
|
-
- `${CLAUDE_SKILL_DIR}
|
|
51
|
+
- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` for the shape, then `canon records validate plans` and `canon markdown audit <the plan file>` on the file once it is written. Nothing else opens a plan, since `.canon/plans/` is gitignored and the audit's default path set is what git lists.
|
|
52
52
|
|
|
53
53
|
A groundwork or intake record passes through whatever its own skill and standard
|
|
54
54
|
name instead. The gitignored-folder problem is the same for all three, so run
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: role-reviewer
|
|
3
|
-
description: Asserts the reviewer role for a session dispatched to review one pull request another session built, holding what it may write, what it reads and never reads, the one message it owes on posting, and the acts it refuses. Use when asked to "be the reviewer", "you are a reviewer session", at the start of a dispatched or hand-launched review of one pull request, or when a reviewing session needs to know what it may not write or who it answers to. Do NOT use to run the pass itself, which is `review-pr` for the code and `review-ui` for the running app,
|
|
3
|
+
description: Asserts the reviewer role for a session dispatched to review one pull request another session built, holding what it may write, what it reads and never reads, the one message it owes on posting, and the acts it refuses. Use when asked to "be the reviewer", "you are a reviewer session", at the start of a dispatched or hand-launched review of one pull request, or when a reviewing session needs to know what it may not write or who it answers to. Do NOT use to run the pass itself, which is `review-pr` for the code and `review-ui` for the running app, or to make the cross-branch call across a wave.
|
|
4
4
|
metadata:
|
|
5
5
|
family: parallel
|
|
6
6
|
---
|
|
@@ -28,13 +28,13 @@ which `auto-ship` Step 2 loads.
|
|
|
28
28
|
|
|
29
29
|
## Where the session stands
|
|
30
30
|
|
|
31
|
-
- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`,
|
|
31
|
+
- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/ready/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.
|
|
32
32
|
- Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is true where this session stands and wrong about the world, and a reader with no second tree to check cannot separate the two.
|
|
33
33
|
- Build the plan the launch named. Do not write a second one when the path fails to resolve, since a row that cites a plan already has one and drafting another produces two plans for one row.
|
|
34
34
|
- Copy a ready folder's files verbatim to the paths its plan's constraints name, when the plan's `**Constraints:**` block names one, and edit only what the gate or the overview's own list requires. A rewrite discards the text the handoff exists to carry.
|
|
35
35
|
- Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft and no step anywhere un-marks, so a flag reading ready afterwards was lifted by the operator or by the controlling session acting on a closed review, each acting directly on the pull request, which GitHub requires before a merge. Re-drafting fights them, and no surface in the tree states a reason to.
|
|
36
36
|
- Refuse an instruction to lift the mark yourself, whoever sends it. This session cannot verify who is asking or whether review actually closed, so the refusal holds regardless of the sender's claimed authority.
|
|
37
|
-
- Rewrite a plan question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against an unanswered one, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}
|
|
37
|
+
- Rewrite a plan question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against an unanswered one, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
|
|
38
38
|
|
|
39
39
|
## The board is read-only
|
|
40
40
|
|
|
@@ -9,14 +9,13 @@ description: Why a plain session needs a handoff surface that is not the task bo
|
|
|
9
9
|
|
|
10
10
|
Without this skill, a session facing a compaction reaches for `session-map`, which writes `.canon/tasks/session-<slug>.md`. The board carries four such files today, and `session-resume` drops them by name prefix to read the real rows, so a reader works around a misplacement on every run.
|
|
11
11
|
|
|
12
|
-
`session-map` also carries the orchestrator's shape: a drift check against a start commit nothing records, a step for role sections, and a `## State` section. A session that shipped nothing pays all three to leave one note behind, and `
|
|
12
|
+
`session-map` also carries the orchestrator's shape: a drift check against a start commit nothing records, a step for role sections, and a `## State` section. A session that shipped nothing pays all three to leave one note behind, and the `session-map` skill's `references/session.md` already names a `## State` filled from the tree as non-conforming, which is the failure that shape invites.
|
|
13
13
|
|
|
14
14
|
Sessions also write the wrong thing into a handoff. They restate the tree, which survives a compaction, and omit what each decision beat, which does not.
|
|
15
15
|
|
|
16
16
|
## Must
|
|
17
17
|
|
|
18
18
|
- Write to `.canon/compact/`, outside the task board and outside scratch.
|
|
19
|
-
- Invoke `canon:memory-capture` before writing, so the note cites entries rather than repeating them.
|
|
20
19
|
- Carry a stated shape for the note, so what belongs in it is not re-derived per session.
|
|
21
20
|
- Require a citation for every claim, and a rejected alternative beside every decision.
|
|
22
21
|
- Decline in one line where the session holds nothing a compaction would destroy.
|
|
@@ -27,7 +26,6 @@ Sessions also write the wrong thing into a handoff. They restate the tree, which
|
|
|
27
26
|
- Write a task row, a plan, or anything under `.canon/tasks/`.
|
|
28
27
|
- Write a `## State` section, or any section a reader could fill from `git status`.
|
|
29
28
|
- Run a drift check or recover a start commit. Both belong to the role that ships code.
|
|
30
|
-
- Restate a memory entry the capture pass wrote.
|
|
31
29
|
- Lose its caller. The `PreCompact` hook names this skill on a manual compaction, and that hook plus an operator typing it are the two callers the third creation question asks for. A hook edit that names another skill leaves one caller, which is a reason to revisit this skill rather than to keep it.
|
|
32
30
|
|
|
33
31
|
## Guards
|
|
@@ -41,5 +39,4 @@ Sessions also write the wrong thing into a handoff. They restate the tree, which
|
|
|
41
39
|
|
|
42
40
|
- The orchestrator's handoff, which carries a drift check and a board row: `canon:session-map`. The two skills are held apart by role, so a plain session belongs here and a session holding `canon:role-orchestrator` belongs there.
|
|
43
41
|
- Reading a handoff back: `canon:session-resume`, which reads `.canon/compact/` ahead of the older task-board form.
|
|
44
|
-
- The memory pen, its routing and its shape: `canon:memory-capture` and `standards/memory.md`.
|
|
45
42
|
- A decision a groundwork track owns, which belongs in that track's `06-decision.md`: `canon:plan-groundwork`.
|