@erclx/canon 4.0.0

package/claude/skills/claude-ui-test/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: claude-ui-test
+description: Why UI changes split into what a browser can assert and what only an eye can judge, and why the visual half is written to disk rather than printed
+---
+
+# Claude UI test requirement
+
+## Gap
+
+Without this skill, UI work ships on the confidence of the session that wrote it. What verification does happen mixes the two kinds without noticing, so a checklist item about spacing sits beside one about a form submission, and neither is done properly because they need different work from different people. Tests get written against a config the project does not use, or duplicate what a component test already covers.
+
+The visual half is where the record is lost. A checklist printed into chat scrolls away before anyone verifies it, so the ship step has nothing to gate on and the work reads as verified because a list was produced. Written from a linked worktree against `pwd`, the file lands where the caller does not look.
+
+## Must
+
+- Split every change into automatable and visual-only before writing anything
+- Read the project's existing test config and patterns before writing a test against them
+- Assert a user action and its outcome per test, covering the happy path and the key edge cases
+- Run the tests after writing them and fix what fails
+- Write a produced checklist to the branch-derived path at the main worktree root, overwriting
+- Report that everything is covered rather than manufacturing a checklist to show work
+
+## Must not
+
+- Try to assert a visual property programmatically
+- Re-test what unit or component tests written during implementation already cover
+- Repeat the full checklist in chat, which is what made it evaporate
+- Stage or commit the checklist, which is gitignored scratch
+
+## Guards
+
+- No implementation context in the session: stop, since there is nothing to derive tests from
+- Every change automatable: skip the file write and report the coverage
+
+## Out of scope
+
+- Judging whether the UI is any good, which `claude-ux-audit` owns
+- Unit and component tests, which belong to implementation
+- Deciding whether an outstanding checklist blocks the ship, which the calling pipeline gates on
+- Performing the visual verification, which needs a person

package/claude/skills/claude-ui-test/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: claude-ui-test
+description: Generates and runs Playwright e2e tests for UI changes, with a manual checklist for visual-only items. Use after implementing UI changes, or when asked "what should I test", "what do I verify", or "give me a test checklist". Do NOT use in empty sessions with no implementation context.
+---
+
+# Claude UI test
+
+## Guards
+
+- If no implementation context exists in the session, stop: `❌ No implementation context. Describe what you built first.`
+
+## Analysis
+
+Review the session to identify what was built or changed. Categorize each change:
+
+- **Automatable:** interactions, state transitions, form submissions, keyboard navigation, conditional rendering, error states, empty states, loading states. These become Playwright e2e tests.
+- **Visual-only:** spacing, alignment, color, typography, layout proportions, animation timing. These become a manual checklist.
+
+Exclude anything already covered by unit or component tests written during implementation.
+
+## E2e tests
+
+Write Playwright tests for all automatable changes. Follow these rules:
+
+- Add tests to the existing e2e test file. If none exists, create `e2e/ui.test.ts`.
+- Use the project's existing Playwright config and test patterns. Read them first.
+- Each test should perform a user action and assert the expected outcome.
+- Cover both happy path and key edge cases (empty state, error state, boundary input).
+- For Chrome extensions: load the unpacked extension via Playwright's `--load-extension` flag and use the extension's sidepanel or popup URL as the test target.
+- Run the tests after writing them. Fix failures before finishing.
+
+Test structure:
+
+```typescript
+test('description of user flow', async ({ page }) => {
+  // Arrange: navigate, set up state
+  // Act: perform user action
+  // Assert: verify expected outcome
+})
+```
+
+## Manual checklist
+
+For visual-only items that cannot be asserted programmatically, produce a checklist. Group by feature area. Use `- [ ]` checkbox syntax.
+
+```markdown
+**What to verify visually:**
+
+**<Feature area>**
+
+- [ ] <action> → <expected visual result>
+```
+
+If all changes are automatable, skip the manual checklist:
+
+`✅ All changes covered by e2e tests. No manual verification needed.`
+
+### Persist the checklist
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+When a manual checklist is produced, write it directly to `.claude/review/ui-checklist-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the checklist 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.
+
+Skip the file write when all changes are covered by e2e tests and no checklist was produced.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+## Output order
+
+1. Write and run e2e tests (report pass/fail)
+2. If a manual checklist was produced, write it to file, then output only the file path in chat:
+   `📝 Wrote .claude/review/ui-checklist-<slug>.md`
+3. If no checklist was needed: `✅ All changes covered by e2e tests. No manual verification needed.`
+
+Do not repeat the full checklist in chat.

package/claude/skills/claude-ux-audit/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: claude-ux-audit
+description: Why UI roughness is reported against stated intent rather than taste, and why the audit observes without fixing
+---
+
+# Claude UX audit requirement
+
+## Gap
+
+Without this skill, UI roughness is found by users. An audit that does run reports personal taste, because nothing anchors it to what the project intended, so the findings are arguable and get argued rather than fixed. It flags work the board already marks in progress, which spends the reader's attention on a surface nobody claimed was finished.
+
+The pass slides into fixing what it finds, and then the audit and the change land together with no record of which observation drove which edit, so neither can be reviewed. Reported into chat, the whole thing evaporates before anyone acts on it, and the next audit rediscovers the same list.
+
+## Must
+
+- Read the design system and the per-surface wireframes as ground truth for intent before flagging any drift
+- Group findings by surface, since a surface is what a person opens and fixes
+- Cover missing feedback states, unhandled edge cases, inconsistencies, and friction in daily use
+- Write the full report to the branch-derived path at the main worktree root, overwriting
+- Report no observations rather than filling the list to show work
+
+## Must not
+
+- Suggest an implementation or change any code
+- Flag a surface the task board marks in progress
+- Report a preference no stated intent supports
+- Repeat the full report in chat, which is what loses it
+- Stage or commit the report, which is gitignored scratch
+
+## Guards
+
+- No UI surfaces in the project: stop, since there is nothing to audit
+
+## Out of scope
+
+- Fixing what it found, which is a separate change with its own review
+- Feature planning, which `claude-feature` owns
+- Verifying one specific change, which `claude-ui-test` owns
+- Defining the intent it audits against, which `claude-design-extract` and the wireframes own
+- Measuring what a running interface costs to paint, block, or shift, which `claude-ux-measure` owns. Contrast stays here rather than going with it, being computable from two color values this skill already reads off the token table.

package/claude/skills/claude-ux-audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: claude-ux-audit
+description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes, and do NOT use to measure what a running interface costs to paint, which is `claude-ux-measure`.
+---
+
+# Claude UX audit
+
+## Guards
+
+- If no UI files exist in the project (no JSX, TSX, Vue, Svelte, or HTML under `src/`), stop: `❌ No UI surfaces found to audit.`
+- If the request asks what the interface costs to paint, block, or shift at runtime, run nothing and name `claude-ux-measure`. This skill reads source and reaches no number a browser produces. Contrast is the exception and stays here, since it is computable from the two color values already in the token table.
+
+## Step 1: read context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: project type and conventions
+- `.claude/DESIGN.md`: visual intent, tokens, typography, spacing rules
+- `.claude/wireframes/index.md` + every `.claude/wireframes/<surface>.md`: intended UI layout, UI copy, interaction rules. Surfaces are loaded one file at a time during Step 3. Per `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`, these carry layout and intent, not implementation detail.
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+
+## Step 2: identify surfaces
+
+List the UI surfaces in the project. A surface is a distinct screen, page, panel, or major component (e.g. sidepanel, popup, settings page, empty state). Group files by surface. Do not audit speculative or unfinished code flagged in `.claude/tasks/` as in-progress.
+
+## Step 3: audit each surface
+
+For each surface, look for:
+
+1. **Missing feedback states**: loading, empty, error, disabled, in-progress
+2. **Unhandled edge cases**: long strings, overflow, zero items, many items, slow networks
+3. **Inconsistencies**: spacing, tone of voice, interaction patterns, icon use, keyboard affordances
+4. **Roughness in daily use**: friction, redundant steps, unclear affordances, ambiguous labels
+
+Use `.claude/DESIGN.md` and the per-surface `.claude/wireframes/<surface>.md` files as ground truth for intent. For each implementation surface, read the matching wireframe file before flagging drift. Observations only, no implementation suggestions or fixes.
+
+## Step 4: report and persist
+
+### Report format
+
+Start with a summary line. Group findings by surface. Omit surfaces with no findings.
+
+```markdown
+X observations across N surfaces.
+
+Surface: <name>
+
+- Missing feedback state: <observation>
+- Inconsistency: <observation>
+
+Surface: <other>
+
+- Edge case: <observation>
+```
+
+If nothing is wrong, use: `✅ No observations.`
+
+### Persist
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+Write the full report directly to `.claude/review/ux-audit-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the report 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.
+
+If there are no observations, write `✅ No observations.` to the file with a timestamp.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output only the summary line and the file path. Do not repeat the full report in chat.
+
+```plaintext
+X observations across N surfaces.
+📝 Wrote .claude/review/ux-audit-<slug>.md
+```
+
+If no observations: `✅ No observations. Wrote .claude/review/ux-audit-<slug>.md`

package/claude/skills/claude-ux-measure/REQUIREMENT.md

@@ -0,0 +1,48 @@
+---
+name: claude-ux-measure
+description: Why a rendering cost question is answered with a number against a published threshold, and why the runner is detected rather than prescribed
+---
+
+# Claude UX measure requirement
+
+## Gap
+
+Without this skill, a session asked what a page costs answers from source. It reads component code, names a suspicious loop, and reports a judgment, so nobody learns the number and the next session repeats the guess. Nothing in the corpus starts a browser, so the question has no surface at all and lands on whichever skill matched the word "UI".
+
+A session that does start one picks a runner on the spot. The reading then comes from a browser nobody chose, cannot be compared against the next run, and disappears with the chat. A number reported with no boundary beside it is the same dead end as the judgment it replaced, because a reader holding `1.9s` and no threshold concludes nothing from it.
+
+## Must
+
+- Detect the harness the project already carries before naming any runner
+- Report a number per metric beside the threshold it is measured against and the published source of that threshold
+- Cover paint, processor, and layout cost, and name what the run left unmeasured
+- Name the elements the layout figure came from, taken off the run that produced the median so the parts sum to the figure beside them
+- Distinguish a layout figure of zero from a harness that reported no attribution, since one is a page that held still and the other is a reading that went missing
+- Report what the measurement needs and stop when no harness is detected, since that is a project without a runner rather than a failure here
+- Take several readings and report the median, since one load carries startup noise wider than the gap between two thresholds
+- Write the reading to the branch-derived path at the main worktree root, overwriting
+- Reach the URL before measuring against it, starting the project's own command only when nothing already answers there
+- Leave the interface stopped and the probe deleted
+
+## Must not
+
+- Install a runner, add a dependency, or write a config to make detection succeed
+- Invent a threshold, or move a published one to fit a reading
+- Report an observation about the source in place of a measurement
+- Suggest a fix for what it measured, which is a change with its own review
+- Measure anything past the three metrics, since every adjacent ask doubles the run. Naming which elements shifted is not a fourth metric, being the composition of the third and already present in the reading it summarizes.
+- Read the source to improve an element name the harness gave. A better selector bought that way is the source judgment this skill replaces.
+
+## Guards
+
+- No command that serves an interface and no URL from the user: stop, since there is nothing to reach. Test for a servable interface rather than for source under a named folder, which refuses a project laying its tree out differently while its server sits ready
+- No harness detected: name the runners this can drive and stop
+- No URL derivable from the project's own commands: ask rather than guessing a port
+
+## Out of scope
+
+- Judging the interface against stated intent, which `claude-ux-audit` owns
+- Contrast, which is computable from two color values in the token table `claude-ux-audit` already reads. A contrast failure from a color computed at runtime stays invisible to that reader, and the cost is accepted rather than overlooked.
+- Network waterfall, bundle size, and accessibility, which no version of this measures
+- Writing behavioral tests against the interface, which `claude-ui-test` owns
+- Fixing what the reading found

package/claude/skills/claude-ux-measure/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: claude-ux-measure
+description: Measures paint, processor, and layout cost against a running interface and reports numbers against published thresholds. Detects the project's existing browser harness rather than requiring one. Use when asked "how fast is this page", "measure the UI", "what does this cost to render", "check Core Web Vitals", or "profile the interface". Do NOT use to judge UI quality by reading source, which is `claude-ux-audit`.
+---
+
+# Claude UX measure
+
+Report numbers. A sentence about what the source looks like is what this exists to replace, so every finding is a reading beside the threshold it is measured against.
+
+## Guards
+
+- If the project names no command that serves an interface and the user names no URL, stop: `❌ Nothing to serve. Name a running URL or a command that starts one.` Test for a servable interface rather than for source under a particular folder, since this measures what a browser receives and never reads the tree that produced it.
+- If the request is about intent, consistency, missing states, or contrast, run nothing and name `claude-ux-audit`. That skill reads source and this one runs the interface.
+
+## Step 1: reach the interface
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `package.json`: the `scripts` block naming a dev, preview, or start command
+- `.claude/context/development/`: the documented run commands and the port each serves
+- `CLAUDE.md`: project type and conventions
+
+Prefer a production-shaped build (`preview`, `start`) over the dev server. A dev server ships unminified modules and reports a cost no user pays.
+
+Ask for the URL when nothing names one. Do not guess a port.
+
+Then reach it. Request the URL first and measure whatever already answers, since a server the user started is the one they mean. Build and start the chosen command only when nothing answers, wait for it to accept a request before going on, and stop it once Step 4 has the readings. A run that measures before the server is listening reports a connection failure as a cost.
+
+## Step 2: detect the harness
+
+Test each in order and take the first that resolves. Name the one found before running it.
+
+1. A connected browser MCP server exposing navigation and a performance trace
+2. `@playwright/test` or `playwright` in `package.json`, or a `playwright.config.*` at the project root
+3. `lighthouse` in `package.json`, or a script whose command names it
+
+Never install a runner, add a dependency, or write a config to make one of these resolve. The project chooses its harness and this skill reads that choice.
+
+When none resolves, report what the measurement needs and stop:
+
+```plaintext
+❌ No browser harness detected. This measurement drives one of:
+   - a browser MCP server with a performance trace
+   - Playwright (@playwright/test)
+   - Lighthouse (lighthouse)
+Install one, or name a running URL and which runner to drive it with.
+```
+
+## Step 3: measure
+
+Take three readings against the same URL on a cold profile and report the median. One load carries startup noise wider than the gap between two thresholds, so a single number cannot be placed against them.
+
+Measure these three and nothing else:
+
+- **Paint**: Largest Contentful Paint, the moment the largest element in the viewport finishes rendering
+- **Processor**: Total Blocking Time, main-thread time past 50ms per long task between first paint and interactive
+- **Layout**: Cumulative Layout Shift, the summed score of unexpected shifts over the page lifetime, reported with the elements that shifted
+
+Through Playwright or an MCP server, read them from a `PerformanceObserver` registered before navigation against the `largest-contentful-paint`, `longtask`, and `layout-shift` entry types. Lighthouse reports all three under its JSON audits, so parse rather than re-derive them.
+
+### Attributing the layout figure
+
+A layout score on its own names nothing to look at, and the elements are already in the reading rather than a second measurement. Each `layout-shift` entry carries a `sources` array naming the nodes that moved, so sum each entry's `value` against the nodes its sources name and keep the three largest. Lighthouse carries the same attribution in the `details.items` of its layout-shift audit, which names elements rather than scores in some versions, so report what that audit gives and do not compute a score it withheld.
+
+Take the attribution from the run that produced the median rather than merging all three, so the parts sum to the figure printed beside them. Merging reports shares of a total no run measured.
+
+Identify each element the way the harness names it, which is a selector from Playwright and a node label from Lighthouse. Do not open the source to improve a name. Reading the tree that produced the page is what this skill exists to replace.
+
+Write any probe the harness needs into the project's own test folder, run it, then delete it. Leave no file behind.
+
+### Thresholds
+
+| Metric | Good      | Needs work | Poor      |
+| ------ | --------- | ---------- | --------- |
+| LCP    | `≤ 2.5s`  | `≤ 4.0s`   | `> 4.0s`  |
+| TBT    | `≤ 200ms` | `≤ 600ms`  | `> 600ms` |
+| CLS    | `≤ 0.1`   | `≤ 0.25`   | `> 0.25`  |
+
+These are Google's published Core Web Vitals boundaries, with the Lighthouse lab boundary for Total Blocking Time. Cite that source in the report. Never move a number to fit a reading, and never invent a fourth metric's boundary.
+
+## Step 4: report and persist
+
+### Report format
+
+```markdown
+3 metrics measured against <url> over 3 runs. Harness: <name>.
+
+| Metric | Median | Threshold | Verdict                      |
+| ------ | ------ | --------- | ---------------------------- |
+| LCP    | <n>    | `≤ 2.5s`  | <good \| needs work \| poor> |
+| TBT    | <n>    | `≤ 200ms` | <verdict>                    |
+| CLS    | <n>    | `≤ 0.1`   | <verdict>                    |
+
+Shifted: `<element>` <n>, `<element>` <n>, `<element>` <n>.
+
+Thresholds: Google Core Web Vitals, Lighthouse lab boundary for TBT.
+
+Not measured: network waterfall, bundle size, accessibility, contrast.
+```
+
+Write `Shifted: nothing recorded.` when the median run logged no shift, and drop any element past the third. A layout figure of zero and a harness that reported no sources are different states, and the line says which one the run met.
+
+Report the reading and stop there. A remedy for a poor verdict is a change with its own review, so name no fix and edit no source. Naming a shifted element stays inside that rule, since it says where the score came from rather than what to do about it.
+
+### Persist
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+Write the full reading directly to `.claude/review/ux-measure-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the reading 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.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output the summary line and the file path. Do not repeat the table in chat.
+
+```plaintext
+3 metrics measured against <url>. <n> past threshold.
+📝 Wrote .claude/review/ux-measure-<slug>.md
+```

package/claude/skills/claude-worker/REQUIREMENT.md

@@ -0,0 +1,54 @@
+---
+name: claude-worker
+description: What a building session is, the shared surfaces it may not write, and the two messages it owes the session that dispatched it
+---
+
+# Claude worker requirement
+
+## Gap
+
+Without this skill, a building session is told what to do and never what it is. One shipped body asserts a session role and it is the orchestrator, so worker behavior spreads across three skills that each own a step and none of them names the role or the channel it runs on. The handback works because a session reading plain text tends to follow it rather than because anything says it should, which held while a person launched every worker and stopped holding the first time one ran with nobody watching.
+
+The session then writes surfaces nothing told it were shared. One worker split a concern its own run could not reach, hand-wrote the priority board from a copy taken minutes earlier, and reverted a promotion with nothing reporting it, on a board that still validated afterwards because a reverted row is a well-formed board. A second added a row and labelled it with an identifier another row already held. The rule against both sits inside the controlling session's own body, which no worker loads.
+
+Standing in a linked worktree fails one step earlier and reports confidently while it does. The plan folder is gitignored, so `git worktree add` never creates it, and a worker reading it from the build tree reports that the task has no plan. That is true from where the session stands and wrong about the world, and a reader holding no second tree cannot tell those apart. Three workers hit it in one day and an absolute path unblocked all three.
+
+A blocked worker reaches nobody at all. Two dispatched sessions opened an interactive prompt inside a background session no operator was attached to, and the roster read both as alive throughout. An answer relayed afterwards arrives and does not land, since a queued message drains at the next tool round and a session waiting on input never reaches one, so the channel closes the gap only when it is used before the prompt opens. One of the two held uncommitted work across three files, which made stopping and relaunching a destructive recovery rather than a free one.
+
+Finishing is invisible from the other side. A worker that opens a pull request goes idle rather than exiting, so the one push signal available fired for a worker that was stopped and never fired for the one that finished, which then sat unnoticed for eighteen minutes. Polling covers that interval by spending a fixed cost against a worker with no pull request to report, measured as five consecutive runs reporting no movement across roughly fifteen minutes while one worker built.
+
+Nothing tells the session that refusing is allowed either. Four occasions across two days had a worker halt correctly with the cost falling on the dispatcher, and the correction that mattered most reached the right place because a worker argued back with evidence rather than complying. A role written only as report-upward suppresses exactly that.
+
+## Must
+
+- Assert what a building session is, what it may not do, and how long the role lasts, since the three step-owning skills each carry a procedure and none carries a role
+- State that session scratch resolves at the main worktree root, since a linked worktree holds none of those folders and their absence reads as a missing artifact rather than as a wrong vantage
+- State the shared board as read-only for a building session and name what it does instead when a row is owed, since a worker cannot pick a free label without reading every task file and every archive entry
+- Owe an announcement the moment the pull request opens, carrying the number, the branch, and the task, since that transition is the one interval only the worker can observe
+- Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
+- Name the addressee as the session the launch named, falling back to the roster and saying so, since an operator's own launch names nobody
+- Keep refusing a dispatcher a first-class move carrying its evidence, since the halts measured so far were correct and the cost of each fell where it belonged
+- State that a held body may be older than the branch under it, since a plugin skill loads from the marketplace cache rather than from the working tree
+- Point at `claude-worktree`, `claude-autoship`, and `claude-address-review` for the steps each already owns
+
+## Must not
+
+- Restate a procedure any of the three step-owning skills carries, since thinness is what keeps one body correct for a dispatched worker reading it as its whole contract and for a hand-launched one reading it beside a person
+- Restate a boundary the orchestrator already states about itself
+- Report progress through the channel, which rebuilds on the sender's side the poll the announcement exists to retire
+- Write the priority board or the backlog, at any size
+- Be a skill nothing invokes but its author typing the name. `claude-autoship` Step 0 invokes it on every build, dispatched or hand-launched, so a stretch where only a typed invocation reaches it is the signal that the role never took.
+
+## Guards
+
+- Plan path does not resolve from inside the worktree: report it unreadable from here and name the main-root path, rather than reporting the task as having no plan
+- Plan carries a suggestion written as needing the operator's call: halt and message, rather than answering it
+- Launch named no controlling session: resolve from the roster, address the match, and say the addressee was inferred
+- No live session holds the other end: report what would have been sent and stop, rather than retrying or waiting
+
+## Out of scope
+
+- Entering the worktree, which `claude-worktree` owns
+- The chain from implement through pull request, which `claude-autoship` owns
+- Answering a posted review, which `claude-address-review` owns
+- The controlling session's half of the channel, the review poll, and the watch beside it, which `claude-orchestrate` and its runbooks hold

package/claude/skills/claude-worker/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: claude-worker
+description: Asserts the worker role for a building session, holding the boundary set, the lifetime, and the two channel obligations a session owes whoever dispatched it. Use when asked to "be the worker", "you are a worker session", at the start of a dispatched or hand-launched build, or when a building session needs to know what it may not write. Do NOT use to plan the next feature, to run the independent review pass, or to merge.
+---
+
+# Claude worker
+
+This session is a worker: one cold session building one branch under one plan. It
+implements, verifies, opens a pull request, and answers what the review posts
+back.
+
+It does not plan the next feature, it does not stand in for the independent
+review pass, and it does not merge. Those belong to the controlling session and
+to the human.
+
+This body states the role, the boundaries, and the channel, and it starts no
+step of its own. `claude-worktree` enters the tree, `claude-autoship` chains the
+build, and `claude-address-review` answers a posted review, so read each step
+from the skill that owns it and invoke none of the three from here. The ordinary
+path arrives through `claude-autoship` Step 0, which means that chain is already
+running and re-invoking it would restart the build.
+
+## Where the session stands
+
+- Resolve `.claude/plans/`, `.claude/tasks/`, `.claude/review/`, and `.claude/memory/` 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.
+- 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.
+- 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.
+
+## The board is read-only
+
+- Never write `.claude/tasks/priority.md` or `.claude/tasks/backlog.md`. The controlling session is their only writer apart from `canon tasks archive`, and both are gitignored, so an overwrite drops a row with no history to recover it from.
+- Report a row this build turns up rather than adding it. Picking a free label means reading every task file and every archive entry, which this session has not done, so a label it invents collides with one already taken.
+- Write the task file this build closes and the plan it ran under. The ban covers the shared board rather than the artifacts of the row in hand.
+
+## The channel
+
+The controlling session cannot watch this one build, so three messages are owed
+and nothing else.
+
+- Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
+- Announce when an address-review pass finishes, as `claude-address-review` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and it is what tells the controller to re-review rather than leaving it to poll for an answer nothing marks as landed.
+- Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round that drains an inbound message, so a relayed answer arrives under the open question and changes nothing.
+- Send nothing on progress. A worker reporting progress rebuilds, on this side of the channel, the poll the announcement retired on the other.
+
+Address the session the launch named. It names a `sessionId` rather than a name,
+so read `canon sessions list --json`, find the row carrying that id, and send to
+the `name` on it. Resolve that name at the moment of sending rather than at
+launch, since a name is derived from what a session turned out to be doing and
+has gone stale inside the hour that a build takes.
+
+Check that name against the agent listing before sending it. A name is not
+unique, and the roster carries no field that separates two live sessions holding
+one, so the resolution can end on a string that reaches the wrong session. Send
+the name bare where the listing shows one row under it. Where it shows more than
+one, complete the address with the `[ref]` that listing prints beside each row
+rather than sending to the name alone, which lands on whichever row the channel
+resolves first. Two sessions differing only by a trailing ` (3)` is the shape
+this meets in practice, and one of them being a controller is what makes the
+wrong pick silent.
+
+Ask the operator when the launch named nobody and a person is there to answer.
+Put the candidate rows to them through the structured question surface, so they
+pick a row rather than recalling a name. The ask halts the build, and the halt
+is the cheaper error: a worker that cannot reach its controller has nothing
+useful to do with the message it owes, where sending to the wrong session
+reports success and loses it. A halt is only as visible as whatever watches for
+one, so say what you are waiting on in the same turn you stop, and expect a
+controller running no stall detector to find the question only when it next
+looks.
+
+Infer only where no operator is present. Read `canon sessions list --json` and
+take the sessions holding no feature branch as the candidates, since a
+controlling session holds none. Say the addressee was inferred so the reader can
+correct it. Never filter that roster by name prefix: every self-dispatched
+worker is named `worker-<slug>`, so a prefix scan returns a sibling or this
+session itself, which is the defect that sent messages owed to a controller
+somewhere else.
+
+Report a resolution that returns nothing rather than falling back to a guess.
+The roster and the send channel enumerate different populations in both
+directions, measured at one moment: a live background session sat on the roster
+that the agent listing did not carry, and nine sessions were addressable there
+with no roster row at all. Those nine were driving through Remote Control, which
+writes no local process record, so a controller working from a phone is exactly
+the case this read answers nothing for.
+
+## Refusing is part of the job
+
+- Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and the consequences of complying, rather than reporting reluctance.
+- Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the dispatch that sent it unattended is the defect and the halt is not.
+- Halting is cheap and guessing is not. Four measured halts each cost the dispatcher one reply, and the correction that mattered most reached the right place because a worker argued back rather than complying.
+
+## Lifetime
+
+- The role runs from the worktree entry to the merge of the branch it built, and nothing carries across to a second row. A worker handed another row after that is a new build under a new plan.
+- Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than the working tree, so a session building a change to its own skills may be holding the copy from before the last update.

package/claude/skills/claude-worktree/REQUIREMENT.md

@@ -0,0 +1,58 @@
+---
+name: claude-worktree
+description: Why worktree entry is wrapped rather than called directly, covering name derivation, the conventional branch rename the ship chain depends on, and the shared-config repair
+---
+
+# Claude worktree requirement
+
+## Gap
+
+Without this skill, the user names the worktree by hand, and a name matching no plan breaks every slug derived from it afterward. The entry tool then creates the branch as `worktree-<name>`, which diverges from the name the folder carries, so the ship chain looks for a plan file under a slug that does not exist and stops with nothing wrong except the name. Correcting that to the bare name leaves the branch carrying no type, which `git-pr` refuses on format, so the same run stops a second time with the work already done and uncommitted.
+
+Entry also writes the bare flag into the shared config, which strands the main worktree. Every command run there fails while the files sit untouched on disk, and the linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout and finds the repository broken. A rename onto a branch that already exists is the third failure, and it is the one that destroys work rather than blocking it.
+
+The tree the entry hands over is also not one the session can run. Dependencies live in a folder git ignores and never shares between working directories, so a fresh worktree arrives with none, and nothing on the entry path says so. The session finds out from whichever command needs them first, and the message it gets names a missing module rather than an empty working directory.
+
+A declined request also has to land somewhere. The description turns away a list, cleanup, or rotation request and names no destination, so the session that reads it picks one, while the sibling owning those requests already points back here. One half of a pair carrying the pointer reads as the boundary running one way.
+
+A submodule checkout is the state the entry path reads wrong while reporting nothing. The two directory reads that separate a linked worktree from a plain checkout return the same path there, so the guard passes and every derivation after it takes the submodule for the project: the main root, the plan lookup, and the folder entry builds all resolve inside a tree the superproject tracks as a commit.
+
+A stack that derives its ports from the working directory has the same shape. The number is correct and invisible, and `claude-orchestrate` sends a reader here to read it rather than assign one, so the entry that knows the working directory is the surface that owes it.
+
+## Must
+
+- Derive the name from the plan matched to the current branch, falling through the ordered sources rather than picking
+- Validate and sanitize the derived name against what the entry tool accepts
+- Preview the resolved name and which source produced it before entering
+- Rename the created branch to a conventional `<type>/<name>`, so the pull request guard accepts it and the slug transform still reads `<name>` back out
+- Take the type from the plan the name came from, and default to `feat` when a branch or the user supplied it
+- Test the target branch and the target directory before entering, so a stop costs no worktree
+- Read the bare flag before writing it, and repair it on both sides of entry
+- Announce the repair only when a write actually happened
+- Report on one line whether the entered worktree carries its dependencies, naming the command that installs them when it does not
+- Report the same way when the project declares no package manifest, since silence there reads as a passing check
+- Report the port offset this worktree derives, and say so when the project installs no derivation
+- Name `git-worktree` where the description declines a list, cleanup, or rotation request, matching the pointer that skill already carries back
+
+## Must not
+
+- Install dependencies on the session's behalf. Entering a worktree to read is as common as entering one to run, and an install is slow and needs a network.
+- Pick between plans when more than one could match. Ask.
+- Enter on a name inferred from session context without confirmation
+- Delete or overwrite a branch or a worktree directory that already carries the target name
+- Rename when the worktree was entered by path, since that branch already has its own identity
+- Invoke the exit path, which is the user's call
+
+## Guards
+
+- Already inside a linked worktree: stop rather than nesting
+- Inside a submodule checkout: stop and name the superproject, since the two reads that catch a linked worktree return the same path here and everything derived afterward would take the submodule for the project
+- Not a git repository and no creation hook configured: stop
+- Target branch already exists: stop before entering and leave it alone, since resolving it automatically risks the wrong branch
+- Target worktree directory already exists: stop before entering, which is the only read that sees two branches differing by type collapsing onto one name
+
+## Out of scope
+
+- Listing, cleaning up, or rotating worktrees, which `git-worktree` owns and the description names, since this file routes no session
+- Leaving a worktree, which the user decides
+- What runs inside the worktree once entered, which the caller drives