@warren-dean/code-kit 0.31.1 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -50,7 +50,7 @@ When the story carries out an intent the team agreed (`code-kit intend`), add `-
50
50
 
51
51
  One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief, "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout", and what `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" replay <story> --brief` prints: the story's last commit, the tests last run, what changed since, and what was reconciled, from its event log, which holds them even when the stopped agent wrote no report. A long-lived agent rereads its whole context on every step, which is most of what a build costs.
52
52
 
53
- Start each story with the Agent tool: `subagent_type` is the lane's agent, `model` the one `code-kit next --json` gives the story in `models` (with the lane model `story`, each story's model follows its `**Size:**`, raised for a security requirement, a fix or a send-back; a story with no size runs on Sonnet, so size it in the plan first if it's plainly small or large), `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
53
+ Start each story with the Agent tool: `subagent_type` is the lane's agent, `model` the one `code-kit next --json` gives the story in `models` (with the lane model `story`, each story's model follows its `**Size:**`, raised for a security requirement, a fix or a send-back; a story with no size runs on Sonnet, so size it in the plan first if it's plainly small or large), `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Each lane works in its own worktree, `.claude/worktrees/lane-<lane>`, kept from story to story with its installs: code-kit gives it to the lane's agent when it starts, detached at the main checkout's HEAD, so the agent makes or switches to its story's branch as the brief says. So start the agents one per message, each right after the last (they still run in parallel in the background): code-kit tells each agent's worktree whose it is as it starts, and refuses a second agent with a worktree in the same message.
54
54
 
55
55
  The brief is the agent's whole context. Write it so the agent needs nothing else:
56
56
 
@@ -69,7 +69,7 @@ Designs: <for a story that builds screens, what `code-kit designs ST-<n>` lists:
69
69
  Out of scope: <what neighbouring stories or other lanes will do>
70
70
 
71
71
  Steps:
72
- 1. Run the spec-check skill against these requirements and save the report (the path guard requires it).
72
+ 1. Run the spec-check skill against these requirements and save the report, with its `| Requirement |` table (the path guard requires it, and reads a report without that table as none).
73
73
  If it recommends "blocked on questions", stop and report the questions.
74
74
  2. Build it end to end in your lane's paths. No mocks, stubs, placeholder screens or "coming soon".
75
75
  3. Write tests that prove each acceptance criterion. Name the requirement ID in each test's title,
@@ -80,6 +80,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
80
80
  - **`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 most stories don't need the session's model. Recommend `story`: each story runs on the model its `**Size:**` in the plan gives (Haiku for small, Sonnet for medium, Opus for large), raised to Opus for a security requirement, to Sonnet at least for a fix, and one step for each time its branch is sent back. Offer one model for every lane (`sonnet`) as the simpler choice, and say the lead, the reviewer and the security reviewer keep their own models either way. A lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "story" } }`, or leave it out for the session's model. A project set up before sizes existed has stories with none, which run on Sonnet until the lead sizes them.
81
81
  - **`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 band and the pane's Needs you: 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.
82
82
  - **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
83
+ - **`cost`, the running budget (spec 29):** from the brief's running budget, or ask the person if it has none: how much a month each environment may cost, in their currency, and the load to plan for. Write `"cost": { "currency": "AUD", "monthly": { "prod": 100, "dev": 20 }, "load": "500 users at launch", "paths": [...] }`. `paths` lists the project's infrastructure files, whatever defines them (Terraform, CDK, Pulumi, Serverless, SST, Docker Compose, Kubernetes or Helm, `fly.toml`, `vercel.json`, `netlify.toml`, `render.yaml`, `wrangler.toml`, `supabase/config.toml`, an `infra/` folder); a branch that changes one has to say in the register what that costs. Set `docs.costs` only if the register isn't `docs/costs.md`. The register is written by any agent (a lane costs the infrastructure its story adds), and a commit that takes an environment past its budget waits for the person's `cost` approval, whatever the config delegates. Show the budget with the rest of the setup.
83
84
  - **`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.
84
85
 
85
86
  ### Standards (spec 22)
@@ -184,6 +185,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
184
185
  - 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);
185
186
  - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
186
187
  - 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.
188
+ - a running budget, when the config has no `cost` (whatever its `setup`): ask the person for it as section 2 describes. Then cost what's already defined in the infrastructure files, or deployed, into `docs/costs.md`, a row per paid thing at its real size, and run `code-kit cost`. When it's over the budget, bring the person options that fit (spec-design's architecture step lists the kinds), each with what it gives up and what it saves a month, and record their choice in the brief's decision log; the stories that bring it within budget go in the plan.
187
189
  3. **Show the difference:**
188
190
 
189
191
  ```bash
@@ -58,6 +58,7 @@ Read the story and every requirement it cites. Then start from what's already be
58
58
  It's refused when the screenshot isn't a PNG at the design's viewport (1x to 4x); take it again at that size. `verify`, and the merge queue, report every approved state of the branch's screens with no screenshot recorded since the screen last changed, so a branch that moves after your review is compared again. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
59
59
 
60
60
  - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
61
+ - **Running cost (spec 29):** where the config has a budget, a branch that changes the infrastructure files (`cost.paths`) changes `docs/costs.md` too (verify fails it otherwise). Read the two together: the size, tier and count in the code are the ones in the register's rows, every new paid thing has a row, and the estimate is for the load the spec gives, not a provider's production default. A mismatch sends the branch back, naming the file and the row. `code-kit cost` shows the totals against the budget and the prices to recheck.
61
62
  - **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.
62
63
 
63
64
  ## 4. The security review
@@ -51,6 +51,7 @@ Get the problem straight before any solution:
51
51
  - **Users:** each kind of user or actor, including admins, other systems and scheduled jobs, and what each is trying to get done.
52
52
  - **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.
53
53
  - **Why now, and constraints:** deadline, budget, team, required platforms and technology, regulation and data residency, existing systems it must fit.
54
+ - **Running budget (spec 29):** how much a month the person will spend running it (hosting, databases, queues, outside services), for each environment they'll have (production at least; dev or staging only if they'll run), in their currency, and the load to plan for at launch (users, requests, data). 0 is a real answer: free tiers only. It shapes the architecture as much as any requirement, so ask it in the first round, and record it in the brief.
54
55
  - **Non-goals:** what this deliberately won't do. Ask for them; they are as useful as the goals.
55
56
 
56
57
  Write `docs/brief.md` as soon as the frame is agreed, with `Status: framed`, and keep it current from then on.
@@ -107,7 +108,9 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
107
108
  - how the quality targets from phase 3 are met;
108
109
  - **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;
109
110
  - 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.
111
+ - the **running cost** of each shape you propose (spec 29): every paid thing (a database, a container, a function's invocations, a queue, a domain, an outside API), its provider, the size or tier, and its monthly estimate at the expected load, per environment, from the provider's published pricing, with the page and the date you read it. Size for the load the brief gives, not for a provider's production default: one small instance before a cluster, a free or starter tier before a dedicated one, managed services that scale to zero before ones that run all the time, no standby, NAT gateway or second region unless a quality target needs it. At least one shape fits the budget. When the one the person prefers doesn't, say by how much, and offer options that fit (a smaller size, a cheaper tier or provider, one environment instead of two, a service the product can do without at launch, less scope), each with what it gives up; the person picks.
110
112
  Propose the architecture from the specs and constraints, explain the choices, and ask about the ones that matter. Record each in the decision log.
113
+ - **`docs/costs.md`:** the chosen shape's costs, one table whose header is `| Item | Provider | Environment | Size | Monthly | Basis |`: a row per paid thing; Environment one the budget names, or `all`; Monthly a plain number in the budget's currency; Basis the pricing page and the date (YYYY-MM-DD). `code-kit cost` adds it up once init has written the budget. Write it before the plan: a design over the budget isn't planned.
111
114
  - **`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.
112
115
  - **`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.
113
116
  - **`docs/plan.md`**, from `${CLAUDE_PLUGIN_ROOT}/templates/plan.md`:
@@ -18,7 +18,7 @@ Lane rules:
18
18
 
19
19
  Always:
20
20
 
21
- - 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.
21
+ - 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, as the skill writes it: a table whose header row starts `| Requirement |`, one row per requirement. The path guard blocks code until it exists, and reads a report without that table as none.
22
22
  - 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.
23
23
  - {{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}}
24
24
  - 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.
@@ -26,6 +26,7 @@ Always:
26
26
  - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
27
27
  - You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
28
28
  - A new dependency needs the lead's approval. Before asking, check the project doesn't already have something that does the job. If the install is refused, put in a change request for the lead: the package, the story and requirement that need it, what you checked, and anything lighter that would do; then stop. The lead approves it, or tells you what to use instead.
29
+ - {{if cost}}The project has a running budget. When you add, remove or resize anything that costs money to run (a database, a container, a function, a queue, an outside service, a plan tier), change its row in `{{docs.costs}}` in the same branch: the item, provider, environment, size, its monthly estimate as a number, and the pricing page and date you read it. Size it for the load the spec gives, not the provider's production default. A branch that changes the infrastructure files without the register fails verify. If your commit is refused for going over the budget, don't look for a way round it: hand the lead a change request with what you need, what it costs a month, and the options that fit, each with what it gives up.{{end}}
29
30
  - Build every feature end to end. No mocks, stubs, placeholder screens or "coming soon".
30
31
  - A screen is built to its approved design: the brief names every state's image and code under `design/`. Read each before you write the screen, match its layout, copy, spacing and states, and build it from the project's components rather than pasting the export. Your report lists each state with what you built for it.
31
32
  - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
@@ -15,6 +15,8 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
15
15
 
16
16
  {{if vibe}}Product and UX are yours: what the spec leaves open, a screen's visual design, the wording, what to build next. Answer from the brief, the specs and the principles, and record each product decision in the brief's decision log with why. Build everything that doesn't need the person, and stop only for what nobody else can give: an account with a service provider, an API key or secret from one, a payment, or an act outside the repository (DNS, an app store). Ask for it with `code-kit ask "<what you need, and what it's for>" --needs account|key|payment|outside` (`--story ST-n --blocks` holds the story until they answer), and carry on with everything else meanwhile, against a local or test stand-in where there is one. Lanes don't ask the person: they write the question for the lead.{{end}}
17
17
 
18
+ {{if cost}}The project has a running budget the person set, per environment, and `{{docs.costs}}` estimates what each paid thing costs a month; `code-kit cost` adds it up against the budget. Design and review to it: size each service for the load the spec gives, not a provider's production default. In review, check a branch that changes the infrastructure against its register rows: the size in the code is the size in the row, and every new paid thing has one; send it back otherwise. Going past the budget is always the person's call, under vibe too: a commit that does is refused until they approve `cost`. Before asking, find options that fit (a smaller size, a cheaper tier or provider, fewer environments, less at launch), and ask with `code-kit ask "<what's over, and by how much>" --option "<option>: <what it gives up, what it saves a month>"`, the over-budget choice among them (under vibe, with `--needs payment`).{{end}}
19
+
18
20
  {{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}}
19
21
 
20
22
  - {{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}}