@lab43/q 0.4.0

package/conventions/pull-requests.md

@@ -0,0 +1,36 @@
+# Pull Requests
+
+Rules for authoring a pull request. Hold its prose to the writing rules (see: q conventions/writing.md). Sign the body and every comment or reply on it: "— Claude 🤖" (source: q conventions/writing.md, Sign what you post). A project's own PR conventions win over this doc (source: q conventions/documentation.md, Three tiers of conventions), and so does a PR template in the repo.
+
+## Title
+
+The title names the work the PR delivers.
+
+## Body
+
+A PR has two goals, in order: make the change easy for a human to review, and prove it does what it says. Every sentence in the body:
+
+- Serves one of the two goals.
+- Assumes no session context — the future reader arriving through git history has none, however much today's reviewer knows.
+
+Describe the change, never the run that produced it. Review rounds, rulings, and session events are the run's story, not the change's.
+
+## Sections
+
+Compose the body from these sections, in order. Most PRs need only Summary and Testing. Add another section only when it has something the reviewer needs.
+
+- **Summary** — the rubric the reviewer checks the diff against: what is true after merge that wasn't before, and why. State outcomes, not edits: one claim per deliverable, each something the reader can now rely on. The diff is the catalog of changes. When the diff is large, say where the substance lives and which files are mechanical fallout. The Summary links the work's source: the tracker item when one exists (source: q conventions/issue-tracking.md, Work links back), and the plan doc when the PR implements a plan. Where the tracker closes an item from the link's wording, word it to close only in the PR whose merge finishes the item — the last layer of a stack, the only PR otherwise. Every other layer links the item without closing it, or the first merge closes work the rest of the stack hasn't delivered.
+- **Callouts** — answers to the questions the diff will raise:
+  - Choices that look wrong but are deliberate.
+  - Expected changes deliberately not made.
+  - Close calls the author wants checked.
+  - Rules added to or changed in standing law that the PR's purpose doesn't explain — the diff shows the rule, not the problem that prompted it.
+
+  Each entry states the question's answer and its reason. A call no reviewer would question is noise here. Callouts also reach the reviewer on the diff itself (see: Diff comments).
+- **Caveats** — the known problems shipping with the change. The reviewer shouldn't spend effort discovering what the author already knows.
+- **Follow-ups** — the work this change obligates: what a reviewer would otherwise ask "doesn't this mean X needs doing?". Link each to its tracker item when one exists — the body informs the reviewer, but nobody returns to a merged body to collect work, so the tracker carries it. Work the session surfaced that this change doesn't obligate goes to the tracker alone.
+- **Testing** — the evidence the diff doesn't carry: what was exercised and what it demonstrated, claim by claim. The project's standing checks prove nothing about this change and go unlisted. When the diff's own tests are the whole proof, say so.
+
+## Diff comments
+
+Post a callout about a specific change also as a comment on its line of the diff, so the reviewer meets it in place. A callout not tied to a specific change needs no comment. Give the comment only what a reader needs to understand why that change was made — the anchor already says where and what, so no labels and no framing.

package/conventions/writing.md

@@ -0,0 +1,54 @@
+# Writing
+
+Rules for writing prose — docs, plans, PR bodies, anything a human or agent will read.
+
+## One idea per sentence
+
+Give each instruction or claim its own sentence. Don't chain ideas with semicolons, commas, or em-dash asides. Chained qualifiers make the reader guess what binds to what. A conditional sits next to the thing it modifies, or becomes its own sentence.
+
+## Lists over paragraphs
+
+Three or more parallel items become a list. Parallelism hides in prose: check any paragraph that names several deliverables, steps, or options. A reader scans a list but has to parse a paragraph.
+
+Each item stands alone, with no trailing commas and no closing "and" or "or". When dropping the connective would lose meaning, the lead-in carries it: "any of the following".
+
+## Constrain content, not length
+
+Never regulate prose with a length target — "keep it short", "a few sentences", a line cap. Define what the piece must carry and what gets cut. A length target doesn't select for the right information, and it backfires when there is genuinely a lot to present.
+
+## Plain words
+
+Use the words a reader would use to describe the thing. Write "errors now show a message instead of crashing", not "error handling was hardened with graceful degradation". Jargon and category labels make the reader translate before they can follow.
+
+## Instructions are commands
+
+Write an instruction — to a human or an agent — as a command: "commit the fixes", never "the fixes are committed" or "the run commits the fixes". Passives and narration hide who acts. Keep declarative sentences for facts a reader relies on.
+
+## Deletion is the default
+
+Deletion is safe: version history keeps everything cut. When a judgment call between keeping and cutting is close, cut. When text is ambiguous or wrong, try deleting it before qualifying it.
+
+## Refine rather than append
+
+Integrate a change by rewriting the text it lands in until the piece reads as if written that way from the start. Appending shows at every scale:
+
+- a qualifier bolted onto an existing sentence
+- a clarification or exception that walks back a statement made earlier — evidence the statement itself needs adjusting
+- a changelog at the bottom of a doc — version history is the changelog
+
+In every case, fix the original text where it stands.
+
+## Write for the reader, not the edit
+
+Write each edit for the reader who arrives fresh: they see the merged text, never the request or the conversation behind the change. Cut detail that earns its place only against that history — a scope note answering something the discussion raised, a clause defending the choice against an objection, a reassurance that some neighboring case still holds. To the fresh reader it answers a question no one asked. The test: would the sentence survive a from-scratch rewrite of the piece?
+
+## Sign what you post
+
+Text posted under the user's account reads as the user's. Sign anything a reader meets as a message from them, with "— Claude 🤖" on its own line at the end:
+
+- a pull request's body
+- a comment or reply on a pull request, on the diff or at the top level
+- an issue or tracker item you file
+- any comment you post on an issue or tracker item
+
+Text committed to the repo is not a message and carries no signature. Git history records who wrote it.

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.mjs

@@ -0,0 +1,125 @@
+// Validate the project's q setup and, when it doesn't validate, tell the
+// session to run /q:sync. Claude Code loads whatever plugin version is on
+// disk, so drift surfaces only if something checks at session start — no
+// other channel runs every session. The checks: the q copy this session
+// loaded vs the project's pin, each watermarked package's pin vs its
+// watermark vs its installed version, and the reverse direction — a
+// q-extension devDependency with no watermark entry (installed by hand,
+// never indexed).
+//
+// The remedy is uniform — /q:sync re-derives the specifics and routes each
+// finding to its remedy — so every failure emits the same message and
+// the script stops at the first one. The only designed silence is a project
+// that declares no @lab43/q devDependency; anything else missing or
+// unreadable fails like any other invalid state.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const proj = process.env.CLAUDE_PROJECT_DIR || ".";
+const root =
+  process.env.CLAUDE_PLUGIN_ROOT ||
+  path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// Keep in sync with the message in session-start.sh (bash can't import it).
+const MESSAGE =
+  "The q plugin could not validate this project's q setup, so its conventions and tooling may be stale or broken. Run /q:sync to repair it.";
+
+const fail = () => {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: MESSAGE,
+      },
+    }),
+  );
+  process.exit(0);
+};
+const read = (file) => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+const parse = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+const installedVersion = (dir) => parse(read(path.join(dir, "package.json")) ?? "")?.version;
+
+// Pins: one exact devDependency for q and one per extension, in the project's
+// package.json. A missing manifest means not a q project. One that exists but
+// can't be read or parsed fails like any other invalid state.
+let pkgText;
+try {
+  pkgText = fs.readFileSync(path.join(proj, "package.json"), "utf8");
+} catch (e) {
+  if (e.code === "ENOENT" || e.code === "ENOTDIR") process.exit(0);
+  fail();
+}
+const pkg = parse(pkgText);
+if (pkg === undefined) fail();
+
+const devDeps =
+  pkg && typeof pkg.devDependencies === "object" && pkg.devDependencies !== null
+    ? pkg.devDependencies
+    : {};
+
+// Declaring no @lab43/q devDependency is the one designed silence. A pin that
+// is declared but is not a version string is an invalid state like any other,
+// and fails the way a malformed pin fails for every extension below.
+if (!Object.hasOwn(devDeps, "@lab43/q")) process.exit(0);
+const pinned = devDeps["@lab43/q"];
+if (typeof pinned !== "string") fail();
+
+// The q this session actually loaded. CLAUDE_PLUGIN_ROOT is the directory it
+// was resolved from, and npm wrote that copy's version, so comparing it
+// against the pin also catches a session running some other checkout's q.
+const loaded = installedVersion(root);
+if (typeof loaded !== "string") fail();
+if (loaded !== pinned) fail();
+
+// Watermarks. A pinned project with no state file is unrecorded drift.
+const stateText = read(path.join(proj, ".claude/q-state.json"));
+if (stateText === null) fail();
+
+const state = parse(stateText);
+if (state === undefined || typeof state !== "object" || state === null) fail();
+
+const recon = state.reconciledAgainst ?? {};
+if (typeof recon !== "object" || recon === null || Array.isArray(recon)) fail();
+// q is the framework rather than an extension, so it is checked by name: a
+// pinned project with no entry for it is caught here. The reverse-direction
+// loop below cannot stand in. It identifies extensions by a keyword read from
+// node_modules, which q does not carry and which an uninstalled or stale copy
+// doesn't supply either.
+if (!Object.hasOwn(recon, "@lab43/q")) fail();
+
+for (const [ext, mark] of Object.entries(recon)) {
+  if (typeof mark !== "string") fail();
+  const pin = Object.hasOwn(devDeps, ext) ? devDeps[ext] : undefined;
+  if (typeof pin !== "string") fail(); // removed out of band, never reconciled
+  if (pin !== mark) fail();
+
+  const inst = installedVersion(path.join(proj, "node_modules", ext));
+  if (typeof inst !== "string") fail();
+  if (inst !== pin) fail();
+}
+
+// Reverse direction: a devDependency whose installed manifest carries the
+// q-extension keyword but that has no watermark entry was installed by hand
+// and never indexed. A dependency that isn't installed can't be identified as
+// an extension — skip it.
+for (const dep of Object.keys(devDeps)) {
+  if (Object.hasOwn(recon, dep)) continue;
+  const keywords = parse(
+    read(path.join(proj, "node_modules", dep, "package.json")) ?? "",
+  )?.keywords;
+  if (Array.isArray(keywords) && keywords.includes("q-extension")) fail();
+}

package/hooks/session-start.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# SessionStart hook entry point. The checks live in session-start.mjs; this
+# wrapper exists so a missing node fails loud with a useful message instead of
+# a cryptic exec error. Node is a given on a project that pins q, which arrives
+# as an npm dependency. The gate below keeps the checks off projects that pin no
+# q at all.
+
+proj="${CLAUDE_PROJECT_DIR:-.}"
+pkg="$proj/package.json"
+[ -f "$pkg" ] || exit 0
+# Match "@lab43/q" in key position only. As a value it is the name of q's own
+# manifest, which pins nothing. This stays a loose pre-filter: it also matches
+# the key under dependencies. session-start.mjs exits silently unless the key
+# is a devDependency.
+grep -qE '"@lab43/q"[[:space:]]*:' "$pkg" 2>/dev/null
+status=$?
+# Exit only on a clean miss: the manifest was read and pins no q. Any other
+# failure means the manifest could not be read, and a project that may well pin
+# q must not be skipped silently — fall through and let the checks report it.
+[ "$status" -eq 1 ] && exit 0
+
+root="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+if ! command -v node >/dev/null; then
+  # No node means the checks can't run — same remedy as any other failure.
+  # Keep the message in sync with MESSAGE in session-start.mjs.
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"The q plugin could not validate this project'"'"'s q setup, so its conventions and tooling may be stale or broken. Run /q:sync to repair it."}}\n'
+  exit 0
+fi
+
+CLAUDE_PROJECT_DIR="$proj" CLAUDE_PLUGIN_ROOT="$root" exec node "$root/hooks/session-start.mjs"

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@lab43/q",
+  "version": "0.4.0",
+  "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"],
+  "scripts": {
+    "check-versions": "node scripts/check-versions.mjs"
+  },
+  "license": "MIT",
+  "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" },
+  "author": { "name": "Cameron Spencer", "email": "cameron@lab43.com" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lab43/q.git"
+  },
+  "homepage": "https://github.com/Lab43/q#readme"
+}

package/references/agent-briefing.md

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

package/references/enforce-pins.md

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

package/references/q-state.md

@@ -0,0 +1,31 @@
+# The q State File
+
+Format and writer rules for `.claude/q-state.json`, the consumer-side record of the versions a project was last reconciled against. The skills that read or write the file follow this doc; nothing else edits it.
+
+## What the file is
+
+The file holds machine-written version watermarks — never rules, never doc enumerations. Pins stay authoritative where they are: the project's `package.json`, one exact devDependency for q and one per installed extension. Reconciliation is the work of folding a version change into the project — holding its docs against an extension release's changed rules, or its scaffolded surfaces against a new q version; `/q:update` performs it. A watermark records the version its pin was last reconciled against, so an out-of-band pin move — a hand-run npm install, a teammate's merge, a Dependabot bump — is detectable as pin ≠ watermark. The skills and the session-start hook compare its versions against the pins; nothing consults it for how to behave.
+
+## Format
+
+The file lives at `.claude/q-state.json`, committed. JSON, one key per line, so a watermark move reads as a one-line diff:
+
+```json
+{
+  "note": "Machine state written by q's skills. Never edit by hand; /q:sync reports drift.",
+  "reconciledAgainst": {
+    "@lab43/q": "0.3.0"
+  }
+}
+```
+
+`reconciledAgainst` holds one entry for `@lab43/q` and one per installed extension: the version the project was last reconciled against. q's entry has the same shape as the rest, carrying no privilege and no separate field.
+
+## Writer rules
+
+- `/q:install` fills in missing watermarks and never touches present ones — a stale entry is reconciliation's to move. Bootstrapping q, it writes the `@lab43/q` entry; installing an extension, it writes that extension's. Each value is the version just installed, which has no reconciliation debt.
+- `/q:update` writes the affected watermark after each reconciliation, whether the run moved a pin or caught up an out-of-band move.
+- `/q:uninstall-extension` drops the extension's entry as part of reconciling its removal.
+- `/q:sync` reads and compares; it never writes. Watermarks certify reconciliation, and sync never reconciles.
+
+An absent file means no record — create it on the first watermark write. The file never ships in an extension: it lives in `.claude/`, outside the `files` whitelist a tarball is built from (source: q conventions/extensions.md).

package/references/run-contract.md

@@ -0,0 +1,112 @@
+# Run Contract
+
+How every q skill run operates, from invocation to finish. Skills reference this contract rather than restating it.
+
+## Collaboration modes
+
+A run is in one of two modes, depending on whether the user has agreed on what to do yet:
+
+- **Conversational** — nothing agreed yet: converge with the user. Present candidates with trade-offs and a recommendation, decide at the right altitude (see: Decide at the right altitude), and proceed to execution only on the user's go-ahead. The conversation ends in an agreement — a plan doc, a confirmed scope, a converged approach.
+- **Autonomous** — an agreement exists: execute it without asking. Interrupt only when the work would step outside what was agreed — a conflict discovered mid-run, an architectural fork, scope the agreement doesn't cover. Small calls inside the agreement stay autonomous: choose what is most consistent with the agreement, the conventions, and the surrounding code, and flag the calls a reviewer would question where the output gets reviewed: the PR body (see: q conventions/pull-requests.md), or the end-of-run report when the run delivers no PR. When the agreement is exhausted or must be reopened, the run is conversational again.
+
+## Review modes
+
+Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled it is never revisited mid-run: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
+
+- **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's approval is what commits it.
+- **Ship** — commit as the running skill's own procedure calls for, without asking, and push when the work is done; the user reviews on GitHub, so finish by directing them to the PR(s). The grant ends at the PR: merging is the user's.
+
+## The delivery branch
+
+Settle the branch before changing anything: work built on one branch and delivered against another invites conflicts. Uncommitted changes the run does not own are the user's call: ask what to do with them before starting. Never mix them into the run's work. Two things then settle the branch — whether another session is working this repo, and which branch the work belongs on.
+
+**Is a peer working this repo?** `ListAgents` supplies the candidates: take only its rows for other local sessions, because the rest are this session's own subagents and sessions running elsewhere. No row records a repo, so a row is a candidate and never a peer on its own. Read the repo for what it shows:
+
+- `git worktree list` names the worktrees peers took. A worktree outlives the session that made it, so one is evidence of a peer only while a candidate is live: with no candidates listed, it is leftovers.
+- A candidate that has announced this repo is a peer outright.
+- Uncommitted work this run does not own settles nothing by itself: it is as likely the user's as a peer's. Ask the live candidates whether the work is theirs, because ownership is the one thing looking cannot establish. Ask the user when no candidate claims it.
+
+Where the evidence leaves the call open, ask the user. A listing that reports itself incomplete leaves it open.
+
+**Found a peer? Take a worktree.** `git fetch origin` first: everything below reads the local remote-tracking refs, which are only as current as the last fetch. Nothing uncommitted follows the session into it, so commit or copy across whatever the run already owns — the plan or doc it was invoked on included. How the worktree is made then depends on whether the run's branch exists yet.
+
+**A branch the run is creating.** `EnterWorktree` makes the worktree and switches the session into it. It arrives on its own new branch, off the default branch under the `worktree.baseRef` default. That branch is this run's: rename it to what the run would have called its branch (`git branch -m <name>`) rather than creating a second one.
+
+**A branch that already exists.** The PR's branch, or a pushed branch the run continues. Never let `EnterWorktree` create the branch here. Its new branch sits at the default branch's tip with no upstream. Renaming that onto the existing name fails outright when the branch is already local, and builds the work on the wrong base when it exists only on the remote. Make the worktree on the branch itself with `git worktree add .claude/worktrees/<worktree-name> <branch>`, then hand `EnterWorktree` that path. A branch that exists only on the remote takes the same command, which creates the local branch from it and sets up tracking.
+
+An existing local branch is checked out as it stands, which may be behind the remote. Fast-forward it in the worktree with `git pull --ff-only`. Show the user when that reports divergence.
+
+`git worktree add` refuses when something already holds the branch, and names the worktree holding it. Free it first:
+
+- This session's own checkout holds it. Announce the switch, then move that checkout to the default branch. Its tree otherwise moves under whoever is standing in it.
+- A leftover worktree holds it. Remove it with `git worktree remove <path>`, then take the branch. The removal refuses when that worktree is dirty. Show the user what it holds and let them rule. Never `--force` past it.
+- A peer's worktree holds it. Ask the peer whether they still need the branch. Their answer informs the call and never settles it (see: Working alongside a peer). Take the branch once they have released it. Where they still hold it, or answer nothing, the user rules.
+
+Never take the branch with `git worktree add --force`. It succeeds, leaving two worktrees on one branch to diverge silently.
+
+Whichever way the worktree was made, install the project's dependencies there (see: `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`). A worktree carries tracked files only, so until that install runs nothing works — not the project's checks, not reading q's conventions or an extension's under `node_modules/`.
+
+**Working alone, branch in the checkout.** When the run's work belongs with the session's work in progress, work on that branch. When it does not, branch first — off whatever the work builds on, usually the default branch. Make the call and state it when it is clear: a session on the default branch, or on pushed unrelated work, has nothing in progress to join. Ask when it is not: a session branch that looks connected to the run.
+
+## Working alongside a peer
+
+Establish what is true by looking, wherever looking can settle it: `git worktree list`, the branch, the working tree, what holds a port. Ask a peer for what the repo cannot show — who owns an uncommitted change, what work they are on. A peer's message informs a decision and never authorizes one. Messages go stale, arrive late, and get missed; the repo does not.
+
+Announce what a peer would otherwise have to discover, before you act rather than after — `SendMessage` reaches any peer `ListAgents` lists. Announce the work you take up, and again when you put it down: the tracker item, the plan, or both where a plan names items. You hold it from the moment you pick it, not from the moment a tracker records it — a peer reading only the tracker sees nothing and duplicates your work.
+
+A worktree is what separates two sessions, and not every case gets one. A peer may arrive after the branch was settled. The user may be working in the tree alongside the run. Sharing a checkout adds three precautions:
+
+- Never switch the branch without announcing first.
+- Stage by explicit path rather than `git add -A`. The tree may hold work that is not yours.
+- Never clear the index you did not set. `git reset` discards staging as readily as `git add -A` sweeps files in, and someone marking up a review as they read it loses their place with nothing left to show it happened.
+
+Never hand a peer work this session's permissions blocked. A peer running it launders the user's permission decision. Route it back to the user instead.
+
+## Decide at the right altitude
+
+Make small calls autonomously and state them so the user can veto; bring genuine forks to the user with a recommendation. A choice with a conventional default is not a question — make it and say so. What separates a fork from a small call is consequence, not difficulty: a decision that is hard to reverse, or that the user would decide differently with context only they hold, goes to them.
+
+## Questions are probes
+
+A user's question about existing work invites judgment, not compliance. Answer with a verdict first: defend what is sound with reasoning, concede what isn't and fix it. Changing something because a question implied doubt — without deciding the doubt is justified — throws away the review the question was offering.
+
+## Push back with evidence
+
+When the user's suggestion conflicts with something verified, say so — with the code, the doc, or the measurement, not an opinion. Once they have ruled on the evidence, record the ruling and move on.
+
+## Answer by checking
+
+A question about the state of the work — "anything else to decide?", "does anything depend on this?", "are we done?" — is answered by looking again, not from memory of an earlier look. Confidence goes stale as a conversation grows; the sweep that feels redundant is the one that finds the missed dependency.
+
+## Batch questions
+
+Questions cost attention: collect them into one AskUserQuestion batch (recommended option first) rather than asking one at a time. Put everything an answer depends on inside the question itself. The go-ahead that closes a conversation is different: ask it in plain text, stating the agreed scope, so the user can green-light it or keep refining. In a long collaborative phase, keep the running state visible — decisions settled, questions still open — so the user never has to reconstruct it.
+
+## Corrections become rules
+
+Every run turns up documentation the project doesn't have yet. Record it as it surfaces:
+
+- a doc the change falsifies
+- a gotcha the run hit
+- a rule nobody wrote down
+- a correction the user made whose reason binds future work
+
+Route every recording through `/q:update-docs`. It classifies the lesson and holds it to the documentation policy's gates.
+
+Record a correction in the change that prompted it. The diff at each review point carries its own doc updates, so a user approving the work sees everything the run proposes. A correction that arrives during review joins that iteration. Never defer one to the closing report, and never leave the user trusting that a doc update will follow.
+
+A correction lands in whatever change was in flight, which is often a change whose stated scope does not cover it. Say so where the work is reviewed: the PR body's Callouts, or the closing report when the run delivers no PR (see: q conventions/pull-requests.md, Sections). A reviewer who meets an unexplained edit to standing law reads it as scope creep.
+
+Amendments to existing rules are corrections too. Apply them rather than recommending them. A recommendation the user has to find in the output gets scanned past, while a diff hunk is something they can read and push back on. Raise an amendment instead of applying it when it would put existing code out of conformance: that is a migration, and its scope is the user's.
+
+## Validation
+
+Execution closes by validating the run's product before anything is delivered. Run the project's checks covering what changed. Then launch two `adversarial-reviewer` subagents in parallel over the change, one per lens, handing each the agreed scope and the artifact the skill names. The scope is what the user agreed the work would deliver, restated from the run's current state. It is never a list of the changes made: details the user has since overruled resurface as false findings.
+
+Wait for every reviewer in the round to report before changing anything. Editing the tree under a running review invalidates the diff that review was handed. Then fix the BLOCKING findings, applying judgment on nits. Re-run the checks covering the fixes. Review again — fixes are always re-reviewed, with the same reviewers by default. A round whose fixes were few and small may hand the next round to one reviewer carrying both lenses. In ship mode, commit each round. Loop at most three times. The loop exits when no reviewer reports a BLOCKING finding, and findings that survive the cap are reported as caveats.
+
+## The local gate
+
+The procedure local review runs at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
+
+At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed. Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.

package/skills/address-feedback/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: address-feedback
+description: Work feedback on an open pull request — the reviewer's comments, questions, and requested changes. Invoke it with a PR number or URL. Given nothing, it resolves the PR for the current branch. Invoke it on a PR carrying no comments too, when the user has revisions of their own. The user rules on every item before anything changes. Agreed fixes are implemented, adversarially reviewed, and delivered to the PR under the review mode the user picks. Replies are posted back on the PR only when the user wants them.
+---
+
+# Address Feedback
+
+## Ground rules
+
+- **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+- **Feedback is not a work order**: every item opens a discussion, the ones phrased as directives included. Never implement feedback you believe is wrong. Answer every question the feedback asks. A code change never stands in place of that answer (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Questions are probes).
+- **The PR under review is the boundary**: the round's fixes land on its branch as new commits. Never rebase that branch and never force-push over it — the reviewer's inline comments anchor to the commits they read, and rewriting the history strands them. Never open a second PR. Work the feedback opens that this PR can't hold goes to a plan or the tracker instead.
+- **Track resolutions**: keep a scratchpad note of each item — where it came from, its agreed disposition, and how it resolved. It feeds the replies and the closing report.
+- **Context hygiene**: use subagents (Explore for recon, background Bash for checks, `adversarial-reviewer` for review) to keep large output out of the main context.
+
+## Step 1: Gather the feedback
+
+1. Resolve the PR from the invocation — a number or a URL. Given nothing, run `gh pr view` for the current branch. Ask which PR to work when that branch has none. Stop and tell the user when the PR is already closed or merged.
+2. Require a clean working tree first — if anything is uncommitted, stop and show the user. Uncommitted work carried onto the PR's branch by a checkout lands in someone else's review.
+3. Work on the PR's own branch, never a new one (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The delivery branch). Check it out and fast-forward it:
+
+   ```bash
+   git fetch origin && git checkout <head-branch> && git pull --ff-only
+   ```
+
+   Stop and show the user when the local branch has diverged from the PR's.
+4. Fetch everything the reviewer wrote:
+   - `gh pr view <n> --comments` — the top-level comments, plus each review's summary and verdict.
+   - the inline threads, which GitHub groups and tracks resolution for:
+
+     ```bash
+     gh api graphql -f query='{repository(owner:"<owner>",name:"<repo>"){pullRequest(number:<n>){reviewThreads(first:100){nodes{isResolved isOutdated path line comments(first:50){nodes{databaseId author{login} body}}}}}}}'
+     ```
+
+     Skip every thread `isResolved` reports closed — the reviewer ended those. An `isOutdated` thread is still live: it anchors to a line that later commits moved. Skip a thread whose last comment already answers the one before it. An earlier round settled that item, and the reviewer has not written back.
+5. Ignore every comment that raises nothing to settle. A callout explaining the change under review is the common case (see: q conventions/pull-requests.md, Diff comments).
+6. Gather the user's own feedback. The invocation may carry it. Ask the user what they want changed whenever the PR carries no feedback of its own.
+7. Build the agenda from everything gathered — one item per inline thread, top-level comment, or review summary that carries feedback, plus one per point the user raised. Merge items that share a root cause or answer each other. Record where each item came from, because that decides how it gets answered. Post the agenda — each item's gist in one line, in the order you propose to take them. No positions yet, and no edits.
+
+## Step 2: Take a position on each item
+
+Establish ground truth before forming a position:
+
+- the code the item points at, and its history
+- the conventions governing that territory, found from the agent briefing's docs index
+- the primary source, wherever the item turns on how a dependency or tool behaves — the library's own code, its documentation, its upstream issues
+
+Never agree or push back from memory of an external fact (package versions, library APIs, option names, tool behavior). Run the check whenever running one can settle the question.
+
+Feedback invites judgment, not compliance (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Questions are probes). Where the evidence contradicts it, say so with the evidence (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Push back with evidence). Where investigating exposes the questioned code as genuinely weak, say that rather than defending it.
+
+Give each item one disposition:
+
+- **Answer** — the item asks a question that evidence answers. Nothing changes.
+- **Push back** — the item is wrong, or the change it asks for is worse than what stands. Name what you would do instead, including nothing.
+- **Fix** — the item is right. Name the change.
+- **Beyond this PR** — the item calls for a redesign, or for more change than this PR can hold.
+
+## Step 3: Agree
+
+Settle the round with the user, in conversational mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Collaboration modes).
+
+Post every item's disposition with its evidence. Most carry no question:
+
+- an obvious fix
+- an answer the evidence settles
+- a push-back the code proves
+
+State those for the user to veto rather than asking them (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Decide at the right altitude).
+
+Ask one batch, carrying only what the user has to rule on:
+
+- the fork a disposition turns on, wherever an item has materially different resolutions, each with a recommendation
+- whether each resolution is posted back where the feedback was written, asked once for the round. Skip it when nothing was written on the PR.
+- the review mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Review modes). In this run, ship covers commit and push to the PR. Local commits nothing until the user has reviewed the diff.
+
+Answers settle decisions. They are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead. That green light, not the last answer, is what makes the rest of the run autonomous.
+
+An item beyond this PR is not resolved here. Settle the rest of the round, and take it to `/q:create-plan` or to the tracker on the user's call.
+
+## Step 4: Implement
+
+1. Record the branch's head SHA before changing anything: `git rev-parse HEAD`. It is the branch as this round found it, and Step 5 reviews the round against it.
+2. Implement each agreed fix, following the governing conventions and matching surrounding code.
+3. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When a fix changed a drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
+4. In ship mode, commit — before review, so the review history is inspectable in git.
+
+When the agreed fixes turn out to need a redesign, or more change than this PR can hold, interrupt. Present the discovery and recommend `/q:create-plan` or a tracker item. Neither starts without the user's go-ahead.
+
+## Step 5: Adversarial review
+
+Validate the round (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Validation) with the **correctness** and **conventions** lenses. The round is the product, so its diff runs from Step 4's recorded SHA: `git diff <recorded-sha>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local review. Hand the reviewers the agreed dispositions as the scope. Per loop round, re-drive a surface only when a fix could change what driving showed.
+
+## Step 6: Deliver to the PR
+
+1. **Local review's gate**: run the gate over the session's uncommitted work (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The local gate).
+2. **Push**: `git push origin HEAD`.
+3. **Bring the PR body up to date** wherever the round changed what it claims, the findings that survived Step 5 included (see: q conventions/pull-requests.md).
+4. **Reply**, when replying was agreed: post each item's resolution where the feedback was written. Skip an item the user raised in session. It has no thread to answer. Give the reviewer what they need to understand it — the answer, the evidence behind a push-back, or the reason a fix took the shape it did. Sign each reply (source: q conventions/writing.md, Sign what you post). Write each reply to a file and pass it by path, so apostrophes in the prose can't break the command. Reply to an inline thread at its first comment's `databaseId`:
+
+   ```bash
+   gh api --method POST repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies -F body=@<reply-file>
+   ```
+
+   Answer a top-level comment or a review summary with `gh pr comment <n> --body-file <reply-file>`. Never mark a thread resolved — that is the reviewer's call.
+5. Close the session by reporting each item's resolution, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: q conventions/issue-tracking.md, Ask before filing).