@warren-dean/code-kit 0.30.2 → 0.31.1

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.30.2",
3
+ "version": "0.31.1",
4
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",
5
5
  "license": "MIT",
6
6
  "author": "Warren Langeveldt",
@@ -7,6 +7,8 @@ description: The lead decides what a lane asked for and couldn't do itself (a ne
7
7
 
8
8
  The person is the product owner and sets the guardrails: the specs, the screens' visual design, CI and the pipelines, the kit (the rules in `.claude/code-kit.json`), and product questions the spec doesn't answer, plus anything with production, cost or strategy implications. Everything technical is yours by default: contracts, migrations, packages, merges into the base, and a weakened test on a lane's branch once you've reviewed it (`code-kit approve tests --lane <lane> --delegated --story ST-n --reason "…"`); on your own branch a weakened test is the person's. Inside them, you run the team. A lane that needs something it can't do itself asks you, and you decide on the merits. Passing a request to the person because you could is not deciding: they'd approve it by default, and the check would be gone.
9
9
 
10
+ **Under vibe** (`harness.autonomy` is `vibe`) the guardrails are yours too: every request is `by: "lead"`, the spec, the design, CI, the kit, the standards and weakened tests on any branch included, and a package beyond the registry's rules is your judgement (approving it records which rules it breaks). Decide each as the person would, against the brief and the principles, and say why in the reason. Nothing goes to the person but what only they can give: an account, a key, a payment, an act outside the repository (`code-kit ask … --needs …`).
11
+
10
12
  The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
11
13
 
12
14
  ## 1. Find the requests
@@ -30,6 +30,8 @@ Use the spec's own content: the real labels, fields, messages and limits from it
30
30
 
31
31
  ## 3. Show it and iterate
32
32
 
33
+ **Under vibe** (`harness.autonomy` is `vibe`), you approve each screen yourself: check every state against the spec's Screens section, the principles and the project's tokens, fix what falls short, and approve it with `code-kit approve design --delegated --story ST-n --reason "…"` when the register is written. Skip the showing below; the person isn't asked.
34
+
33
35
  Show the person each screen (a screenshot, or the file to open) with one line on what it does and which requirements it serves. Ask what to change. Make the changes and show them again until they say a screen is approved. A screen they want rethought goes back to step 2; one that needs the spec changed goes to `/code-kit:spec-design` first.
34
36
 
35
37
  ## 4. Export what's approved
@@ -68,14 +68,14 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
68
68
  - **`protected`:** registers and contracts that need a person's sign-off, each with an `approval` name and a `why`.
69
69
  - **`designGate`:** whenever a lane owns screens (web, mobile, desktop), designs come before code:
70
70
  - `register`: `design/register.json`, written now as `{ "screens": [] }`;
71
- - `screens`: a glob for each such lane's screen files (routes, pages, views), from the architecture's folders, with `not` for tests and stories;
71
+ - `screens`: a glob for each such lane's screen files (routes, pages, views), from the architecture's folders, with `not` for tests and stories. Where a file-based router puts other files beside its screens, `not` leaves out those that draw no screen: its layouts, API routes, middleware and special files (such as `_layout`, `+html`, `+native-intent`, `+middleware` and `*+api` in an Expo Router app, `route` and `middleware` in a Next.js one);
72
72
  - `howTo`: "Design it first: run /code-kit:design for this area's design story, and a person approves it.";
73
73
  - a `protected` entry for the register (approval `design`, why "only approved designs are built"). Never put `design` in `approvals.delegate`: approving a design is the person's.
74
74
  - **`shell.block`:** deploy, release and production commands reserved for CI or a person. Each rule that names a command (`cdk deploy`, `supabase db push`, `terraform apply`) gets `"command": true`, with a pattern for the command and its arguments (`"cdk\\s+deploy\\b"`), so a grep, a heredoc or a commit message that mentions the command isn't refused, while running it, after `cd …`, through `npx` or `pnpm exec`, or in `sh -c`, still is. Leave `command` out only for a rule about the whole line, such as a download piped into a shell.
75
75
  - **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
76
76
  - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
77
77
  - **`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.
78
- - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the three choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), or `off`. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes.
78
+ - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the four choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), `off`, or `vibe` (it keeps going on its own, and every product and project decision is the lead's: the specs for later milestones, the designs, CI, the standards, packages, weakened tests, merges and pushes; they're asked only for what nobody else can give, an account with a service provider, a key from one, a payment, or an act outside the repository). Say what vibe gives up: nobody but the lead reviews a decision before it's built on, and a push to the base can deploy. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes. With `vibe`, leave `approvals.delegate` out: vibe delegates everything, whatever it says, and the Settings tab shows every approval as the lead's.
79
79
  - **`approvals.delegate`, who decides what (HELM-1, WHO-1):** the person is the product owner; the lead decides everything technical, so lanes ask the lead, never the person. With no `approvals.delegate`, that's the default: the lead approves new packages (only when the story's requirements need them and they fit the spec, the principles and the architecture; npm packages must also pass the registry limits on licence, popularity and age), every protected change except the specs (`spec`), the screens' designs (`design`), CI (`ci`) and the kit, merges into the base, and weakened tests on a lane's branch after its review. 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. Only if they do, draft `approvals.delegate` with exactly what the lead keeps (`{ "protected": [...], "merge": true, "tests": true, "dependencies": {} }`, leaving out what they keep), or `false` to keep everything. They can change it later in the Settings tab's Approvals section.
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.
@@ -17,6 +17,7 @@ It returns `step`, `why`, `args`, `then` (steps that can follow straight after)
17
17
 
18
18
  | State | Step |
19
19
  | ------------------------------------------------------------ | --------------------------------------------------------- |
20
+ | This is a working session (another session leads) | working: the step is the lead's, not this session's |
20
21
  | Invalid config | `check`, then fix the config |
21
22
  | No config, a draft waiting | `init`, to show it for approval |
22
23
  | No config, a spec still being shaped (brief not `ready`) | `spec-design`, resuming |
@@ -47,6 +48,7 @@ Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the
47
48
  - **`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.
48
49
  - **`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.
49
50
  - **`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.
51
+ - **`working`:** another session leads the project, and the step (`lead.step` in the JSON) is its own, not this one's. Don't dispatch, review, merge or write contracts here. Tell the person which session leads and what its step is. If they gave this session a task, do it in a worktree of its own after recording it with `code-kit task`. If they want this session to lead instead, they make it the lead.
50
52
  - **`wait`:** say which stories are being built and on which branches, and which ready stories wait for their lane (a lane runs one story at a time), 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.
51
53
  - **`done`:** give the `status` summary in a few lines, then offer to run spec-design for the next milestone or feature.
52
54
 
@@ -57,9 +59,11 @@ After a step finishes, run `next --json` again and carry on with the new step, w
57
59
  - a skill asks the person questions (spec-design's rounds, spec-check's blocking questions, review's scope questions);
58
60
  - something needs the person's approval (init's draft, an approval that's theirs: `requests --json` marks it `by: "person"`). What a lane asks for that's yours (`by: "lead"`) you decide with `/code-kit:decide`, without stopping. If the config has `approvals.lead`, ask for it in chat: when they approve in their own message, record it with the `code-kit approve` command the refusal names (their words as the reason) and carry on;
59
61
  - a person has to act: merge a pull request to a protected branch, add a CI secret;
60
- - the step is `wait` or `done`;
62
+ - the step is `wait`, `done` or `working`;
61
63
  - the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
62
64
 
65
+ **Under vibe** (`harness.autonomy` is `vibe`), you're the product owner too, and only the last two stop you. Answer spec-design's, spec-check's and review's questions yourself, from the brief, the specs and the principles, and record each in the brief's decision log with why. Every approval is yours (`by: "lead"`, with `--delegated`); merge and push as the queue says. What only the person can give (an account with a service provider, an API key or secret, a payment, an act outside the repository) you ask with `code-kit ask "…" --needs account|key|payment|outside`, and you build everything else meanwhile: behind the setting the key will fill, against a local or test stand-in, with the step to switch it on in the story's notes.
66
+
63
67
  **Ask the person through code-kit, not only in chat.** Anything you can't settle yourself and the person has to decide or do (a product choice, an account or key only they can create, wording or a design only they can sign off, whether to keep something private) goes to their band and the pane's Needs you, where it waits until they answer instead of scrolling away:
64
68
 
65
69
  ```
@@ -86,7 +86,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
86
86
  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
87
87
  ```
88
88
 
89
- 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. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one. In a team whose provider checks pushes for drift, a branch with an open finding at the level the provider's setting names waits in its place too, and the queue goes on with the next: `queue` and `next` say which finding and that the tech lead decides. It clears when the finding is resolved on the provider, or a push fixes what it found; never merge around it.
89
+ 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` or `vibe`, 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. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one. In a team whose provider checks pushes for drift, a branch with an open finding at the level the provider's setting names waits in its place too, and the queue goes on with the next: `queue` and `next` say which finding and that the tech lead decides. It clears when the finding is resolved on the provider, or a push fixes what it found; never merge around it.
90
90
 
91
91
  - **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:
92
92
 
@@ -96,6 +96,6 @@ Report the table, `verify`'s result, the security review's findings (or that non
96
96
 
97
97
  Dispatch the story again to a fresh agent with the list added to the brief (`/code-kit:dispatch`, which first releases the branch's worktree), never to the agent that built it: its context is already large. Set the story's status to `in progress`.
98
98
 
99
- - **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.
99
+ - **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. Under vibe it's yours: decide it, record it in the brief's decision log, and send the branch back or merge accordingly.
100
100
 
101
101
  Keep the report short: the verdict first, then the table, then the problems.
@@ -30,6 +30,8 @@ Say which one applies before you start.
30
30
 
31
31
  ## How to ask
32
32
 
33
+ **Under vibe** (`harness.autonomy` is `vibe` in `.claude/code-kit.json`, set once the first spec was done), you shape later milestones without the person. Ask each question below of yourself instead: answer it from the brief, the specs, the principles and what's built, take your recommended option, and write it in the brief's decision log as the lead's, with why. Ask the person only for what nobody else can give (`code-kit ask … --needs account|key|payment|outside`), and leave nothing open that you can decide.
34
+
33
35
  The questions are the skill. Ask well:
34
36
 
35
37
  - **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.
@@ -6,11 +6,14 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
6
6
  - the layer rules ({{layers}});
7
7
  - spec-check before lane code{{designGate}};
8
8
  - an audit log of every change to protected paths (`.claude/approval-log.jsonl`), which the person reviews in the pull request;
9
- - 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);
9
+ - {{if notVibe}}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);{{end}}
10
+ - {{if vibe}}an approval for every new dependency and every protected change, per lane. The person chose vibe: every decision is yours, the specs, the designs, CI, the kit, the standards, weakened tests, packages, merges and pushes included. A lane asks you, never the person. Decide each on its merits against the brief, the specs, the principles and the architecture, record why (the approval's reason, or the brief's decision log for a product choice), and carry on;{{end}}
10
11
  - {{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}}
11
12
  - the project's checks before any agent finishes.
12
13
 
13
- 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 band and the pane's Needs you, 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.
14
+ {{if notVibe}}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 band and the pane's Needs you, 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.{{end}}
15
+
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}}
14
17
 
15
18
  {{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}}
16
19