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, Node.js — the conventions install as an npm package — and an authenticated GitHub CLI (gh).

Adding q to a project

npm install --save-dev --save-exact --ignore-scripts @lab43/q
claude --plugin-dir ./node_modules/@lab43/q/q-extension

npm delivers q's bytes before Claude Code is involved, so installing q doesn't require already having q. --plugin-dir loads q for that one session, which is all it takes to run /q:install in it:

• scaffolds your conventions
• gives the project its own marketplace, sourcing the q you just installed
• records the version your docs were reconciled against

Start every session after that with plain claude. The marketplace /q:install wrote is the project's own, and your tracked settings point each session at it.

Joining a project that uses q

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 with the project's dependencies, and the project's tracked settings tell Claude Code to load it. /q:install writes a q section into the project's own README, so contributors meet q without leaving the repo.

Skills

How it works

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:

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
• builds on the @lab43/q npm package you installed — its conventions and its plugin arrive together, at one version, and the skill scaffolds around it
• indexes every tier in your agent briefing (CLAUDE.md)
• gives your project its own marketplace, sourcing the q you installed and the plugin of any extension that ships one, so every teammate's machine runs the versions the repo chose
• records watermarks in a committed .claude/q-state.json — the versions your docs were last reconciled against

Every session start validates that your lockfile, the installed copies, and the watermarks still agree — drift from any direction, a hand-run npm install or a Dependabot bump included, is flagged with its fix: run /q:reconcile. And every agent session, whether or not it ever invokes a q skill, is told to check every tier of conventions — q's, any extensions' you install, and yours — before writing code, making design decisions, or changing docs; your recorded decisions bind future sessions instead of living in one person's head.

Decisions become conventions as you make them. The scaffold is deliberately near-empty, because conventions are earned as decisions are made, not pre-written. When a session hits a decision, lesson, or gotcha worth binding, /q:update-docs records it under q's documentation policy — phrased as a rule, one home per fact, placed where its next reader will look.

A convention records practice. A spec records a promise. A convention says how code here gets written, and it grows out of the decisions you make while working. A spec says what a feature does, and you write it on purpose, before the code or as a deliberate change to it. Break a convention and the code is wrong. Break a spec and the product is wrong, unless you meant to change the promise, in which case the spec changes with it.

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.

• Versions are yours to move — npm and your lockfile decide what runs, and /q:reconcile folds each move into your docs.
• Your project's rulings win on conflict — record the disagreement and it stands (see the markers below).
• Every run that delivers work settles its review mode with you up front. In local mode nothing is committed until you review it. In ship mode the work goes straight to a PR you review on GitHub. Merging is always yours.
• It's all plain text files in your repo — removing q leaves your docs intact and yours.

Markers

q's documentation keeps every fact in exactly one authoritative home. Text still has to point at, copy, or disagree with what lives elsewhere, and one site sometimes has to sit outside a rule the rest of the project follows. A marker declares which of those is in play — making it visible to readers and checkable by grep, with no central list to maintain:

Developing q

This repo has two conventions directories, by design. q-extension/ is the payload the @lab43/q npm package ships, and its conventions/ are the framework policy that binds every consuming project. docs/conventions/ is q's own project tier — rules for developing q itself (skill authoring, for example) that are not framework law. The split exists because q is a consuming project of its own workflow: it keeps its working docs at the same contract path any consumer would, kept apart from the product it ships. Every extension gets the same two homes, and the rule deciding between them ships with the rest.

To work on q:

• claude in your checkout auto-loads your working copy of the plugin (the repo declares itself as the q-dev marketplace in .claude/settings.json); from any other project, claude --plugin-dir <path to your checkout>/q-extension loads it without registering anything. SKILL.md edits apply immediately; /reload-plugins picks up hook and agent changes mid-session.
• When the q: skills don't load in your checkout, read the q-dev entry in claude plugin marketplace list. An entry naming a directory that is gone — usually a worktree that held the name and was then removed — takes registering your checkout again, with its path written in full. No q-dev entry at all means the registry holds your directory under another name: remove that entry with claude plugin marketplace remove <name>, then register your checkout again. That remove also strips the marketplace from the repo's tracked .claude/settings.json, so check that file afterwards and put the declaration back.
• npm run check runs every check the repo has, npm test among them. package.json names them; this line deliberately doesn't, because a list here goes stale the next time one is added. CI runs it on every pull request and on pushes to main.
• npm install installs the pre-commit hook that runs npm run check. A tree you have not installed commits without checking anything.
• Releasing is separate from merging, and PRs never touch a version. The steps live in docs/guides/releasing.md.
• When another session is already working your checkout, take a worktree rather than sharing it. Run npm install in it. .claude/settings.json is tracked, so the plugin loads there.