@warren-dean/code-kit 0.20.0 → 0.21.0

package/skills/init/SKILL.md

@@ -17,7 +17,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project
 - **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.
+- **No config, no code and no docs** (just an idea) → stop and suggest `/code-kit:spec-design` first. It writes the brief, specs, architecture, standards, principles and plan this skill works from.
 
 Say which one applies and why before you start.
 
@@ -77,8 +77,20 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`approvals.delegate`, who decides what (HELM-1):** the person sets the guardrails and decides what crosses them; the lead decides everything inside them, so lanes ask the lead, never the person. Draft `"dependencies": {}` (the lead approves a package only when the story's requirements need it and it fits the spec, the principles and the architecture; npm packages must also pass the default registry limits on licence, popularity and age) and `"protected"` listing every protected approval except those guarding the specs, contracts and the architecture's rules, the screens' designs (`design`), and CI. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. `tests` (weakening a test) is always theirs.
 - **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so Sonnet usually does the work well for much less than the session's model; recommend `sonnet`, and say the lead, the reviewer and the security reviewer keep the session's model. The mod sets it as each lane agent starts; a lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "sonnet" } }`, or leave it out for the session's model.
 - **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their Decisions tab: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
+- **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
 - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
 
+### Standards (spec 22)
+
+After the layers, suggest the project's standards: named engineering rules every agent builds to, each graded and saying how firmly code-kit applies it. Standards are guardrails, and guardrails are the person's: suggest them, and write nothing until the person has approved, edited or dropped each one.
+
+- **Format.** Each standard is a `### <id> <title>` heading in `docs/standards.md`, followed by its fields, one per line: `level` (required or recommended), `applied` (enforced, checked or advice), `layers` (layer names, or all), `why` (one or two sentences), `source` (where it came from) and, for an enforced one, `enforced by`. The id's prefix is its category: `PRI-` principles (judgement, such as single responsibility; never enforced), `PAT-` patterns (how a kind of problem is solved here), `ARC-` architecture (what may depend on what, where things live), `CON-` conventions (naming, layout, tests' shape), `POL-` policies (what must or must never happen). The title is one sentence an agent can act on.
+- **How firmly.** Mark a standard `enforced` only where a rule the draft already has refuses the change, and name it: `enforced by: layers (domain may not import infrastructure)`, `layers (web may not import the package pg)`, `protected (<approval>)`, `check (<name>)` or `shell (<words of its why>)`. code-kit then names the standard in that rule's refusal. Everything else review can judge is `checked`; the rest is `advice`.
+- **With specs**, suggest them from the architecture, the principles, the specs' threat models and the brief's decision log, each citing its source (`source: the threat model in docs/specs/03-payments.md`). A threat model saying card numbers are never stored is a `POL-` standard; a layer rule the architecture sets is an `ARC-` standard enforced by that layer rule. The engineering rules in `docs/principles.md` move into standards; principles keeps the definition of done, the commands and the privacy and residency targets.
+- **With no specs but code**, infer them from the code: the import graph (`graph`) for layering and import directions; naming and folder layout; the data-access pattern (repositories, direct queries, an ORM); the formatter's and linter's configs; the tests' shape and where they live. Count, don't guess: each inferred standard carries its evidence (`source: the code: 41 of 43 modules reach the database through *Repository classes`), names the files that don't follow it, and starts as `recommended`. A pattern the code follows inconsistently (3 of 5 services through repositories, 2 querying directly) isn't a standard yet: put it to the person as a choice, with both counts, and write the way they pick.
+- **Protect the file.** Add `{ "glob": "docs/standards.md", "approval": "standards", "why": "the project's standards" }` to `protected`, before any broader glob that also covers `docs/`. The lead may approve adding a recommended standard if the person puts `standards` in `approvals.delegate.protected`; removing a standard, or weakening a required one, is always the person's, whatever the config delegates.
+- **Check it** once the config is written: `code-kit standards` reports a duplicate id, an unknown category, an enforced principle, or an `enforced by` that names no rule the config has. Each lane agent's rules then list the standards for its layers, one line each, and CLAUDE.md lists them all.
+
 Prove the draft:
 
 ```bash
@@ -124,6 +136,7 @@ Show the person:
 3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
    and whether the lead may record approvals given in chat (`approvals.lead`), how hands-off the build is (`harness.autonomy`), the lane agents' model (`harness.agents.lanes.model`), and whether agents may draft bug reports for code-kit (`harness.report.on`);
 4. the project skills, and which lane agents use each;
+   and the standards you suggest, each with its category, level, how it's applied and its source (for inferred ones, the evidence and the files that don't follow it), with the choices where the code is inconsistent;
 5. the active adapters and what each adds, from `adapters`. A companion tool that's installed but not set up here (its init skill is in your skills list, for example `/context-graph:init` with no `.ctx/` folder): add `"adapters": { "<name>": true }` to the draft and say it will be set up before any code is written;
 6. every **question**: where the docs or the code are silent, ambiguous or contradictory. Don't guess; a wrong owner or layer blocks real work.
 
@@ -155,13 +168,14 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
 
 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. If the live config has no `harness.autonomy`, ask the person about it as in section 2.
-   Bring code-kit's own instructions up to date: run `code-kit instructions`. Parts between markers are rewritten with `--write`. A part written before the markers (CLAUDE.md's `## Enforced, not advised` section, an agent's `Always:` list) is merged once: replace it with what `code-kit instructions show lead` or `show lane` prints, and move every line the project wrote itself into a section of its own outside the markers. Show the person the difference with the rest.
+   Bring code-kit's own instructions up to date: run `code-kit instructions`. Parts between markers are rewritten with `--write`. A part written before the markers (CLAUDE.md's `## Enforced, not advised` section, an agent's `Always:` list) is merged once: replace it with what `code-kit instructions show lead` or `show lane <lane>` prints, and move every line the project wrote itself into a section of its own outside the markers. Show the person the difference with the rest.
    A config without `"setup": 3` predates what setup now includes; add whichever of these the project is missing, as section 2 and 3 describe, and set `"setup": 3`:
    - project skills for the recipes in the docs (or, without recipes, the patterns the code follows), listed on the lane agents;
    - the design gate for every lane that owns screens, with its register; and design stories in the plan for screens not yet built (ask the person before adding stories);
    - the QA lane, its agent and its checks, when there are screens or journeys across lanes;
    - the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
    - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
+   - project standards, when the project has no `docs/standards.md`: suggest them as section 2's Standards describes, moving the engineering rules out of `docs/principles.md`, and protect the file.
 3. **Show the difference:**
 
    ```bash

package/skills/next/SKILL.md

@@ -44,7 +44,7 @@ Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the
 
 - **`setup`:** run the skill named in `args` (for example `context-graph:init`); it's another plugin's, so call it by that full name.
 - **`update`:** run `code-kit:init`. `why` names what the setup is missing (the design gate, design stories, a QA lane, a security reviewer); init adds those, shows the person the difference, and sets `"setup": 3`. Until then no new story starts; work already started goes on to review and merge.
-- **`instructions`:** there's no skill to run. With `args` `write`, run `code-kit instructions --write`. With `merge`, some files were written before code-kit marked its part: run `code-kit instructions` to list them, replace each old part with what `code-kit instructions show lead` (CLAUDE.md) or `show lane` (an agent file) prints, keep every line the project wrote itself outside the markers, then run `--write` for the rest. Commit it on a branch and merge it like your own stories.
+- **`instructions`:** there's no skill to run. With `args` `write`, run `code-kit instructions --write`. With `merge`, some files were written before code-kit marked its part: run `code-kit instructions` to list them, replace each old part with what `code-kit instructions show lead` (CLAUDE.md) or `show lane <lane>` (that lane's agent file) prints, keep every line the project wrote itself outside the markers, then run `--write` for the rest. Commit it on a branch and merge it like your own stories.
 - **`lead`:** there's no skill to run. Build each story yourself, on the branch `lead/st-<n>`: spec-check it first if it cites requirements, do the work, commit, then run `code-kit:review` on the branch like any other. A spike's result goes in the docs it names.
 - **`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.

package/skills/review/SKILL.md

@@ -49,6 +49,7 @@ Read the story and every requirement it cites. Then start from what's already be
 - **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) are sent back, or split into their own story. A new dependency is yours to judge, as in `/code-kit:decide`: the story's requirements need it, nothing the project has does the job, and it fits the principles and the layer. Only what crosses a guardrail (the spec, a contract, the architecture) is 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.
+- **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
 
 ## 4. The security review
 
@@ -78,7 +79,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
 
   Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree.
 
-- **Send back.** List each problem, where it is, and what "fixed" looks like. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
+- **Send back.** List each problem, where it is, and what "fixed" looks like, with the requirement or the standard's id it breaks. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
 
   ```bash
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sent-back <branch> --reason "<the problems, in one line>"

package/skills/spec-design/SKILL.md

@@ -1,11 +1,11 @@
 ---
 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.
+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, standards, 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 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.standards`, `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.
 
@@ -16,7 +16,8 @@ The output is what the rest of code-kit runs on:
 | `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/principles.md`      | What counts as a contract, the definition of done, the privacy and residency targets, commands                                   | `init` (checks, shell rules), lane agents |
+| `docs/standards.md`       | The engineering rules, each a named standard: graded, and how firmly code-kit applies it (spec 22)                               | `init` (enforced rules), lanes, reviews   |
 | `docs/plan.md`            | Milestones, stories that cite requirement IDs, the work split into lanes, sequencing                                             | `init` (lanes), the lead delegating work  |
 
 ## Which situation
@@ -91,7 +92,7 @@ Each requirement gets an ID (`<AREA>-<n>`, for example `BOOK-4`) and its own hea
 
 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
+## 5. Architecture, standards, principles and plan
 
 These are what `/code-kit:init` turns into enforced rules, so be concrete.
 
@@ -105,7 +106,8 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
   - **recipes**: under `## Recipes`, a `### <recipe-name>` for each layer's common addition (a new screen, endpoint, migration, domain service, job): the steps in order, the files each step creates or changes, and how it's tested. Each becomes a project skill when init sets up the lanes, so every lane agent builds the same thing the same way;
   - the **design tool** for screens, when there are any: the one the person uses (Paper, Figma, Pencil), or design files under `design/` when they have none.
     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; the privacy and data residency targets from the brief (where data may be stored and processed, what is never logged), which the security reviewer checks against; 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/standards.md`:** the engineering rules, each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why` and `source` lines, the id's prefix its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Draw them from the architecture (an `ARC-` standard for each layer rule, `enforced by: layers (<layer> may not import <layer>)`), the threat models (a `POL-` standard for what must never happen to sensitive data), and the decisions; cite each one's source. Propose them and ask about each: a standard is a guardrail, so the person decides it. Init checks the file and protects it.
+- **`docs/principles.md`:** the privacy and data residency targets from the brief (where data may be stored and processed, what is never logged), which the security reviewer checks against; 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. Each lane writes and runs the unit tests for its own code;
   - a **QA lane** (`qa`, agent `test-engineer`) whenever the product has screens or journeys that cross lanes: it owns the end-to-end suites (for example `e2e/**` or `apps/*/e2e/**`), in the runner that suits each surface (Playwright for web, Maestro or Detox for mobile), and its command runs them. Nobody else owns these tests, so without it nothing proves a journey works across the lanes;
@@ -133,7 +135,7 @@ Fix what you can. Put the rest to the person as a last round of questions. Then
 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:init docs/` turns the architecture, standards, principles and plan into enforced lanes, layers and standards. 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.

package/templates/agent.md

@@ -19,6 +19,7 @@ Always:
 
 - Work on the branch the brief names (`<lane>/st-<n>`). Start every task with the spec-check skill and save its report to .claude/state/spec-check/<branch>.md; the path guard blocks code until it exists.
 - Follow `{{docs.principles}}`, including the rules for AI agents. Hooks enforce ownership, layers and the project's checks; if one blocks you, fix the cause, never work around it.
+- {{if standards}}Build to the project's standards for your layers, from `{{docs.standards}}` (read a standard's why and evidence there when you need it). A required one that review checks sends your branch back if it's broken; advice is yours to weigh:{{standards}}{{end}}
 - Read every file you change in full. Of what it imports and what calls it, read what your change needs: the definitions it uses and the call sites it changes. A context tool's fresh card for a file stands for reading it whole; read the source where the card is missing, stale or not enough.
 - Search before you build; reuse existing services, providers, components and schemas.
 - Write only in your owned paths. For anything else, write a short change request for the lead and stop.

package/templates/claude-md.md

@@ -12,6 +12,8 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
 
 UX is yours: what a screen does on an error, an empty list or a slow load, and the wording the spec implies, answered from the spec and the principles the person agreed. A screen's visual design is theirs. When something needs the person to decide or do (a product choice the spec doesn't settle, an account only they can create, a design to sign off), ask it with `code-kit ask "<question>" --option "<choice>: <what it does>"` (`--story ST-n --blocks` holds the story until they answer). It waits in their Decisions tab, and their answer comes back to you; asking only in chat, it scrolls away. Lanes don't ask the person: they write the question for the lead.
 
+{{if standards.all}}The project's standards, in `{{docs.standards}}`: {{standards.all}}. Each lane is given the ones for its layers. In review, check each changed file against the checked standards for its layer (`code-kit standards --for <file>`): a broken required one sends the branch back, naming the standard; a broken recommended one is a concern, and advice at most a nit. Adding a recommended standard may be yours where the config delegates the `standards` approval; removing one, or weakening a required one, is always the person's.{{end}}
+
 - {{if harness.report.on}}When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.{{end}}
 
 If a hook blocks you, fix the cause; never work around it.