@lab43/q 0.4.0 → 0.6.0

package/q-extension/references/agent-briefing.md

@@ -0,0 +1,66 @@
+# Agent Briefing
+
+The shape of a project's agent briefing — `CLAUDE.md`. `/q:install` scaffolds it, `/q:update-docs` extends it, and `/q:groom-docs` checks it.
+
+The documentation policy decides what the briefing must carry (see: @lab43/q conventions/documentation.md, Taxonomy). This file gives that a shape.
+
+## The template
+
+```markdown
+## Documentation
+
+This project follows q, an agentic coding workflow. Its rules live in the project's own documentation. Those rules are conventions: binding decisions about how this project's code and docs get written, recorded as they are made. Guides sit alongside them — how to operate the project, rather than rules for writing it.
+
+If the session's skill list has no `/q:` skills, this machine is missing the q plugin — ask the user to install the project's dependencies (`npm install`, or the project's package manager's equivalent), then run `/q:reconcile`.
+
+When another session is already working this repo, take a worktree rather than sharing the checkout.
+
+Conventions come in three tiers: q's own, the conventions of any installed extensions, and this project's own `docs/conventions/` (source: @lab43/q conventions/conventions.md, Three tiers of conventions). q and the extensions are dependencies in `package.json`. Project rules win over an extension's rule, and an extension's rule wins over q's. Check all three tiers before writing code, before design decisions and reviews, and before changing docs. Doc changes — the README and this briefing itself included — go through `/q:update-docs`.
+
+Package doc paths are package name plus path from the package's `q-extension/` payload directory, resolved under `node_modules/`: `@lab43/q conventions/principles.md` is `node_modules/@lab43/q/q-extension/conventions/principles.md` (source: @lab43/q conventions/documentation.md, Package doc paths).
+
+`@lab43/q` — <its `q.description`>
+
+- `@lab43/q conventions/principles.md` — cross-cutting rules for any design decision, plan, or review
+- `@lab43/q conventions/documentation.md` — what belongs in a project's documentation, where it lives, and how it stays accurate
+- `@lab43/q conventions/conventions.md` — rules for a project's conventions docs: the tiers they come in and which tier wins, what a conventions doc holds, and when a rule leaves prose for a stronger enforcement rung
+- `@lab43/q conventions/extensions.md` — the extension format: rules for authoring and publishing a q extension
+- `@lab43/q conventions/plans.md` — format, sequencing, and lifecycle rules for `docs/plans/` documents
+- `@lab43/q conventions/specs.md` — rules for `docs/specs/` documents: what a spec holds, how it is written, and how the code is held to it
+- `@lab43/q conventions/issue-tracking.md` — rules for working a project's issue tracker from any session
+- `@lab43/q conventions/pull-requests.md` — rules for authoring a pull request
+- `@lab43/q conventions/writing.md` — rules for writing prose: docs, plans, PR bodies, anything a human or agent will read
+
+`<package>` — <its `q.description`>
+
+- `<package> conventions/<name>.md` — one line per doc, restating its intro
+
+`<this package>` — <its `q.description`>
+
+- `<this package> conventions/<name>.md` — one line per doc, restating its intro
+
+This project's own:
+
+- `docs/conventions/principles.md` — cross-cutting rules, including deviations from q's
+- `docs/conventions/documentation.md` — documentation rulings and deviations
+
+Specs:
+
+- `docs/specs/<name>.md` — one line per spec, restating its intro
+
+Guides:
+
+- `docs/guides/<name>.md` — one line per guide, restating its intro
+```
+
+## Maintaining it
+
+- **Write into `CLAUDE.md`**, creating it when it doesn't exist. Leave any `AGENTS.md` the project keeps for other tools alone. Linking the two is the project's call, not q's.
+- **Conform to the structure**: the section heading, the groups in the order they run here, one line per doc. Name each group for what it actually holds.
+- **Head each group with what its docs govern** (source: @lab43/q conventions/documentation.md, Taxonomy). A package's group is headed by its name, an em dash, and the `q.description` from its `package.json`, q's own group included (see: @lab43/q conventions/extensions.md, Description). A package shipping no `q.description` gets a heading of its name alone, never its `description` — that field answers the registry's readers.
+- **Give the payload this repo ships its own group.** When the repo's own `q-extension/` holds `conventions/`, it ships those rules and consumes them too: index them in the same form as an installed extension's, read from the working tree rather than `node_modules/` (see: @lab43/q conventions/extensions.md, Authoring).
+- **Treat the prose as a floor, not a script.** Carry at least what the template's prose carries. Leave the project's own wording where it says the same thing. Where a statement isn't true of the project — it authors an extension rather than installing one, or loads the plugin some other way — say what is true instead.
+- **Keep what the project put there** — its own standing instructions, notes, and index entries beyond the required ones. Work missing information into what is already written rather than bolting a sentence alongside it. Rewrite freely to do that, but drop nothing the project said.
+- **Drop a group with no entries.** A fresh project has no extensions, no specs, and no guides, so those groups arrive with the first one of each. The q group is always there.
+- **Index every doc the policy requires, and nothing stale** — every conventions doc, from q, from an installed extension, from this repo's own payload, or the project's own, every spec, and every guide (source: @lab43/q conventions/documentation.md, Taxonomy). Drop the line for a doc that is gone. An extension the project no longer installs loses every line and its heading with them. The installed extensions are the direct dependencies — `dependencies` and `devDependencies` alike — whose installed copy carries both the `q-extension` keyword and a payload directory (source: @lab43/q conventions/extensions.md, Identity). An extension shipping no conventions docs contributes no lines, and so no group.
+- **Write each line as a path plus a blurb restating the doc's intro** — q's docs, an installed extension's, and this repo's own payload by their path form (see: @lab43/q conventions/documentation.md, Package doc paths), the project's own by repo-relative path.

package/q-extension/references/enforce-declarations.md

@@ -0,0 +1,16 @@
+# Enforce Declarations
+
+The machine-local enforcement procedure: make this machine match what the project declares. Enforce without asking — the declarations are the project's recorded decisions, and this merely applies them.
+
+1. Check that `node` and `npm` resolve. When either is missing, Node.js is not installed — report that fix. Nothing below runs without it.
+2. When `node_modules/` is missing a declared dependency, or holds a version other than the lockfile's, run the project's package-manager install — `npm install`, or the pnpm or yarn equivalent its lockfile indicates. That install is the whole update mechanism: a session reads q from `node_modules/@lab43/q` as it stands, so nothing else has to reach it.
+3. Register the project's marketplace: `claude plugin marketplace add --scope local ./`. The tracked settings only declare the marketplace — sessions resolve it against a machine-global registry the declaration does not update: an interactive session offers the registration behind a trust prompt, and a headless one never registers it at all. The manifest at the project root supplies the name, so nothing has to read or pass one. Skip this step when the project has no `.claude-plugin/marketplace.json`. The add fails outright against a directory holding no manifest. A project without one has not been scaffolded yet. Otherwise run it unconditionally, since the add changes nothing when the registry already points here. Local scope records the registration in the project's own `.claude/settings.local.json`, which does not keep it private.
+
+   Three situations need it:
+
+   - A fresh clone has never registered the marketplace.
+   - A declined trust prompt left it unregistered.
+   - Another checkout of this repo has repointed the project's name at itself. The machine-global registry holds one entry per marketplace name. The add repoints it back, because an entry whose name matches but whose path differs is updated to the new path.
+4. After any change above, run `/reload-plugins`.
+
+Name any tracked file the enforcement rewrote (a lockfile). That change stays in the tree as the user's.

package/q-extension/references/q-state.md

@@ -0,0 +1,31 @@
+# The q State File
+
+Format and writer rules for `.claude/q-state.json`, the consumer-side record of the versions a project was last reconciled against. The skills that read or write the file follow this doc; nothing else edits it.
+
+## What the file is
+
+The file holds machine-written version watermarks — never rules, never doc enumerations. Reconciliation is the work of folding a version change into the project — holding its docs against an extension release's changed rules, or its scaffolded surfaces against a new q version; `/q:reconcile` performs it. A watermark records the version the project was last reconciled against. Drift is the lockfile or the installed version disagreeing with it, however the move arrived — a hand-run npm install, a teammate's merge, a Dependabot bump. The skills and the session-start hook compare its versions against the lockfile and `node_modules`; nothing consults it for how to behave.
+
+## Format
+
+The file lives at `.claude/q-state.json`, committed. JSON, one key per line, so a watermark move reads as a one-line diff:
+
+```json
+{
+  "note": "Machine state written by q's skills. Never edit by hand; /q:reconcile repairs drift.",
+  "reconciledAgainst": {
+    "@lab43/q": "0.3.0"
+  }
+}
+```
+
+`reconciledAgainst` holds one entry for `@lab43/q` and one per installed extension: the version the project was last reconciled against. q's entry has the same shape as the rest, carrying no privilege and no separate field.
+
+## Writer rules
+
+- `/q:install` writes a missing `@lab43/q` entry when it scaffolds, from the version installed, which has no reconciliation debt. It never touches a present entry — a stale one is reconciliation's to move.
+- `/q:reconcile` writes watermarks as reconciliation's record: it moves a package's entry after reconciling its version move, writes an arrival's first entry from the version installed, and drops an entry as part of reconciling a departure. It writes nothing before a reconciliation — watermarks certify one.
+
+An absent file means no record — create it on the first watermark write.
+
+What divides this file from `package.json` is who writes it. The manifest is hand-authored and npm's to rewrite, so it carries what a person sets and a consumer reads — the q declaration, `q.description`. Watermarks are machine-written, so they live here, where the format stays q's to guarantee and nothing edits them by hand.

package/{references → q-extension/references}/run-contract.md

@@ -7,13 +7,15 @@ How every q skill run operates, from invocation to finish. Skills reference this
 A run is in one of two modes, depending on whether the user has agreed on what to do yet:
 
 - **Conversational** — nothing agreed yet: converge with the user. Present candidates with trade-offs and a recommendation, decide at the right altitude (see: Decide at the right altitude), and proceed to execution only on the user's go-ahead. The conversation ends in an agreement — a plan doc, a confirmed scope, a converged approach.
-- **Autonomous** — an agreement exists: execute it without asking. Interrupt only when the work would step outside what was agreed — a conflict discovered mid-run, an architectural fork, scope the agreement doesn't cover. Small calls inside the agreement stay autonomous: choose what is most consistent with the agreement, the conventions, and the surrounding code, and flag the calls a reviewer would question where the output gets reviewed: the PR body (see: q conventions/pull-requests.md), or the end-of-run report when the run delivers no PR. When the agreement is exhausted or must be reopened, the run is conversational again.
+- **Autonomous** — an agreement exists: execute it without asking. Interrupt only when the work would step outside what was agreed — a conflict discovered mid-run, an architectural fork, scope the agreement doesn't cover. Small calls inside the agreement stay autonomous: choose what is most consistent with the agreement, the conventions, and the surrounding code, and flag the calls a reviewer would question where the output gets reviewed: the PR body (see: @lab43/q conventions/pull-requests.md), or the end-of-run report when the run delivers no PR. When the agreement is exhausted or must be reopened, the run is conversational again.
 
 ## Review modes
 
-Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled it is never revisited mid-run: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
+Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled, the run never reopens it: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
 
-- **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's approval is what commits it.
+The user can still overrule a step: telling a local run to commit now (see: The local gate), or a ship run to hold its push. The ruling spends itself on the step it names — the mode stands for everything after, however much the instruction resembles the other mode's procedure. Name the conflict before complying rather than inferring a switch.
+
+- **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's go-ahead is what commits it.
 - **Ship** — commit as the running skill's own procedure calls for, without asking, and push when the work is done; the user reviews on GitHub, so finish by directing them to the PR(s). The grant ends at the PR: merging is the user's.
 
 ## The delivery branch
@@ -44,7 +46,7 @@ An existing local branch is checked out as it stands, which may be behind the re
 
 Never take the branch with `git worktree add --force`. It succeeds, leaving two worktrees on one branch to diverge silently.
 
-Whichever way the worktree was made, install the project's dependencies there (see: `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`). A worktree carries tracked files only, so until that install runs nothing works — not the project's checks, not reading q's conventions or an extension's under `node_modules/`.
+Whichever way the worktree was made, install the project's dependencies there (see: `${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.md`). A worktree carries tracked files only, so until that install runs nothing works — not the project's checks, not reading q's conventions or an extension's under `node_modules/`.
 
 **Working alone, branch in the checkout.** When the run's work belongs with the session's work in progress, work on that branch. When it does not, branch first — off whatever the work builds on, usually the default branch. Make the call and state it when it is clear: a session on the default branch, or on pushed unrelated work, has nothing in progress to join. Ask when it is not: a session branch that looks connected to the run.
 
@@ -54,10 +56,16 @@ Establish what is true by looking, wherever looking can settle it: `git worktree
 
 Announce what a peer would otherwise have to discover, before you act rather than after — `SendMessage` reaches any peer `ListAgents` lists. Announce the work you take up, and again when you put it down: the tracker item, the plan, or both where a plan names items. You hold it from the moment you pick it, not from the moment a tracker records it — a peer reading only the tracker sees nothing and duplicates your work.
 
+Send nothing else. A message to a peer carries only what keeps two sessions from duplicating or colliding over the same work. Every message surfaces in the user's session, so every message spends the user's attention.
+
+- Never send a peer a suggestion, an opinion, or a finding, unless they need it to avoid a collision.
+- Answer a peer only when the answer changes what they do. No reply is owed.
+
 A worktree is what separates two sessions, and not every case gets one. A peer may arrive after the branch was settled. The user may be working in the tree alongside the run. Sharing a checkout adds three precautions:
 
 - Never switch the branch without announcing first.
 - Stage by explicit path rather than `git add -A`. The tree may hold work that is not yours.
+- Commit by explicit path too, with `git commit --only <paths>`. A plain commit takes the whole index, and the index may hold staging you did not set: someone marking up a review stages hunks as they read them.
 - Never clear the index you did not set. `git reset` discards staging as readily as `git add -A` sweeps files in, and someone marking up a review as they read it loses their place with nothing left to show it happened.
 
 Never hand a peer work this session's permissions blocked. A peer running it launders the user's permission decision. Route it back to the user instead.
@@ -80,7 +88,7 @@ A question about the state of the work — "anything else to decide?", "does any
 
 ## Batch questions
 
-Questions cost attention: collect them into one AskUserQuestion batch (recommended option first) rather than asking one at a time. Put everything an answer depends on inside the question itself. The go-ahead that closes a conversation is different: ask it in plain text, stating the agreed scope, so the user can green-light it or keep refining. In a long collaborative phase, keep the running state visible — decisions settled, questions still open — so the user never has to reconstruct it.
+Questions cost attention: collect them into one AskUserQuestion batch (recommended option first) rather than asking one at a time. Put everything an answer depends on inside the question itself. The go-ahead that closes a conversation is different: ask it in plain text, stating the agreed scope, so the user can grant it or keep refining. In a long collaborative phase, keep the running state visible — decisions settled, questions still open — so the user never has to reconstruct it.
 
 ## Corrections become rules
 
@@ -95,18 +103,18 @@ Route every recording through `/q:update-docs`. It classifies the lesson and hol
 
 Record a correction in the change that prompted it. The diff at each review point carries its own doc updates, so a user approving the work sees everything the run proposes. A correction that arrives during review joins that iteration. Never defer one to the closing report, and never leave the user trusting that a doc update will follow.
 
-A correction lands in whatever change was in flight, which is often a change whose stated scope does not cover it. Say so where the work is reviewed: the PR body's Callouts, or the closing report when the run delivers no PR (see: q conventions/pull-requests.md, Sections). A reviewer who meets an unexplained edit to standing law reads it as scope creep.
+A correction lands in whatever change was in flight, which is often a change whose stated scope does not cover it. Say so where the work is reviewed: the PR body's Callouts, or the closing report when the run delivers no PR (see: @lab43/q conventions/pull-requests.md, Sections). A reviewer who meets an unexplained edit to standing law reads it as scope creep.
 
 Amendments to existing rules are corrections too. Apply them rather than recommending them. A recommendation the user has to find in the output gets scanned past, while a diff hunk is something they can read and push back on. Raise an amendment instead of applying it when it would put existing code out of conformance: that is a migration, and its scope is the user's.
 
 ## Validation
 
-Execution closes by validating the run's product before anything is delivered. Run the project's checks covering what changed. Then launch two `adversarial-reviewer` subagents in parallel over the change, one per lens, handing each the agreed scope and the artifact the skill names. The scope is what the user agreed the work would deliver, restated from the run's current state. It is never a list of the changes made: details the user has since overruled resurface as false findings.
+Execution closes by validating the run's product before anything is delivered. Run the project's checks covering what changed. Then launch two `adversarial-reviewer` subagents in parallel over the change, one per lens. Hand each its lens, the artifact the skill names, and what the work is meant to deliver: the scope the user agreed to, restated from the run's current state, or the plan plus which of its steps are in scope, which came earlier, and which are deferred. That is the whole prompt. Never add a hunt-list, a checklist, or an account of what changed. A list steers the review toward what the caller listed, and nothing marks the round as compromised. An account of what changed carries details the user has since overruled, which resurface as false findings.
 
-Wait for every reviewer in the round to report before changing anything. Editing the tree under a running review invalidates the diff that review was handed. Then fix the BLOCKING findings, applying judgment on nits. Re-run the checks covering the fixes. Review again — fixes are always re-reviewed, with the same reviewers by default. A round whose fixes were few and small may hand the next round to one reviewer carrying both lenses. In ship mode, commit each round. Loop at most three times. The loop exits when no reviewer reports a BLOCKING finding, and findings that survive the cap are reported as caveats.
+Wait for every reviewer in the round to report before changing anything. Editing the tree under a running review invalidates the diff that review was handed. Then fix the BLOCKING findings, applying judgment on nits. Re-run the checks covering the fixes. Review again — fixes are always re-reviewed, with the same reviewers by default. A round whose fixes were few and small may hand the next round to one reviewer carrying both lenses. In ship mode, commit each round. Loop at most three times. The loop exits when no reviewer reports a BLOCKING finding, and findings that survive the cap are reported as caveats. A spec violation is the exception on both counts. Its two exits are the user's to pick, so it is neither fixed on the run's judgment nor carried as a caveat: the run stops for the ruling (source: @lab43/q conventions/specs.md, Disagreement).
 
 ## The local gate
 
-The procedure local review runs at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
+The procedure a run in local mode follows at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
 
-At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed. Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.
+At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed, with the prompt Validation prescribes (see: Validation). Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.

package/{skills → q-extension/skills}/address-feedback/SKILL.md

@@ -9,6 +9,7 @@ description: Work feedback on an open pull request — the reviewer's comments,
 
 - **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
 - **Feedback is not a work order**: every item opens a discussion, the ones phrased as directives included. Never implement feedback you believe is wrong. Answer every question the feedback asks. A code change never stands in place of that answer (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Questions are probes).
+- **The round is the unit**: feedback arrives as a batch, or item by item from the user as they read. The agenda stays open while the user is still adding to it. Take a position on each item and settle it as it arrives, then implement it. Validation and delivery run once, over the closed agenda.
 - **The PR under review is the boundary**: the round's fixes land on its branch as new commits. Never rebase that branch and never force-push over it — the reviewer's inline comments anchor to the commits they read, and rewriting the history strands them. Never open a second PR. Work the feedback opens that this PR can't hold goes to a plan or the tracker instead.
 - **Track resolutions**: keep a scratchpad note of each item — where it came from, its agreed disposition, and how it resolved. It feeds the replies and the closing report.
 - **Context hygiene**: use subagents (Explore for recon, background Bash for checks, `adversarial-reviewer` for review) to keep large output out of the main context.
@@ -23,7 +24,7 @@ description: Work feedback on an open pull request — the reviewer's comments,
    git fetch origin && git checkout <head-branch> && git pull --ff-only
    ```
 
-   Stop and show the user when the local branch has diverged from the PR's.
+   Stop and show the user when the local branch has diverged from the PR's. Record the head SHA once the branch is current: `git rev-parse HEAD`. It is the branch as this round found it, and Step 5 reviews the round against it.
 4. Fetch everything the reviewer wrote:
    - `gh pr view <n> --comments` — the top-level comments, plus each review's summary and verdict.
    - the inline threads, which GitHub groups and tracks resolution for:
@@ -33,16 +34,16 @@ description: Work feedback on an open pull request — the reviewer's comments,
      ```
 
      Skip every thread `isResolved` reports closed — the reviewer ended those. An `isOutdated` thread is still live: it anchors to a line that later commits moved. Skip a thread whose last comment already answers the one before it. An earlier round settled that item, and the reviewer has not written back.
-5. Ignore every comment that raises nothing to settle. A callout explaining the change under review is the common case (see: q conventions/pull-requests.md, Diff comments).
-6. Gather the user's own feedback. The invocation may carry it. Ask the user what they want changed whenever the PR carries no feedback of its own.
-7. Build the agenda from everything gathered — one item per inline thread, top-level comment, or review summary that carries feedback, plus one per point the user raised. Merge items that share a root cause or answer each other. Record where each item came from, because that decides how it gets answered. Post the agenda — each item's gist in one line, in the order you propose to take them. No positions yet, and no edits.
+5. Ignore every comment that raises nothing to settle. A callout explaining the change under review is the common case (see: @lab43/q conventions/pull-requests.md, Diff comments).
+6. Gather the user's own feedback. The invocation may carry it. Ask the user what they want changed whenever the PR carries no feedback of its own. Always ask whether more is coming, because the user may still be reading the PR and add items as they go.
+7. Build the agenda from everything gathered — one item per inline thread, top-level comment, or review summary that carries feedback, plus one per point the user raised. Merge items that share a root cause or answer each other. Record where each item came from, because that decides how it gets answered. Post the agenda — each item's gist in one line, in the order you propose to take them. No positions yet, and no edits. Leave the agenda open when the user has more coming, and add each new item to it as it arrives. The agenda closes when the user says nothing more is coming. Ask them rather than reading a pause as the end.
 
 ## Step 2: Take a position on each item
 
 Establish ground truth before forming a position:
 
 - the code the item points at, and its history
-- the conventions governing that territory, found from the agent briefing's docs index
+- the conventions and specs governing that territory, found from the agent briefing's docs index
 - the primary source, wherever the item turns on how a dependency or tool behaves — the library's own code, its documentation, its upstream issues
 
 Never agree or push back from memory of an external fact (package versions, library APIs, option names, tool behavior). Run the check whenever running one can settle the question.
@@ -74,33 +75,36 @@ Ask one batch, carrying only what the user has to rule on:
 - whether each resolution is posted back where the feedback was written, asked once for the round. Skip it when nothing was written on the PR.
 - the review mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Review modes). In this run, ship covers commit and push to the PR. Local commits nothing until the user has reviewed the diff.
 
-Answers settle decisions. They are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead. That green light, not the last answer, is what makes the rest of the run autonomous.
+Ask the batch's round-wide questions at the first item and carry the answers forward. A later item reopens the batch only for the fork it turns on.
+
+Answers settle decisions. They are not the agreement. While the agenda is open, a go-ahead authorizes the item it names and nothing beyond it. Implement that item, then return to Step 2 with the next one. Ask for the round's go-ahead once the agenda is closed, summarizing the agreed scope. That go-ahead is what makes the rest of the run autonomous.
 
 An item beyond this PR is not resolved here. Settle the rest of the round, and take it to `/q:create-plan` or to the tracker on the user's call.
 
 ## Step 4: Implement
 
-1. Record the branch's head SHA before changing anything: `git rev-parse HEAD`. It is the branch as this round found it, and Step 5 reviews the round against it.
-2. Implement each agreed fix, following the governing conventions and matching surrounding code.
-3. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When a fix changed a drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
-4. In ship mode, commit — before review, so the review history is inspectable in git.
+1. Implement each agreed fix, following the governing conventions and matching surrounding code.
+2. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When a fix changed a drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
+3. In ship mode, commit — before review, so the review history is inspectable in git.
 
 When the agreed fixes turn out to need a redesign, or more change than this PR can hold, interrupt. Present the discovery and recommend `/q:create-plan` or a tracker item. Neither starts without the user's go-ahead.
 
 ## Step 5: Adversarial review
 
-Validate the round (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Validation) with the **correctness** and **conventions** lenses. The round is the product, so its diff runs from Step 4's recorded SHA: `git diff <recorded-sha>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local review. Hand the reviewers the agreed dispositions as the scope. Per loop round, re-drive a surface only when a fix could change what driving showed.
+Validate the round (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Validation) with the **correctness** and **conventions** lenses. Enter this step once, over a closed agenda. Settling one item while the agenda is still open is iteration, so never launch reviewers over it.
+
+The round is the product, so its diff runs from Step 1's recorded SHA: `git diff <recorded-sha>`, which holds the round's work whether or not it is committed. Name any file the round added and left untracked, which no diff shows. Hand the reviewers the agreed dispositions as the scope. In each pass of the validation loop, re-drive a surface only when a fix could change what driving showed.
 
 ## Step 6: Deliver to the PR
 
-1. **Local review's gate**: run the gate over the session's uncommitted work (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The local gate).
+1. **The local gate**: run it over the session's uncommitted work (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The local gate).
 2. **Push**: `git push origin HEAD`.
-3. **Bring the PR body up to date** wherever the round changed what it claims, the findings that survived Step 5 included (see: q conventions/pull-requests.md).
-4. **Reply**, when replying was agreed: post each item's resolution where the feedback was written. Skip an item the user raised in session. It has no thread to answer. Give the reviewer what they need to understand it — the answer, the evidence behind a push-back, or the reason a fix took the shape it did. Sign each reply (source: q conventions/writing.md, Sign what you post). Write each reply to a file and pass it by path, so apostrophes in the prose can't break the command. Reply to an inline thread at its first comment's `databaseId`:
+3. **Bring the PR body and title up to date** wherever the round changed what they claim, the findings that survived Step 5 included (see: @lab43/q conventions/pull-requests.md).
+4. **Reply**, when replying was agreed: post each item's resolution where the feedback was written. Skip an item the user raised in session. It has no thread to answer. Give the reviewer what they need to understand it — the answer, the evidence behind a push-back, or the reason a fix took the shape it did. Sign each reply (source: @lab43/q conventions/writing.md, Sign what you post). Write each reply to a file and pass it by path, so apostrophes in the prose can't break the command. Reply to an inline thread at its first comment's `databaseId`:
 
    ```bash
    gh api --method POST repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies -F body=@<reply-file>
    ```
 
    Answer a top-level comment or a review summary with `gh pr comment <n> --body-file <reply-file>`. Never mark a thread resolved — that is the reviewer's call.
-5. Close the session by reporting each item's resolution, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: q conventions/issue-tracking.md, Ask before filing).
+5. Close the session by reporting each item's resolution, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: @lab43/q conventions/issue-tracking.md, Ask before filing).

package/q-extension/skills/clean-worktrees/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: clean-worktrees
+description: Clear the git worktrees that finished parallel sessions leave behind. Use when worktrees have piled up in a repo, or before starting parallel work in a cluttered one. Invoke it bare — it sweeps the repo itself. It reports what each worktree holds and whether that work has reached the remote, and the user rules on the list before anything is removed. Never deletes a branch, and delivers no repo change or PR.
+---
+
+# Clean Worktrees
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. This run changes no tracked file, so there is no branch, review mode, or PR.
+
+## Step 1: Sweep
+
+1. Run `git fetch origin`. Never add `--prune`. It drops the tracking ref for a branch the remote deleted on merge. That worktree's commits then look like they never reached a remote, which blocks the cleanup this skill exists for.
+2. Run `git worktree prune`. It clears the registrations whose directory is already gone. A locked worktree keeps its registration either way, because locking is what protects a registration from pruning.
+3. Run `git worktree list --porcelain` for the worktrees. Then list the directories under `.claude/worktrees/`. One that git does not list is not a worktree. Never delete it.
+
+Two worktrees are never candidates. Rule them out first:
+
+- the main worktree, which `git worktree list` names first. Git refuses to remove it.
+- the worktree this session is running in, which `git rev-parse --show-toplevel` names. It reports the worktree's root from any depth, so it matches the path `git worktree list` reports however deep the session has moved.
+
+Ask the peers what they hold, before probing anything. `ListAgents` lists the live candidates (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The delivery branch). With none listed, every worktree is leftovers. Otherwise ask each candidate it lists which worktrees they are working in. The repo cannot show what work a peer is on (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Working alongside a peer). A session that made a worktree and stepped out of it leaves nothing behind to show that it did.
+
+A worktree a peer claims is never removable. Silence is not a claim: a candidate that has not answered by the end of the sweep holds nothing, and every worktree stays as removable as the rest of the test found it. Never wait on a reply. Report the silence in Step 2 instead, so the user rules on the list knowing one candidate never accounted for itself.
+
+Then establish what each of the rest holds:
+
+- whether it is locked, which `git worktree list --porcelain` reports. A locked worktree is never removable. Its directory may be gone, which fails every command below. Report it and probe no further.
+- whether its tree is clean — `git -C <path> status --porcelain`
+- whether every commit it carries has reached a remote — `git -C <path> log --oneline HEAD --not --remotes` prints the ones that have not
+
+Then establish whether its work has landed. Run `gh pr list --head <branch> --state all` for each branch's pull requests. Never use `git branch --merged` for this. A squash-merged branch is not an ancestor of the default branch, so that test reports long-merged work as unmerged. A detached worktree has no branch, so it has no pull requests to read.
+
+A worktree is removable when it holds nothing the remote does not already have:
+
+- its tree is clean
+- no commit it carries is missing from a remote
+- it is not locked
+- no peer claims it
+
+Removing one costs only the checkout. It deletes no ref, and by the test above every commit the worktree carries is already on a remote.
+
+## Step 2: Agree what goes
+
+Settle the list with the user, in conversational mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Collaboration modes). How a removable worktree reaches the user depends on what its pull requests say:
+
+- Merged or closed — the work is done with. Name it in the go-ahead below, for the user to veto rather than asking them (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Decide at the right altitude).
+- Open, or no pull request at all — nothing says the work is finished. Put it in a batch of choices (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Batch questions), and say what its pull requests showed. The user may be coming back to the checkout.
+
+A sweep that turns up none of the second kind asks no questions at all.
+
+Close with the go-ahead, in plain text. State what it removes. Name any candidate that never answered the ask, and which of the worktrees it removes that candidate might yet claim. State what the go-ahead leaves out, and why:
+
+- the worktrees ruled out before probing
+- the worktrees that failed the removable test
+- the directories git does not list
+
+The go-ahead is the agreement.
+
+## Step 3: Clear it
+
+Remove what the user agreed to, without asking again.
+
+1. Drop any worktree a peer has claimed since the sweep, whether the reply arrived while Step 2 was still settling the list or after the go-ahead. A late reply still settles ownership, and the user agreed to remove a worktree nobody had claimed. Report each one dropped.
+2. Remove each remaining agreed worktree with `git worktree remove <path>`. Never `--force` (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The delivery branch). A removal that refuses means something changed since the sweep — show the user what it reports instead of forcing past it.
+3. Leave every branch alone. Deleting the branch a removed worktree held is the user's call.
+4. Report what was removed, what was left and why, and each directory under `.claude/worktrees/` that git does not list.

package/{skills → q-extension/skills}/create-plan/SKILL.md

@@ -10,17 +10,17 @@ The idea to plan comes from the invocation, at any fidelity — a phrase ("email
 ## Ground rules
 
 - **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
-- **Plan, don't implement**: implement nothing, and make no commits unless the user asks. The plan doc is this skill's product — `docs/plans/<plan-name>.md` (create the directory on the first plan). Two writes sit outside it: what driving taught, recorded in the project's driving manual, and the corrections planning turns up (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Corrections become rules).
+- **Plan, don't implement**: implement nothing, and make no commits unless the user asks. The plan doc is this skill's product — `docs/plans/<date>-<plan-name>.md` (source: @lab43/q conventions/plans.md, Filename), creating the directory on the first plan. Two writes sit outside it: what driving taught, recorded in the project's driving manual, and the corrections planning turns up (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Corrections become rules).
 - **Ground everything**: every claim about current behavior comes from reading the code (cite `file:line`); every external fact (package versions, library APIs, option names, client support) is verified during planning, never stated from memory — online where reading settles it, and through `/q:drive` where only running something can, naming the question to settle as what to exercise. A plan resting on an unverified assumption is a planning failure, not a note for the implementer.
 - **Evidence can flip decisions**: when exploration contradicts a tentative decision (a planned feature depends on data that turns out not to exist), surface the finding prominently and re-decide before it gets written into the plan.
-- **Tooling limitations never dictate content** (see: q conventions/principles.md): if a design choice would break a test helper, CI step, or script, the plan schedules the tooling fix — it does not bend the design around it.
+- **Tooling limitations never dictate content** (see: @lab43/q conventions/principles.md): if a design choice would break a test helper, CI step, or script, the plan schedules the tooling fix — it does not bend the design around it.
 
 ## Step 1: Explore
 
 Before proposing anything, establish current state:
 
 1. The relevant code — use an Explore subagent for breadth; read the load-bearing files yourself.
-2. The conventions governing the affected territory, found from the agent briefing's docs index — plus this workflow's own rubric, the plan format (see: q conventions/plans.md).
+2. The conventions and specs governing the affected territory, found from the agent briefing's docs index — plus this workflow's own rubric, the plan format (see: @lab43/q conventions/plans.md).
 3. Prior plans in the same territory (`docs/plans/`, if it exists). Read their decisions and rejected alternatives for the rationale, not the ruling: a rejection whose grounds still hold isn't re-proposed; one whose grounds have shifted is back on the table, with its history. Deferrals are candidates to raise with the user, not inheritances. Status matters: a `pending` plan in the same territory is a possible collision to surface, and an `abandoned` one's decisions never bound anything. Trust newer plans and the code over older ones, and take no format cues — the plan format doc is the only format authority.
 
 ## Step 2: Discuss
@@ -28,13 +28,13 @@ Before proposing anything, establish current state:
 Tease out the goals and key aspects with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). Beyond the design decisions themselves, two calls are settled here:
 
 - Scope boundaries are decisions too: record what's explicitly out of scope or deferred, and why.
-- The delivery shape — single PR or stacked, per the format's defaults (see: q conventions/plans.md, Delivery shape) and any PR rules the project's conventions record. The defaults usually decide it: state the call for veto rather than asking, unless the estimate is genuinely borderline.
+- The delivery shape — single PR or stacked, per the format's defaults (see: @lab43/q conventions/plans.md, Delivery shape) and any PR rules the project's conventions record. The defaults usually decide it: state the call for veto rather than asking, unless the estimate is genuinely borderline.
 
 Once the scope, delivery shape, and key design decisions feel settled, ask for the go-ahead to write. That settled shape is the agreement: Steps 3 and 4 run autonomously inside it, and Step 5 is conversational again.
 
 ## Step 3: Write the plan
 
-Write `docs/plans/<plan-name>.md` according to the plan format (see: q conventions/plans.md) and the writing rules (see: q conventions/writing.md).
+Write `docs/plans/<date>-<plan-name>.md` according to the plan format (see: @lab43/q conventions/plans.md) and the writing rules (see: @lab43/q conventions/writing.md). Cite the spec sections governing the territory in Context, as givens (source: @lab43/q conventions/plans.md, Sections). When the plan changes committed behavior, schedule the spec's amendment in the phase that ships the behavior (source: @lab43/q conventions/specs.md, Disagreement).
 
 ## Step 4: Adversarial review
 

package/{skills → q-extension/skills}/drive/SKILL.md

@@ -58,4 +58,4 @@ Make the change through `/q:update-docs`. Deliver nothing here. The change joins
 
 ## Step 4: Report
 
-Report what you exercised and what it demonstrated, claim by claim — the evidence a PR's Testing section carries (source: q conventions/pull-requests.md, Sections). Name what changed in the manual, and say whether that change is still uncommitted. Name anything you waited on, and how long it held you. Report what failed and stop there.
+Report what you exercised and what it demonstrated, claim by claim — the evidence a PR's Testing section carries (source: @lab43/q conventions/pull-requests.md, Sections). Name what changed in the manual, and say whether that change is still uncommitted. Name anything you waited on, and how long it held you. Report what failed and stop there.

package/q-extension/skills/groom-docs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: groom-docs
+description: Audit the project's whole documentation surface against the documentation policy and consolidate what has drifted. Approved edits ship as a PR. Use when docs feel inflated or stale, after a stretch of merged changes, or on a docs-cleanup request.
+---
+
+# Groom Docs
+
+**Read the rubric first, and follow it over any instinct:**
+
+1. q's documentation policy (see: @lab43/q conventions/documentation.md), its conventions rules (see: @lab43/q conventions/conventions.md), and its writing rules (see: @lab43/q conventions/writing.md), plus any installed extension's doc whose topic governs documentation. An extension's rule beats q's where the two disagree (source: @lab43/q conventions/conventions.md, Three tiers of conventions).
+2. The project's recorded rulings and deviations, which win over both: `docs/conventions/documentation.md` plus any "(overrides: …)" markers across `docs/conventions/` — grep for them. An exception marker is a recorded ruling of a different kind, excusing its one site rather than replacing a rule (see: @lab43/q conventions/documentation.md, Markers). Honour one where you meet it; the accumulation check is what counts them.
+
+Stop and suggest the fix when the project has no `docs/conventions/` directory, or when q's `conventions/` don't resolve by their path form (see: @lab43/q conventions/documentation.md, Package doc paths). Without both there is no surface or rubric to groom against. A fresh clone missing q's `conventions/` may just need `npm install`.
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+
+## Step 1: Inventory
+
+Build the grooming surface, taking each item only if it exists in this project. Read each `docs/` directory whole: every markdown file under it, subdirectories included (source: @lab43/q conventions/documentation.md, Taxonomy).
+
+- `docs/conventions/`, `README.md`, `CLAUDE.md` (the agent briefing) — full checks.
+- `docs/specs/` — **spec mode**: the full checks, with accuracy reversed, per the policy's `docs/specs/` taxonomy rule.
+- `q-extension/conventions/` — the conventions in the payload this repo ships, when that directory exists — full checks, like the project's own conventions (source: @lab43/q conventions/extensions.md, Layout). The root manifest's `q.description` joins the surface with them (source: @lab43/q conventions/extensions.md, Description). Anything else the project's own `documentation.md` puts on the surface joins it, under rubric item 2.
+- `docs/guides/` — **guide mode**, per the policy's Taxonomy rules.
+- `docs/plans/` — **status check only**, per the policy's `docs/plans/` taxonomy rule.
+
+Project-local `.claude/` skills and agents are outside the surface — q doesn't govern them. Everything installed under `node_modules/` is read-only, q's conventions and every extension's alike — never groomed.
+
+## Step 2: Fan out verification (read-only subagents)
+
+Launch read-only subagents in parallel — one per check below, except accuracy, which fans out per doc cluster; the duplication and consistency sweeps each hold the whole surface, since cross-file checks can't be sharded. Each reads the rubric first and returns findings with `file:line` citations:
+
+1. **Accuracy, per doc cluster** (conventions docs grouped by area; specs clustered separately, in spec mode; guides clustered separately, in guide mode): every checkable claim — file paths, symbol names, behavior descriptions, commands — verified against current source. In spec mode the check reverses: a commitment the code does not honor is a finding for the user, never a doc correction, because a spec may run ahead of its code (source: @lab43/q conventions/documentation.md, Taxonomy). Exemplar references get a deeper check: the file exists and still exhibits the rules its doc attaches to it. An authored extension's `q.description` is checked with its docs: it must still name the territory they govern.
+2. **Duplication sweep**, cross-surface: facts stated in more than one place. For each, name the home — implied by the taxonomy, or assigned by a recorded ruling; where the call is genuinely contestable, flag it for the user, whose decision becomes a new ruling. The sweep also runs **cross-tier**, comparing project docs against q's conventions and every installed extension's: a project statement matching one of their rules in substance is duplication to prune; one differing from such a rule without an overrides marker naming it is drift or an unrecorded deviation — escalate to the user; a site carrying an exception marker naming the rule is neither, being excused from it rather than in conflict with it; a marked override whose target updated to agree or disappeared is spent — propose deleting it (source: @lab43/q conventions/conventions.md, Three tiers of conventions). Docs installed under `node_modules/` are read-only: an extension's stale override of a q rule, or two extensions in conflict, can't be edited here — escalate; the remedy is a project ruling or the extension author's.
+3. **Dead references**: every file, symbol, helper, script, and skill named anywhere on the surface exists. Greps must exclude build artifacts (`dist/`, `node_modules/`, and the like) — stale generated files resurrect deleted symbols.
+4. **Consistency**: the agent briefing matches the briefing template (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`); any README skills/conventions table matches its home (skill tables drift-check against `SKILL.md` frontmatter descriptions); cross-references between docs resolve. One concept goes by one name across the surface. Report a synonym against the name its home doc establishes (source: @lab43/q conventions/writing.md, One name per concept).
+5. **Organization**: each doc's structure — topic scope, intro, section placement, and splits or merges across docs — conforms to the policy. Findings here become reorganization proposals.
+6. **Plan statuses** (if `docs/plans/` exists): every plan has valid `status` frontmatter (source: @lab43/q conventions/plans.md, Frontmatter); list every `pending` plan with its age (last git commit date).
+7. **Exception accumulation**: grep the repo for exception markers, excluding `node_modules/` and build artifacts, and group the hits by the rule each names. Match the marker's shape rather than the bare word — `(exception:` where prose carries it, and a comment line beginning `exception:` where a comment does (source: @lab43/q conventions/documentation.md, Markers). Ordinary English use of the word matches neither, and a malformed target still matches, which is what lets the malformations below be seen at all. Skip the text that defines the marker and the examples illustrating it. Report every rule carrying more than one, for the user's ruling — several exceptions against one rule are evidence the rule wants revisiting. Report each of these too: a marker naming no doc or no section, one whose named doc or section does not exist, one carrying no reason, one whose reason the surrounding text no longer bears out, and one whose rule has changed to admit its site, which makes it spent. A file outside the grooming surface joins the run for its exceptions alone: nothing else in it is groomed, and a fix to one goes to the user rather than being applied autonomously.
+8. **Spec markers**: grep the repo for spec markers, excluding `node_modules/` and build artifacts. Match the marker's form, `spec:` followed by a path under `docs/specs/` (source: @lab43/q conventions/documentation.md, Markers). Never match the bare keyword: `spec:` is an ordinary YAML key, at the top of every Kubernetes manifest a project carries, and the path is what no key carries. Skip the text that defines the marker and the examples illustrating it. Report each marker naming a doc or section that does not exist, and each spec section no marker names. An unmarked section is reported and not required: not every commitment is testable.
+
+## Step 3: Consolidate with the user
+
+Merge the findings into proposed edits, each stating its remedy and citing its finding — in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes).
+
+- Apply autonomously: wording-level fixes, replacing a single restated sentence or bullet with a cross-reference to its home, and dead-reference corrections.
+- **Everything else goes to the user** (AskUserQuestion) — including larger deletions and rewrites, any reorganization, any `pending` plan proposed as `abandoned` (only the user flips a status), any fact that couldn't be verified either way, and every spec commitment the code does not honor. Report that one as unmet, never as violated: only the user knows whether it is in progress, missed, or regressed (source: @lab43/q conventions/documentation.md, Taxonomy).
+- When a user ruling sets a precedent, record it in the same run: project-specific rulings go in the project's `docs/conventions/documentation.md`; a ruling that would apply to every q project is recorded as a project deviation and flagged in the report as a candidate to upstream (via `/q:upstream`).
+- In the same batch, ask which review mode — local or ship — the delivery runs under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes).
+
+## Step 4: Apply
+
+1. Pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch).
+2. Step 3's rulings are the agreement — apply the approved edits autonomously. In ship mode, commit them.
+3. Re-run the dead-reference and consistency checks over the result — approved edits can break each other's targets.
+
+## Step 5: Adversarial review
+
+Validate the applied edits (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
+
+## Step 6: Open the PR
+
+1. **The local gate**: run it over the uncommitted edits (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
+2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md).
+3. Close the session by reporting: what changed per doc, what was deduped and into where, every autonomous fix, every user decision and its outcome, any upstream-to-q candidates, and anything that couldn't be verified — named explicitly, never silently dropped.

package/{skills/tackle → q-extension/skills/implement}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: tackle
+name: implement
 description: Take on unplanned work — an issue, a bug, a task at any fidelity. Ground it in the code, then route it on the user's go-ahead — fix it here in a single adversarially reviewed PR, escalate to /q:create-plan when it's plan-worthy, or show with evidence that nothing needs doing. The expected entry point for work without a plan; planned work runs under /q:implement-plan.
 ---
 
-# Tackle
+# Implement
 
-The work comes from the invocation, at any fidelity — an issue number or URL, a pasted error, a phrase ("the export button 404s"); given nothing, ask what to tackle.
+The work comes from the invocation, at any fidelity — an issue number or URL, a pasted error, a phrase ("the export button 404s"); given nothing, ask what the work is.
 
 ## Ground rules
 
@@ -17,18 +17,18 @@ The work comes from the invocation, at any fidelity — an issue number or URL,
 ## Step 1: Understand
 
 1. Announce the item to the peers before reading it — investigating it is already work a peer should not duplicate (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer). A run continued from `/q:triage` arrives with the item already announced. Release it whenever this run stops working the item, whether it turns out unavailable or the verdict is nothing to do.
-2. Read the work item at its source — its description, comments, and related items, when the source carries them — and whatever it cites: stack traces, linked discussions, named files. Read it fresh even when a caller just read it: a tracker moves for reasons no peer announces. An item no longer available to pick up goes back to the user before any further work (source: q conventions/issue-tracking.md, Respect existing claims).
-3. Read the conventions governing the affected territory, found from the agent briefing's docs index.
+2. Read the work item at its source — its description, comments, and related items, when the source carries them — and whatever it cites: stack traces, linked discussions, named files. Read it fresh even when a caller just read it: a tracker moves for reasons no peer announces. An item no longer available to pick up goes back to the user before any further work (source: @lab43/q conventions/issue-tracking.md, Respect existing claims).
+3. Read the conventions and specs governing the affected territory, found from the agent briefing's docs index.
 4. Explore the affected code — use an Explore subagent for breadth; read the load-bearing files yourself.
 5. Check `docs/plans/` (if it exists) for collisions: surface a `pending` plan in the same territory in Step 2 rather than silently working around it.
 
-The outcome is a verdict: what the work actually is, whether the item's claims hold against the code, and how big the real change is.
+The outcome is a verdict: what the work actually is, whether the item's claims hold against the code, how big the real change is, and whether it contradicts a spec.
 
 ## Step 2: Agree
 
-Settle the run with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). One batch: the verdict and a recommended route, the approach where the fix is genuinely forked, and — when fixing here — the review mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). In this run, ship covers commit, push, and the PR; local commits nothing until the user has reviewed the diff.
+Settle the run with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). One batch: the verdict and a recommended route, the approach where the fix is genuinely forked, the exit when the work contradicts a spec — amend the spec with the change, or reshape the work to honor it (source: @lab43/q conventions/specs.md, Disagreement) — and — when fixing here — the review mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). In this run, ship covers commit, push, and the PR; local commits nothing until the user has reviewed the diff.
 
-Answers settle decisions; they are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead — that green light, not the last answer, is what makes the rest of the run autonomous.
+Answers settle decisions. They are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead. That go-ahead, not the last answer, is what makes the rest of the run autonomous.
 
 The routes:
 
@@ -38,13 +38,13 @@ The routes:
 
 ## Step 3: Branch
 
-Settle the branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). A tackle item is its own delivery unit, so the call is a fresh branch. Require a clean working tree first — if anything is uncommitted, stop and show the user. Branch, unless the contract's peer check already put this run on a worktree's branch:
+Settle the branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). The work item is its own delivery unit, so the call is a fresh branch. Require a clean working tree first — if anything is uncommitted, stop and show the user. Branch, unless the contract's peer check already put this run on a worktree's branch:
 
 ```bash
 git fetch origin && git checkout -b <work-slug> origin/<default-branch>
 ```
 
-## Step 4: Implement
+## Step 4: Build
 
 1. Implement the agreed fix, following the governing conventions and matching surrounding code.
 2. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When the change produced a newly drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
@@ -54,10 +54,10 @@ When implementation reveals the work is deeper than the agreement — a redesign
 
 ## Step 5: Adversarial review
 
-Validate the diff (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses. Hand the reviewers the agreed scope and the diff scope: `git diff origin/<default-branch>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local review. Per loop round, re-drive a surface only when a fix could change what driving showed. Surviving findings become Caveats in the PR description.
+Validate the diff (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses. Hand the reviewers the agreed scope and the diff scope: `git diff origin/<default-branch>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local mode. Per loop round, re-drive a surface only when a fix could change what driving showed. Surviving findings become Caveats in the PR description.
 
 ## Step 6: Open the PR
 
-1. **Local review's gate**: run the gate over the session's uncommitted work (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
-2. **Open the PR**: `git push -u origin <work-slug>`, then `gh pr create`, per the PR-authoring rules (see: q conventions/pull-requests.md).
-3. Close the session by reporting the PR URL, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: q conventions/issue-tracking.md, Ask before filing).
+1. **The local gate**: run it over the session's uncommitted work (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
+2. **Open the PR**: `git push -u origin <work-slug>`, then `gh pr create`, per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md).
+3. Close the session by reporting the PR URL, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: @lab43/q conventions/issue-tracking.md, Ask before filing).