@warren-dean/code-kit 0.37.0 → 0.38.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.
@@ -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.37.0",
12
+ "version": "0.38.1",
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.37.0",
3
+ "version": "0.38.1",
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,20 @@
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.38.1 (2026-11-16)
6
+
7
+ - **Shared lists found from the history.** In a project built as streams, `code-kit next` now tells the platform's lead (or the lead in the main checkout) when a core file looks like a shared list: three stories of two or more streams changed it only by adding lines. It names the stories and gives the `anyActor` entry to propose to you, so a project set up before shared lists existed finds its own without re-running init.
8
+
9
+ ## 0.38.0 (2026-11-16)
10
+
11
+ - **Any stream's lead merges the queue.** In a project built as streams only the lead in the main checkout was given the merge step, so every stream's reviewed branches waited on that one session, while it worked on its own stream's stories: branches waited three to twelve hours, and dozens stood in the queue. Now another stream's lead merges the queue's head whenever its own stream has only waiting to do. One merge still runs at a time: a lock stops two leads starting one at once.
12
+ - **A failed group sends back only the branch at fault.** When branches queued to merge together failed, every one went back to its lane, though most had nothing wrong, and each needed reviewing and queueing again. Now a member that doesn't merge onto the base, or breaks its own lane's rules, goes back alone, and its partners keep their places and their reviews. Only a failure of the merged tree's checks, which can't be pinned on one member, sends the group back together.
13
+ - **Shared lists in core.** In a project built as streams, a stream's story that needed one more line in a core file every stream adds to (an allow-list of routes, a catalogue of lines) had to ask core for it, and wait for a core story, a core lane and a merge together. Name such a file a shared list (`anyActor` with `"adds": true`): any lane adds its entries in its own branch, and changing or removing an entry already there stays the owner's, refused as the edit is made and by `verify`.
14
+ - **Fewer, real candidates for core.** The check for code that belongs in core raised a candidate for every run of 60 tokens alike, tests included, and one per function a pair of files shared, so a platform lead could face over a thousand to decide. Now tests are left out, a clone takes 100 tokens alike by default, a pair of files is one candidate, a whole-project `promote scan` withdraws open clones it no longer finds, and module code that repeats core's is its own stream's lead's to decide.
15
+ - **A fix check that couldn't run no longer sends its branch back.** The fresh checkout a fix's tests run in copied installs only when it had none, so one holding a virtualenv but no `node_modules` ran the web checks without their tools, and the merge queue sent good branches back. It now copies each install it lacks, runs the project's install where its lockfiles differ, as the merge's checkout does, and a check that couldn't run (a tool not installed, an install that failed, a run out of time) leaves the branch in its place.
16
+ - **A stream's lead keeps its worktree after its branch merges.** Merging a stream's `lead/<stream>` branch took away that lead's own worktree, as a finished lane's is, and its shell stopped working. It stays now.
17
+ - **`defer` finds a story a stream's lead added in its own worktree.** It read only the main checkout's plan, where the story arrives when the lead's branch merges, so it answered that there was no such story.
18
+
5
19
  ## 0.37.0 (2026-11-15)
6
20
 
7
21
  - **The README covers every feature: what it does, how to use it and why.** It was checked against every spec and the code. Added: why streams exist and how to turn them on in a project that started as one, the usage-limit wait, branches merged together, standards, the QA lane, design hand-over, the plan's extra story lines, what a fix's test must show, teams when GitHub can't be reached, vibe's how and why, and every hook. The settings' Approvals section is in `/harness`; there's no Settings tab.
package/README.md CHANGED
@@ -361,7 +361,7 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
361
361
  - **The Decide pane.** Nothing pops up over the conversation: a decision waits in the band and Needs you, with a notification, until you open it with **d**, its line in Needs you, or `/lanes decide`. The Decide pane sits beside the conversation and shows one decision at a time, all of it: the whole question, why it's yours, the story and requirements, what was happening, and each option on its number with what it does. A question that takes your own words has a box for them, and an **Ask about it** box first. **n** and **p** move between decisions; each stays in view as others come and go.
362
362
  - **Stalled lanes.** A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue). At `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times; after that the lead decides how the story goes on (a narrower brief, smaller stories, or handing it back), and the band shows a note.
363
363
  - **The reviewer agent**, with `harness.agents.reviewer.on`: a second, independent read of each finished branch, so the lead isn't the only one checking its own lanes' work, without holding the lead up. A finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it.
364
- - **The merge queue** (`code-kit queue`). A branch the lead's review passes joins the queue. Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. The queue records the commit each review passed, and merges exactly that commit: a branch that moves on after its review leaves the queue (`moved`) for the lead to review it again. A head that conflicts or fails verify goes back to its lane. A merged lane's worktree is removed when it holds nothing uncommitted. Where `branches.publish` is set, each merge then reaches the remote's base: pushed, or, where the remote only takes pull requests, as one code-kit opens and (where you delegate pushing) merges. A story's branch merges only into the base, through the queue: an agent's `git merge` of it into any other branch (an integration branch such as `lead/next`) is refused, since the story would look unmerged and its worktree would never be cleaned up. The pane lists the queue, and lanes whose branch waits in it read `queued`. Some branches break the base when merged alone, such as a new API and the change that updates its callers: the lead queues them together with `code-kit queue add <branch> --with <branch>`, and the group waits until every member has passed review, is verified as one tree, and merges, or goes back to its lanes, together.
364
+ - **The merge queue** (`code-kit queue`). A branch the lead's review passes joins the queue. Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. The queue records the commit each review passed, and merges exactly that commit: a branch that moves on after its review leaves the queue (`moved`) for the lead to review it again. A head that conflicts or fails verify goes back to its lane. A merged lane's worktree is removed when it holds nothing uncommitted. Where `branches.publish` is set, each merge then reaches the remote's base: pushed, or, where the remote only takes pull requests, as one code-kit opens and (where you delegate pushing) merges. A story's branch merges only into the base, through the queue: an agent's `git merge` of it into any other branch (an integration branch such as `lead/next`) is refused, since the story would look unmerged and its worktree would never be cleaned up. The pane lists the queue, and lanes whose branch waits in it read `queued`. Some branches break the base when merged alone, such as a new API and the change that updates its callers: the lead queues them together with `code-kit queue add <branch> --with <branch>`, and the group waits until every member has passed review, is verified as one tree, and merges together. When a group fails, what's down to one member (it doesn't merge onto the base, or breaks its own lane's rules) sends that member back alone, and its partners keep their places and their reviews until its fix rejoins; only a failure of the merged tree's checks sends the whole group back, since nothing says which member caused it. A check that couldn't run (its tool isn't installed, an install failed, a run ran out of time) says nothing against a branch, so the branch keeps its place. One merge runs at a time, whichever session starts it.
365
365
  - **After a crash.** Every agent's tool calls are recorded before and after they run, per story, in `.claude/state/events/` (paths, commands, results and commits; never file contents or prompts, and never sent anywhere). When a session or an agent stops mid-story, `next` checks each call left open against git before it chooses any work: a commit or a merge that happened is recorded as done, an edit or a test can simply run again, and a command that can't safely run twice and that git can't settle (a migration, a deploy) goes to the lead to find out, never run again on its own. The fresh agent that carries the story on is briefed from the log (`code-kit replay <story> --brief`), even when the stopped one wrote no report, and lanes commit after each step whose tests pass, so a crash loses at most one step. A merged story's log goes 30 days after it merges.
366
366
  - **The first merge.** There's none for you: setting up commits the rules you approved straight onto the base, and in a project set up before that, the lead puts them there itself (`code-kit queue rules`) before its first merge.
367
367
 
@@ -438,9 +438,10 @@ One product in one repository can have separate product lines (offerings for dif
438
438
  - **A lead per stream.** Each stream has its own lead session, plan file, specs and lanes, and they lead at once: type `/code-kit:lead <stream>` in the session that should lead it. Each lead's loop and `code-kit next` give it only its own stream's stories, and it writes only its own stream's plan and specs. The first lead works in the main checkout, the others in a worktree each, on `lead/<stream>`.
439
439
  - **Streams kept apart.** A layer with `stream` is that stream's module; one without is core. A module may import core and its own stream's modules, never another stream's, and core never imports a module: the hooks refuse both, and the refusal says to ask for it in core rather than copy it.
440
440
  - **Core has one owner.** A stream with `platform: true` owns core's lanes: the other streams ask it for changes with `code-kit core ask "<what>" --story ST-n`, and their story waits on its decision. Without a platform stream, core's lanes are in no stream, and the streams take them in turns.
441
- - **Shared capability noticed.** code-kit raises a candidate for core when it sees the same code in two streams' modules (names aside), an import of another stream's module refused, a copy into a module, module code that repeats core, or a requirement another stream's spec already has. `code-kit promote` lists them; the platform's lead decides each (`/code-kit:promote`), and a promotion is a platform story. Set `harness.promote.coreClones` to `refuse` and verify refuses a branch whose module code repeats core's.
441
+ - **Shared lists take additions from any stream.** Some core files are lists every stream's stories add to: an allow-list of routes, a catalogue of strings, a registry. Asking core for each new entry costs a core story, a core lane and a merge together for one line, and holds the stream's story meanwhile. Name such a file a shared list in `anyActor`, with `"adds": true` and its owner as reviewer: `{ "glob": "src/core/routes.ts", "reviewer": "api-core", "adds": true }`. Any lane then adds its entries in its own branch. Changing or removing an entry already there is still the owner's: the edit is refused as it's made, and `verify` refuses a branch that does it, saying to ask core. You don't have to find these files yourself: when three stories from two or more streams have only added lines to a core file, `code-kit next` tells the platform's lead (or the lead in the main checkout) that it looks like a shared list, with the entry to add. Adding it is a config change, so the lead proposes it to you.
442
+ - **Shared capability noticed.** code-kit raises a candidate for core when it sees the same code in two streams' modules (names aside), an import of another stream's module refused, a copy into a module, module code that repeats core, or a requirement another stream's spec already has. `code-kit promote` lists them; the platform's lead decides each (`/code-kit:promote`), and a promotion is a platform story. Module code that repeats core's is its own stream's lead's to decide, since switching to core's is the module's work. To keep the list to what's worth a lead's time, a clone is one candidate per pair of files, tests are left out (they repeat their setup by nature), it takes 100 tokens alike by default (`harness.promote.tokens`), and a scan of the whole project (`code-kit promote scan`) withdraws open clones it no longer finds. Set `harness.promote.coreClones` to `refuse` and verify refuses a branch whose module code repeats core's.
442
443
  - **Each lead sees its own stream.** In the mod, a stream's lead sees its stream's build: the Build panel's milestone and bar, the Lanes panel (its lanes and the shared core lanes), what's ready, and the Trail are its own, and each says the stream ("Lanes: play"). The other streams are a line each, with who leads them and what their lanes are on, and the shared core lanes a line with whose turn it was. A session that leads nothing offers each stream to lead from here, with **Lead `<stream>`**. The Code map labels each layer core or its stream's module.
443
- - **Project-wide still.** One merge queue, one approval log, one set of standards and checks.
444
+ - **Project-wide still.** One merge queue, one approval log, one set of standards and checks. The queue is every stream's, so it doesn't wait on one session: the lead in the main checkout merges its head first, and any other stream's lead merges it whenever its own stream has only waiting to do. A stream's lead keeps its own worktree after its `lead/<stream>` branch merges.
444
445
 
445
446
  A project without `streams` is one stream holding every lane, and works as before. `spec-design` and `init` ask once whether the product has separate product lines, and only then lay out core and modules.
446
447
 
@@ -593,39 +594,39 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
593
594
 
594
595
  `.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
595
596
 
596
- | Field | Required | What it is |
597
- | ------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
598
- | `version` | yes | `1` |
599
- | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
600
- | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
601
- | `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 |
602
- | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
603
- | `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 |
604
- | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
605
- | `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. |
606
- | `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. |
607
- | `streams` | no | Spec 31: `{ "<name>": { lanes, plan, specs?, platform?, label? } }`, the product lines built at once, each with its own lead session. `lanes` are the stream's (each lane in one stream; a lane in none is a core lane the streams share in turns); `plan` its plan file or folder, inside `docs.plan`; `specs` the spec files it builds (globs); `platform: true` makes the stream the owner of core, and then every lane must be in a stream. Leave it out for one product line. |
608
- | `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. |
609
- | `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`. |
610
- | `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 |
611
- | `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label?, stream? }`: the first layer whose paths match a file owns it. A layer may always import itself. With `streams`, `stream` makes the layer that stream's module: it may import core and its own stream's layers, never another stream's, and a layer without `stream` (core) may import no module, whatever `mayImport` says. `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. |
612
- | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
613
- | `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 |
614
- | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes. A read's quoted arguments don't count, as for `shell.block` |
615
- | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
616
- | `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. |
617
- | `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. |
618
- | `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. |
619
- | `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). |
620
- | `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). |
621
- | `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). |
622
- | `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 |
623
- | `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 |
624
- | `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. |
625
- | `branches.protected` | no | Default `["main", "master"]` |
626
- | `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 |
627
- | `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) |
628
- | `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), `promote.tokens` (with `streams`, how many tokens of code alike, names aside, make a clone a candidate for core; default 60) and `promote.coreClones` (what verify does with module code that repeats core's: `note` or `refuse`; default `note`), `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`. |
597
+ | Field | Required | What it is |
598
+ | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
599
+ | `version` | yes | `1` |
600
+ | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
601
+ | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
602
+ | `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 |
603
+ | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
604
+ | `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 |
605
+ | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
606
+ | `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. |
607
+ | `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. With `"adds": true` it's a shared list: any lane adds entries to it, and only its owner changes or removes what's already there (see [Streams](#streams-several-product-lines-in-one-product)). |
608
+ | `streams` | no | Spec 31: `{ "<name>": { lanes, plan, specs?, platform?, label? } }`, the product lines built at once, each with its own lead session. `lanes` are the stream's (each lane in one stream; a lane in none is a core lane the streams share in turns); `plan` its plan file or folder, inside `docs.plan`; `specs` the spec files it builds (globs); `platform: true` makes the stream the owner of core, and then every lane must be in a stream. Leave it out for one product line. |
609
+ | `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. |
610
+ | `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`. |
611
+ | `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 |
612
+ | `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label?, stream? }`: the first layer whose paths match a file owns it. A layer may always import itself. With `streams`, `stream` makes the layer that stream's module: it may import core and its own stream's layers, never another stream's, and a layer without `stream` (core) may import no module, whatever `mayImport` says. `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. |
613
+ | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
614
+ | `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 |
615
+ | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes. A read's quoted arguments don't count, as for `shell.block` |
616
+ | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
617
+ | `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. |
618
+ | `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, and the fix check, run the install the lockfile calls for. |
619
+ | `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. |
620
+ | `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). |
621
+ | `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). |
622
+ | `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). |
623
+ | `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 |
624
+ | `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 |
625
+ | `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. |
626
+ | `branches.protected` | no | Default `["main", "master"]` |
627
+ | `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 |
628
+ | `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) |
629
+ | `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), `promote.tokens` (with `streams`, how many tokens of code alike, names aside, make a clone a candidate for core, tests left out; default 100) and `promote.coreClones` (what verify does with module code that repeats core's: `note` or `refuse`; default `note`), `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`. |
629
630
 
630
631
  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.
631
632