@warren-dean/code-kit 0.3.4

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@warren-dean/code-kit",
+  "version": "0.3.4",
+  "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
+  "license": "MIT",
+  "author": "Warren Langeveldt",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warrendeanlangeveldt/code-kit.git"
+  },
+  "homepage": "https://github.com/warrendeanlangeveldt/code-kit#readme",
+  "bugs": "https://github.com/warrendeanlangeveldt/code-kit/issues",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agents",
+    "guardrails",
+    "architecture",
+    "ci"
+  ],
+  "bin": {
+    "code-kit": "bin/code-kit.mjs"
+  },
+  "files": [
+    "bin",
+    "hooks",
+    "skills",
+    "templates",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/units.test.mjs && node test/hooks.test.mjs"
+  }
+}

package/skills/check/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: check
+description: Validate the project's .claude/code-kit.json and show who owns what. Use after changing the config, when a path's owner or layer is unclear, or when the person asks what the kit enforces here.
+---
+
+# Check the code-kit config
+
+From the project root:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" check
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" unowned
+```
+
+- If `check` reports problems, fix `.claude/code-kit.json` (the lead only). Until it's valid, every write except the config itself is blocked.
+- Files listed by `unowned` can't be written by anyone. Give each one an owner, or confirm with the person that it should stay frozen.
+- For a particular path, run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" who <path>...`. It shows the path's owner and layer.
+
+Report the summary, and any problem or unowned file, in a few lines.

package/skills/dispatch/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: dispatch
+description: Hand stories from the plan to their lane agents, as many at once as can safely run in parallel. Picks the ready stories, checks each is buildable, briefs each lane agent with its story, requirements and acceptance criteria, and starts it on its own branch and worktree. Use when the lead is ready to start building, asks what to work on next, or runs /code-kit:dispatch [story IDs, a milestone, or "next"].
+---
+
+# Dispatch stories to lanes
+
+Only the lead dispatches. Lane agents build; the lead writes contracts, reviews and merges.
+
+The argument names what to dispatch: story IDs (`ST-4 ST-7`), a milestone, or `next` (everything that's ready). With no argument, show what's ready and ask.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root.
+
+## 1. See what's ready
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" status
+```
+
+A story is **ready** when its dependencies are done and nobody has started it. `status` also lists gaps between the specs and the plan; a story with a gap (an unknown lane, a requirement no spec defines) isn't dispatched until the lead fixes the plan.
+
+If the project has no `docs.plan`, or the plan has no stories in the `### ST-n` form (`${CLAUDE_PLUGIN_ROOT}/templates/plan.md`), stop and suggest the spec-design skill.
+
+## 2. Check each story before it goes
+
+For every story you're about to dispatch, read in full:
+
+- the story in the plan;
+- every requirement it cites, in its spec, with the spec's open questions;
+- the lane's agent file in `.claude/agents/`.
+
+Then check:
+
+- **No open question blocks it.** If a spec's open questions touch a cited requirement, don't dispatch the story; list the question for the person.
+- **The contracts exist.** If the story needs an API schema, event or database contract that isn't written yet, that's the lead's work first. Write it (the lead owns contracts), commit it on the lead's branch, then dispatch. A lane never invents a contract.
+- **The lane is right.** Run `who` on the paths the story will touch. If they belong to two lanes, split the story or sequence it; don't hand one lane another's files.
+- **Nothing overlaps.** At most one story per lane at a time, unless two stories touch disjoint folders. Two lanes may run in parallel; that's the point of lanes.
+
+Commit everything the lanes need first. Each lane branches from the lead's branch as committed, so uncommitted work isn't there.
+
+## 3. Brief and start each lane
+
+Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background. Start every story in the batch in the same message so they run in parallel.
+
+The brief is the agent's whole context. Write it so the agent needs nothing else:
+
+```text
+Story ST-<n>: <title>   (lane <lane>)
+Branch: <lane>/st-<n>. Create it first, from the lead's branch: git switch -c <lane>/st-<n> <lead's branch>
+
+Requirements (read each one in full, with its acceptance criteria):
+- <spec path>#<ID> <name>
+- …
+
+What to build: <the story's description, and anything the lead decided that the spec doesn't say>
+Contracts to use: <paths of the schemas, events or tables this story relies on>
+Out of scope: <what neighbouring stories or other lanes will do>
+
+Steps:
+1. Run the spec-check skill against these requirements and save the report (the path guard requires it).
+   If it recommends "blocked on questions", stop and report the questions.
+2. Build it end to end in your lane's paths. No mocks, stubs, placeholder screens or "coming soon".
+3. Write tests that prove each acceptance criterion. Name the requirement ID in each test's title,
+   e.g. test('BOOK-4 a customer can cancel up to 24 hours before'), so `code-kit status` can trace it.
+4. Run <the lane's proving command> until it passes.
+5. Commit on your branch. The message names ST-<n>, what changed and the proof.
+6. Finish with: what you built, per requirement; the commands you ran and their output; open questions.
+```
+
+**A person running a lane** instead of an agent gets its own worktree, marked with the lane:
+
+```bash
+git worktree add ../<repo>-<lane>-st-<n> -b <lane>/st-<n> <lead's branch>
+echo <lane> > ../<repo>-<lane>-st-<n>/.lane
+```
+
+Give them the same brief. Claude Code opened in that worktree then acts as the lane.
+
+## 4. Keep track
+
+- Set each dispatched story's `**Status:**` in the plan to `in progress`, and commit it on the lead's branch.
+- Tell the person, in a few lines: what was dispatched, to which lane and branch, what's still blocked and on what, and what's ready next.
+- As each agent finishes, read its report. If it came back blocked on questions, bring the questions to the person. If it came back done, run the review skill on its branch.

package/skills/init/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: init
+description: Set up code-kit in a project, or bring an existing setup up to date. Works from the project's docs (new builds) or from its code (brownfield), drafts .claude/code-kit.json, the lane agents and the CLAUDE.md section, and shows the person exactly what changes before anything is enforced. Use when the person says to apply the kit to a project, to re-run or refresh it, or runs /code-kit:init [docs path].
+---
+
+# Set up or update code-kit
+
+The argument, if given, is the path to the project's docs (a folder or one file).
+
+Always the same shape: **read, draft, show, and switch on only once the person approves.** The hooks read only `.claude/code-kit.json`. Every draft goes to `.claude/code-kit.draft.json`, which enforces nothing.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root. Its commands are `check`, `unowned`, `who`, `diff`, `baseline` and `graph`, each taking `--config <file>` to read the draft.
+
+## Which situation
+
+- **`.claude/code-kit.json` exists** → **Update** (section 4). The lanes stay in step with the build.
+- **No config, and the docs describe the architecture** → **New from docs** (sections 1–3).
+- **No config, and the docs are thin or missing** → **Brownfield** (sections 1–3, with the brownfield steps). The code is the main source, and the docs fill in what they can.
+
+- **No config, no code and no docs** (just an idea) → stop and suggest `/code-kit:spec-design` first. It writes the brief, specs, architecture, principles and plan this skill works from.
+
+Say which one applies and why before you start.
+
+## 1. Read everything first
+
+1. **The docs, in full.** Every file under the docs path, not excerpts. Note where each of these is described:
+   - **Layers:** names, which folders each covers, which way dependencies point, what each may not use.
+   - **Work split:** lanes, teams, packages, apps or services, and who owns which paths. An implementation plan or a sub-agent table is the best source.
+   - **Principles:** engineering rules, definitions of done, what counts as a contract.
+   - **Protected things:** registers, contracts and schemas that need a person's sign-off.
+   - **Design-first rules:** screens designed before they are built, and where approvals are listed.
+   - **Commands:** test, lint, typecheck, database and deploy commands, and which must never run locally.
+2. **The repository.** Map the real layout: `git ls-files | cut -d/ -f1-3 | sort | uniq -c`, package manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`), workspace files, existing lint, format and test scripts, CI workflows and CODEOWNERS.
+3. **Existing kit.** If the project has `.claude/hooks`, agents or skills, read them. The kit replaces local hooks; agents and skills are kept and adapted, not rewritten.
+4. **Other tools.** Run `adapters --config .claude/code-kit.draft.json` once the draft exists. It lists the tools code-kit has an adapter for (such as Context Graph, found by its `.ctx/` folder), what each adds to the rules, and the setup each needs. Don't copy an adapter's paths into the config; they're added automatically while the tool is present.
+
+**Brownfield, in addition:**
+
+5. **Find the layers in the code.** Run `graph` (default depth 2, and `--depth 3` for deeper packages). It lists which folders import which, most-used first. Look for:
+   - folders nothing depends on (the edges: apps, UI, entry points);
+   - folders everything depends on (the core: domain, schemas, shared types);
+   - edges in both directions between two folders. These are existing tangles; record them, don't design around them.
+6. **Find the work split in the history.** Use `git log --format='%an' -- <folder> | sort | uniq -c | sort -rn | head` per top-level folder, plus CODEOWNERS. Folders that change together and are worked on by the same people make a lane.
+7. **Check the checks.** Run each candidate check command once on the current code, before proposing it. If a command already fails, that's a finding, not a check to switch on silently. Offer three options: fix first, leave it out for now, or scope `files` narrower so it guards only new work.
+
+## 2. Draft the config
+
+Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md` › Config for every field.
+
+- **`docs`:**
+  - `specs`, `principles` and `plan` as found. `plan` is the plan file itself; with stories in the `### ST-n` form, the dispatch, review and status skills work from it. Leave `specs` out if the project has no specs: without it, lanes aren't held to a spec-check report.
+  - Brownfield: if there are no specs, say so, and offer the spec-check gate for later, once specs exist.
+- **`layers`:** one entry per layer, documented or found in the graph. Each needs:
+  - `paths`: globs matching where that layer's code really lives;
+  - `mayImport`: the direction the docs set. For brownfield code, the direction most of the code already follows;
+  - `denyPackages`: packages forbidden for that layer, for example `node:*` or a vendor SDK outside its adapter.
+  - Also add `importAliases` for path aliases in `tsconfig` `paths` that the graph can't see. Workspace package names are found automatically.
+  - The import check reads JavaScript and TypeScript. For another language, record the layers anyway (agents and spec-check use them), and say the import check doesn't cover that language yet.
+- **`lanes`:** one per documented or discovered ownership area. Each needs:
+  - `agent`: a kebab-case agent name, for example `api-engineer`;
+  - `paths` and `exclude`: every path must have exactly one owner.
+- **`lead.paths`:** contracts, specs, design, root config, and anything the docs reserve for the lead.
+- **`anyActor`:** lockfiles, if lanes may update them.
+- **`protected`:** registers and contracts that need a person's sign-off, each with an `approval` name and a `why`.
+- **`designGate`:** only if the docs require designs before screens.
+- **`shell.block`:** deploy, release and production commands reserved for CI or a person.
+- **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
+- **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
+- **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
+
+Prove the draft:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" check --config .claude/code-kit.draft.json
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" unowned --config .claude/code-kit.draft.json
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" baseline --config .claude/code-kit.draft.json
+```
+
+- **`check`:** fix every problem it reports.
+- **`unowned`:** a file it lists can't be written by anyone. Give each one an owner, or confirm with the person that it should stay frozen.
+- **`baseline`:** lists the layer violations already in the code.
+  - New from docs: expect none. Any it finds are drift from the documented design; list them.
+  - Brownfield: expect some. They'll be recorded as the baseline, so only new violations block.
+
+## 3. Agents, CLAUDE.md, and switching on
+
+Draft, alongside the config:
+
+- **One agent per lane:** write `.claude/agents/<agent>.md` from `${CLAUDE_PLUGIN_ROOT}/templates/agent.md`, filled in from the docs (or the code, for brownfield):
+  - owned paths;
+  - its layers and what they may depend on;
+  - the specs it reads;
+  - the command that proves its work;
+  - its lane rules.
+  - If an agent already exists, keep its content and add only what's missing.
+  - Drop the spec-check lines if the config has no `docs.specs`.
+- **CLAUDE.md:** add the section from `${CLAUDE_PLUGIN_ROOT}/templates/claude-md.md`.
+- **Project skills** (recipes like "new migration" or "new endpoint"): list the recipes the docs describe step by step, and offer to write them. Don't write them unasked, and never write an empty one.
+
+Show the person:
+
+1. the layers and what each may depend on, and for brownfield the existing violations the baseline will record;
+2. the lanes, their agents and their paths;
+3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
+4. the active adapters and what each adds, from `adapters`;
+5. every **question**: where the docs or the code are silent, ambiguous or contradictory. Don't guess; a wrong owner or layer blocks real work.
+
+Once they approve (with any changes):
+
+1. Rename the draft to `.claude/code-kit.json`. From then on, every hook enforces it.
+2. If there are existing violations, run `baseline --write`. This writes `.claude/code-kit.baseline.json`.
+3. If the project had local hooks in `.claude/settings.json` that the kit replaces, remove those hook entries and the local hook files. Keep the `permissions` block.
+4. Add `.claude/approvals/`, `.claude/state/` and `.claude/code-kit.draft.json` to `.gitignore`. Add `.claude/approval-log.jsonl merge=union` to `.gitattributes`: when lanes and the lead both log changes, merging keeps every entry instead of conflicting.
+5. Apply each active adapter's `setup` lines (ignore files, merge drivers, the CLAUDE.md note), and say which you applied.
+6. Offer CI enforcement, since the hooks only see Claude Code sessions. On yes:
+   - write `.github/workflows/code-kit.yml` from `${CLAUDE_PLUGIN_ROOT}/templates/github-workflow.yml`;
+   - set the version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`;
+   - fill in the install steps the project's checks need, from its existing CI or package manager;
+   - make sure the lead owns the workflow file, and add it to `protected` (approval `ci`, why "the CI that enforces the rules"), so a lane can't switch it off;
+   - tell the person to make the `code-kit` check required on the protected branches.
+7. Run `check` and `unowned` again, without `--config`.
+8. Commit on a branch. The kit records the protected files in `.claude/approval-log.jsonl`.
+
+Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions.
+
+## 4. Update an existing setup
+
+Re-run whenever the build has moved on: new apps or packages, folders that moved, a changed plan, or files `unowned` keeps listing.
+
+1. **Re-read** the docs and the repository as in section 1, including the brownfield steps if the code has grown past the docs.
+2. **Draft** the whole config again into `.claude/code-kit.draft.json`, starting from the live one. Keep everything that's still right, so the diff shows only real changes.
+3. **Show the difference:**
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" diff --config .claude/code-kit.draft.json
+   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" unowned --config .claude/code-kit.draft.json
+   ```
+
+   `diff` lists lanes, layers, checks and rules that were added (`+`), removed (`-`) or changed (`~`), and how many files change owner, route by route. Explain each change in a sentence, with where it came from: the doc section, or the folder in the repository.
+
+4. **Also propose:**
+   - agent files for new lanes, and updates to agents whose paths changed;
+   - a smaller baseline when `baseline` shows violations were fixed. It only ever shrinks.
+5. **On approval:**
+   1. Replace `.claude/code-kit.json` with the draft and delete the draft.
+   2. Write or update the agents.
+   3. Run `baseline --write` if it shrank.
+   4. Run `check` and `unowned`.
+   5. Commit on a branch.
+
+   Nothing changes until then.

package/skills/next/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: next
+description: The one command for code-kit. Reads where the project stands (a blank folder, a spec being shaped, a ready spec, existing code, a draft config, stories ready, finished or being built) and runs the right skill in the right order, carrying on until something needs the person. Use when the person runs /code-kit:next, asks "what now?" or "what's next?", wants to start a project with code-kit without knowing which skill to use, or comes back to a project mid-build.
+---
+
+# Next step
+
+The argument, if given, is passed to the first skill that runs. From a blank folder, that's the idea itself: `/code-kit:next a booking app for mobile dog groomers`.
+
+## 1. Read the state
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" next --json
+```
+
+It returns `step`, `why`, `args`, `then` (steps that can follow straight after) and `attention` (things the person should know). The order it applies:
+
+| State                                                      | Step                                                      |
+| ---------------------------------------------------------- | --------------------------------------------------------- |
+| Invalid config                                             | `check`, then fix the config                              |
+| No config, a draft waiting                                 | `init`, to show it for approval                           |
+| No config, a spec still being shaped (brief not `ready`)   | `spec-design`, resuming                                   |
+| No config, a ready spec                                    | `init <docs folder>`                                      |
+| No config, existing code or docs                           | `init`                                                    |
+| Nothing at all                                             | `spec-design`                                             |
+| Config, but no specs, plan or stories                      | `spec-design`                                             |
+| Stories finished on their branches                         | `review`, then `dispatch` what's ready                    |
+| Stories ready                                              | `dispatch`                                                |
+| Stories being built, nothing else can start                | wait                                                      |
+| Ready stories with gaps in the plan, or a dependency cycle | `spec-design`, to fix the plan                            |
+| Every story done                                           | done: `status`, then `spec-design` for the next milestone |
+
+Tell the person in one or two lines what you found and what you're about to run, with anything under `attention`. If `attention` says the folder isn't a git repository, run `git init` before init (spec-design doesn't need one).
+
+## 2. Run it
+
+Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the person's argument, if they gave one). Follow that skill in full. This skill only chooses; it never does a step's work itself.
+
+- **`wait`:** say which stories are being built and on which branches, then stop. When a lane agent finishes, its notification arrives in this session; run this skill again then. If a story has been in progress with no agent running (the session ended, or the agent stopped without committing), dispatch it again.
+- **`done`:** give the `status` summary in a few lines, then offer to run spec-design for the next milestone or feature.
+
+## 3. Keep going until the person is needed
+
+After a step finishes, run `next --json` again and carry on with the new step, without asking, as long as nothing needs the person. Stop and hand over when:
+
+- a skill asks the person questions (spec-design's rounds, spec-check's blocking questions, review's scope questions);
+- something needs the person's approval (init's draft, an approval for a protected path);
+- a person has to act: merge a pull request to a protected branch, add a CI secret;
+- the step is `wait` or `done`;
+- the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
+
+When you stop, end with one line saying what happens next and who does it, e.g. "Next: you approve the draft config, then I dispatch ST-1 to ST-4."

package/skills/review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: review
+description: The lead's review of a lane's finished branch before it merges. Runs code-kit verify on the branch, checks the work against its story's requirements and acceptance criteria, the spec-check report, the approval log and the tests, and ends with merge or send back. Use when a lane agent or person finishes a story, when the person asks to review a branch or pull request, or runs /code-kit:review [branch, story ID or PR number].
+---
+
+# Review a lane's branch
+
+Only the lead reviews. The argument names the branch (`web/st-4`), the story (`ST-4`, whose branch is `<lane>/st-4`) or a pull request number. With none, review every story `code-kit status` shows in review.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`. `<base>` is the branch the lanes started from: the lead's branch, or the first protected branch.
+
+## 1. Find the work
+
+- **The branch and its story.** `status --json` lists each story with its branch, its commits ahead of the base, and its worktree, if one is checked out. For a pull request, `gh pr view <n> --json headRefName,baseRefName` gives both.
+- **Where to run things.** Use the branch's worktree if it has one. Otherwise check it out in a throwaway worktree: `git worktree add .claude/worktrees/review-st-<n> <branch>`, and remove it when you're done.
+- **The spec-check report** is in that worktree, in `.claude/state/spec-check/<branch with / as _>.md`. The state folder isn't committed, so a branch pushed from elsewhere may not have one. Say so, and review against the specs directly.
+
+## 2. Run the rules
+
+From the branch's worktree:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" verify --base <base>
+```
+
+`verify` holds a `<lane>/…` branch to that lane's paths, and checks:
+
+- that every protected change is in the approval log, which is append-only;
+- new layer violations, and a baseline that grew;
+- screens without an approved design;
+- committed secrets;
+- the project's checks for the changed files.
+
+Any problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
+
+## 3. Check the work against the story
+
+Read the story, every requirement it cites, and the full diff (`git diff <base>...<branch>`). Read each changed file in full where the diff alone doesn't show the behaviour. Then, for each requirement:
+
+| Requirement | Acceptance criterion | Built (where) | Test (which) | Verdict |
+| ----------- | -------------------- | ------------- | ------------ | ------- |
+
+- **Built end to end:** the behaviour works from the entry point to storage and back, including the errors, permissions and states the spec lists. A mock, stub, hard-coded response, placeholder screen, `TODO` or "coming soon" in shipped code fails the requirement.
+- **Tested:** a test proves each acceptance criterion and names the requirement ID. The test would fail if the behaviour were broken; one that asserts nothing, or only asserts a mock, doesn't count.
+- **The spec-check report matches:** its table has no row still `missing` or `conflicts` without an answer, and its questions were answered, not guessed.
+- **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements, new dependencies) are called out. They may be fine, but they're the person's call.
+- **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
+
+## 4. Verdict
+
+Report the table, `verify`'s result and one of:
+
+- **Merge.** Everything passes. The lead merges the branch into its own branch (`git merge --no-ff <branch>`), sets the story's `**Status:**` to `done` in the plan, and commits. `main` and the other protected branches are merged by a person, through a pull request, after `verify` passes in CI. When the branch is merged, remove its worktree.
+- **Send back.** List each problem, where it is, and what "fixed" looks like. Send the list to the same lane agent if it's still running (SendMessage), or dispatch the story again with the list added to the brief. Set the story's status to `in progress`.
+- **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it.
+
+Keep the report short: the verdict first, then the table, then the problems.

package/skills/spec-check/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: spec-check
+description: Check a task against the project's specs before implementing it, and again before declaring it done. Produces the requirement table that the code-kit path guard requires before a lane writes code on a branch. Use at the start of any non-trivial task, or when checking code against the spec.
+---
+
+# Spec check
+
+The project's specs are in the folder named by `docs.specs` in `.claude/code-kit.json`. The engineering principles are in `docs.principles`, and the plan in `docs.plan`.
+
+## Steps
+
+1. **Find the section.** The task should name its requirement IDs (`BOOK-4`, headings in the specs) or a spec section. If it doesn't, search the specs folder for the domain nouns. Read the whole section, not just the matching lines, plus every section it references.
+2. **Read the principles.** Re-read the parts of `docs.principles` that apply: layers, ports and providers, events, testing and the rules for agents. Note this lane's layer rules from `layers` in the config.
+3. **Make a checklist.** One line per requirement: behaviour, fields, error cases, permissions, states, tests.
+4. **Compare with the code.** For each line, search for where it's implemented, then read those files in full.
+5. **Report** as a table:
+
+| Requirement | Status (done / partial / missing / conflicts) | Where | Note |
+| ----------- | --------------------------------------------- | ----- | ---- |
+
+6. **List questions** for the lead wherever the spec is missing, ambiguous, or contradicts the code or another spec. Don't resolve them by guessing.
+
+## Output
+
+The table, the questions, and a one-line recommendation: ready to implement, or blocked on questions.
+
+**Save it** to `.claude/state/spec-check/<branch>.md`, with `/` in the branch name replaced by `_` (for example `lane_data-e2-s1.md`). The table must keep its `| Requirement |` header. A lane can't write code on a branch until this report exists, and the lead reads it when reviewing the pull request. If the recommendation is "blocked on questions", stop and ask the lead instead of writing code.

package/skills/spec-design/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: spec-design
+description: Turn an idea into a buildable specification by working it through with the person. Frames the problem, explores options, asks the questions that decide scope and behaviour, and writes the brief, specs, architecture, principles and plan that code-kit init and spec-check work from. Use when someone starts a new product or feature with an idea rather than a spec, wants to ideate or shape requirements, or runs /code-kit:spec-design [idea or docs path]. Also use to resume or extend specs it wrote earlier.
+---
+
+# Spec design
+
+The argument is either the idea itself, in a sentence or a paragraph, or the path to the docs folder to write to (default `docs/`). If `.claude/code-kit.json` exists, use its `docs.specs`, `docs.principles` and `docs.plan` paths instead of the defaults.
+
+The job is to think the idea through **with** the person, not for them. You propose, question and push back; they decide. Every decision ends up in a document, so the build never depends on a conversation nobody can read later.
+
+The output is what the rest of code-kit runs on:
+
+| File                      | Holds                                                                                                                            | Used by                                   |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `docs/brief.md`           | Problem, users, outcomes, scope, non-goals, the decision log and the open questions (`${CLAUDE_PLUGIN_ROOT}/templates/brief.md`) | Everyone; where a resumed session starts  |
+| `docs/specs/NN-<area>.md` | One capability area each, with numbered requirements (`${CLAUDE_PLUGIN_ROOT}/templates/spec.md`)                                 | `spec-check`, lane agents                 |
+| `docs/architecture.md`    | Components, layers and which way they depend, contracts, integrations, quality targets                                           | `init` (layers, lanes, protected paths)   |
+| `docs/principles.md`      | Engineering rules, what counts as a contract, the definition of done, commands                                                   | `init` (checks, shell rules), lane agents |
+| `docs/plan.md`            | Milestones, stories that cite requirement IDs, the work split into lanes, sequencing                                             | `init` (lanes), the lead delegating work  |
+
+## Which situation
+
+- **A new idea, no docs** → all phases, from 1.
+- **Docs this skill wrote earlier** (`docs/brief.md` exists) → **Resume**: read every file in full, then start from the brief's open questions and the phase its `Status` line names. Say where you're picking up.
+- **An existing codebase, a new feature** → phases 1–4 and 6 for the feature, and phase 5 only where the feature changes the architecture. Read the code first (entry points, the modules the feature touches, existing docs and the code-kit config). Existing layers, contracts and conventions are constraints, not suggestions. Write the feature's spec next to the others and add its stories to the existing plan.
+
+Say which one applies before you start.
+
+## How to ask
+
+The questions are the skill. Ask well:
+
+- **Only what the person can answer.** Look up anything the repository, the docs or a quick search can tell you, and state what you found instead of asking.
+- **Few at a time.** Up to four questions per round, most decisive first: a question whose answer changes the shape of everything else comes before any detail. Use the AskUserQuestion tool for choices, with 2–4 concrete options, your recommendation first and marked, and a line on what each option costs. Ask open questions in plain text.
+- **Say why it matters.** One clause per question on what the answer changes: scope, a data model, a permission, a dependency, the cost.
+- **Offer a default.** When you have a sensible default, state it, so "yes" is a complete answer.
+- **Push back.** Name contradictions, scope creep, risky assumptions, and requirements that can't be tested. Suggest the smaller version that still delivers the outcome.
+- **Never fill a gap by guessing.** An unanswered question goes into the brief's open questions with its owner and what it blocks. It doesn't quietly become a requirement.
+
+After each round, summarise what was decided in a few lines, append it to the decision log, and move on.
+
+## 1. Frame
+
+Get the problem straight before any solution:
+
+- **Problem:** what's wrong or missing today, for whom, and how they cope now.
+- **Users:** each kind of user or actor, including admins, other systems and scheduled jobs, and what each is trying to get done.
+- **Outcome:** what's different when this works, and how anyone will know. Prefer something observable ("a new customer books without calling us") over a feature list.
+- **Why now, and constraints:** deadline, budget, team, required platforms and technology, regulation and data residency, existing systems it must fit.
+- **Non-goals:** what this deliberately won't do. Ask for them; they are as useful as the goals.
+
+Write `docs/brief.md` as soon as the frame is agreed, with `Status: framed`, and keep it current from then on.
+
+## 2. Explore
+
+Before narrowing, widen:
+
+- Sketch **two or three different shapes** of solution: different scopes, workflows or build-versus-buy choices, not the same idea three times. For each: how it works in a paragraph, what it's good at, what it costs, the biggest risk.
+- Walk through the **main journey** of each kind of user, step by step, for the shape you recommend. Journeys expose missing capabilities faster than feature lists.
+- List the **riskiest assumptions**: things that, if wrong, sink the idea. Say how each could be checked cheaply.
+- **Recommend** one shape and say why. The person chooses.
+
+Record the choice and the rejected options, with why, in the decision log. `Status: explored`.
+
+## 3. Shape the scope
+
+- Break the chosen shape into **capability areas**, for example accounts, booking, payments, notifications, admin. Each becomes one spec file.
+- For each area, agree what's in the **first release** and what's later. The first release must be a complete, working slice end to end, with nothing mocked or stubbed and no placeholder screens. If it's too big, cut capability, not quality.
+- Agree **quality targets** that change the build: expected scale, response times, availability, security and privacy, accessibility, supported devices and languages.
+
+Write the scope into the brief. `Status: scoped`.
+
+## 4. Specify
+
+Write one spec per capability area from `${CLAUDE_PLUGIN_ROOT}/templates/spec.md`. Work through the areas one at a time, with a round of questions per area.
+
+Each requirement gets an ID (`<AREA>-<n>`, for example `BOOK-4`) and its own heading, `### BOOK-4 Short name`, which is how `code-kit status` finds it. `ST` is reserved for stories. Every requirement must be testable: someone reading it can say whether the code does it. For every area, work through:
+
+- **Behaviour:** what each actor can do, step by step, including what the system does in response.
+- **Data:** the entities, their fields, types, which are required, uniqueness, and who owns the data.
+- **States:** the lifecycle of anything that changes state, with the allowed transitions and what triggers each.
+- **Rules:** validation, calculations, limits and business rules, with real values rather than "reasonable".
+- **Permissions:** who can see and do what, including other users' data.
+- **Errors and edge cases:** invalid input, duplicates, concurrency, partial failure, timeouts, an external service being down, empty and very large data.
+- **Events and integrations:** what other parts of the system or external services are told, and what they send back.
+- **Acceptance criteria:** Given / When / Then for the main path and for each important error.
+
+A spec answers what and why, not how: no framework, file or function names unless the person requires them. Anything still undecided goes in the spec's open questions and the brief's, never into a requirement. `Status: specified`.
+
+## 5. Architecture, principles and plan
+
+These are what `/code-kit:init` turns into enforced rules, so be concrete.
+
+- **`docs/architecture.md`:**
+  - the components (apps, services, packages, jobs) and what each is for;
+  - the **layers**, the folders each will live in, and which layers each may depend on (for example `ui → application → domain`, with adapters implementing the domain's ports);
+  - what each layer must not use, for example no database client in the domain;
+  - the **contracts** (API schemas, events, database schema) and who may change them;
+  - external services and how each is isolated;
+  - how the quality targets from phase 3 are met.
+    Propose the architecture from the specs and constraints, explain the choices, and ask about the ones that matter. Record each in the decision log.
+- **`docs/principles.md`:** the engineering rules; what counts as a contract; the definition of done (tests, checks, reviews, end-to-end working features); the test, lint, typecheck and database commands once they're known; and which commands only CI or a person may run, such as deploys.
+- **`docs/plan.md`**, from `${CLAUDE_PLUGIN_ROOT}/templates/plan.md`:
+  - the **work split**: lanes (for example web, api, data), the paths each will own, the agent name for it and the command that proves its work, so work can run in parallel without overlap;
+  - milestones, each a usable increment;
+  - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers), `**Depends on:**` and `**Status:** todo` lines. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
+  - sequencing: contracts and shared foundations first (the lead's own stories), then work that can run in parallel.
+
+`Status: planned`.
+
+## 6. Check it's buildable
+
+Before handing over, review everything once, as a sceptical engineer about to build it:
+
+- every journey step maps to a requirement, and every requirement to a story;
+- every requirement is testable and has acceptance criteria where it matters;
+- data, states, permissions and errors are covered for every area;
+- no requirement contradicts another, the constraints or a non-goal;
+- nothing is left as "TBD" outside the open-questions lists.
+
+Fix what you can. Put the rest to the person as a last round of questions. Then give them:
+
+1. what was written, file by file, in one line each;
+2. the open questions that still block building, with who owns each;
+3. the next steps:
+   - `/code-kit:init docs/` turns the architecture, principles and plan into enforced lanes and layers. If the project already runs code-kit, `/code-kit:init` updates it.
+   - `/code-kit:dispatch next` starts the ready stories on their lanes. Each lane spec-checks its story against these specs before writing code.
+   - `/code-kit:review` checks each finished branch against its requirements before it merges.
+   - `/code-kit:status` shows where the build stands against the spec.
+   - Or just `/code-kit:next`, which picks each of these in turn.
+
+`Status: ready` once no open question blocks the first milestone.
+
+## Keep it current
+
+A spec is the source of truth while it's being built. When a decision changes, re-run this skill: update the spec, the brief's decision log and the plan together, and keep requirement IDs stable (mark a dropped requirement `Removed` rather than reusing its number). If the project enforces code-kit and the specs are protected paths, the change goes through the approval log like any other.

package/skills/status/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: status
+description: Where the build stands against the spec. Traces every requirement to its story, branch and tests, shows what's done, in review, ready or blocked, lists gaps between the specs, the plan and the tests, and brings the plan's status fields up to date. Use when the person asks how the build is going, what's left, what's untested or what to do next, or runs /code-kit:status.
+---
+
+# Build status
+
+From the project root:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" status          # the report
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" status --json   # the same, to work from
+```
+
+Add `--base <ref>` when the lanes branch from something other than the first protected branch, for example the lead's integration branch.
+
+It reads the specs (`### BOOK-4 …` headings), the plan (`### ST-n` stories with `**Lane:**`, `**Requirements:**`, `**Depends on:**` and `**Status:**`), git (each story's `<lane>/st-n` branch) and the tracked tests (which requirement IDs each names). If the config has no `docs.specs` or `docs.plan`, suggest the spec-design skill instead.
+
+## Report
+
+Lead with the answer, in a few lines:
+
+1. **Progress:** requirements done, of how many; stories done, in review, in progress, ready and blocked. Name the milestone that's closest to done and what it still needs.
+2. **Needs the lead now:**
+   - stories in review (run the review skill);
+   - stories that are ready (run the dispatch skill);
+   - blocked stories, and what they wait on.
+3. **Risks:**
+   - requirements marked done that no test names;
+   - requirements in no story;
+   - stories citing requirements no spec defines;
+   - stories whose branch has been in review a long time.
+
+Then the detail only if the person asks: the story table and the requirement table from the CLI.
+
+"No test names it" means no tracked test mentions the ID, so it may be tested under another name. Treat it as a question for the review, not proof of a gap.
+
+## Keep the plan current
+
+`status` shows where the plan's `**Status:**` lines disagree with git ("the plan is out of date"). Offer to fix them. The lead edits the plan, updates the lines, and commits on the lead's branch. Git is right about branches; the plan is right about `done` for stories whose branch was merged and deleted.
+
+Gaps between the specs and the plan (a requirement in no story, an unknown lane, a duplicate ID) are the lead's to fix in the plan or the spec. If fixing one needs a product decision, ask the person rather than guessing.