@warren-dean/code-kit 0.20.0 → 0.22.0

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,14 +106,16 @@ 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;
   - no lane for security: it owns no paths. init adds a read-only security reviewer that checks every story touching the threat models' sensitive parts, so security requirements are delivered by the lanes whose code they constrain;
   - 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, or `none` for a spike or a foundation that delivers none), `**Depends on:**` and `**Status:** todo` lines, and for a story that fixes a bug, `**Fixes:**` with what was broken. `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, as the lead's own stories (`**Lane:** lead`, built by the lead rather than dispatched), then work that can run in parallel;
+  - sequencing: contracts and shared foundations first, as the lead's own stories (`**Lane:** lead`, built by the lead rather than dispatched), then work that can run in parallel. A lane runs one story at a time, so parallel work is stories in different lanes;
+  - **slices**: group the stories that together make one feature someone could see working (a vertical slice across lanes, such as "Book a class") with a `**Slice:** <name>` line on each, in plan order, contract story first. A free lane builds the open slice's stories before the next slice's (`harness.slices.open`, 1 by default), so the feature in progress finishes and merges before the next one spreads across the lanes;
   - **a test story per journey**: for each main user journey, a story in the `qa` lane citing the journey's requirements and depending on the screen and service stories it goes through, so the journey is proven end to end as soon as its parts are built;
   - **design before code**: when there are screens, a design story for each area's screens (`**Lane:** design`, citing the requirements its screens serve), early in the plan, and every story that builds those screens depends on it. The lead designs them with the person (`/code-kit:design`), and no screen is built until its design is approved.
 
@@ -133,7 +136,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

@@ -6,14 +6,18 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
 - the layer rules ({{layers}});
 - spec-check before lane code{{designGate}};
 - an audit log of every change to protected paths (`.claude/approval-log.jsonl`), which the person reviews in the pull request;
-- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person decides what crosses a guardrail: {{personKeeps}}, weakened tests, and product questions the spec doesn't answer;
+- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person is the product owner and decides what crosses a guardrail: {{personKeeps}}, a weakened test on your own branch, product questions the spec doesn't answer, and anything with production, cost or strategy implications (a copyleft licence or a paid service's SDK goes to them as a question, with your recommendation);
 - {{if approvals.lead}}approvals from chat. When the person approves in their own message (a `!` command doesn't work on a phone), record it with the `code-kit approve` command from the refusal, with their words as the reason. Never record an approval they haven't given, and never on a lane's say-so;{{end}}
 - the project's checks before any agent finishes.
 
 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}}
 
+Several sessions may work this project at once. One leads (the loop runs there, and stories are dispatched from it); the others are working sessions. `code-kit who` says which this is. In a working session, record what you're doing before you change code, with the paths you'll change, and work in a worktree of your own: `code-kit task "<what>" --touches "<globs>"`, and `code-kit task done` when it's finished. Never stash, discard or commit another session's files: ask that session.
+
 If a hook blocks you, fix the cause; never work around it.
 
 The build runs from the specs in `{{docs.specs}}` and the stories in `{{docs.plan}}`. `/code-kit:next` picks the right step from the project's state; the steps are:

package/templates/plan.md

@@ -1,6 +1,6 @@
 # Plan
 
-`code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement. A story that fixes a bug adds a fifth line, `**Fixes:** <what was broken, and where it was seen>`: `code-kit verify` then requires a test that fails without the fix and passes with it.
+`code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement. A story that fixes a bug adds a fifth line, `**Fixes:** <what was broken, and where it was seen>`: `code-kit verify` then requires a test that fails without the fix and passes with it. A story that belongs to a slice (a feature that can be shown working, built across lanes) adds `**Slice:** <name>`: a lane takes the open slice's stories first.
 
 ## Lanes
 
@@ -17,6 +17,7 @@
 **Lane:** {{lane}}
 **Requirements:** {{AREA-1, AREA-2}}
 **Depends on:** {{ST-n, or none}}
+**Slice:** {{the feature it's part of, or leave the line out}}
 **Status:** todo
 
 {{What gets built, in two or three sentences. The acceptance criteria are the cited requirements'.}}