@warren-dean/code-kit 0.25.0 → 0.26.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.
@@ -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.25.0",
12
+ "version": "0.26.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.25.0",
3
+ "version": "0.26.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,22 @@
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.26.0 (2026-10-26)
6
+
7
+ The lanes pane is redesigned around what needs you, a lane's work survives its agent stopping, and merged work reaches the remote.
8
+
9
+ - **The pane.** `/lanes` is one page of panels with no tabs: Build (the milestone, by requirements tested), Needs you (everything waiting on you, most urgent first, one line each), Lanes (a card per lane at work, with a cell per requirement on its trail and a chip per layer of its code map), Queue and Log. When the cards don't fit, the lanes become swimlanes. It fits at any width, docked, inline or on Desktop.
10
+ - **The band** above the prompt is at most three lines while something needs you, one line while the build moves, and gone otherwise. A digit presses the button showing it, the same in the band and the pane.
11
+ - **Views.** On a story, `t` opens its Trail and `c` its Code map, and Escape comes back. `/lanes trail`, `/lanes map`, `/lanes journal`, `/lanes usage` and `/lanes characters` open those views directly.
12
+ - **Characters.** Each lane has a small animated character, drawn from the lane's name, so any number of lanes gets its own. Each one shows what its agent is doing, and plays a move when a story arrives, is handed back, is sent back or merges. `harness.motion: off` keeps them still.
13
+ - **Durable lanes.** Every tool call is logged per story in `.claude/state/events/` (paths, commands with credentials masked, results and commits, never file contents or prompts). `code-kit replay <story>` rebuilds where a story got to. When an agent stops partway, `next`, a session's start and `code-kit reconcile` check what it left open against git: what's done is marked done, what's safe runs again, and a command that can't safely run twice is put to the lead to find out, never rerun. A fresh agent on the story starts from a hand-over brief.
14
+ - **Merges reach the remote.** `branches.publish` says how: `push` pushes the base, and `pull-request` opens (or updates) a pull request from code-kit's own branch, for a base that GitHub only changes through pull requests. `code-kit publish` tries again when GitHub won't merge yet. A story branch merges only into the base: an agent's merge of one into any other branch is refused, pointing to the queue.
15
+ - **Worktrees** of stories merged on the remote's base are now cleaned up even when the local base is behind it.
16
+ - **A lane's claim** is no longer released while its agent is pending, waiting or idle, so a second agent can't start on the same paths. Only an agent that has ended frees it.
17
+ - **Reports** to a team provider (report version 4) carry each story's summary, the paragraph under its fields in the plan (at most 600 characters, cut at a sentence), and each requirement's title.
18
+ - code-kit's part of CLAUDE.md is updated for the band and the pane: `code-kit instructions` shows the change.
19
+ - The npm package no longer includes the mod's test file.
20
+
5
21
  ## 0.25.0 (2026-10-25)
6
22
 
7
23
  code-kit spends far fewer GitHub Actions minutes: a project's full CI runs once per release instead of once per story, and you can see what it costs.
package/README.md CHANGED
@@ -304,16 +304,13 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
304
304
 
305
305
  ### The band
306
306
 
307
- The band sits above the prompt. With nothing happening and nothing waiting, it's gone.
307
+ The band sits above the prompt, and speaks only when it's needed, in at most three lines:
308
308
 
309
- - **The mission**, while the build is moving (the lead mid-turn, an agent at work, the loop started):
310
- - **goal**: the milestone being built and how many of its stories are done;
311
- - **now**: what the lead is doing and the loop's state, with **Pause** or **Resume**;
312
- - **next**: the step the loop takes next;
313
- - **agents**: a line per agent at work, with its current tool and how long since;
314
- - with Context Graph installed, a line when a lane edited files without understanding them, and only then.
315
- - **you**: what only you can decide, each with the story it's for ("for ST-4 Booking form (BOOK-1)"). **d** ("Why, and what each choice does") opens it as a card in the Decisions tab. Usage and the plan's pause are labelled **note**.
316
- - **The team**, with `team` in the config: only what of the team needs you. Your stale claim (Keep or Release), a claim of yours changing the same files as someone else's, an intent touching what you own or lease (every intent, with Agree and Drop, for the tech lead), and a pull request in a lane you own.
309
+ - **What needs you**: the most urgent thing waiting, with the story it's for ("for ST-4 Booking form (BOOK-1)") and its buttons, and how many more wait ("2 more waiting · /lanes"). **d** ("Why, and what each choice does") opens it as a card in the pane. Most urgent first: a held call, then the lead's questions, approvals, merges and reviews that are yours, stalled lanes, your brief's open questions, then notes (usage, the plan's pause).
310
+ - **While the build moves** and nothing needs you, one line: the milestone, its bar of requirements tested, and how many agents are at work, with **Pause**; a paused loop says so, with **Resume**.
311
+ - **Nothing** while nothing is happening and nothing waits.
312
+
313
+ With `team` in the config, what of the team needs you is among what waits: your stale claim (Keep or Release), a claim of yours changing the same files as someone else's, an intent touching what you own or lease (every intent, with Agree and Drop, for the tech lead), and a pull request in a lane you own.
317
314
 
318
315
  What waits for you there:
319
316
 
@@ -325,9 +322,9 @@ What waits for you there:
325
322
  - **Stories waiting for review**, with the loop off: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes. While the loop runs, a lane's finished work is the lead's to review and merge, so it never waits here.
326
323
  - **Warnings:** a finish check failing in this session, or a story using more than three times the median of the stories finished this session (once three have finished), each with **Lanes** to open the pane; and background agents paused once the plan's 5-hour use passes `harness.background.pauseAtPercent` (80% unless set).
327
324
 
328
- Every decision belongs to the session that raised it: it's shown, asked and answered there, and its answer goes to that session's lead. Another session's band shows only how many wait there ("1 decision in session kim/7f3a91c2, answered there"). Only what's holding work up is a decision: a call Claude Code's own permission check refused (its auto mode, a deny rule) shows in the Lanes pane as that lane's activity, and the lead asks you with `code-kit ask` only if there's no other way. `code-kit decisions` lists this session's.
325
+ Every decision belongs to the session that raised it: it's shown, asked and answered there, and its answer goes to that session's lead. Another session's band shows only how many wait there ("1 decision in session kim/7f3a91c2, answered there"). Only what's holding work up is a decision: a call Claude Code's own permission check refused (its auto mode, a deny rule) shows on that lane's card in the pane as its activity, and the lead asks you with `code-kit ask` only if there's no other way. `code-kit decisions` lists this session's.
329
326
 
330
- Each button has a digit: type it in an empty prompt to press it. The band keeps one line per kind ("2 approvals waiting"); the Decisions tab says how many of each kind, then lists a short card for each decision, five at a time (**j** and **k** move), with the selected one in full below.
327
+ Each button has a digit: type it in an empty prompt to press it. A digit presses the button showing it, the same in the band and the pane. Each decision is its own (two approvals are two); the pane's decision view says how many of each kind, then lists a short card for each, five at a time (**j** and **k** move), with the selected one in full below.
331
328
 
332
329
  - **Notifications.** When something new needs you (an approval, a question from the lead, the lead waiting on you, a step or a merge that's yours), code-kit raises a system notification through your notification channel, once per decision, from the session the decision belongs to: "code-kit: the lead asks you". What was already waiting when the session started isn't announced. It needs Claude Code 2.1.301 or later; turn it off with `notify.on`.
333
330
 
@@ -344,27 +341,36 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
344
341
  - **Designs.** A design story is handed to the lead once a session; while you and the lead design it, the loop leaves it to you.
345
342
  - **One session leads.** The loop runs in the project's lead session: the one that started when no other led, or the one you chose with **Lead from here** (or `/code-kit:lead`). See [Several sessions in one project](#several-sessions-in-one-project).
346
343
  - **Modes.** **Pause** and **Resume** stop and start it. Under `propose`, each step waits for **Go**; under `off`, the loop does nothing. When every story is done, the band says so and the loop stops.
347
- - **Choices in Claude Code's dialog.** A decision you settle by choosing (how hands-off the loop is, a step to take under `propose`, a stale claim, a question from the lead with answers offered) is asked in Claude Code's own question dialog while the lead is idle, once; dismissed, it stays in the band and the Decisions tab. Approvals, send-backs and settings, which need your reason, stay in the pane.
344
+ - **Choices in Claude Code's dialog.** A decision you settle by choosing (how hands-off the loop is, a step to take under `propose`, a stale claim, a question from the lead with answers offered) is asked in Claude Code's own question dialog while the lead is idle, once; dismissed, it stays in the band and the pane's Needs you. Approvals, send-backs and settings, which need your reason, stay in the pane.
348
345
  - **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.
349
346
  - **The reviewer agent**, with `harness.agents.reviewer.on`. 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.
350
- - **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. The pane lists the queue, and lanes whose branch waits in it read `queued`.
347
+ - **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`.
348
+ - **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.
351
349
  - **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.
352
350
 
353
- ### The Lanes pane
351
+ ### The pane
352
+
353
+ **`/lanes`** opens it; `/lanes` again, or Escape, closes it. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. It's one page of panels with no tabs, each starting with a status line (its name, its state in a word or two, a count at the right), and a panel with nothing to say takes no room:
354
+
355
+ - **Build**: is the build moving? The milestone being built and a bar of its requirements by state, counted from the trail: tested, built but untested, in progress and todo, each its own glyph and colour, with the counts beside it ("Milestone 3: Booking · 9 of 14 tested · 3 untested"). A milestone whose stories are all merged with requirements untested says untested, not done. Beneath it, the loop's next step, with **Pause** or **Resume** on **p**.
356
+ - **Needs you**: everything waiting on you, and only here in the pane, most urgent first. The first is open with its story, what it's for and its buttons; the rest are a line each, and choosing one opens it in its place. **Why…** shows its full card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does.
357
+ - **Lanes**: where each story is. Each lane at work is a card, the lead's first: its character, the story, its state, its agent's current tool with a clock (amber once quiet, red when stalled), its tokens, and two small pictures. Its **trail**: a cell per requirement the story cites, coloured as in the Trail, so you see coverage grow as it moves. Its **map**: a chip per layer its changed files are in, red while a layer rule or another refusal is unresolved there, amber where a changed file's Context Graph card isn't written or is out of date. A card also says the background review's state, a note from the loop (nudged, restarted, stalled) and, with Context Graph, edits made without understanding. Lanes with nothing at work fold into one line ("resting: api, data, qa"). When the cards don't fit, the lanes are swimlanes on a shared time axis, a line each.
358
+ - **Queue**: the merge queue while it isn't empty: each branch, its story, the commit its review passed and its state, and what it merged or sent back lately, and why.
359
+ - **Log**: the build's latest events, a line each ("14:02 ✓ ST-4 merged · web"), yours in yellow.
360
+
361
+ Each lane has its own character, from its name: six shapes, then a mark (glasses, a scarf, a belt) for each lane past six, so up to 24 lanes read apart without colour; the lead's wears a crown. While its agent works it plays the kind of work its current tool is (writing, running, reading, thinking); it raises a hand while it waits on you, slumps when stalled, and rests otherwise. It arrives with a story, hands back its work, stumbles when sent back, and cheers when its story merges. Only the characters, the clocks and the rail from the lead to the lanes it dispatched move, and only while work flows, each on the surface's own frame clock; `harness.motion` `off` keeps everything still. `/lanes characters` shows every lane in every pose and move.
362
+
363
+ **Keys**, listed on the pane's last line for what's selected: **j** and **k** move through what needs you and the lanes; **Enter** opens what's selected; a digit presses the button showing it. A selected story's acts are buttons on its card, each with its key: **a** approve, **r** review, **s** send back (with your reason), **m** merge, **w** watch (its agent's own transcript in the main view, on Claude Code 2.1.301 or later), **n** nudge and **x** stop; **t** and **c** open its trail and code map. **p** pauses or resumes the loop, **f** filters the lanes by name, agent or story, and **l** opens the Journal.
364
+
365
+ **Views**, over the panels; Escape comes back:
354
366
 
355
- **`/lanes`** opens it; `/lanes` again, or Escape, closes it. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane.
367
+ - **A story**, with Enter on its card: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, its timeline, and its diff against the base, file by file, with the acts its state allows.
368
+ - **Trail** (**t** on a story, or `/lanes trail`): every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it. Beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red.
369
+ - **Code map** (**c** on a story, or `/lanes map` for the whole project's folders by layer): a story's files in a column per layer with the imports between them. A file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet. **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph.
370
+ - **Journal** (**l**, or `/lanes journal`): the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow.
371
+ - **Usage** (`/lanes usage`): the plan's 5-hour use, each story's and each lane's tokens, and the background agents' share.
356
372
 
357
- - **The top.** A count of the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key.
358
- - **Tabs, on 1 to 7:**
359
- - **Lanes**: the loop as a card (its mode, the steps it took, the one running and the next), then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns.
360
- - **Decisions**: each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does.
361
- - **Journal**: the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow.
362
- - **Code map**: the whole project's folders by layer when no story is at work, or a story's files in a column per layer with the imports between them. A file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet. **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop).
363
- - **Trail**: every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it. Beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red.
364
- - **Queue**: the merge queue.
365
- - **Usage**.
366
- - **Keys.** **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **w** (watch: its agent's own transcript in the main view, on Claude Code 2.1.301 or later; the tasks list brings the conversation back), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story.
367
- - **A story.** **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes.
373
+ The pane has three layouts: inline above the prompt when the terminal can't dock it (at most four lines: the Build bar, a cell per lane coloured by its state, and the first thing waiting), docked beside the transcript (the panels in one column), and wide, docked at 110 columns or more (Build across the top, Lanes on the left, Needs you, Queue and Log on the right). Desktop draws the same panels, with the characters, bars and timelines as SVG.
368
374
 
369
375
  ### Other views
370
376
 
@@ -458,9 +464,12 @@ code-kit instructions [--write] [--json] | instructions show lead|lane [<lane>]
458
464
  code-kit standards [--json] [--for <path>...] # the project's standards with any its organisation's provider supplies, and what's wrong with them; --for keeps the ones for those files' layers
459
465
  code-kit trace <path>... [--json] # what a file is for: requirements, lane, layer rules
460
466
  code-kit merge <branch> --delegated|--person [--into branch] # merge a branch that passes verify: the lead where approvals.delegate.merge is on, or the person
467
+ code-kit publish --delegated|--person # put what's merged into the base onto the remote's, as branches.publish says
468
+ code-kit replay <story> [--json|--brief] # a story's state rebuilt from its event log: its phase, last commit, tests, what's left open
469
+ code-kit reconcile [--json] # check what a stopped agent left open against git; the lead records what git can't settle with --act
461
470
  code-kit requests [--json] # approval requests still waiting, numbered, each the lead's or the person's to decide, the approvals in force, and every approval given
462
471
  code-kit requests drop <n>[,<n>…]|all [--reason "…"] # stop waiting on requests nobody needs answered (the lead, or Not needed in the pane)
463
- code-kit ask "<question>" [--story ST-n] [--blocks] [--why "…"] [--option "Label: what it does"]... # the lead asks you what it can't settle; it waits in your Decisions tab
472
+ code-kit ask "<question>" [--story ST-n] [--blocks] [--why "…"] [--option "Label: what it does"]... # the lead asks you what it can't settle; it waits in your band and the pane's Needs you
464
473
  code-kit ask [--json] | ask answer <id> "<answer>" | ask withdraw <id> --reason "…" # the questions; your answer (given in chat, recorded by the lead); one settled another way
465
474
  code-kit report "<title>" --what "…" [--expected …] [--command …] [--refusal …] [--rule …] # with harness.report.on, an agent drafts a bug report for code-kit
466
475
  code-kit report [--json] | report send|discard <id> # the drafts; sending files it on code-kit's GitHub with your gh, which only you do
@@ -514,34 +523,36 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
514
523
 
515
524
  `.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
516
525
 
517
- | Field | Required | What it is |
518
- | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
519
- | `version` | yes | `1` |
520
- | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
521
- | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
522
- | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
523
- | `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 |
524
- | `lead.paths` | yes | What the main session writes. `.claude/**` is always added. |
525
- | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
526
- | `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. |
527
- | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `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. |
528
- | `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`. |
529
- | `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
530
- | `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
531
- | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
532
- | `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, so a heredoc or quoted text that mentions it isn't refused |
533
- | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
534
- | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
535
- | `tests[]` | no | Globs naming the test files, for the weakened-test and fix rules. Default: the usual conventions (`*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/`, `e2e/`, `*_test.go`, `test_*.py`). |
536
- | `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. Without it, the checkout's `node_modules` and virtualenvs are linked in. |
537
- | `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. |
538
- | `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). |
539
- | `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). |
540
- | `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). |
541
- | `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 |
542
- | `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, approvals, token use and the rules; 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. |
543
- | `branches.protected` | no | Default `["main", "master"]` |
544
- | `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `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`) 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`. |
526
+ | Field | Required | What it is |
527
+ | ------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
528
+ | `version` | yes | `1` |
529
+ | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
530
+ | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
531
+ | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
532
+ | `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 |
533
+ | `lead.paths` | yes | What the main session writes. `.claude/**` is always added. |
534
+ | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
535
+ | `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. |
536
+ | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `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. |
537
+ | `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`. |
538
+ | `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
539
+ | `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
540
+ | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
541
+ | `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, so a heredoc or quoted text that mentions it isn't refused |
542
+ | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
543
+ | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
544
+ | `tests[]` | no | Globs naming the test files, for the weakened-test and fix rules. Default: the usual conventions (`*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/`, `e2e/`, `*_test.go`, `test_*.py`). |
545
+ | `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. Without it, the checkout's `node_modules` and virtualenvs are linked in. |
546
+ | `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. |
547
+ | `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). |
548
+ | `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). |
549
+ | `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). |
550
+ | `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 |
551
+ | `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, approvals, token use and the rules; 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. |
552
+ | `branches.protected` | no | Default `["main", "master"]` |
553
+ | `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 |
554
+ | `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) |
555
+ | `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `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`. |
545
556
 
546
557
  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.
547
558
 
@@ -614,13 +625,13 @@ Other tools share a project with code-kit and keep files of their own. An adapte
614
625
  - how to detect the tool;
615
626
  - what the tool adds to the rules: paths for the lead, paths any actor may write, protected paths, blocked commands;
616
627
  - the setup init should apply;
617
- - what the tool knows of the lanes' work, for the Lanes pane (its `facts`).
628
+ - what the tool knows of the lanes' work, for the pane's lane cards (its `facts`).
618
629
 
619
630
  While the tool is detected, its additions are merged into the effective config, like the kit's own defaults. Run `code-kit adapters` to see them, or switch one off with `"adapters": { "<name>": false }`.
620
631
 
621
- | Adapter | Detected by | Adds |
622
- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
623
- | `context-graph` | `.ctx/` | `.ctx/**` for the lead. `.ctx/decisions.ctx` and `.ctx/cards.ctx` for any actor, since every agent records decisions and file cards. `graph.ctx` and `config.toml` are protected (approval `ctx`). No Claude actor may write a person's `Ctx-Ratified-By` trailer: ratifying is a person's act (with `approvals.lead`, the lead may add it when the person says so in chat). A delegated trailer, `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's alone, under Context Graph's `[delegate]` rules. `verify` accepts a `graph.ctx` change whose commits carry a person's trailer (`ctx ratify --commit`, `ctx drop --commit`) without an approval-log entry. Changing Context Graph's harness settings (`ctx settings set`) is the person's act too. Agents can't run those commands. With `ctx` on the PATH, the Lanes pane shows each lane's edits made without understanding and the cards it owes, and a story's drill-down lists the files still unread and the rules on its files, agreed and proposed; **v** opens a file in Context Graph's pane (`/graph <path>`). |
632
+ | Adapter | Detected by | Adds |
633
+ | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
634
+ | `context-graph` | `.ctx/` | `.ctx/**` for the lead. `.ctx/decisions.ctx` and `.ctx/cards.ctx` for any actor, since every agent records decisions and file cards. `graph.ctx` and `config.toml` are protected (approval `ctx`). No Claude actor may write a person's `Ctx-Ratified-By` trailer: ratifying is a person's act (with `approvals.lead`, the lead may add it when the person says so in chat). A delegated trailer, `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's alone, under Context Graph's `[delegate]` rules. `verify` accepts a `graph.ctx` change whose commits carry a person's trailer (`ctx ratify --commit`, `ctx drop --commit`) without an approval-log entry. Changing Context Graph's harness settings (`ctx settings set`) is the person's act too. Agents can't run those commands. With `ctx` on the PATH, each lane's card in the pane shows its edits made without understanding and the cards it owes, and a story's drill-down lists the files still unread and the rules on its files, agreed and proposed; **v** opens a file in Context Graph's pane (`/graph <path>`). |
624
635
 
625
636
  Its setup:
626
637