@lab43/q 0.4.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,6 @@
+{
+  "name": "q",
+  "description": "Serves q's plugin from the installed package.",
+  "owner": { "name": "Lab43" },
+  "plugins": [{ "name": "q", "source": "./" }]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "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.4.0",
+  "author": { "name": "Cameron Spencer", "email": "cameron@lab43.com" },
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# q
+
+An agentic coding workflow for Claude Code: skills for planning, implementing, verifying, and grooming, grounded in per-project conventions docs that each consuming project builds up over time.
+
+Named for Q, the quartermaster who equips James Bond with his gadgets — q outfits your agents before they go into the field.
+
+## Requirements
+
+[Claude Code](https://claude.com/claude-code), [Node.js](https://nodejs.org) — the conventions install as an npm package — and an authenticated [GitHub CLI](https://cli.github.com) (`gh`).
+
+## Adding q to a project
+
+```
+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
+```
+
+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:
+
+<!-- source: 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
+
+## Joining a project that uses q
+
+<!-- source: skills/install/SKILL.md -->
+
+Install the project's dependencies, substituting your package manager where the project isn't on npm:
+
+```
+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.
+
+## Skills
+
+<!-- source: 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.
+-->
+<table>
+  <tr>
+    <th>Type</th>
+    <th>Skill</th>
+    <th>What it does</th>
+  </tr>
+  <tr>
+    <th rowspan="4" 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>
+  </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>
+  </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 briefing index lines, its watermark, and your ruling on each doc that references it.</td>
+  </tr>
+  <tr>
+    <th rowspan="8" 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:tackle</code>.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:tackle</samp></td>
+    <td>Take on unplanned work — ground it in the code, then fix it in a single adversarially reviewed PR, escalate to planning, or show with evidence that nothing needs doing.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:create-plan</samp></td>
+    <td>Collaboratively plan a feature into <code>docs/plans/</code> — grounded in the code, settled with you, hardened by adversarial review. Produces the plan doc, never code.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:implement-plan</samp></td>
+    <td>Execute a plan end-to-end — phased implementation with adversarial review, then the PR (or stacked PRs) the plan calls for.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:review</samp></td>
+    <td>Review anything ad hoc — a diff, file, directory, feature, or plan doc — through the adversarial reviewer; you rule on the findings, and a finding may fault a convention rather than the work.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:address-feedback</samp></td>
+    <td>Work feedback on a PR — the reviewer's comments, or revisions you raise yourself. Every item gets a position and your ruling, then the agreed fixes are implemented, reviewed, and pushed to the PR, with replies posted when you want them.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:drive</samp></td>
+    <td>Bring the product up and exercise it — to see a change working, or to settle a question only running something can. Records what launching and navigating it took, so the next session doesn't rediscover it.</td>
+  </tr>
+  <tr>
+    <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>
+    <th rowspan="3" scope="rowgroup">Docs</th>
+    <td nowrap><samp>/q:update-docs</samp></td>
+    <td>The single write path for doc changes — record a lesson, fix a guide, amend the briefing. Invoked directly, the changes ship as a PR.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:groom-docs</samp></td>
+    <td>Audit the whole documentation surface against the documentation policy and consolidate what has drifted. Approved edits ship as a PR.</td>
+  </tr>
+  <tr>
+    <td nowrap><samp>/q:upstream</samp></td>
+    <td>Turn session friction and recorded deviations into PRs against the repos that own the rules — q's own, or an extension's.</td>
+  </tr>
+</table>
+
+## How it works
+
+<!-- source: docs/workflow-chart/chart.html -->
+<!-- regenerated by docs/workflow-chart/screenshot.py -->
+<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 tackle 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">
+  </picture>
+</a>
+
+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 -->
+
+**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
+- 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
+
+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.
+
+**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.
+
+**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.
+- 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.
+
+## Markers
+
+<!-- source: q conventions/documentation.md, Markers -->
+<!-- source: 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:
+
+| 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: 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. |
+
+## Developing q
+
+<!-- source: docs/conventions/documentation.md, The tier test -->
+
+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.
+
+<!-- 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 plugin validate --strict .` checks the marketplace manifest; `claude plugin validate --strict skills` and `claude plugin validate --strict agents` check the components; `npm run check-versions` checks that the two manifests carrying a version agree.
+- Releasing is separate from merging, and PRs never touch a `version`; the steps live in `docs/guides/releasing.md`.
+- When another session is already working your checkout, take a worktree rather than sharing it. A worktree needs no setup here: the repo has no dependencies to install. `.claude/settings.json` is tracked, so the plugin loads there.

package/agents/adversarial-reviewer.md

@@ -0,0 +1,62 @@
+---
+name: adversarial-reviewer
+description: Adversarial reviewer grounded in the project's conventions — tries to refute what it is given, reporting blocking findings vs nits with file:line references and convention citations. Invoke it two ways. 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 outside the invoking project — another repo's checkout — the prompt names the conventions surface that grounds 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.
+
+Then hunt through the assigned lens or lenses:
+
+**correctness** — defects by universal engineering judgment, rules or no rules. Read enough surrounding/related code to judge integration points and the local idiom — 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). This lens owns **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, hunt 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, not 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.
+
+**conventions** — defects against this project's recorded law. Read the conventions governing the artifact's territory first, found from the agent briefing's docs index. For prose, the writing rules always apply (see: q conventions/writing.md). Then hunt: violations of those docs (cite the specific doc and rule for every finding), and documentation updates the change requires per the documentation policy (README, briefing, conventions docs). Check whether a reviewed file is a living exemplar — grep the project's conventions for its path. Drift in an exemplar outranks every other finding: the docs actively send imitators to it. On a code-versus-rule conflict the rule is presumed right; grep sibling sites for evidence — many sites deviating the same way indicts the rule, one site indicts the code. 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.
+
+## 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:
+
+**feasibility** — 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).
+
+**rigor** — the plan held against its standards. Read the plan format (see: q conventions/plans.md) and the conventions governing the plan's territory, found from the agent briefing's docs index — then hunt: violations of either, quoting the failing text and citing the rule; and sections that contradict each other. 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`.
+
+```
+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, 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.
+- 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/conventions/documentation.md

@@ -0,0 +1,99 @@
+# 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: q conventions/writing.md).
+
+## Three tiers of conventions
+
+- **Framework conventions** — `@lab43/q`'s own `conventions/`, pinned 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: q conventions/extensions.md), each pinned the same way, so rule improvements reach the project on pin updates. 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 this 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: 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.
+- No other override mechanism exists or is needed — the readers are agents, so a stated deviation is the mechanism.
+
+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 graduate into an extension when their audience grows beyond one project (source: q conventions/extensions.md, Graduation).
+
+## 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: 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, and it arrives complete in one change: its intro (see: Taxonomy) plus its line in the agent briefing's index.
+
+## Taxonomy
+
+The policy owns what this taxonomy names — the `docs/` directories below, the README, and the briefing — plus an authored extension's `conventions/` in its authoring repo (source: 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. 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.
+
+- **`docs/conventions/`** — the project's conventions docs (see: Conventions docs).
+- **`docs/plans/`** — feature plans across their whole lifecycle — upcoming, in flight, and shipped; format and lifecycle rules live in their own doc (see: 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: 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, or the project's own, and every guide. 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
+
+Reference q's docs and an extension's by package name plus path from the package root — `@acme/q-ext-x conventions/retries.md`. `q` is the alias for `@lab43/q`: `q conventions/documentation.md`. The name resolves to the installed copy in `node_modules/`, or to the package's working tree in the repo that authors it. 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.
+
+## Markers
+
+Inline cross-references tying a statement to the doc it depends on. They are the doc 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, by path from the repo root — 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/`)
+- one of q's docs or an extension's, by its path form (see: Package doc paths)
+
+In docs rendered for humans (README, guides), the marker may sit in an HTML comment — agents and grep read the raw file either way. A doc's comments are otherwise ordinary comments (see: q conventions/principles.md, Comments carry constraints, not justification).
+
+Three 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: 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`).
+
+## 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 a sanctioned exception to the no-code-readable-facts rule; 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: 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.
+

package/conventions/extensions.md

@@ -0,0 +1,48 @@
+# Extensions
+
+The format behind the extension conventions tier — rules for authoring and publishing a q extension.
+
+## Identity
+
+A q extension is an npm package whose `package.json` carries the `q-extension` keyword. The keyword is the identity: how tooling tells extensions from a project's other dependencies, and how they are found on the registry. Carrying it means q's machinery:
+
+- discovers the package
+- indexes what it documents
+- reconciles the project against its releases
+
+Nothing without it is an extension — a project's own `docs/conventions/` included.
+
+q is not an extension but what extensions extend: the framework whose rules they add to and whose format they follow (source: q conventions/documentation.md, Three tiers of conventions). `@lab43/q` carries no keyword, and is named outright wherever a rule reaches it.
+
+Installing an extension runs no code. The install passes `--ignore-scripts`, and an extension declares no lifecycle scripts. An extension may ship executable files — a plugin's hooks run inside a session — but nothing in it runs as a consequence of being installed.
+
+## Layout
+
+The layout is conditional on what the extension carries:
+
+- `conventions/` at the package root when it ships conventions docs, each written to the documentation policy (see: q conventions/documentation.md).
+- `.claude-plugin/` when it ships a plugin.
+
+Every extension ships at least one of the two.
+
+An extension with no `conventions/` 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` (configurable paths, a per-doc manifest) — every job it would do is already covered by the two directories above, the keyword, and the doc intros, and an enumeration of docs rots against its own contents.
+
+## Pinning
+
+An extension is authored in a project that itself uses q, with `@lab43/q` pinned in the extension's own `package.json` — an exact devDependency that is also the authoring project's live install (in a monorepo, the extension as a workspace), so pin and declaration are one field, never two to drift apart. Shipped in the tarball, the pin declares the q version the extension is written against; the skills hold it against a consuming project's own pin and flag drift. q carries no such pin: its version is the thing declared against.
+
+## Authoring
+
+In its authoring project, an extension's `conventions/` joins the documentation surface — groomed and reconciled against q's updates like the project's own docs. Moving the q pin asserts that reconciliation happened: the moved pin declares the docs written against the new version (see: Pinning). Don't record a deviation from a convention you ship — edit it. Deviations, overrides, and upstreaming are for rules you consume, not rules you author. In the authoring repo, references to the extension's docs resolve to its working tree (source: q conventions/documentation.md, Package doc paths).
+
+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: q conventions/documentation.md, Markers); the project's own rulings still win over any extension's (source: q conventions/documentation.md, Three tiers of conventions).
+
+## Graduation
+
+Conventions graduate into an extension when their audience grows beyond one project — org-wide rules, or rules for code that uses a product. Graduating docs move out of the authoring project's `docs/conventions/` into the extension, never copied into both homes; the authoring project keeps only its project-specific rulings local.
+
+## Publishing
+
+The format says nothing about repositories: publishing an extension from a subdirectory of the authoring repo works as well as a dedicated repo. An extension published from a subdirectory sets `repository.directory` so registry links resolve to it. Use a `files` whitelist limiting the tarball to what the extension ships — npm adds `package.json`, the README, and the license itself.

package/conventions/issue-tracking.md

@@ -0,0 +1,19 @@
+# Issue Tracking
+
+Rules for working a project's issue tracker — the shared source of work items — from any session. Sign every item you file and every comment you post: "— Claude 🤖" (source: q conventions/writing.md, Sign what you post).
+
+## Respect existing claims
+
+An item assigned to someone else, marked in progress or blocked, or with a fix already in review is not available to pick up. A claim that looks stale — long untouched, its PR closed unmerged — may be wrong: surface it to the user rather than working the item or silently passing it by.
+
+## Claim what you work
+
+Picking up a tracker item means assigning it to the user and moving it to the tracker's working status — on the user's agreement, asked once per session and carried forward.
+
+## Ask before filing
+
+Filing a new tracker item — the follow-up work a session surfaces — happens on the user's agreement, given per item rather than once per session. Ask the session's candidates together, in one batch.
+
+## Work links back
+
+The PR addressing an item links to it from the PR body; when the tracker doesn't pick that link up automatically, comment the PR's link on the item — on the user's agreement, asked once per session and carried forward.

package/conventions/plans.md

@@ -0,0 +1,60 @@
+# Plans
+
+Format, sequencing, and lifecycle rules for `docs/plans/` documents. `/q:create-plan` writes to this rubric and its adversarial plan reviews enforce it; `/q:implement-plan` executes the delivery shape the plan records.
+
+## Audience
+
+The plan documents the work, not the conversation that produced it: the reader is `/q:implement-plan` with none of that conversation.
+
+- Every sentence either directs work or prevents a wrong decision — cut anything else.
+- State each fact in one section only; other sections reference it, never restate it.
+- A reference may run forward when the acting section comes later. Treat each forward reference as evidence to weigh: the plan may be presenting information in the wrong order.
+
+## Frontmatter
+
+- `status: pending | completed | abandoned` — when each applies and who flips it are lifecycle rules (see: Lifecycle).
+- `delivery: single | stacked` — absent means single; the choice is a sizing call (see: Delivery shape).
+- `tracks` — the work items this plan delivers, as their tracker names them: one reference, or a list of them. Absent means the plan answers to no tracker. This is where a reader looks for what the plan is against, and where a session announces what it holds, so the body states an item's reference only where it has something to say beyond naming it.
+
+## Sections
+
+In order. A section with nothing load-bearing to say for this plan is omitted, never padded — and what already binds every session (the conventions docs, the project's standing tooling) goes without saying:
+
+- **Goal** — what the plan delivers and why it's worth doing.
+- **Context** — the givens the plan inherits rather than chooses: what is true today, with `file:line` references, and any constraints the solution must respect — invariants, compatibility, external realities. A fact the code can't witness states how it was verified — the source read, or the check run — as evidence reviewers audit instead of repeating the verification. A given needs no defending rationale; anything that could have gone another way is a Decision instead.
+- **Decisions** — numbered, each carrying its rationale from the discussion (the why, not just the what) and its rejected alternatives inline. Rationale is the shortest argument that keeps a decision from being reopened. Rejected alternatives appear only when a reviewer would plausibly re-propose them.
+- **Out of scope** — only work a reader would otherwise assume was included, each item marked deferred or declined, with why. Not a parking lot: adjacent ideas the discussion surfaced but the plan doesn't need stay out entirely.
+- **Phases** — the implementation sequence, per Phases below.
+- **Verification** — how to prove the integrated result works: the end-to-end flows to exercise, and any proof beyond the phases' own tests. Phases prove themselves (see: Phases) — this section covers what no single phase's tests can. Only checks that prove *this plan's* changes: generic process steps (baseline runs, extra suite passes, added review rounds) belong in the workflow skills, decided once, not re-imposed per plan.
+
+## Phases
+
+A phase is the unit of work and of review; the PR is the unit of shipping. A single-PR delivery ships every phase as one PR; a stacked delivery groups them into several (see: Delivery shape).
+
+- **Green boundaries**: every phase ends with the repo green (lint, typecheck, tests) and shippable. Each phase ideally delivers a visible improvement on its own; at minimum it is inert (machinery landed dark), never a broken in-between state.
+- **Cutovers stay small**: when the plan replaces an existing path, the switch is its own small phase — not bundled into a machinery diff — and the old path retires in a later phase, so the riskiest change stays reviewable and revertable on its own. This is a rule for replacements, never an argument for building dark what could ship working.
+- **Phases split at seams, not line counts**: a phase boundary falls only where a natural seam exists — an independent subsystem, the cutover from an old path to its replacement. Size is a smell, not a rule: a phase running far past a few hundred changed lines (lockfiles and generated files excluded) is a prompt to look for a seam that was missed, never a mandate to cut at an unnatural place. A phase with no internal seam stays whole, whatever its size.
+- **Steps are concrete**: a phase's steps name the files and functions they touch — a step the implementer must first re-derive is planning left undone.
+- **Tests ride with their phase**: each phase carries the tests of the behavior it adds — never a trailing tests phase.
+
+## Delivery shape
+
+The `delivery` call:
+
+- **Single PR** — the default when the whole change is a scope a reviewer can hold in one sitting (roughly a few hundred changed lines).
+- **Stacked PRs** — for anything larger, using the `gh stack` CLI extension: per-layer CI and review, cascading bottom-up merge. A stacked plan's Phases section groups its phases into PRs, each group one or more phases making a reviewable scope; `/q:implement-plan` carries the mechanics.
+
+When in doubt, ask the user. A genuinely borderline call records its rationale as a Decision.
+
+## Lifecycle
+
+Plans are written as `pending`, flipped to `completed` when their implementation ships, and flipped to `abandoned` only by the user.
+
+Deviations discovered while the implementation runs are recorded as amendments — added during the run, never after it ships. An amendment is an italicized parenthetical appended directly to the text it amends; the agreed text stays as written, quoted inside the amendment if it must be contradicted rather than extended. Two forms:
+
+- *(deviation: …)* — reality diverged from the text: a step done differently, a decision or given that shifted mid-run. States what happened instead, and what forced it.
+- *(result: …)* — the outcome of a step the plan could only pose as a question — a check, a measurement, a re-verified fact.
+
+After merge, a plan's body is frozen history: it describes the world at planning time, and readers treat plan age (git history) as the recency signal. How grooming treats plans is the documentation policy's rule (see: q conventions/documentation.md, Taxonomy).
+
+Rejected: an `archive/` directory for terminal plans (moves break links; status is machine-readable in place) and a `superseded` status (chain-tracking costs more than it returns; a plan implemented then reversed stays `completed` — both plans are accurate history).

package/conventions/principles.md

@@ -0,0 +1,41 @@
+# Principles
+
+Cross-cutting rules that apply to any design decision, plan, or review — not tied to a layer, package, or stack.
+
+## Tooling limitations never dictate content
+
+Product and design decisions are made on their merits. If a design choice would break a test helper, e2e spec, CI step, or script, fix the tooling to accommodate the design — never bend the design to accommodate the tooling.
+
+Example: an e2e helper that can only extract the first link in an email body is not a reason to require emails to contain a single link — the helper grows a way to target the link the test wants, and email content stays a pure design choice.
+
+When a plan or review catches this pattern, the fix belongs on the tooling side, scheduled in the same plan or change as the design decision that exposed it.
+
+## Copying is the signal to extract
+
+Before copying code from one file into another — a test stub, a helper function, a repeated component or hook shape — extract instead: the copy you're about to make is the second use. Move the shared code to one home and import it from both call sites. Duplication is created one copy at a time, and the act of copying is the cheapest place to stop it.
+
+Two guards:
+
+- Extract sameness, not resemblance: extract only mechanical duplicates that must change together. Keep code that merely looks similar but diverges in semantics separate (a link styled to mimic a button's visuals is still a link — two components, not one).
+- Don't treat imitating an exemplar as copying: the rule targets verbatim plumbing and scaffolding, not structural similarity to the file a convention doc holds up as the model.
+
+When tooling genuinely forces a copy (an environment that can't import shared modules), mark both copies with a keep-in-sync note so the duplication reads as intent, not oversight. A plain note, not a `(source:)` marker (see: q conventions/documentation.md, Markers): neither copy is the authority it would name.
+
+## Colocate knowledge with its next reader
+
+The test is where the next reader who needs the fact will be standing. A fact needed only when touching one specific site — a lint rule's rationale, why this workaround exists, a keep-in-sync note, why a doc's markup takes the shape it does — lives as a comment at that site: the comment reaches exactly that reader and moves with what it describes, while a conventions entry for it taxes every reader and rots independently. But a lesson that binds code not yet written — a gotcha the next person would re-trip writing similar code elsewhere — is cross-cutting even with one current instance, and goes to the conventions doc, where its future reader will actually look. When the future is genuinely uncertain, start with the comment; a second occurrence is the promotion signal (see: Copying is the signal to extract).
+
+A private note only the agent reads — a memory file, a stored preference — is not a home. Its next reader is one agent on one project, while the lesson binds every session running the same workflow. Friction with a skill, a convention, or an agent's instructions is a defect in that surface, so the correction belongs there.
+
+## Comments carry constraints, not justification
+
+A comment, in code or in a doc's markup, states what its file cannot show: the constraint, the gotcha, the reason a workaround must stay. The test: does the comment change how the next reader edits this site? If not, cut it.
+
+What fails the test is the author addressing someone other than that reader, in two shapes:
+
+- **Justification** — defending the chosen design, weighing alternatives, narrating how the solution was arrived at. That addresses the reviewer, and it's noise once merged; git history and the PR carry it.
+- **Pointers to unmaintained artifacts** — plan docs (frozen after merge) (source: q conventions/plans.md, Lifecycle), tickets, PRs, external trackers. State the constraint in the comment itself, or point at the convention doc that owns it. The one sanctioned link: a ticket tracking work that will change this code when it lands — a workaround awaiting an upstream fix, a shim awaiting a migration. The dependency is stated inline so the comment stands alone; the link exists only to check the pending work's status.
+
+## Prefer the strongest enforcement rung
+
+When establishing a rule or pattern, put it on the strongest rung that can hold it: bake it into a component or API so violations are impossible, else lint it so they're mechanical to catch, and only as the last rung document it. Prose enforcement depends on a reader noticing; components and lint don't.