@lab43/q 0.5.0 → 0.6.1

package/README.md

@@ -12,21 +12,22 @@ Named for Q, the quartermaster who equips James Bond with his gadgets — q outf
 
 ```sh
 npm install --save-dev --save-exact --ignore-scripts @lab43/q
-claude plugin marketplace add --scope local ./node_modules/@lab43/q
-claude plugin install q@q --scope project
+claude --plugin-dir ./node_modules/@lab43/q/q-extension
 ```
 
-npm delivers q's bytes before Claude Code is involved, so installing q doesn't require already having q. Then run `/q:install` in the project, which:
+npm delivers q's bytes before Claude Code is involved, so installing q doesn't require already having q. `--plugin-dir` loads q for that one session, which is all it takes to run `/q:install` in it:
 
-<!-- source: skills/install/SKILL.md -->
+<!-- source: @lab43/q skills/install/SKILL.md -->
 
 - scaffolds your conventions
 - gives the project its own marketplace, sourcing the q you just installed
 - records the version your docs were reconciled against
 
+Start every session after that with plain `claude`. The marketplace `/q:install` wrote is the project's own, and your tracked settings point each session at it.
+
 ## Joining a project that uses q
 
-<!-- source: skills/install/SKILL.md -->
+<!-- source: @lab43/q skills/install/SKILL.md -->
 
 Install the project's dependencies, substituting your package manager where the project isn't on npm:
 
@@ -34,16 +35,14 @@ Install the project's dependencies, substituting your package manager where the
 npm install
 ```
 
-That is the whole of it — q arrives as a pinned dependency, and the project's tracked settings tell Claude Code to load it. `/q:install` folds this into the project's README, so a q-using repo carries it itself.
+That is the whole of it — q arrives with the project's dependencies, and the project's tracked settings tell Claude Code to load it. `/q:install` writes a q section into the project's own README, so contributors meet q without leaving the repo.
 
 ## Skills
 
-<!-- source: skills/ -->
+<!-- source: @lab43/q skills/ -->
 <!--
   Skill names must not wrap.
-  Keep each name in <samp>. Keep nowrap on its cell.
-  Do not switch a name in this column to <code>. GitHub gives <code> its own white-space: break-spaces. A value set on the element replaces the one inherited from the cell.
-  Do not replace nowrap with a style attribute. GitHub strips style.
+  see: docs/conventions/documentation.md, Table cells that must not wrap
 -->
 <!-- markdownlint-disable MD033 -->
 <table>
@@ -53,24 +52,16 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
     <th>What it does</th>
   </tr>
   <tr>
-    <th rowspan="4" scope="rowgroup">Setup</th>
+    <th rowspan="2" scope="rowgroup">Setup</th>
     <td nowrap><samp>/q:install</samp></td>
-    <td>Install q into a project, or add an extension to one. Idempotent, safe to re-run on a partially set-up project.</td>
-  </tr>
-  <tr>
-    <td nowrap><samp>/q:sync</samp></td>
-    <td>Set up or repair this machine for a q-using project, handing off to <code>/q:install</code>, <code>/q:update</code>, or <code>/q:uninstall-extension</code> when the project's records don't match its pins.</td>
+    <td>Set up q in a project you've already npm-installed it into, or repair a scaffold that has drifted. Safe to re-run on a partially set-up project.</td>
   </tr>
   <tr>
-    <td nowrap><samp>/q:update</samp></td>
-    <td>Update q and the project's installed extensions: move pins to the latest releases with your go-ahead, reconcile the project's docs with what each release changed, and catch up any pin that moved out of band.</td>
+    <td nowrap><samp>/q:reconcile</samp></td>
+    <td>Reconcile the project's records with what npm already did — q or an extension updated, installed, or removed. Also sets up or repairs this machine.</td>
   </tr>
   <tr>
-    <td nowrap><samp>/q:uninstall-extension</samp></td>
-    <td>Remove an extension from a project, or reconcile a removal made out of band — the package, its group in the briefing's docs index, its watermark, and your ruling on each doc that references it.</td>
-  </tr>
-  <tr>
-    <th rowspan="8" scope="rowgroup">Workflow</th>
+    <th rowspan="9" scope="rowgroup">Workflow</th>
     <td nowrap><samp>/q:triage</samp></td>
     <td>Choose what to work on next from a set of items — a Jira board, GitHub issues, a Notion doc — and hand each agreed pick to <code>/q:implement</code>.</td>
   </tr>
@@ -102,6 +93,10 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
     <td nowrap><samp>/q:parallelize</samp></td>
     <td>Give parallel sessions their own copies of what they contend over while driving — ports, databases, caches, devices. Isolates what it can, and names what sessions must take turns over instead.</td>
   </tr>
+  <tr>
+    <td nowrap><samp>/q:clean-worktrees</samp></td>
+    <td>Clear the git worktrees that finished parallel sessions leave behind. Reports what each one holds and whether that work has reached the remote. You rule on the list before anything is removed.</td>
+  </tr>
   <tr>
     <th rowspan="3" scope="rowgroup">Docs</th>
     <td nowrap><samp>/q:update-docs</samp></td>
@@ -126,33 +121,36 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
 <a href="docs/workflow-chart/light.png">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/workflow-chart/dark.png">
-    <img alt="The q workflow: work flows from triage and start through plan, implement, and human review to merge, with adversarial review gating plan and implement. Conventions documentation — project docs over the installed extensions over q — grounds each step; gotchas and corrections flow back down as rules on project docs, and rules that belong upstream leave as PRs." src="docs/workflow-chart/light.png">
+    <img alt="The q workflow. Entry points — /q:triage takes a set of work, /q:implement a single task, /q:review existing work — feed one workflow loop: investigate, discuss, execute, adversarial review, then a PR, opened directly in ship mode or after the human's local review in local mode, then human PR review and merge, with requested changes looping back into discuss. Docs ground every step: project docs — conventions, specs, guides, plans — over installed extensions over q, with plans, findings, and new rulings written back as work happens, and upstream PRs carrying overrides to the layers that own them." src="docs/workflow-chart/light.png">
   </picture>
 </a>
 <!-- markdownlint-enable MD033 -->
 
 q's effect on your repo comes from context routing and documentation discipline — everything it produces lives in plain text files in your repo, and it works in one loop:
 
-<!-- source: skills/install/SKILL.md -->
-<!-- source: hooks/session-start.mjs -->
+<!-- source: @lab43/q skills/install/SKILL.md -->
+<!-- source: @lab43/q hooks/session-start.mjs -->
 
 **Every session starts knowing where the rules are.** `/q:install` puts the routing in place:
 
 - scaffolds `docs/conventions/` — your project's conventions, one doc per topic, seeded with a `principles.md` for your cross-cutting rules and a `documentation.md` for your documentation rulings
-- installs q as the `@lab43/q` npm package, pinned exactly in your `package.json` — its conventions and its plugin arrive together, at one version
+- builds on the `@lab43/q` npm package you installed — its conventions and its plugin arrive together, at one version, and the skill scaffolds around it
 - indexes every tier in your agent briefing (`CLAUDE.md`)
-- gives your project its own marketplace, sourcing the q it just pinned, so every teammate's machine runs the version the repo chose
-- records watermarks in a committed `.claude/q-state.json` — the versions those pins were last reconciled against
+- gives your project its own marketplace, sourcing the q you installed and the plugin of any extension that ships one, so every teammate's machine runs the versions the repo chose
+- records watermarks in a committed `.claude/q-state.json` — the versions your docs were last reconciled against
 
-Every session start validates that installed, pinned, and watermarked versions still agree — drift from any direction, a hand-run npm install or a Dependabot bump included, is flagged with its fix: run `/q:sync`. And every agent session, whether or not it ever invokes a q skill, is told to check every tier of conventions — q's, any extensions' you install, and yours — before writing code, making design decisions, or changing docs; your recorded decisions bind future sessions instead of living in one person's head.
+Every session start validates that your lockfile, the installed copies, and the watermarks still agree — drift from any direction, a hand-run npm install or a Dependabot bump included, is flagged with its fix: run `/q:reconcile`. And every agent session, whether or not it ever invokes a q skill, is told to check every tier of conventions — q's, any extensions' you install, and yours — before writing code, making design decisions, or changing docs; your recorded decisions bind future sessions instead of living in one person's head.
 
 **Decisions become conventions as you make them.** The scaffold is deliberately near-empty, because conventions are earned as decisions are made, not pre-written. When a session hits a decision, lesson, or gotcha worth binding, `/q:update-docs` records it under q's documentation policy — phrased as a rule, one home per fact, placed where its next reader will look.
 
+**A convention records practice. A spec records a promise.** A convention says how code here gets written, and it grows out of the decisions you make while working. A spec says what a feature does, and you write it on purpose, before the code or as a deliberate change to it. Break a convention and the code is wrong. Break a spec and the product is wrong, unless you meant to change the promise, in which case the spec changes with it.
+<!-- source: @lab43/q conventions/documentation.md, Taxonomy -->
+
 **Grooming keeps the docs true.** `/q:groom-docs` periodically verifies the whole documentation surface against the code and the policy — accuracy, duplication, dead references — so the docs agents are routed to stay worth trusting, which is what makes the routing worth anything.
 
 **You stay in charge.**
 
-- Both halves of q install pinned, and pins move only when you approve an update, which reconciles your docs with what changed.
+- Versions are yours to move — npm and your lockfile decide what runs, and `/q:reconcile` folds each move into your docs.
 - Your project's rulings win on conflict — record the disagreement and it stands (see the markers below).
 - Every run that delivers work settles its review mode with you up front. In local mode nothing is committed until you review it. In ship mode the work goes straight to a PR you review on GitHub. Merging is always yours.
 - It's all plain text files in your repo — removing q leaves your docs intact and yours.
@@ -162,27 +160,54 @@ Every session start validates that installed, pinned, and watermarked versions s
 <!-- source: @lab43/q conventions/documentation.md, Markers -->
 <!-- source: @lab43/q conventions/documentation.md, Single source of truth -->
 
-q's documentation keeps every fact in exactly one authoritative home, but text still needs to point at, copy, or disagree with facts that live elsewhere. Markers declare which of those relationships is in play — making them visible to readers and checkable by grep, with no central list to maintain:
+q's documentation keeps every fact in exactly one authoritative home. Text still has to point at, copy, or disagree with what lives elsewhere, and one site sometimes has to sit outside a rule the rest of the project follows. A marker declares which of those is in play — making it visible to readers and checkable by grep, with no central list to maintain:
 
-| Marker | Meaning |
-| --- | --- |
-| `(see: X)` | Plain cross-reference — nothing copied, the detail lives at X. |
-| `(source: X)` | This text is a copy and X is the authority — `/q:groom-docs` checks that the copy still agrees with X. |
-| `(overrides: X)` | This rule deliberately replaces the named one — a q rule (`overrides: @lab43/q conventions/documentation.md, Code examples in conventions docs`), an extension's rule (`overrides: @acme/q-ext-x conventions/retries.md, Backoff`), or a broader project convention (`overrides: docs/conventions/style.md, Magic numbers`). `/q:groom-docs` respects it, and `/q:upstream` picks up overrides worth carrying to the rule's owner. |
+<!--
+  Markers must not wrap.
+  see: docs/conventions/documentation.md, Table cells that must not wrap
+-->
+<!-- markdownlint-disable MD033 -->
+<table>
+  <tr>
+    <th>Marker</th>
+    <th>Meaning</th>
+  </tr>
+  <tr>
+    <td nowrap><samp>(see: X)</samp></td>
+    <td>Plain cross-reference — nothing copied, the detail lives at X.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>(source: X)</samp></td>
+    <td>This text is a copy and X is the authority — <code>/q:groom-docs</code> checks that the copy still agrees with X.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>(overrides: X)</samp></td>
+    <td>This rule deliberately replaces the named one — a q rule (<code>overrides: @lab43/q conventions/conventions.md, Code examples in conventions docs</code>), an extension's rule (<code>overrides: @acme/q-ext-x conventions/retries.md, Backoff</code>), or a broader project convention (<code>overrides: docs/conventions/style.md, Magic numbers</code>). <code>/q:groom-docs</code> respects it, and <code>/q:upstream</code> picks up overrides worth carrying to the rule's owner.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>(exception: X)</samp></td>
+    <td>This site is exempt from the named rule, which still stands everywhere else (<code>exception: docs/conventions/logging.md, Structured fields</code>). It always names both a doc and a section, and the reason is the text it sits in, in prose or in a comment — without either part it excuses nothing. <code>/q:groom-docs</code> counts them by rule, so several against one rule surface as a signal the rule wants revisiting.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>(spec: X)</samp></td>
+    <td>This code enforces the named spec statement (<code>spec: docs/specs/tasks.md, Due dates</code>). It sits only at enforcing code — a test, a validation, a guard — in that file's comment syntax, never in prose, and always names a section. Amending the section means visiting every site marked with it. <code>/q:groom-docs</code> reports a marker naming a doc or section that no longer exists, and a section no marker names.</td>
+  </tr>
+</table>
+<!-- markdownlint-enable MD033 -->
 
 ## Developing q
 
-<!-- source: docs/conventions/documentation.md, The tier test -->
+<!-- source: @lab43/q conventions/extensions.md, Which rules ship -->
 
-This repo has two conventions directories, by design. `conventions/` is the framework policy: it ships in the `@lab43/q` npm package and binds every consuming project. `docs/conventions/` is q's own project tier — rules for developing q itself (skill authoring, for example) that are not framework law. The split exists because q is a consuming project of its own workflow: it keeps its working docs at the same contract path any consumer would, kept apart from the product it ships.
+This repo has two conventions directories, by design. `q-extension/` is the payload the `@lab43/q` npm package ships, and its `conventions/` are the framework policy that binds every consuming project. `docs/conventions/` is q's own project tier — rules for developing q itself (skill authoring, for example) that are not framework law. The split exists because q is a consuming project of its own workflow: it keeps its working docs at the same contract path any consumer would, kept apart from the product it ships. Every extension gets the same two homes, and the rule deciding between them ships with the rest.
 
 <!-- source: CLAUDE.md, Developing -->
 <!-- source: docs/guides/driving-manual.md -->
 
 To work on q:
 
-- `claude` in your checkout auto-loads your working copy of the plugin (the repo declares itself as the `q` marketplace in `.claude/settings.json`); from any other project, `claude --plugin-dir <path to your checkout>` loads it. SKILL.md edits apply immediately; `/reload-plugins` picks up hook and agent changes mid-session.
-- When the `q:` skills don't load in your checkout, the CLI's registry holds that directory under a name other than `q`, so `q@q` resolves to nothing. `claude plugin marketplace add` matches the registry by path, so re-adding `./` just reports the stale entry. Remove it with `claude plugin marketplace remove <name>`, then add `./` again.
+- `claude` in your checkout auto-loads your working copy of the plugin (the repo declares itself as the `q-dev` marketplace in `.claude/settings.json`); from any other project, `claude --plugin-dir <path to your checkout>/q-extension` loads it without registering anything. SKILL.md edits apply immediately; `/reload-plugins` picks up hook and agent changes mid-session.
+- When the `q:` skills don't load in your checkout, read the `q-dev` entry in `claude plugin marketplace list`. An entry naming a directory that is gone — usually a worktree that held the name and was then removed — takes registering your checkout again, with its path written in full. No `q-dev` entry at all means the registry holds your directory under another name: remove that entry with `claude plugin marketplace remove <name>`, then register your checkout again. That remove also strips the marketplace from the repo's tracked `.claude/settings.json`, so check that file afterwards and put the declaration back.
 - `npm run check` runs every check the repo has, `npm test` among them. `package.json` names them; this line deliberately doesn't, because a list here goes stale the next time one is added. CI runs it on every pull request and on pushes to `main`.
 - `npm install` installs the pre-commit hook that runs `npm run check`. A tree you have not installed commits without checking anything.
 - Releasing is separate from merging, and PRs never touch a `version`. The steps live in `docs/guides/releasing.md`.

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@lab43/q",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "An agentic coding workflow framework: skills for planning, implementing, verifying, and grooming, grounded in per-project conventions docs.",
-  "files": ["conventions", "skills", "agents", "hooks", "references", ".claude-plugin"],
+  "q": {
+    "description": "The rules of the q workflow, governing how a project's work gets planned, decided, documented, and shipped."
+  },
+  "files": ["q-extension"],
   "scripts": {
     "prepare": "husky",
     "check": "npm run check-plugin && npm run check-versions && npm run check-markdown && npm run check-frontmatter && npm test",
-    "test": "node --test 'test/*.test.mjs'",
-    "check-plugin": "claude plugin validate --strict . && claude plugin validate --strict skills && claude plugin validate --strict agents",
+    "test": "node --test 'tests/*.test.mjs'",
+    "check-plugin": "claude plugin validate --strict q-extension && claude plugin validate --strict q-extension/skills && claude plugin validate --strict q-extension/agents",
     "check-versions": "node scripts/check-versions.mjs",
     "check-markdown": "markdownlint-cli2",
     "check-frontmatter": "node scripts/check-frontmatter.mjs"

package/{.claude-plugin → q-extension/.claude-plugin}/plugin.json

@@ -2,7 +2,7 @@
   "name": "q",
   "displayName": "q",
   "description": "An agentic coding workflow framework: skills for planning, implementing, verifying, and grooming, grounded in per-project conventions docs.",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "author": { "name": "Cameron Spencer", "email": "cameron@lab43.com" },
   "license": "MIT"
 }

package/q-extension/agents/adversarial-reviewer.md

@@ -0,0 +1,98 @@
+---
+name: adversarial-reviewer
+description: Adversarial reviewer grounded in the project's conventions and specs — tries to refute what it is given, reporting blocking findings vs nits. Work review — a diff command or files to examine, code or prose, optionally with what the work is meant to deliver (an agreed scope, or the plan plus which of its steps are in scope, which came earlier, and which are deferred) — under the correctness and/or conventions lens. Plan review — a pre-implementation plan doc — under the feasibility and/or rigor lens. For an artifact in another repo's checkout, the prompt names the conventions surface grounding the review.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are an adversarial reviewer for this repository. Your job is to try to refute the artifact you are given — assume it has problems and hunt for them. You are read-only: never modify files and never commit. An unexpected change in the working tree is covered by that, including one you believe you caused. Report it with your findings rather than reverting it. Never run a command that changes state outside this repository. Installs, plugin or package registrations, and writes to machine-wide config belong to the run, not to the review — a command that mutates them can break a project this review has nothing to do with.
+
+Baseline checks are not your job: lint, typecheck, and the test suites are verified green before a review is launched. Never run them — a green suite is not a finding, and re-running it adds nothing. Use Bash for git and investigation. If you suspect a specific defect that only executing code can confirm, run the narrowest command that tests that suspicion (a single test file or one name-filtered test), never a package or project suite. The same economy governs facts: where the artifact records how a fact was verified, audit that evidence — is the method sound, the source current? Driving the product (launching apps or simulators, exercising UI) is outside your scope: the run owns the environment. When a suspicion only the running product can settle, report it as a finding that names exactly what to check.
+
+Your prompt supplies an artifact and a lens; the artifact decides the review:
+
+- **Work review** (see: Work review) — the artifact is a diff, given as a git command (`git diff <sha>..HEAD`, `git diff main...HEAD`) and/or a list of changed files — or, with no change in play, the files or directories to examine for what's already wrong. The prompt may also supply what the work is meant to deliver: an agreed scope, or the plan plus which of its steps are in scope, which came earlier, and which are deferred. Lenses: **correctness**, **conventions**, or both.
+- **Plan review** (see: Plan review) — the artifact is a plan doc from `docs/plans/`, alone. Lenses: **feasibility**, **rigor**, or both.
+
+For an artifact outside this project — another repo's checkout — the prompt names a substitute grounding surface. Wherever these instructions read this project's docs — the agent briefing's docs index, the project's conventions — read that surface instead, and treat the artifact's own repo as the codebase to search.
+
+A combined review applies each lens in turn over the same artifact. If the prompt is missing something named here, do not review: return only a line naming what is missing, so the caller can relaunch with a complete prompt.
+
+What to hunt for is defined here, not by the prompt. Anything the prompt carries beyond the artifact, the lens, and what the work is meant to deliver is background. Background may add a place to look. It never narrows the hunt. An account of what changed and why is a claim to refute, not a fact to confirm.
+
+## Work review
+
+The artifact is a diff, or existing files with no change in play — code and prose alike. Your job is to refute it: show what shouldn't merge, or shouldn't stand. Given a diff, run its command and read every changed file in full; given files or directories, read them.
+
+A site may already carry an exception marker excusing it from a named rule (source: @lab43/q conventions/documentation.md, Markers). Under either lens, don't report the site for breaking that rule when the marker's reason holds. Report it when the marker is missing its reason or its section, or when the reason does not bear out at the site. An incomplete or hollow marker dodges the rule rather than excusing the site. A marker the work under review introduces gets no deference at all: judge the excuse on its merits, and never let a change excuse itself by adding one.
+
+Then hunt through the assigned lens or lenses.
+
+### The correctness lens
+
+Defects by universal engineering judgment, rules or no rules. Read enough surrounding and related code to judge integration points and the local idiom first. Then hunt:
+
+- bugs, broken or missed edge cases, error handling, security implications, race conditions, state bugs, dead code
+- inconsistency with the surrounding code's patterns
+- missing or hollow test coverage: tests that exist but don't exercise the new behavior
+- reuse: for each helper, component, or pattern the code introduces, search the codebase (Grep/Glob) for an existing implementation or established pattern that already covers it, and name the existing code to use instead
+- in prose, claims the repo contradicts and references that don't resolve
+
+When a plan or an agreed scope accompanies the work, verify the work actually delivers it, implemented rather than just started, and treat falling short as a BLOCKING finding. With a plan, judge only the in-scope steps: a step assigned elsewhere and missing from the code is NOT a finding.
+
+### The conventions lens
+
+Defects against this project's recorded law: its conventions and its specs. Read the law governing the artifact's territory first:
+
+- the conventions, found from the agent briefing's docs index
+- the specs, found from that index and from the markers in the changed files and the tests covering them: grep those files for `spec:` followed by a path under `docs/specs/`, and read every spec a hit names
+- for prose, the writing rules, which always apply (see: @lab43/q conventions/writing.md)
+
+Then hunt:
+
+- violations of those docs, citing the specific doc and rule for every finding
+- docs the change should have updated and didn't, held to what the documentation policy says each doc carries (see: @lab43/q conventions/documentation.md): a README describing the old interface, a briefing index missing a new doc's line, a conventions doc the change falsifies
+- drift in a living exemplar: grep the project's conventions for each reviewed file's path. Drift there outranks every other finding, because the docs actively send imitators to it
+- code that contradicts a spec statement
+- a spec section the diff amends while a site marked with that section did not move: grep the whole repo for markers naming the section, because the sites that must move sit outside the diff
+- enforcing code the diff adds without its marker: for each validation, guard, constraint, or test the diff adds, ask whether it enforces a commitment in the specs you read
+
+A conflict between code and law resolves by the kind of law:
+
+- Against a convention, the rule is presumed right. Grep sibling sites for evidence: many sites deviating the same way indicts the rule, one site indicts the code, and marked exceptions are that evidence already gathered. Report a rule the evidence indicts as a FOLLOW-UP, flagged as a candidate to amend the rule and carrying the evidence. That call is the user's, and the code is not the thing to fix.
+- Against a spec, the finding is BLOCKING with two exits, revert the change or amend the spec in the same change. Name both and choose neither, because only the user picks (source: @lab43/q conventions/specs.md, Disagreement). However many sites disagree, give no verdict on which side is wrong.
+
+## Plan review
+
+The artifact is a plan doc in `docs/plans/` with no implementation yet — there is no diff to run. Your job is to refute the plan before any code is written. Read it in full. Its recorded decisions are constraints, not findings — do not relitigate them, but DO flag when verified evidence contradicts one (as a finding that names the evidence).
+
+Then hunt through the assigned lens or lenses.
+
+### The feasibility lens
+
+The plan held against reality. Read every file, function, config value, and helper the plan names, plus the code around them — then hunt: claims about current behavior that the code contradicts (wrong file, wrong signature, behavior that doesn't exist); ripple effects the plan misses — search for tests, helpers, CI steps, scripts, and docs that depend on what the plan changes and aren't accounted for; plan steps already done or obsoleted by the current codebase; phases that can't stand alone as commits that build and pass their tests; insufficiency — executing every phase would still not deliver what the Goal section promises; over-engineering — machinery, phases, or generality the Goal does not require, where the codebase offers a simpler path (name it).
+
+### The rigor lens
+
+The plan held against its standards. Read the plan format (see: @lab43/q conventions/plans.md) and the conventions and specs governing the plan's territory, found from the agent briefing's docs index — then hunt: violations of any of them, quoting the failing text and citing the rule; sections that contradict each other; and phases that would contradict a spec statement without scheduling the spec's amendment in the phase that ships the behavior (source: @lab43/q conventions/specs.md, Disagreement). When the plan is right and the cited rule looks stale, report the conflict as a FOLLOW-UP, flagged as a candidate to amend the rule — that call is the user's, and the plan is not the thing to fix.
+
+## Output
+
+Your final message is the review: the three sections below, each a numbered list of one-line findings, a section omitted when it is empty — except BLOCKING, which when empty is replaced by the line `NO BLOCKING FINDINGS`.
+
+```text
+BLOCKING:
+1. <anchor> — the defect, in one line; a finding that rests on a rule names it.
+
+NITS:
+1. ...
+
+FOLLOW-UPS:
+1. ...
+```
+
+- The anchor is the finding's evidence: `file:line` for code; the plan section plus what contradicts it for plans (`plan §Phase 2 vs src/services/email.ts:32`).
+- BLOCKING = what must not proceed. For a work review: wrong to merge, or wrong to leave as it stands — bugs, convention violations, spec violations, reimplementation of existing code, missing tests for new behavior, unimplemented plan steps. For a plan: implementing it as written would fail, break something it doesn't mention, or violate conventions or specs.
+- NITS = worth noting, fine to skip.
+- FOLLOW-UPS = improvements outside the review's scope, as candidates for future work — the reviewed code's approach beats an existing pattern used elsewhere (name where), duplication or debt discovered nearby. Never BLOCKING, never fixed here.
+- Do not invent findings to appear useful, and do not rubber-stamp — verify claims against the actual code, not its surface appearance. Every finding must name a concrete failure or a specific violated rule.

package/q-extension/conventions/conventions.md

@@ -0,0 +1,49 @@
+# Conventions
+
+Rules for how a project's conventions are tiered, written, and enforced.
+
+## Three tiers of conventions
+
+- **Framework conventions** — the conventions docs `@lab43/q` ships, a dependency in the project's `package.json`. It carries the rules of the workflow itself, and defines the format an extension follows. Every q project installs it, and none can remove it.
+- **Extension conventions** — the installed extensions (see: @lab43/q conventions/extensions.md), each a dependency the same way, so rule improvements reach the project as its versions move. An extension extends q with rules of its own — for a library, a stack, or an organization's shared standards.
+- **Project conventions** — `docs/conventions/` in the consuming repo (a fixed contract path). Everything specific to the project's stack and codebase, plus its `documentation.md` mirror of the documentation policy, where documentation rulings and deviations are recorded. These are living docs: skills grow them as decisions are made and groom them as they rot.
+
+**Precedence: project conventions win over any extension's rule, whichever extension carries it. An extension's rule in turn wins over q's.** A project overrides a rule by recording the deviation in the project conventions doc whose topic owns it (created if needed), so the override sits where a reader applying the rule will look.
+
+- A deviation is written as an ordinary rule: the decision and the rationale, plus an overrides marker (see: @lab43/q conventions/documentation.md, Markers) naming the rule it replaces.
+- A deviation is refined in place or deleted as the decision evolves, never appended as a log entry.
+- An override outlived by its target — updated to agree, or gone — is spent and comes out.
+- Overriding a rule needs no other mechanism — the readers are agents, so stating the deviation is enough.
+
+A refinement that reaches beyond this project — one that would improve a q rule, or an extension's — is a candidate to upstream. Record it as an ordinary rule where it belongs and suggest `/q:upstream` to the user in the session. Never annotate the doc with its upstream candidacy.
+
+Conventions move into what a repo publishes when their audience grows beyond one project, on the user's decision (source: @lab43/q conventions/extensions.md, Which rules ship).
+
+## Conventions docs
+
+Rules for whoever is about to write or evaluate code — the unit this workflow reads and grows.
+
+**One topic per doc, broadly targeted until proven otherwise**: a doc is about "tests", not about "mocking data in Jest". Narrow docs scatter rules a reader needs together and multiply index lines — a doc that proves narrower than its topic merges into the doc owning the broader one. A doc narrows only by splitting, when a second topic has demonstrably grown inside it.
+
+**Every statement is a rule** — something to follow, a constraint to check, or a decision that binds future code, phrased that way. A sentence that wouldn't change what a reader writes or flags gets cut.
+
+- Descriptions of how the system currently works are not conventions — the code and exemplars carry those.
+- Never facts readable from the code: directory listings, dependency lists, schema enumerations, config values, and model/version names rot the moment code moves, and the code already answers them.
+- Record decisions and rejected alternatives only when they're highly likely to come up again: the alternative is the first thing a reader would reach for, or something deliberately ignored reads as an oversight. Each rejection names the alternative and the reason, nothing more.
+- The rationale stands inline — never cite the repo's issues or PRs as provenance; git history is the paper trail. Links to other projects' trackers as evidence for external-tool claims, and operational pointers to pending work tracked in an issue, remain fine.
+
+**A rule lands in the doc whose topic owns it**, integrated into the section it belongs to (see: @lab43/q conventions/writing.md, Refine rather than append) — grep the surface first; the rule may sharpen a sentence already there. A new doc is created only when no existing topic owns the rule.
+
+## Code examples in conventions docs
+
+Prose rules carry the conventions; code carries itself:
+
+- Each pattern names a **living exemplar** — a real file in the repo — and says which of its lines are load-bearing for the pattern, so an imitator doesn't copy the incidental along with the essential. Exemplar references and these notes are carved out of the no-code-readable-facts rule as a class; they exist to point *into* the code.
+- Short shape-only snippets are allowed where a rule is illegible without one. Snippets must not be copy-paste-complete: no import paths, no env-var literals, no full bodies. Anything an agent would paste verbatim must come from the exemplar.
+- Symbols, files, and helpers named in prose must exist — `/q:groom-docs` greps for them.
+
+Rejected: full copy-paste code templates, even compile-checked ones — doc inaccuracies cluster inside template code and code-readable fact restatements, not prose rules, and a stale template actively produces failing code.
+
+## Documentation is the last rung
+
+Documentation is the weakest enforcement rung (source: @lab43/q conventions/principles.md, Prefer the strongest enforcement rung): conventions prose carries only what components and lint can't express — decisions, rationale, rejected alternatives, cross-component gotchas. When a rule graduates into a component or a lint rule, delete its doc prose and move the rationale into the component or lint rule itself, where the reader who would remove it will see it. A doc entry survives graduation only if it meets the rejected-alternatives bar; git history keeps everything else. A spec's prose is the one carve-out: it stays after a test holds it, because it records the intent behind the test, and the test cannot drift from the commitment without the drift being visible (source: @lab43/q conventions/specs.md, Enforcement).

package/q-extension/conventions/documentation.md

@@ -0,0 +1,79 @@
+# Documentation Policy
+
+Rules for what belongs in a project's documentation, where it lives, and how it stays accurate. Follow them over any instinct. Every doc this policy governs must stay reviewable by a human: hold every edit to the writing rules (see: @lab43/q conventions/writing.md).
+
+## Taxonomy
+
+The policy owns what this taxonomy names — the `docs/` directories below, the README, and the briefing — plus, in the repo that authors an extension, its conventions docs and the `q.description` in its `package.json` (source: @lab43/q conventions/extensions.md, Authoring). Anything else under `docs/` — assets, generated output, tooling — is outside the policy: no rule here governs it, and grooming leaves it alone.
+
+File names are kebab-case. A taxonomy directory is read whole, subdirectories included, so a project groups its docs into subdirectories as it likes. Every doc opens with a topic title and an intro stating what the doc is *for* — its purpose, not an inventory of its contents: "Guidance for writing tests", never "Mocking data in Jest, stubbing API calls, and assertion gotchas". A purpose holds as sections change; a contents list rots on the next edit — and purpose is what a reader deciding whether the doc applies actually needs.
+
+The intro is the authoritative description of its doc. The briefing index's line for the doc is drawn from it and restates it, and grooming checks each pair for agreement. A doc the index carries arrives complete in one change: its intro plus its index line.
+
+Two doc types carry rules, and they divide by what they govern. A convention governs how code is written, and is recorded as the decision surfaces. A spec governs what a feature does, and is written on purpose: on the user's instruction naming the change, or through a plan the user approved that schedules the edit. Never write or amend a spec on a run's own initiative. A lesson that reads as a product commitment is reported to the user as a spec candidate and left unwritten.
+
+- **`docs/conventions/`** — the project's conventions docs (see: @lab43/q conventions/conventions.md).
+- **`docs/specs/`** — the project's specs: what the product commits to, stated as behavior the code must honor. Format and enforcement rules live in their own doc (see: @lab43/q conventions/specs.md). Grooming gives a spec every check a conventions doc gets, with accuracy reversed: a commitment the code does not honor is reported to the user as unmet, never corrected as a doc, because a spec may run ahead of its code and only the user knows whether the gap is work in progress, work missed, or a regression. Grooming also audits the spec markers (see: Markers), reporting each marker naming a doc or section that does not exist and each spec section no marker names.
+- **`docs/plans/`** — feature plans across their whole lifecycle — upcoming, in flight, and shipped; format and lifecycle rules live in their own doc (see: @lab43/q conventions/plans.md). Grooming checks status only — surfacing stale `pending` plans for the user's ruling — and treats merged plans' frozen bodies as exempt from accuracy, duplication, and pruning checks.
+- **`docs/guides/`** — guides: instructions for using and operating the product, not for writing its code (deployment walkthroughs, feature guides, operational procedures). Step-by-step detail is fine, and so are inline code-readable specifics — bucket names, URLs, ports — a reader mid-task shouldn't have to dig out of code or config; only repo-referencing facts (script names, env vars, paths, such specifics) are held to accuracy — external-console steps can't be verified from the repo.
+- **`README.md`** — the human overview, answering an arriving reader's questions: what this is, what it does, how to use it.
+  - **Summarizing facts owned elsewhere is its normal mode**, not a violation — the obligation is checkability: a summary that mirrors one identifiable home carries a source marker; free-form overview prose is held accurate against the things it describes by grooming. Inline code-readable specifics — URLs, ports, commands — are fine under the same obligations; the arriving reader shouldn't have to dig for them.
+  - **Interface, not internals**: enumerating the product's interface (commands, skills, entry points) serves the reader and belongs; inventorying the repo's internals (directory layout, file lists) restates what browsing already shows — an internal detail earns mention only when it explains something non-obvious.
+  - **Prose is evergreen**: a sentence describing the current moment ("being migrated to…") rots silently once the moment passes — describe what the product is, and let git history carry the journey.
+- **`CLAUDE.md`** — the always-loaded agent briefing. Rejected: `AGENTS.md`, the cross-tool briefing convention — Claude Code doesn't read it, and q runs in Claude Code. Every line costs context in every session, so only what applies session-wide belongs; information needed for particular kinds of work lives in the relevant convention doc or skill, with at most a one-line pointer here. Two things are required:
+  - **The standing instructions** that make the conventions bind: all three tiers of conventions apply (see: @lab43/q conventions/conventions.md, Three tiers of conventions) — check them before writing code, before design decisions and reviews, and before changing docs — and doc changes go through `/q:update-docs`, the README and the briefing itself included.
+  - **The docs index** — one line per doc, restating its intro: every conventions doc, whether q's, an installed extension's, this repo's own payload, or the project's own, every spec, and every guide. Group the lines by where the docs come from, the specs in a group of their own. Head each group with what its docs govern, so a session reading the index can tell whose rules are whose. An extension's heading pairs its package name with its `q.description`, whether the project installs that extension or authors it (see: @lab43/q conventions/extensions.md, Description). An index line is routing, not content. A guide a session can't act on is still one it should know exists. Skills are never indexed: the session's skill list already carries every skill's name and description.
+
+## Single source of truth
+
+Every fact has exactly one home; every other doc links to it, never restates it. A fact's home is normally implied by the taxonomy and the docs' topics — cross-references carry readers there, and no record of the placement is needed. A placement is recorded in the project's `docs/conventions/documentation.md` only when a reasonable writer or groomer would have put the fact elsewhere — the record exists so grooming doesn't re-litigate it; obvious homes need no entry.
+
+**Restatements**: a doc may restate a rule or fact it operationally depends on — a skill's procedure executing it, the briefing orienting every session with it, a README table presenting it to humans — provided the restatement carries a source marker (see: Markers). The marker is the sanction; an unmarked restatement is ordinary duplication.
+
+Rejected: a standing central registry of all shared facts and their homes. It accumulates entries whose home is obvious from the doc's topic, and it rots like any other enumeration.
+
+## Package doc paths
+
+`q` names the workflow itself — in prose, in the plugin and marketplace a project publishes, and as what a user types to name it. `@lab43/q` is the npm package: use it wherever npm has to recognize the name — a path into the package, an install command, a `package.json` field.
+
+Reference q's docs and an extension's by package name plus path from the package's payload directory — `@lab43/q conventions/documentation.md`, `@acme/q-ext-x conventions/retries.md`. The name resolves to the installed copy in `node_modules/`, or to the package's working tree in the repo that authors it. The payload directory is `q-extension/` at the package root (source: @lab43/q conventions/extensions.md, Layout). The reference never spells that segment: `@lab43/q conventions/documentation.md` is `node_modules/@lab43/q/q-extension/conventions/documentation.md`. Use the form for every such reference across the documentation surface — markers, the briefing's index lines, doc prose. Use it even for a sibling in the doc's own package: a reference must stay unambiguous when its text is quoted away from its file.
+
+Rejected: abbreviating `@lab43/q` to `q` in the path form. `q` is a different package on the public registry, so the abbreviated reference resolves to whatever `node_modules/q/` holds.
+
+## Markers
+
+Inline cross-references tying a statement to the doc it depends on. They are the documentation surface's own routing, and must suffice for a reader arriving with no skill running — the skills reinforce the routing but can't be assumed. Agents follow them to the related detail; `/q:groom-docs` reads them as recorded intent — a marked restatement or deviation is checked against its target rather than re-flagged as duplication or drift on every run.
+
+All share one grammar — `(verb: target)` or `(verb: target, section)`, the section naming a heading within the target. The target is one of:
+
+- a heading in the current doc (`see: Markers`)
+- a repo file or directory, read from the repo root exactly as written — a project doc (`docs/conventions/testing.md`), any other file a fact is read from (`source: config.yml`), or a directory when the text summarizes its files (`source: migrations/`)
+- anything a package ships, by its path form (see: Package doc paths)
+
+A leading package name is what separates the last two forms. Use the path form for every target a package ships, because a bare path would be read literally and find nothing.
+
+A conventions doc always takes the path form, wherever the marker sits. It binds every session, and a session meets it with no skill running, so the marker has to resolve from the documentation surface alone.
+
+`${CLAUDE_PLUGIN_ROOT}` is for the files nothing but a running skill ever opens — a plugin's own references and manifest. It resolves wherever the session loaded that plugin from, including a `--plugin-dir` directory that sits under no `node_modules/` and belongs to no authoring repo.
+
+Five markers, all ordinary language:
+
+- **`(see: X)`** — cross-reference. Nothing is copied; detail lives at X. No obligations attach.
+- **`(source: X)`** — provenance. This text restates a fact whose authoritative home is X (see: Single source of truth).
+- **`(overrides: X)`** — precedence. This rule deliberately replaces the named rule — a q rule (`overrides: @lab43/q conventions/conventions.md, Code examples in conventions docs`), an extension's rule (`overrides: @acme/q-ext-x conventions/retries.md, Backoff`), or a broader project convention (`overrides: docs/conventions/style.md, Magic numbers`).
+- **`(exception: X)`** — excuse. This site is exempt from the named rule (`exception: docs/conventions/logging.md, Structured fields`). The rule still stands everywhere else. Several exceptions against one rule are evidence the rule wants revisiting.
+- **`(spec: X)`** — enforcement. This code enforces the named spec statement (`spec: docs/specs/tasks.md, Due dates`). Which sites carry it, and what amending the statement obliges, are the specs rules (see: @lab43/q conventions/specs.md, Enforcement).
+
+`(see:)`, `(source:)`, and `(overrides:)` live in the documentation surface, the only place anything reads them. An exception may sit in any file, because the site it excuses is as often a line of code or config as a passage of prose. A spec marker never sits in the documentation surface, because what enforces a commitment is code, config, or a test. A doc that restates a commitment carries `source:` instead.
+
+A marker may sit in a comment rather than in running prose:
+
+- In docs rendered for humans (README, guides), it sits in an HTML comment.
+- In any other file, which only an exception or a spec marker reaches, it sits in that file's own comment syntax.
+- Either way it drops the parentheses. The comment's own delimiters stand in for them, so it reads `<!-- source: docs/conventions/testing.md -->`.
+
+A comment carrying prose as well gives the marker its own line. Comments are otherwise ordinary (see: @lab43/q conventions/principles.md, Comments carry constraints, not justification).
+
+An exception and a spec marker each must name a section, because only a marker that identifies the rule or the statement can be counted against it. An exception must also carry a reason, which is the text the marker sits in: the sentence in a doc, or the comment in any other file. An exception missing either part excuses nothing.
+
+An exception is spent once its site no longer needs excusing: the rule is gone, or it changed to admit the site. A spent exception comes out. One whose rule merely moved is retargeted, because the site still needs it.

package/q-extension/conventions/extensions.md

@@ -0,0 +1,70 @@
+# Extensions
+
+The format behind the extension conventions tier — rules for authoring and publishing a q extension.
+
+## Identity
+
+A q extension is an npm package that carries the `q-extension` keyword in its `package.json` and ships a `q-extension/` payload directory (see: Layout). Both halves identify it. The keyword is how tooling tells extensions from a project's other dependencies and how they are found on the registry. The payload is what the keyword promises. A package carrying the keyword and shipping nothing is not an extension, and q's machinery passes over it in silence rather than reporting a state no skill can repair.
+
+Look for extensions across a project's direct `dependencies` as well as its `devDependencies`. A package can ship rules and code together — a component library carrying the conventions for using it — and a project that imports such a package holds it as a regular dependency. Meeting both halves means q's machinery:
+
+- discovers the package
+- indexes what it documents
+- registers the plugin it ships, for the project's sessions to load
+- reconciles the project against its releases
+
+q is not an extension but what extensions extend: the framework whose rules they add to and whose format they follow (source: @lab43/q conventions/conventions.md, Three tiers of conventions). `@lab43/q` carries no keyword, and is named outright wherever a rule reaches it.
+
+## Which rules ship
+
+A repo that publishes rules has two homes for a rule it writes, and every rule goes to one of them. A repo that publishes none has one home, `docs/conventions/`, and becoming a publisher is the user's call rather than a session's.
+
+- **The payload** — everything under the package's `q-extension/` directory, which is what binds its consumers (see: Layout).
+- **`docs/conventions/`** — rules for developing the repo itself: its own code, its docs, its repo mechanics. Consumers are never bound by these and never routed to them.
+
+The test is one question: would this change what a session in a consuming repo writes or flags? Yes puts it in the payload. No keeps it local.
+
+A rule can pass that test later, as its audience outgrows one project — org-wide rules, or rules for code that uses a product. Move it then: out of `docs/conventions/` into the payload, never copied into both, its index line crossing from the project's group to the payload's rather than disappearing (see: Authoring).
+
+**Payload is addressed solely to consumers.** Payload docs never name the repo that authors them, its development practices, or its internal layout. Even acknowledging that they might be read from inside that repo muddies them for the audience they speak to. A repo still follows the payload it ships, as a consuming project of its own rules.
+
+Rejected: shipping the payload's conventions at the contract path, `docs/conventions/`, so that one path means conventions everywhere. It conflates what the package ships with the repo's own working rules, so a consumer reading the shipped docs would meet repo-local rulings as law.
+
+## Description
+
+`package.json`'s `q.description` states what the extension's rules govern. A consuming project's briefing heads the extension's group of index lines with it (source: @lab43/q conventions/documentation.md, Taxonomy). Name the territory the rules cover, not the package's shape.
+
+## Layout
+
+A package's payload is a `q-extension/` directory at its package root. Everything the package ships for q lives inside it. Name `q-extension` in the `files` whitelist: without it the package ships no rules at all, announces itself as an extension anyway, and nothing warns.
+
+What it holds depends on what the extension carries:
+
+- `conventions/` when it ships conventions docs, each written to the documentation policy (see: @lab43/q conventions/documentation.md).
+- `.claude-plugin/` when it ships a plugin, beside whatever that plugin loads — its skills, agents and hooks. `q-extension/` is then the plugin root, and `${CLAUDE_PLUGIN_ROOT}` resolves to it. A consuming project registers the plugin in its own marketplace under the `name` in the plugin's `plugin.json`, so that name is the namespace its sessions type: `/<name>:<skill>`. Choose one no other extension is likely to carry. `q` is taken. What else a plugin may hold is Claude Code's to decide; q fixes only where its root sits.
+
+Every extension ships at least one of the two, which is what identifies a payload (see: Identity). Anything else the package ships for q sits beside them.
+
+An extension shipping no conventions docs is watermarked but never indexed, having nothing for a briefing's docs index to carry. Watermarking and indexing are separate for that reason.
+
+Rejected: a `q` metadata key in `package.json` naming paths or listing docs — the payload directory and the keyword already answer where everything is, and an enumeration of docs rots against its own contents. The key carries the description and nothing else (see: Description).
+
+## Pinning
+
+Declare `@lab43/q` as a devDependency in the `package.json` at the repo root. That is the only place anything looks for it, whatever else the repo holds — a monorepo declares q at the root, never in a workspace manifest. Keep it a devDependency: q is tooling rather than code a project imports, and a project holding it in `dependencies` goes unvalidated at session start, silently.
+
+Declare each extension in that same root manifest. `dependencies` and `devDependencies` both serve (see: Identity), but no other manifest does — a declaration in a workspace package is one nothing reads. The specifier's form is the project's own choice: q reads versions from the lockfile and `node_modules`, never from the manifest.
+
+A repo that publishes rules already declares q at its root, like any q project, with one requirement of its own: the pin is exact. With the payload at that root, the published package is the repo itself — its `package.json` goes into the tarball, and the pin in it tells consumers which q version the rules were written against. That is a fact only an exact version can state, and the manifest is the author's only channel for it: the lockfile that would resolve a range never ships. The declaration stays inert in consumers — npm installs no dependency's devDependencies — so extensions declaring different q versions never collide; the gap is surfaced at reconciliation and closes through releases.
+
+## Authoring
+
+In its authoring project, an extension's conventions docs and its `q.description` join the documentation surface (see: Description). Both are groomed and reconciled against q's updates like the project's own docs.
+
+They are indexed there too. The authoring repo's briefing gives them a group of their own, shaped like a consumed extension's and headed the same way. The group carries no pin, because a repo does not depend on itself, and no watermark, because a watermark certifies that changed rules have been absorbed and there is nothing to absorb in rules you are editing.
+
+An extension's doc may deviate from a q rule the same way a project doc does, stating the deviation with an overrides marker (see: @lab43/q conventions/documentation.md, Markers); the project's own rulings still win over any extension's (source: @lab43/q conventions/conventions.md, Three tiers of conventions).
+
+The plugin the extension ships loads from the working tree too. Add its entry to the project's own marketplace by hand, beside q's: sourced at `./q-extension` and named by the `name` in its `plugin.json`. Enable it in `.claude/settings.json` the way q's entry is enabled there.
+
+All of this assumes the payload sits at the repo's own root. Publish from a sub-package of a larger repo and consumers install it exactly the same way, but the authoring repo gets none of the above: no group in its briefing, and a root declaration that is not the pin the package ships (see: Pinning).