@warren-dean/code-kit 0.32.0 → 0.34.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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +21 -0
- package/README.md +51 -33
- package/bin/code-kit.mjs +62 -1
- package/hooks/guard-bash.mjs +98 -8
- package/hooks/lib/checkout.mjs +38 -3
- package/hooks/lib/config.mjs +43 -2
- package/hooks/lib/costs.mjs +217 -0
- package/hooks/lib/harness.mjs +15 -0
- package/hooks/lib/instructions.mjs +8 -2
- package/hooks/lib/next.mjs +45 -0
- package/hooks/lib/plan.mjs +8 -2
- package/hooks/lib/shell.mjs +52 -5
- package/hooks/lib/verify.mjs +28 -1
- package/hooks/mod/board.mjs +2 -0
- package/hooks/mod/loop.mjs +66 -3
- package/hooks/mod/register.mjs +202 -4
- package/hooks/mod/view.mjs +17 -1
- package/package.json +1 -1
- package/skills/decide/SKILL.md +1 -1
- package/skills/init/SKILL.md +2 -0
- package/skills/review/SKILL.md +1 -0
- package/skills/spec-design/SKILL.md +3 -0
- package/templates/agent.md +1 -0
- package/templates/claude-md.md +2 -0
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"name": "code-kit",
|
|
10
10
|
"source": "./",
|
|
11
11
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
12
|
-
"version": "0.
|
|
12
|
+
"version": "0.34.0",
|
|
13
13
|
"category": "development",
|
|
14
14
|
"tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
|
|
15
15
|
"license": "MIT"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.34.0",
|
|
4
4
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Warren Langeveldt"
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,27 @@
|
|
|
2
2
|
|
|
3
3
|
What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
|
|
4
4
|
|
|
5
|
+
## 0.34.0 (2026-11-08)
|
|
6
|
+
|
|
7
|
+
- **The loop no longer cuts into a conversation.** It prompted the lead as soon as each turn ended, so when you were talking with the lead about something else, the next step landed a minute after its answer to you. The reading of the lead's reply is now given what you said and tells a conversation from asking it to carry on; after a conversation, the loop waits until you've been quiet for `harness.loop.quietMinutes` (10 by default), and the band says so, with **Carry on**.
|
|
8
|
+
- **Each step is checked against the project before the lead gets it.** The loop kept prompting steps the lead had already explained: a merge whose verify was still running, instructions already brought up to date on the base, a story already under way. A story the lead said waits was held, but a merge or an instructions step wasn't, and anything you said to the lead let every step come back. Before each prompt, the loop now reads the project itself (the step's branches against the base, the merge queue, the agents at work, the latest commits and the lead's last replies) and a small model judges whether the step is still due. One that isn't waits in the band as a note with **Ask now**, and is checked again once the project moves. A step the lead said waits, or didn't take, is held the same way. `harness.loop.check` switches the check off. In auto mode a mod can't start an agent itself, so this is a side call, not a subagent.
|
|
9
|
+
|
|
10
|
+
- **code-kit's own records, then a commit.** `node "$CK" ask withdraw Q-3 --reason "…"`, `defer release`, `sent-back` or `queue add`, followed by a commit in the same command, was refused as a write the commit's checks can't see. These write only code-kit's state folder, which the project ignores, so they now pass when run by this code-kit's own CLI, by its path or through a variable the line sets to it. Any other code-kit command (one that writes instructions, merges or publishes), a script elsewhere with the same name, and a redirect into the checkout still count.
|
|
11
|
+
- **`git switch -qc <branch>`, then a commit.** A branch made with its flags combined was refused, though `git switch -q -c <branch>` passed. Both pass now.
|
|
12
|
+
- **A branch queued again after a batch failed no longer goes back to its lane.** When a batch fails verify in the merge queue, every branch in it is sent back, including those with nothing wrong. The lead queued those again at the same commits, yet `status` still read them as sent back, and `next` proposed dispatching lanes with nothing to fix whenever it wasn't the lead's turn to merge. A branch queued since its send-back, at that commit, now reads as passed and waits to merge. A branch that's sent back while it's in the queue stays sent back.
|
|
13
|
+
- **A branch merged after a send-back no longer asks for a dispatch.** A branch sent back, queued again and merged at the same commit still read as sent back until the plan said `done`, so the loop asked the lead to dispatch a story that was already on the base. A branch whose commits the base holds has nothing left to fix, and now reads as merged.
|
|
14
|
+
- **The loop says how to hold a story it keeps asking about.** A story the lead left because it waits on something outside the build (a run on a set day, say) was asked about again every half hour, as soon as other lanes committed. When a story comes up again with nothing it waits on having moved, the loop's prompt now adds that `code-kit defer` holds it, with a reason and an optional date, so the loop stops asking.
|
|
15
|
+
- **A lane's report, then its commit.** `cat >> .claude/state/reports/<branch>.md <<'EOF' … EOF`, followed by `git add … && git commit` in the same command, was refused as a write the commit's checks can't see, and lanes hit this often as they finished a story. The state folder is ignored, so no commit can take what goes there. A read or a heredoc redirected only into it now passes, as long as the project's `.gitignore` covers the folder.
|
|
16
|
+
- **Instructions from a newer code-kit are left alone.** When a teammate had updated code-kit and committed its instructions, a session on an older plugin read them as out of date. Its loop kept asking it to run `instructions --write`, which would have put the older rules back. From this release, `instructions` reads them as ahead, `--write` leaves them, and `next` says to update the plugin and restart instead. The instructions' version is now raised whenever they change, so this works between releases; existing projects will be asked once to bring theirs up to date. A session still on an older release keeps the old behaviour until it updates.
|
|
17
|
+
- **Reading the approval log beside a variable of your own.** `CK=…/code-kit.mjs; node "$CK" status; tail -3 .claude/approval-log.jsonl` was refused, because any variable set in the line made the whole line count as a possible write. A variable now counts only if a command could read it: `PATH`, `HOME`, `GIT_*` and the like, or one already exported.
|
|
18
|
+
- **The merge queue no longer fails every branch when the OS empties its kept installs.** The queue's kept checkout lives in the temporary folder, and macOS removes old files there while leaving the folders and links. The installs looked present, so checks failed with missing modules and each queued branch was sent back to its lane. Each merge now counts the kept installs' files. If any have gone, it copies them again and runs the project's install over the copy.
|
|
19
|
+
|
|
20
|
+
## 0.33.0 (2026-11-06)
|
|
21
|
+
|
|
22
|
+
- **A running budget.** Projects were being designed on each provider's production defaults, with nothing adding up what they'd cost a month. spec-design now asks how much a month each environment may cost, in your currency, and the load to plan for; init writes it to `cost` in the config, with the project's infrastructure files. spec-design costs each architecture it proposes against it and, when your preferred one doesn't fit, offers options that do, each with what it gives up. The costs go in `docs/costs.md`, a row per paid thing with where its price came from, and `code-kit cost` adds them up against the budget. A branch that changes the infrastructure has to change the register (verify), lanes may write it, and a commit that takes an environment past its budget waits for your `cost` approval, which the lead can't give, under vibe either. `next` asks a project with infrastructure and no budget for one. It works for any provider: code-kit holds no prices, and the lead cites where each came from. Reading real spend from an account comes later.
|
|
23
|
+
- **A branch made where the checkout stands, then a commit.** `git checkout -b <branch> main && git add … && git commit …`, run with the checkout already at main, was refused as a command that may write files the commit can't see, because the branch named a start point. A start point that is the commit the checkout is at changes no file, so it now passes like a branch made with no start point. One at any other commit is still refused.
|
|
24
|
+
- **Reverting a commit that logged approvals.** A `git revert` of a merge, or of any commit that appended to `.claude/approval-log.jsonl`, takes those entries back out with the rest, so verify failed the branch as an edited log, and no shell command was allowed to put the log back: the only way out was to make the branch again by hand. A command that doesn't commit may now put the log back as the last commit has it (`git restore --staged --worktree .claude/approval-log.jsonl`, or `git checkout HEAD -- …`), which can lose only what isn't committed. Verify's problem now says what took the entries out and how to make the revert again: `git revert --no-commit <commit>`, then that restore, then commit. A restore from any other commit, or in the same command as a commit, is still refused, since the commit hook appends before the command runs.
|
|
25
|
+
|
|
5
26
|
## 0.32.0 (2026-11-06)
|
|
6
27
|
|
|
7
28
|
- **Writes outside the checkout before a commit.** Drafting a commit message in a scratchpad and committing it in one command (`git log -1 --format=%B > /tmp/msg && sed -i '' 's/…/…/' /tmp/msg && git commit --amend -F /tmp/msg`) was refused as a command that may write files the commit can't see. A read whose output goes only to full paths outside the project and the commit's checkout, and sed's substitutions on such files in place, can't change what's committed, so they're allowed. A path from a variable, a link back into the project, a sed that writes a file or runs a command, and any write into the checkout are still refused.
|
package/README.md
CHANGED
|
@@ -52,7 +52,8 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
|
|
|
52
52
|
|
|
53
53
|
- **Lanes:** each lane agent writes only its own paths. The main session (the lead) writes contracts, specs and config, and delegates the rest. Any other subagent is read-only. An edit outside those paths is refused before it happens; a file a shell command writes outside them is reported straight after, for the agent to revert, and the finish check refuses to finish until it's gone.
|
|
54
54
|
- **Layers:** each layer depends only on the layers it lists, and never on packages it's denied, for JavaScript and TypeScript imports. An edit that would add a violation is refused before it's written; the rules are checked again after each edit and before finishing, which is what catches a file a shell command wrote. In brownfield code, existing violations can be recorded in a baseline so only new ones block. Imports are found by pattern, not by parsing: see [the limits](#what-verify-proves-and-its-limits).
|
|
55
|
-
- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Only the lead writes these paths without an approval, and the person reviews them in the pull request. A lane needs an approval: the lead's for what `approvals.delegate` gives it, otherwise the person's.
|
|
55
|
+
- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Nobody edits the log: a shell command may only read it, or put it back as the last commit has it (`git restore --staged --worktree .claude/approval-log.jsonl`, in a command that doesn't commit), as after a `git revert --no-commit` took a reverted commit's entries out. Only the lead writes these paths without an approval, and the person reviews them in the pull request. A lane needs an approval: the lead's for what `approvals.delegate` gives it, otherwise the person's.
|
|
56
|
+
- **A running budget** (spec 29): the person sets how much a month each environment may cost, and `docs/costs.md` estimates each paid thing against it. A commit that takes an environment past its budget waits for the person's `cost` approval, whatever is delegated; before asking, the lead finds options that fit.
|
|
56
57
|
- **Spec-check before code:** when the project has specs, a lane can't write code on a branch until it has saved a spec-check report for that branch. The hook checks that the report exists; review checks what it says.
|
|
57
58
|
- **Designs before screens** (optional): a screen file can't be written until the design register holds its approved design as files, every state exported from the design tool; the review records its screenshot of each built state beside the design, and verify checks it did.
|
|
58
59
|
- **Shell rules**, matched against the command's text before it runs:
|
|
@@ -75,6 +76,7 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
|
|
|
75
76
|
- no screens without an approved design;
|
|
76
77
|
- no secret files (`.env`, `secrets/`, keys and keystores) anywhere in the branch's history, including ones committed and deleted again, and, where gitleaks is installed, no secrets in any commit's content;
|
|
77
78
|
- no test weakened (deleted, skipped or focused, cut down, or its snapshot rewritten) without the person's `tests` approval in the log;
|
|
79
|
+
- with a running budget, a branch that changes the infrastructure files changes the cost register too, and one that takes an environment past its budget has the person's `cost` approval in the log;
|
|
78
80
|
- a fix (a plan story with `**Fixes:**`, or a `<lane>/fix-…` branch) comes with a test that fails without it, as the bug, and passes with it;
|
|
79
81
|
- the project's checks pass.
|
|
80
82
|
|
|
@@ -334,8 +336,10 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
|
|
|
334
336
|
|
|
335
337
|
- **Each step.** Once the lead has finished a turn, with the lead idle and nothing typed in the prompt, the loop asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own. It never prompts the same step twice while nothing has changed, and never a story an agent is still on: one its lane agent is building, or a reviewer is reviewing, waits until that agent finishes ("waiting: ST-10 is still with its agent").
|
|
336
338
|
- **It reads the lead's reply first.** Before prompting again, the loop reads the lead's last reply with a side call over the lead's own conversation. A reply that waits on you (a question, a design to look at, an approval), or a turn you stopped, holds the loop until you answer or speak to the lead: the band says what the lead waits on, and the Decide pane answers it. A step the lead didn't take shows in the band as a note, with its reason and **Ask again**.
|
|
337
|
-
- **Stories waiting on other work.** When the lead says a story isn't due yet because it waits on work still going (a paired story a lane is building, a rebuild, a check running), the loop parks that story and leaves it out of every step, so a step naming it with others prompts only the others. It wakes when its own branch or state moves, or when a story it waits on (one the lead named, or an unfinished one building on it) changes state; that story's commits along the way don't wake it, nor do other lanes'. A story the lead's turn left exactly where it stood is parked too, whatever the reply said. After 30 minutes with nothing moving, the lead is asked once more.
|
|
339
|
+
- **Stories waiting on other work.** When the lead says a story isn't due yet because it waits on work still going (a paired story a lane is building, a rebuild, a check running), the loop parks that story and leaves it out of every step, so a step naming it with others prompts only the others. It wakes when its own branch or state moves, or when a story it waits on (one the lead named, or an unfinished one building on it) changes state; that story's commits along the way don't wake it, nor do other lanes'. A story the lead's turn left exactly where it stood is parked too, whatever the reply said. After 30 minutes with nothing moving, the lead is asked once more, and told that `code-kit defer` holds a story that waits on a date or on something outside the build.
|
|
338
340
|
- **Holding on purpose.** A story the lead means to leave alone for a while (it waits on something outside the build, or on a date) is held with `code-kit defer <story> --reason "…" [--until <date>]`: `next`, the loop and the merge queue don't dispatch, review or merge it until then, or until `code-kit defer release <story>`, and it isn't asked about again in the meantime. `code-kit queue pause --reason "…"` holds the whole merge queue the same way, until `code-kit queue resume`. `next` lists each hold with its reason, and the band shows them as notes.
|
|
341
|
+
- **It doesn't cut into a conversation.** When you talk with the lead about something other than the build (a question, a discussion, another task), the loop waits until you've been quiet for `harness.loop.quietMinutes` (10) before it prompts again; the band says so, with **Carry on**. Asking the lead to carry on with the build holds nothing.
|
|
342
|
+
- **Each step is checked first.** code-kit's records can lag the work, so before it prompts the lead the loop reads the project itself (the step's branches against the base, the merge queue, the agents at work, the latest commits and the lead's last replies) and a small model judges whether the step is still due. One that isn't (merged already, under way, or one the lead said why it won't take, with nothing changed since) is held as a note with **Ask now**, and checked again once the project moves. A step the lead said waits, or didn't take, is held the same way, so speaking to the lead doesn't bring it back. `harness.loop.check` switches the check off.
|
|
339
343
|
- **A step that doesn't move.** One the lead was prompted with three times in a row that is still next shows as a note, not a decision: "Merge lead/st-1: still next after 3 prompts to the lead", with **Ask again** if you want it.
|
|
340
344
|
- **A lean lead.** A lane writes its full report, with its commands and their output, to `.claude/state/reports/<branch>.md`, and hands the lead a few lines naming it; the stop hook won't let a lane on a story branch finish without it, or with a hand-back of more than ten lines, and the lead reads the file when it reviews. Lanes don't message the lead while they work. When a milestone finishes, the lead's context is compacted before the next one (`harness.compact.milestone`: you're asked by default, or it's done at once): the summary keeps what's in flight and what waits on you, and drops the finished stories' detail.
|
|
341
345
|
- **Token use.** A long-lived agent rereads its whole context on every request, which is most of what a build costs. So each lane agent builds one story; one past `agents.lanes.contextLimit` is told to wrap up, and the lead carries its story on with a fresh agent that reads its report (`code-kit worktrees release` frees the branch). The lead's context is compacted between turns once it's past `compact.at`. The loop reads the lead's replies with Sonnet, and the reviewers run on Sonnet by default.
|
|
@@ -424,6 +428,17 @@ For several people in one repository, each with their own agents. Not every deve
|
|
|
424
428
|
|
|
425
429
|
It's a preview: it's tested end to end against a stand-in for GitHub, and has been run once against a real private repository (claims, leases, intents as discussions, decision records, since-you-last-looked and the Project board). Spec: `docs/specs/16-teams.md`.
|
|
426
430
|
|
|
431
|
+
## What it costs to run
|
|
432
|
+
|
|
433
|
+
Spec 29. A build that nobody costs ends up on each provider's production defaults: a managed database with a standby, a NAT gateway per zone, containers that never stop. So the running cost is a guardrail, set once and checked as the work lands, for whatever providers the project uses.
|
|
434
|
+
|
|
435
|
+
- **The budget.** spec-design asks for it with the other constraints: how much a month each environment may cost, in the person's currency, and the load to plan for. 0 means free tiers only. init writes it to `cost` in the config, with the project's infrastructure files as `cost.paths`.
|
|
436
|
+
- **The register.** `docs/costs.md` has one table, `| Item | Provider | Environment | Size | Monthly | Basis |`: a row per paid thing, its monthly estimate as a number, and where the price came from, with the date. An `all` row counts in every environment. code-kit holds no price list: the lead estimates from each provider's published pricing, and `code-kit cost` adds it up and names a price older than 90 days.
|
|
437
|
+
- **The design fits first.** spec-design costs each architecture it proposes, and when the one the person prefers doesn't fit, it says by how much and offers options that do (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.
|
|
438
|
+
- **Each change is costed.** Any agent may write the register: a lane changes its row when its story adds or resizes something paid, and `verify` fails a branch that changes `cost.paths` without it. The review checks the sizes in the code against the rows.
|
|
439
|
+
- **Over the budget is the person's.** A commit that takes an environment past its budget, or further past it, is refused until the person approves `cost` (the lead can't, under vibe either); the log records the totals it allowed. A lane takes it to the lead, and the lead to the person with the options that fit and the cost of the one that doesn't.
|
|
440
|
+
- **Existing projects.** `next` names a project with infrastructure and no budget, and init's next run asks for one; the lead then costs what's built.
|
|
441
|
+
|
|
427
442
|
## Enforce it in CI
|
|
428
443
|
|
|
429
444
|
The hooks only see Claude Code sessions. For everything else, init offers `.github/workflows/code-kit.yml` (from `templates/github-workflow.yml`). It runs `verify --no-checks` on every pull request, through `npx @warren-dean/code-kit@<version>`, pinned so CI doesn't change under you: the rules, in seconds, with a 10-minute limit, and a new push cancels the run it replaces. The project's checks aren't run again there, because the merge queue ran them before each merge; the project's full CI runs on its release branches instead, once per release (`code-kit release <version>` cuts one). `code-kit ci check` says what in the project's own workflows still runs once per story, and `code-kit ci usage` what the project spent. The workflow needs no secret. Mark the `code-kit` check as required on the protected branches, and keep its install step: a fix story's test is run without its fix (REG-1). Add gitleaks to the workflow for the secret scan of commits' content.
|
|
@@ -482,6 +497,7 @@ code-kit sent-back <branch> [--reason "…"] # record a revie
|
|
|
482
497
|
code-kit ci check [--json] # what in the project's workflows runs once per story, or without a time limit, and the fix
|
|
483
498
|
code-kit ci usage [--days N] [--json] # the project's GitHub Actions runs and minutes, by workflow and trigger
|
|
484
499
|
code-kit release <version> # cut release/<version> from the base and push it: the project's full CI runs there once
|
|
500
|
+
code-kit cost [--json] # each environment's estimated running cost against its budget, the register's problems and the prices to recheck
|
|
485
501
|
code-kit decisions [--json] [--all] # what waits on you in this session, and a count in each other one; --all lists every session's
|
|
486
502
|
code-kit who # which session this is, whether it leads the project, and its task
|
|
487
503
|
code-kit sessions [--json] # the sessions working the project, which one leads, and each one's task
|
|
@@ -531,36 +547,38 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
|
|
|
531
547
|
|
|
532
548
|
`.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
|
|
533
549
|
|
|
534
|
-
| Field | Required | What it is
|
|
535
|
-
| ------------------------------ | ----------------- |
|
|
536
|
-
| `version` | yes | `1`
|
|
537
|
-
| `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch
|
|
538
|
-
| `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan
|
|
539
|
-
| `docs.
|
|
540
|
-
| `docs.
|
|
541
|
-
| `
|
|
542
|
-
| `lead.
|
|
543
|
-
| `
|
|
544
|
-
| `
|
|
545
|
-
| `
|
|
546
|
-
| `
|
|
547
|
-
| `
|
|
548
|
-
| `
|
|
549
|
-
| `
|
|
550
|
-
| `shell.
|
|
551
|
-
| `
|
|
552
|
-
| `
|
|
553
|
-
| `
|
|
554
|
-
| `
|
|
555
|
-
| `
|
|
556
|
-
| `
|
|
557
|
-
| `approvals.
|
|
558
|
-
| `
|
|
559
|
-
| `
|
|
560
|
-
| `
|
|
561
|
-
| `
|
|
562
|
-
| `
|
|
563
|
-
| `
|
|
550
|
+
| Field | Required | What it is |
|
|
551
|
+
| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
552
|
+
| `version` | yes | `1` |
|
|
553
|
+
| `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
|
|
554
|
+
| `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
|
|
555
|
+
| `docs.costs` | no | The cost register (spec 29), default `docs/costs.md`: one table, `\| Item \| Provider \| Environment \| Size \| Monthly \| Basis \|`, a row per paid thing with its monthly estimate as a number and where the price came from, dated. Any agent may write it once `cost` is set |
|
|
556
|
+
| `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
|
|
557
|
+
| `docs.standards` | no | The project's standards (spec 22), default `docs/standards.md`: each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why`, `source` and, when enforced, `enforced by` naming the layer rule, protected path, check or shell rule that refuses a breach. The id's prefix is its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Each lane agent is given the ones for its layers; a refusal from an enforcing rule names the standard; reviews check the checked ones. Protect the file with the `standards` approval: removing a standard, or weakening a required one, always needs the person's, whatever is delegated |
|
|
558
|
+
| `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
|
|
559
|
+
| `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory is always included, and the session's own folder in Claude Code's temporary folder (`/tmp/claude-<uid>/<project>/<session id>/`: its scratchpad and tool output), which the lanes may write too; another session's isn't. |
|
|
560
|
+
| `anyActor` | no | Paths every writer may change (e.g. the lockfile), read-only agents included. `.claude/state/**` is always included. An entry may be `{ "glob", "reviewer" }` to name the lane (or `"lead"`) that reviews changes to it; otherwise the lead reviews them, and `who` and `trace` say so. |
|
|
561
|
+
| `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners?, label? }`: the agent name maps a subagent to its lane; `label` names what the lane delivers ("Screens", "API contract"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the lane's name; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane. |
|
|
562
|
+
| `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs an approval: the lead's where `approvals.delegate.protected` names it, otherwise a person's (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`. |
|
|
563
|
+
| `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) holds their exported designs; an entry naming only a design tool's artboard doesn't open the gate. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
|
|
564
|
+
| `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label? }`: the first layer whose paths match a file owns it. A layer may always import itself. `label` names what the layer delivers ("Data", "Service"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the layer's name. |
|
|
565
|
+
| `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
|
|
566
|
+
| `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs (after a package runner such as `npx` or `pnpm exec`, and inside `sh -c` or `eval`), with quoted text masked unless the pattern has quotes, so a grep, a heredoc or a message that mentions it isn't refused. Without it the pattern reads the whole line, except a read's quoted arguments: `grep "<command>" docs` doesn't run it |
|
|
567
|
+
| `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes. A read's quoted arguments don't count, as for `shell.block` |
|
|
568
|
+
| `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
|
|
569
|
+
| `tests[]` | no | Globs naming the test files, in place of the conventions, for every rule that asks what a test is: weakened tests, a fix's tests, the tests that name a requirement, the code map and the security review. Default: a file named as a test (`*.test.*`, `*.spec.*`, `*.smoke.*`, `test_*.py`, `*_test.go`, `*_test.py`) or in a test folder (`test/`, `tests/`, `__tests__/`, `e2e/`, `smoke/`). Proving a fix keeps the files named as tests and takes the rest back, test-folder helpers included; with `tests` set, the files it names are the ones kept. |
|
|
570
|
+
| `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. The checkout's `node_modules` and virtualenvs are copied in first (a copy-on-write clone where the disk has one), so it can't change the checkout's own. The merge queue runs it too, in the merged tree's checkout, when its manifests or lockfiles differ from the installs copied in; without it, the queue runs the install the lockfile calls for. |
|
|
571
|
+
| `checks[]` | no | `{ name, files, exclude?, run[], each?, owners?, ifMissing?, timeoutSeconds? }`: before finishing, when matching files changed. `each` runs the commands in every changed folder matching that glob. `owners` limits who may change the files (the lead always may). `ifMissing: "fail"` makes a missing tool an error (the default is to skip the check, which `verify` and a merge list as not run). `timeoutSeconds` (240 unless set) is how long each command may run; one that runs out of time leaves its branch at the head of the merge queue rather than sending it back. |
|
|
572
|
+
| `adapters` | no | `{ "<adapter>": false }` switches off an adapter that would otherwise be detected; `true` says the project wants that tool, so until it's set up here `next` gives its setup before any code. See [Adapters](#adapters). |
|
|
573
|
+
| `approvals.lead` | no | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals). |
|
|
574
|
+
| `approvals.delegate` | no | `false`, or `{ protected?: [approval names], merge?: true, push?: true, tests?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`; with `push`, pushes the protected branch, never by force (yours unless you set it, since a push can deploy; read from the config committed on that branch); with `tests`, weakened tests on a lane's branch. Left out, the lead decides everything technical: every protected approval but `spec`, `design`, `ci` and `kit`, packages, merges and weakened tests (WHO-1); `false` keeps everything for you. Lanes ask the lead for these, never you. npm packages are also checked against the npm registry, and a Python lane's against PyPI; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals). |
|
|
575
|
+
| `setup` | no | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it |
|
|
576
|
+
| `cost` | no | The running budget (spec 29): `{ currency, monthly, load?, paths? }`. `currency` is a three-letter code (USD, AUD, EUR); `monthly` maps each environment (`prod`, `dev`, …, not `all`) to what it may cost a month; `load` says in words what the budget plans for; `paths` are the infrastructure files, whatever defines them, and a branch that changes one changes the register too. A commit that takes an environment past its budget needs the person's `cost` approval, whatever is delegated |
|
|
577
|
+
| `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, the specs' titles and outcome lines, approvals, token use, the rules, the design register and the sessions at work; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
|
|
578
|
+
| `branches.protected` | no | Default `["main", "master"]` |
|
|
579
|
+
| `branches.publish` | no | How a merge reaches the remote's base: `push` (the base is pushed, fast-forward only) or `pull-request` (for a base the remote only lets change through pull requests: code-kit opens one from `code-kit/publish-<base>` after each merge, and merges it where `approvals.delegate.push` is on, otherwise it waits for you). Left out, code-kit leaves pushing the base to you |
|
|
580
|
+
| `execution.unrepeatable` | no | Patterns (regular expressions) for commands that can't safely run twice, such as a seed or a deploy. With migrations, the commands `shell.block` and `shell.restricted` name, and `git push`, an interrupted one is never run again on its own after a crash: the lead finds out what happened first (spec 26) |
|
|
581
|
+
| `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose`, `off` or `vibe`; default `autonomous`; `vibe` is autonomous with every decision the lead's, see [Vibe](#vibe)), `loop.quietMinutes` (while you talk with the lead about something else, how long the loop waits after you last spoke, 0 to 120; default 10), `loop.check` (check each step against the project before the lead is prompted with it; default `true`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (code-kit's reviewer and the security reviewer; default `sonnet`), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one: a model, or `story` for each story's `**Size:**` in the plan, raised for security requirements, fixes and send-backs; default the session's), `slices.open` (how many of the plan's slices are in focus: a free lane builds an open slice's stories first; default 1), `background.pauseAtPercent` (default 80), `compact.at` (compact the lead's context between turns once it's past this share of its window; default 40, 0 for never), `compact.milestone` (when a milestone finishes, compact the lead's context: `ask`, `auto` or `off`; default `ask`), `agents.lanes.contextLimit` (the context a lane agent may reach before it hands its story to a fresh agent; default 250,000 tokens), `notify.on` (a system notification when something new needs you; default `true`), `motion` (whether the pane's characters, clocks and the lead's rail move while work flows: `while-active` or `off`; default `while-active`) and `report.on` (agents draft bug reports for code-kit, which you send or discard; default `false`). Change them with `/harness` or `code-kit settings set`. |
|
|
564
582
|
|
|
565
583
|
Add `.claude/approvals/`, `.claude/state/` and `.claude/code-kit.draft.json` to `.gitignore`, and `.claude/approval-log.jsonl merge=union` to `.gitattributes`, so merging branches that both logged changes keeps every entry. Commit `.claude/code-kit.baseline.json` if the project has one.
|
|
566
584
|
|
|
@@ -622,7 +640,7 @@ code-kit approve pillow --lane api --delegated --story ST-138 --reason "MED-5 ne
|
|
|
622
640
|
- **Who:** only the lead. With `"approvals": { "delegate": false }`, `--delegated` is refused, and every approval is yours.
|
|
623
641
|
- **Weakened tests:** with `"tests": true` (the default), the lead approves a weakened test on a lane's branch for the story it reviewed, with `--lane` and `--story`; on its own branches it's yours.
|
|
624
642
|
- **Merges:** with `"merge": true`, the lead merges a reviewed branch into a protected branch with `code-kit merge <branch> --delegated`.
|
|
625
|
-
- It runs `code-kit verify` on the branch first, checks included, and merges only if it passes. The checks run on the branch merged with the base, in code-kit's own checkout of the project, kept between merges with its installs (`node_modules`, virtualenvs), copied in from the base's checkout the first time. Keeping it means a merge doesn't copy millions of files in and delete them again each time, which keeps macOS's file-change tracking and Spotlight busy; it lives in the temporary folder under `code-kit-checkouts.noindex`, which Spotlight skips. Where the merged tree's manifests or lockfiles differ from them, the install runs in that checkout first: `regression.prepare` if set, else the one its lockfile calls for (pnpm, npm, yarn, bun, uv). An install that fails there keeps the branch in its place in the queue; where code-kit knows no install, the merge says the installs it used may not match. A branch the base already holds is merged already: it leaves the queue as merged, never verified again.
|
|
643
|
+
- It runs `code-kit verify` on the branch first, checks included, and merges only if it passes. The checks run on the branch merged with the base, in code-kit's own checkout of the project, kept between merges with its installs (`node_modules`, virtualenvs), copied in from the base's checkout the first time. Keeping it means a merge doesn't copy millions of files in and delete them again each time, which keeps macOS's file-change tracking and Spotlight busy; it lives in the temporary folder under `code-kit-checkouts.noindex`, which Spotlight skips. The OS empties old files out of that folder, so each merge counts the kept installs' files. If any have gone, it copies them again and runs the install over the copy. Where the merged tree's manifests or lockfiles differ from them, the install runs in that checkout first: `regression.prepare` if set, else the one its lockfile calls for (pnpm, npm, yarn, bun, uv). An install that fails there keeps the branch in its place in the queue; where code-kit knows no install, the merge says the installs it used may not match. A branch the base already holds is merged already: it leaves the queue as merged, never verified again.
|
|
626
644
|
- Only uncommitted changes to files the merge changes stop it, in the base's checkout; it checks before the verify and again after. Other changes there, such as a log another tool appends to each turn, are carried as they are.
|
|
627
645
|
- Run from inside the lane's worktree, the merge keeps that worktree (the shell is in it); it goes at the next merge.
|
|
628
646
|
- The merge commit says it was verified and delegated.
|