@warren-dean/code-kit 0.36.0 → 0.37.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.36.0",
12
+ "version": "0.37.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.36.0",
3
+ "version": "0.37.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,17 @@
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.37.0 (2026-11-15)
6
+
7
+ - **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.
8
+ - **Each stream's lead sees its own stream in the mod.** The panes showed the whole project to every session, so a stream's lead saw the other streams' lanes, stories and milestone as if it ran them. Now the Build panel, the Lanes panel, what's ready and the Trail are the stream's own, each named for it, with a line per other stream (who leads it and what its lanes are on) and one for the shared core lanes. A session that leads nothing offers **Lead `<stream>`** for each stream, and the Code map labels each layer core or its stream's module.
9
+ - **A stream's loop gets its own stream's step.** The mod asked `code-kit next` without naming its session, so in a project built as streams a stream's lead could be prompted with the project's next step, another stream's story among them. It now names the session, and each lead's loop gets only its own stream's work.
10
+
11
+ ## 0.36.1 (2026-11-14)
12
+
13
+ - **`/code-kit:lead` moves the lead itself.** Typing `/code-kit:lead` (or `/code-kit:lead <stream>`) answered with which session leads and a `!` command for you to run, since the hooks refuse moving the lead from an agent. Typing the command is already your choice, so code-kit now records this session as the lead, of the stream you named, as the prompt arrives; the skill confirms it, says what it means, and moves into a worktree when another stream's lead holds the main checkout. A stream that doesn't exist changes nothing, and the answer names the streams.
14
+ - **Re-running init asks about product lines.** `/code-kit:init` asked whether the product has separate product lines only on a project with no specs, or drafted streams when the architecture already laid out a core and modules. A project whose brief or specs name several product lines, with code laid out by technical role, was never asked. init now asks once, naming the lines it found, on a first run and on every re-run while the config has no `streams`.
15
+
5
16
  ## 0.36.0 (2026-11-14)
6
17
 
7
18
  - **Streams: several product lines in one product.** A product with separate product lines in one repository can now be built by a squad, or a session, per line at once. Declare them as `streams` in the config: each stream has its own lead session (`/code-kit:lead <stream>`), plan file, specs and lanes, and each lead's loop dispatches only its own stream's stories, so two sessions no longer fight over one lead. Layers become a core per technical layer and a module per stream: a module may use core and its own stream's modules, never another stream's, and core uses no module; the hooks refuse both and say to ask for it in core rather than copy it. Core is owned by a platform stream, which the others ask with `code-kit core ask`, or, without one, its lanes are shared and taken in turns. A project without `streams` works as before.
package/README.md CHANGED
@@ -44,6 +44,7 @@ Rules in `CLAUDE.md` and agent prompts are advice. Over a long session, or acros
44
44
  - a contract or schema changes with no record of who changed it or why;
45
45
  - code gets written before anyone checked it against the spec, or a screen before it was designed;
46
46
  - an agent declares "done" with failing type checks, or with work nobody committed;
47
+ - a fix ships with no test, so the bug comes back, or an agent skips or deletes a failing test to get to green;
47
48
  - someone force-pushes, commits to `main`, adds a dependency, or runs a deploy nobody asked for.
48
49
 
49
50
  code-kit catches each of these, most at the moment it would happen: the hook refuses the edit or command and tells the agent why and what to do instead. A file a shell command writes is caught straight after the command, and the agent is told to revert it. The rules live in one reviewed file, not in every prompt, so they hold for every agent and every session. They are guard rails for agents, not a sandbox: see [What verify proves, and its limits](#what-verify-proves-and-its-limits).
@@ -77,7 +78,7 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
77
78
  - no secret files (`.env`, `secrets/`, keys and keystores) anywhere in the branch's history, including ones committed and deleted again, and, where gitleaks is installed, no secrets in any commit's content;
78
79
  - no test weakened (deleted, skipped or focused, cut down, or its snapshot rewritten) without the person's `tests` approval in the log;
79
80
  - with a running budget, a branch that changes the infrastructure files changes the cost register too, and one that takes an environment past its budget has the person's `cost` approval in the log;
80
- - a fix (a plan story with `**Fixes:**`, or a `<lane>/fix-…` branch) comes with a test that fails without it, as the bug, and passes with it;
81
+ - a fix (a plan story with `**Fixes:**`, or a `<lane>/fix-…` branch) comes with a test that fails without it, as the bug, and passes with it. The test has to fail on an assertion: one that fails only because it calls something the fix adds proves nothing, and verify asks for one through the existing code;
81
82
  - the project's checks pass.
82
83
 
83
84
  A project without `.claude/code-kit.json` isn't governed at all. An invalid config fails closed: nothing but the config itself can be written until it's fixed.
@@ -122,15 +123,20 @@ Set it up at the start of a new build, straight from the architecture docs, or b
122
123
  - **In Claude Code**, as a plugin. It's installed once per machine and governs only projects that have `.claude/code-kit.json`.
123
124
  - **On every edit, shell command and finish** in those projects, through Claude Code hooks:
124
125
 
125
- | Hook | Runs | Enforces |
126
- | ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
127
- | `PreToolUse` Edit/Write | `hooks/guard-paths.mjs` | lanes, protected paths, spec-check and design gates |
128
- | `PreToolUse` Bash | `hooks/guard-bash.mjs` | shell rules, dependencies, approval log and secret scan on commit |
129
- | `PostToolUse` Edit/Write | `hooks/post-edit-check.mjs` | layer rules and the project's `postEdit` commands |
130
- | `PostToolUse` Bash | `hooks/lane-audit.mjs` | ownership of files a shell command wrote, reported for revert |
131
- | `PreToolUse` Agent | `hooks/guard-agent.mjs` | one agent per lane at a time, across every session |
132
- | `Stop`, `SubagentStop` | `hooks/stop-check.mjs` | proof before finishing; a lane's finish frees the lane |
133
- | `SessionStart`, `SessionEnd` | `hooks/session.mjs` | the session recorded as the lead or a working session; as it ends, it leads nothing, and its lanes are freed |
126
+ | Hook | Runs | Enforces |
127
+ | ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
128
+ | `PreToolUse` Edit/Write | `hooks/guard-paths.mjs` | lanes, protected paths, spec-check and design gates |
129
+ | `PreToolUse` Bash | `hooks/guard-bash.mjs` | shell rules, dependencies, approval log and secret scan on commit |
130
+ | `PostToolUse` Edit/Write | `hooks/post-edit-check.mjs` | layer rules and the project's `postEdit` commands |
131
+ | `PostToolUse` Bash | `hooks/lane-audit.mjs` | ownership of files a shell command wrote, reported for revert |
132
+ | `PreToolUse` Agent | `hooks/guard-agent.mjs` | one agent per lane at a time, across every session |
133
+ | `Stop`, `SubagentStop` | `hooks/stop-check.mjs` | proof before finishing; a lane's finish frees the lane |
134
+ | `SessionStart`, `SessionEnd` | `hooks/session.mjs` | the session recorded as the lead or a working session; as it ends, it leads nothing, and its lanes are freed |
135
+ | `SessionStart`, `SessionEnd` | `hooks/team-session.mjs` | with a hosted team provider, the session's live link, and the project's report as it starts | |
136
+ | `UserPromptSubmit` | `hooks/lead-prompt.mjs` | `/code-kit:lead [stream]`, typed by the person, makes the session the lead |
137
+ | `WorktreeCreate` | `hooks/worktree-create.mjs` | a lane agent gets its lane's worktree, reused by each of its stories |
138
+ | `SubagentStop` | `hooks/worktree-done.mjs` | an agent's own worktree goes when it changed nothing |
139
+ | every tool call, `SubagentStop` | `hooks/act.mjs` | the event log of each act and a lane's hand-back, for recovery after a crash |
134
140
 
135
141
  - **For the main session and every subagent**, including agents in worktrees under `.claude/worktrees/`.
136
142
  - **In front of you, in the terminal and the Desktop app,** through the code-kit mod (Claude Code 2.1.287 or later; see [In the session](#in-the-session)). It shows and acts, and never enforces: the hooks above do that everywhere, the mod or not.
@@ -216,7 +222,7 @@ spec-design works an idea into a specification with you before any code exists.
216
222
 
217
223
  It writes `docs/brief.md` (with the decision log and open questions), `docs/specs/NN-<area>.md`, `docs/architecture.md`, `docs/standards.md`, `docs/principles.md` and `docs/plan.md`. Those are exactly what `/code-kit:init docs/` turns into lanes, layers and standards, and what lanes spec-check against. Run it again to resume where it left off, to change a decision, or to spec a new feature in an existing codebase.
218
224
 
219
- Requirements are headings (`### BOOK-4 Cancel a booking`). Stories are `### ST-12` headings in the plan with `**Lane:**`, `**Requirements:**`, `**Depends on:**` and `**Status:**` lines (`templates/plan.md`). The lane `lead` marks the lead's own stories, such as contracts and spikes, which the lead builds itself instead of dispatching; the lane `design` marks a design story, which the lead designs with you (`/code-kit:design`) before any screen that depends on it is built; `**Requirements:** none` marks a story that delivers no requirement. `**Status:** dropped` takes a story out of the plan without deleting it (folded into another, or no longer wanted): it's never dispatched, never waited on, and covers no requirement. Those two formats are what the build loop below runs on.
225
+ Requirements are headings (`### BOOK-4 Cancel a booking`). Stories are `### ST-12` headings in the plan with `**Lane:**`, `**Requirements:**`, `**Depends on:**` and `**Status:**` lines (`templates/plan.md`). A story may also carry `**Slice:**` (the feature it's part of: a free lane builds the open slice's stories first), `**Size:**` small, medium or large (with `harness.agents.lanes.model` set to `story`, it picks the lane agent's model, Haiku, Sonnet or Opus, raised for security requirements, fixes and send-backs, since most stories don't need the session's model), `**Fixes:**` for a bug fix (verify then needs a test that fails without it), and, on a design story, `**Screens:**`, the screens it designs. The lane `lead` marks the lead's own stories, such as contracts and spikes, which the lead builds itself instead of dispatching; the lane `design` marks a design story, which the lead designs with you (`/code-kit:design`) before any screen that depends on it is built; `**Requirements:** none` marks a story that delivers no requirement. `**Status:** dropped` takes a story out of the plan without deleting it (folded into another, or no longer wanted): it's never dispatched, never waited on, and covers no requirement. Those two formats are what the build loop below runs on.
220
226
 
221
227
  ## Set up a project
222
228
 
@@ -234,6 +240,10 @@ Requirements are headings (`### BOOK-4 Cancel a booking`). Stories are `### ST-1
234
240
  - new ones, even in the same file, do;
235
241
  - the baseline only ever shrinks: re-recording drops what's been fixed and refuses anything new.
236
242
 
243
+ **Standards.** Rules written as prose in the principles couldn't say which one a change broke, or how much it mattered. So init suggests the project's standards in `docs/standards.md`: from the specs, architecture and threat model, or, for existing code, from the code, each with its evidence ("41 of 43 modules reach the database through repositories"). You approve, edit or drop each before anything is written. Each is graded required or recommended, and applied as firmly as code-kit can: enforced by a rule whose refusal names it, checked in review, or given as advice. Each lane agent gets only its own layers' standards. `code-kit standards` lists them and what's wrong with them (spec 22).
244
+
245
+ **A QA lane.** Each lane writes its own unit tests, but nobody owned whether a whole journey across lanes still works. When the product has screens, or journeys that cross lanes, init adds a `qa` lane whose `test-engineer` agent owns the end-to-end suites, with a check that runs them when they change.
246
+
237
247
  **No specs yet?** Leave `docs.specs` out, and lanes aren't held to a spec-check report. Add it once specs exist.
238
248
 
239
249
  ## The agents and skills it creates
@@ -316,12 +326,13 @@ With `team` in the config, what of the team needs you is among what waits: your
316
326
 
317
327
  What waits for you there:
318
328
 
319
- - **A held call.** An agent installing a new package, writing or committing a protected file, or a lane changing the kit, where the approval is yours. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. What the lead decides (`approvals.delegate`) is never held for you: the lane asks the lead, which approves it on its merits. Nothing is held under `claude -p` or the SDK, where nobody can answer.
329
+ - **A held call.** An agent installing a new package, writing or committing a protected file, or a lane changing the kit, where the approval is yours. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. What the lead decides (`approvals.delegate`) is never held for you: the lane asks the lead, which approves it on its merits. Nothing is held under `claude -p` or the SDK, where nobody can answer. Set `harness.hold.minutes` to 0 and no call is held: each is refused at once, as under `claude -p`.
320
330
  - **Approvals agents asked for.** **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite. When it isn't clear what it's for, **Ask about it**: the answer comes from a side call over the lead's conversation and code-kit's facts about the request, shown in the pane and never added to the lead's session, and follow-ups carry on the aside. A request waits until it's answered, its file is committed by someone who could, or it's dropped (at most a week); on its card, **Not needed** drops it.
321
331
  - **Questions from the lead** ("The lead asks: which weather provider?"), asked with `code-kit ask`: what it can't settle and only you can. **Answer…** opens it as a card with each of the lead's options and what it does, and **Something else…** for your own words; your answer is recorded and sent to the lead. A question can hold its story, which then reads `waiting on you`: nothing dispatches or reviews it, and the stories that depend on it wait, until you answer.
322
332
  - **Your brief's open questions**, each with who decides and what it holds up (from the table's Owner and Blocks columns; one owned by the lead alone isn't yours, and doesn't show). **Answer…** sends your answer to the lead, which records it in the brief's decisions, and **Ask about it** in the answer box explains it first, beside the conversation; **Later** puts one off until the next session.
323
333
  - **A bug report for code-kit**, with `harness.report.on`, drafted by an agent code-kit got in the way of. It holds only code-kit's own facts (its version, the rule, what it said, the command), with the project's folders and email addresses taken out. **Read it** shows the exact text; **Send** files it on code-kit's GitHub with your own `gh` (a comment, if it's filed already; without `gh`, you get the link to file it); **Discard** drops it.
324
334
  - **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.
335
+ - **A merged worktree with changes left in it**, listing the files: **Keep** leaves it until the next session, and **Discard** removes it, kept as a patch under `.claude/state/discarded`. Only you can discard.
325
336
  - **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).
326
337
 
327
338
  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.
@@ -341,25 +352,26 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
341
352
  - **It doesn't cut into a conversation.** When you talk with the lead about something other than the build (a question, a discussion, another task), the loop waits until you've been quiet for `harness.loop.quietMinutes` (10) before it prompts again; the band says so, with **Carry on**. Asking the lead to carry on with the build holds nothing.
342
353
  - **Each step is checked first.** code-kit's records can lag the work, so before it prompts the lead the loop reads the project itself (the step's branches against the base, the merge queue, the agents at work, the latest commits and the lead's last replies) and a small model judges whether the step is still due. One that isn't (merged already, under way, or one the lead said why it won't take, with nothing changed since) is held as a note with **Ask now**, and checked again once the project moves. A step the lead said waits, or didn't take, is held the same way, so speaking to the lead doesn't bring it back. `harness.loop.check` switches the check off.
343
354
  - **A step that doesn't move.** One the lead was prompted with three times in a row that is still next shows as a note, not a decision: "Merge lead/st-1: still next after 3 prompts to the lead", with **Ask again** if you want it.
355
+ - **Usage limits.** A lead turn that ends on Claude's usage limit, a rate limit or an API error did nothing, so the loop prompts nothing and restarts no quiet lane until it can work again: until the used-up limit resets, or, where Claude Code reports no reset, after 5 minutes, then 10, 20 and at most 60. The band says when it will try again, with **Try now**, and speaking to the lead ends the wait. Without it, the loop would prompt into the limit and count every quiet lane as stalled.
344
356
  - **A lean lead.** A lane writes its full report, with its commands and their output, to `.claude/state/reports/<branch>.md`, and hands the lead a few lines naming it; the stop hook won't let a lane on a story branch finish without it, or with a hand-back of more than ten lines, and the lead reads the file when it reviews. Lanes don't message the lead while they work. When a milestone finishes, the lead's context is compacted before the next one (`harness.compact.milestone`: you're asked by default, or it's done at once): the summary keeps what's in flight and what waits on you, and drops the finished stories' detail.
345
357
  - **Token use.** A long-lived agent rereads its whole context on every request, which is most of what a build costs. So each lane agent builds one story; one past `agents.lanes.contextLimit` is told to wrap up, and the lead carries its story on with a fresh agent that reads its report (`code-kit worktrees release` frees the branch). The lead's context is compacted between turns once it's past `compact.at`. The loop reads the lead's replies with Sonnet, and the reviewers run on Sonnet by default.
346
358
  - **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.
347
359
  - **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).
348
- - **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.
360
+ - **Modes.** **Pause** and **Resume** stop and start it. A pause is recorded (`code-kit loop pause`), so other tools' background work in the project, such as Context Graph's card writer, pauses with it, and a pause another tool records pauses the loop too, within seconds. 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.
349
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.
350
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.
351
- - **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.
352
- - **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`.
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.
353
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.
354
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.
355
367
 
356
368
  ### The pane
357
369
 
358
- **`/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:
370
+ **`/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. With an invalid config, the pane says so in one line, with `code-kit check` to see why, and draws no lanes until it's fixed:
359
371
 
360
372
  - **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**.
361
373
  - **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.
362
- - **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.
374
+ - **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. Beneath the lanes, the stories ready to start, each with its lane, the lead's own named as such.
363
375
  - **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.
364
376
  - **Log**: the build's latest events, a line each ("14:02 ✓ ST-4 merged · web"), yours in yellow.
365
377
 
@@ -380,7 +392,7 @@ The pane has three layouts: inline above the prompt when the terminal can't dock
380
392
  ### Other views
381
393
 
382
394
  - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.
383
- - **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, the lane agents' model, the use at which background agents pause, and whether agents draft bug reports for code-kit. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
395
+ - **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, the lane agents' model, the use at which background agents pause, and whether agents draft bug reports for code-kit, and, in its Approvals section, who decides each approval. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
384
396
  - **`/approvals`** lists the approvals waiting (one per approval and lane, with every file it covers), the approvals in force with minutes left, and every approval given, newest first: who gave it (you, or the lead within your delegated rules), its reason, and the files and branches it covered, merged or not. A request stops waiting once an approval is given for it, or its file is committed by someone who could; a read-only agent such as the reviewer never asks.
385
397
  - **`/verify-branch`** runs `code-kit verify` on this branch. Neither it nor `/approvals` calls the model.
386
398
 
@@ -395,6 +407,7 @@ Once init has switched the rules on, the lead runs the build in a loop:
395
407
  /code-kit:decide # decide what lanes asked for: approve, offer something better, or bring it to you
396
408
  /code-kit:review ST-12 # check a finished branch, then merge or send it back
397
409
  /code-kit:status # where the build stands against the spec
410
+ /code-kit:design # design a design story's screens with you, before any is built
398
411
  /code-kit:promote # with streams: decide what goes into core, from what two streams share
399
412
  ```
400
413
 
@@ -402,12 +415,13 @@ Once init has switched the rules on, the lead runs the build in a loop:
402
415
  - **Decide** takes what a lane asked for and couldn't do itself: a package, a migration, a protected file, a UX question. The lead judges it against the story's requirements, the spec, the principles and the architecture, and approves it, tells the lane what to use instead, or brings it to you when it crosses a guardrail. See [Who decides what](#who-decides-what).
403
416
  - **Review** runs `verify` on the branch, then checks each requirement: built end to end, proved by a test, matching the spec-check report, and nothing beyond the story. It ends with merge, send back with the list of problems, or a question for you.
404
417
  - **Status** traces every requirement to its story, branch and tests. It shows what's done, in review, ready and blocked, which requirements no test names, and where the plan's status lines are out of date.
418
+ - **Design** works a design story's screens through with you, in the project's design tool (Paper, Figma, Pencil) or as HTML under `design/`. A lane has no connection to the design tool and used to build screens from the spec's words, so as you approve each screen it exports every state into `design/<area>/<screen>/<state>` (the tool's code and a PNG) and records them, with their hashes, in the design register the design gate reads. The screen's lane is briefed with those files, and the review compares each built state with its design. A register entry that names only an artboard doesn't open the gate: `code-kit next` names such entries, and `/code-kit:design --hand-over` exports them once you confirm each is still the approved design (spec 24).
405
419
 
406
420
  ## Several sessions in one project
407
421
 
408
422
  You can open several Claude Code sessions in one project: one building the plan, others auditing, checking merges or looking into something ad hoc. code-kit treats each session as a member of the team, as it treats each developer in a team:
409
423
 
410
- - **One lead session.** The loop runs there, and the plan's stories are dispatched from it. The first session to start leads; one started while it's open is a working session. When the lead session ends, no other takes over by itself: the next session to start leads, or you choose one with **Lead from here** or `/code-kit:lead`. `code-kit who` says which this session is.
424
+ - **One lead session.** The loop runs there, and the plan's stories are dispatched from it. The first session to start leads; one started while it's open is a working session. When the lead session ends, no other takes over by itself: the next session to start leads, or you choose one: type `/code-kit:lead` in the session you want, and it leads from that moment (or use **Lead from here** in its band). An agent can't move the lead itself; typing the command is your choice. `code-kit who` says which this session is.
411
425
  - **Working sessions stay quiet.** Their band shows only their own: their refusals and held calls, their lead's questions, their task. No loop prompts, no other session's decisions or notifications. Every rule still applies.
412
426
  - **Ad hoc work records a task.** A working session records what it's doing before it changes code, with the paths it'll change: `code-kit task "Integration readiness" --touches "src/integrations/**"`. The task leases those paths: another session's agents writing there are refused, naming the session and its task. `code-kit sessions` lists the sessions and their tasks; `task done` ends one, and `task take <session>` moves a task whose session ended to yours.
413
427
  - **Each in its own worktree.** A working session that changes code works in a worktree of its own (`claude --worktree`); its writes in the main checkout are refused, so its uncommitted files never block another session's git. Where git does refuse because of another session's uncommitted files, code-kit says whose they are.
@@ -419,19 +433,29 @@ Spec: `docs/specs/23-the-team.md`.
419
433
 
420
434
  One product in one repository can have separate product lines (offerings for different users, each with its own roadmap) built by separate squads, or sessions, at once. Declare them as `streams` in the config, and the project is built as a modular monolith: per technical layer, a **core** the streams share and a **module** per stream.
421
435
 
422
- - **A lead per stream.** Each stream has its own lead session, plan file, specs and lanes, and they lead at once: `/code-kit:lead <stream>`. 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>`.
436
+ **Why.** Without streams a project has one lead, one plan and lanes cut by technical layer. Two sessions meant for two product lines fight over the lead, the lead's loop hands each the other line's stories, and one line's API story holds the API lane while the other line's waits. Streams add the second axis, the product line (Team Topologies' stream-aligned teams, with a platform team owning what they build on), so each line moves at its own pace while the code stays one codebase, and what the lines share is built once, in core.
437
+
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>`.
423
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.
424
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.
425
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.
442
+ - **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.
426
443
  - **Project-wide still.** One merge queue, one approval log, one set of standards and checks.
427
444
 
428
445
  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.
429
446
 
447
+ **Turning streams on in a project that started as one:**
448
+
449
+ 1. Run `/code-kit:init`. When the brief, specs or plan name more than one product line, it asks whether separate squads or sessions build them (or tell it so). On a yes it drafts `streams`, a lane per line in each technical layer, a module layer per line, and a plan file per stream under `docs/plan/`, and shows the difference before anything is enforced.
450
+ 2. Where the code isn't split into core and modules yet, init doesn't move it: it writes the move as stories, lower layers first, a few files each. Until a story moves a file, it stays with the lane that owns it today.
451
+ 3. Open a session per stream and type `/code-kit:lead <stream>` in each. The first leads from the main checkout; each other one is told to lead from a worktree of its own on `lead/<stream>` and moves itself there (or start it with `claude --worktree`). Its writes in the main checkout are refused until it does.
452
+ 4. `code-kit streams` lists the streams, their lanes and leads; `code-kit who` says which stream this session leads.
453
+
430
454
  Spec: `docs/specs/31-streams-and-platform.md`.
431
455
 
432
456
  ## Teams (preview)
433
457
 
434
- For several people in one repository, each with their own agents. Not every developer works in a team, so it's off until you set it up: `/code-kit:init` asks whether others work in the repository, and `/code-kit:team-init` sets the team up (or changes it, or takes it out) at any time, asking for the tech lead and each lane's owners and showing what it writes first. Everything goes through GitHub; there's no server:
458
+ For several people in one repository, each with their own agents. Without it, two developers' agents can take the same story or edit the same files, and work drifts from what the team agreed until someone reads every branch by hand. Teams add who owns what, who's working on what right now, and what was agreed. Not every developer works in a team, so it's off until you set it up: `/code-kit:init` asks whether others work in the repository, and `/code-kit:team-init` sets the team up (or changes it, or takes it out) at any time, asking for the tech lead and each lane's owners and showing what it writes first. With GitHub as the provider (the default) everything goes through GitHub, with no server:
435
459
 
436
460
  - **Owners and claims.** A lane's owners are the only ones whose agents work it. Making a story's branch claims the story, through a ref in the shared repository, so two people can't both take it. The lead says what files the story will change (`team claim --lease`), and each commit adds what it changed; another person's agent editing a leased file is refused with who holds it. A story that carries out an intent says so on its claim (`team claim --intent`).
437
461
  - **Drift holds a merge.** With a hosted provider that checks each push for drift, and whose setting says what blocks a merge (a finding against a spec or decision, any finding, or nothing), the merge queue holds a branch while it has an open finding at that level. `queue`, `queue merge` and `next` say which finding, that the tech lead decides, and how it clears: resolved on the provider, or a push the drift check no longer finds conflicting. GitHub alone checks no drift, so it never holds; a provider that can't be reached holds nothing, and code-kit says so.
@@ -439,7 +463,8 @@ For several people in one repository, each with their own agents. Not every deve
439
463
  - **Since you last looked.** `code-kit team since` says, by person, what was pushed, opened, merged, reviewed, claimed and intended. The Team pane shows it.
440
464
  - **`/team`** opens the Team pane: the tech lead, who you are, and what coordinates the team (GitHub, or a hosted provider, and whether it's live). Its tabs: **People**, each person with their lanes, where they're at work (with a live provider), claims, pull requests and intents; **Since you looked**; **Claims**, with Keep and Release on yours, and Release and Reassign for the tech lead; **Intents**, with Agree and Drop for the tech lead; **Drift**, when the provider checks for it; and **Setup**, the team's config and what GitHub still needs.
441
465
  - **Stale claims** (nothing pushed for three working days) are flagged, never released on their own: the holder keeps or releases it, and the tech lead can reassign it.
442
- - **GitHub does its part.** `code-kit team codeowners --write` writes CODEOWNERS from the config, and `"board": { "owner", "number" }` mirrors the plan onto a GitHub Project.
466
+ - **GitHub does its part.** `code-kit team codeowners --write` writes CODEOWNERS from the config, and `"board": { "owner", "number" }` mirrors the plan onto a GitHub Project. Writing to the board needs the `project` permission on your `gh` sign-in (`gh auth refresh -s project`).
467
+ - **When GitHub can't be reached**, claims and leases can't be checked, and code-kit says so; every local rule still holds. A hosted provider with `fallback: "github"` hands its operations to GitHub while it's down.
443
468
 
444
469
  It's a preview: it's tested end to end against a stand-in for GitHub, and has been run once against a real private repository (claims, leases, intents as discussions, decision records, since-you-last-looked and the Project board). Spec: `docs/specs/16-teams.md`.
445
470
 
@@ -516,7 +541,7 @@ code-kit cost [--json] # each environmen
516
541
  code-kit decisions [--json] [--all] # what waits on you in this session, and a count in each other one; --all lists every session's
517
542
  code-kit who # which session this is, whether it leads the project, and its task
518
543
  code-kit sessions [--json] # the sessions working the project, which one leads, and each one's task
519
- code-kit sessions lead [stream] # make this session the lead, or its stream's lead (the person's own act, as Lead from here)
544
+ code-kit sessions lead [stream] # make this session the lead, or its stream's lead (the person's own act: /code-kit:lead runs it as they send it)
520
545
  code-kit sessions stream <name> # a working session joins a stream (the person's own act)
521
546
  code-kit streams [--json] # the project's streams: each one's lanes, plan and lead, and the core lanes they share
522
547
  code-kit core [--json] # change requests to core; core ask "<what>" --story ST-n asks the platform, core accept <id> --story ST-n | core decline <id> --reason "…" decides
@@ -643,7 +668,7 @@ Every refusal that an approval would allow is recorded as a request in `.claude/
643
668
 
644
669
  ### Who decides what
645
670
 
646
- You're the product owner: you set the guardrails and decide what crosses them, which is the specs, the screens' visual design, CI and the pipelines, the kit, product questions the spec doesn't answer, and anything with production, cost or strategy implications. The lead is the technical lead and decides everything technical. With no `approvals.delegate`, that's the default: the lead approves packages within the registry rules, every protected change but `spec`, `design`, `ci` and `kit`, merges into the base (merging isn't releasing; your pipelines decide what reaches production), and weakened tests on a lane's branch after its review. `approvals.delegate` draws the line differently where you want it to: what it names is the lead's, the rest is yours, and `false` keeps everything for you. Change it in the Settings tab's Approvals section, or `code-kit settings set approvals.<name> lead|person --reason "…"`.
671
+ You're the product owner: you set the guardrails and decide what crosses them, which is the specs, the screens' visual design, CI and the pipelines, the kit, product questions the spec doesn't answer, and anything with production, cost or strategy implications. The lead is the technical lead and decides everything technical. With no `approvals.delegate`, that's the default: the lead approves packages within the registry rules, every protected change but `spec`, `design`, `ci` and `kit`, merges into the base (merging isn't releasing; your pipelines decide what reaches production), and weakened tests on a lane's branch after its review. `approvals.delegate` draws the line differently where you want it to: what it names is the lead's, the rest is yours, and `false` keeps everything for you. Change it in `/harness`, whose Approvals section lists each approval as yours or the lead's, or with `code-kit settings set approvals.<name> lead|person --reason "…"`.
647
672
 
648
673
  ```json
649
674
  "approvals": { "delegate": { "protected": ["schema", "truth"], "dependencies": {} } }
@@ -670,6 +695,8 @@ code-kit approve pillow --lane api --delegated --story ST-138 --reason "MED-5 ne
670
695
 
671
696
  ## Vibe
672
697
 
698
+ Under `autonomous`, every guardrail that stays yours (a spec, a design, CI, a package past the registry rules) stops the build until you come back. Vibe is for a build you want done without you. `/code-kit:init` offers it as the fourth answer to how hands-off the build is; switch to it later in `/harness`, or with `code-kit settings set harness.autonomy vibe --reason "…"`.
699
+
673
700
  Once the spec is done and code-kit is set up, `"harness": { "autonomy": "vibe" }` hands the whole build to the lead. The loop runs as under `autonomous`, and every decision the person would make is the lead's: the specs for later milestones, the screens' designs, CI, the kit, the standards, weakened tests (its own branches included), packages (beyond the registry's rules too, recorded with the rules each breaks), merges and pushes to the base (never by force). Whatever `approvals.delegate` says is set aside. The lead answers the brief's open questions and spec-design's, spec-check's and review's itself, recording each in the brief's decision log.
674
701
 
675
702
  The person is asked only for what nobody else can give: `code-kit ask "…" --needs account|key|payment|outside` (an account with a service provider, an API key or secret, a payment, an act outside the repository such as DNS). Under vibe, `code-kit ask` refuses a question without `--needs`, and the lead builds everything else meanwhile. The project's `shell.block` rules, and the person's own acts (pausing the loop, choosing the lead session, changing the harness settings), stay as they are. What vibe gives up: nobody but the lead looks at a decision before it's built on, and a push to the base can deploy.
package/bin/code-kit.mjs CHANGED
@@ -241,9 +241,12 @@ import {
241
241
  coreRequests,
242
242
  decideCore,
243
243
  hasStreams,
244
+ heldByCore,
245
+ lastTurn,
244
246
  platformOf,
245
247
  sharedLanes,
246
248
  streamOfLane,
249
+ streamOfStory,
247
250
  streamsOf,
248
251
  } from '../hooks/lib/streams.mjs';
249
252
  import {
@@ -388,6 +391,8 @@ function checkJson() {
388
391
  Object.entries(config.lanes).map(([name, l]) => [name, { agent: l.agent, paths: l.paths }]),
389
392
  );
390
393
  report.adapters = config.adapters;
394
+ // STRM-10: the streams' names, for the mod to read them.
395
+ report.streams = streamsOf(config).map((st) => st.name);
391
396
  report.docs = config.docs ?? null;
392
397
  report.harness = config.harness;
393
398
  // The harness settings the person chose, as opposed to defaults: the mod asks before acting on autonomy.
@@ -3652,8 +3657,21 @@ function streamsCommand() {
3652
3657
  const root = resolve('.');
3653
3658
  const all = streamsOf(config);
3654
3659
  const claims = laneClaims(root);
3660
+ // STRM-10: what the mod scopes a stream lead's views to: each stream's stories and requirements, the
3661
+ // stories core holds, and what it asks of core or has to decide for it.
3662
+ const stories = config.docs?.plan ? readStories(root, config.docs.plan) : [];
3663
+ const requirements = config.docs?.specs ? readRequirements(root, config.docs.specs) : [];
3664
+ const held = heldByCore(
3665
+ root,
3666
+ stories.map((s) => ({ id: s.id, state: s.status })),
3667
+ );
3668
+ const asks = coreRequests(root).filter((r) => r.state === 'open');
3669
+ const candidates = promotions(root).filter((c) => c.state === 'open');
3670
+ const me = callerSession ? readSession(root, callerSession) : null;
3655
3671
  const rows = all.map((st) => {
3656
3672
  const lead = leadSession(root, Date.now(), st.name);
3673
+ const own = stories.filter((s) => streamOfStory(config, s) === st.name);
3674
+ const cited = new Set(own.flatMap((s) => s.requirements));
3657
3675
  return {
3658
3676
  ...st,
3659
3677
  lead: lead
@@ -3662,13 +3680,28 @@ function streamsCommand() {
3662
3680
  running: claims
3663
3681
  .filter((c) => st.lanes.includes(c.lane))
3664
3682
  .map((c) => ({ lane: c.lane, story: c.story })),
3683
+ stories: own.map((s) => s.id),
3684
+ requirements: requirements
3685
+ .filter((r) => cited.has(r.id) || (st.specs.length && matchesAny(r.file, st.specs)))
3686
+ .map((r) => r.id),
3687
+ held: own.filter((s) => held.has(s.id)).map((s) => ({ story: s.id, why: held.get(s.id) })),
3688
+ asks: asks.filter((r) => r.stream === st.name).map((r) => r.id),
3689
+ toDecide: [
3690
+ ...(st.platform ? asks.map((r) => r.id) : []),
3691
+ ...candidates.filter((c) => decidedFor(config, c) === st.name).map((c) => c.id),
3692
+ ],
3665
3693
  };
3666
3694
  });
3667
3695
  const shared = sharedLanes(config).map((lane) => ({
3668
3696
  lane,
3669
3697
  running: claims.find((c) => c.lane === lane)?.story ?? null,
3698
+ turn: lastTurn(root, lane),
3670
3699
  }));
3671
- if (flag('--json')) return out(JSON.stringify({ streams: rows, shared }, null, 2));
3700
+ // The streams this session leads, or, a working session's, the one it works in.
3701
+ const mine = rows
3702
+ .filter((r) => (callerSession && r.lead?.session === callerSession) || r.name === me?.stream)
3703
+ .map((r) => r.name);
3704
+ if (flag('--json')) return out(JSON.stringify({ streams: rows, shared, mine }, null, 2));
3672
3705
  if (!all.length)
3673
3706
  return out(
3674
3707
  "This project isn't built as streams: one lead runs every lane. docs/specs/31-streams-and-platform.md says how to add them.",
@@ -246,7 +246,7 @@ if (
246
246
  runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+sessions\s+(lead|beat|stream)\b`))
247
247
  )
248
248
  block(
249
- `Blocked: which session leads the project is recorded by code-kit, and choosing it is the person's own act (Lead from here, in the code-kit band, or \`code-kit sessions lead\` in their terminal). Carry on with your work.\nCommand: ${cmd}`,
249
+ `Blocked: which session leads the project is recorded by code-kit, and choosing it is the person's own act (they type \`/code-kit:lead\`, with the stream in a project built as streams, or use Lead from here in the code-kit band). Carry on with your work.\nCommand: ${cmd}`,
250
250
  );
251
251
  // TEAM-9: handing someone's claim to someone else is the tech lead's own decision too.
252
252
  if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+team\s+reassign\b`)))
package/hooks/hooks.json CHANGED
@@ -166,6 +166,17 @@
166
166
  }
167
167
  ]
168
168
  }
169
+ ],
170
+ "UserPromptSubmit": [
171
+ {
172
+ "hooks": [
173
+ {
174
+ "type": "command",
175
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/lead-prompt.mjs\"",
176
+ "timeout": 10
177
+ }
178
+ ]
179
+ }
169
180
  ]
170
181
  }
171
182
  }
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env node
2
+ // UserPromptSubmit (docs/specs/23-the-team.md, SESS-2; docs/specs/31-streams-and-platform.md, STRM-2):
3
+ // the person typing `/code-kit:lead [stream]` is their own choice of lead, so it's recorded as the prompt
4
+ // arrives. The agent can't run `sessions lead` itself (guard-bash refuses it); the skill only confirms.
5
+ import { spawnSync } from 'node:child_process';
6
+ import { readFileSync } from 'node:fs';
7
+ import { fileURLToPath } from 'node:url';
8
+ import { loadConfig } from './lib/config.mjs';
9
+ import { mainCheckoutLead, memberOf, readSession } from './lib/sessions.mjs';
10
+ import { hasStreams } from './lib/streams.mjs';
11
+ import { projectDir } from './lib/rules.mjs';
12
+
13
+ let input = {};
14
+ try {
15
+ input = JSON.parse(readFileSync(0, 'utf8') || '{}');
16
+ } catch {
17
+ // no input: nothing to do
18
+ }
19
+ const asked = String(input.prompt ?? '').match(/^\s*\/(?:code-kit:)?lead(?:\s+(\S+))?\s*$/);
20
+ const session = input.session_id ?? null;
21
+ const project = projectDir();
22
+ const { config } = loadConfig(project);
23
+ if (!asked || !session || !config) process.exit(0);
24
+
25
+ const cli = fileURLToPath(new URL('../bin/code-kit.mjs', import.meta.url));
26
+ const run = spawnSync(
27
+ process.execPath,
28
+ [cli, 'sessions', 'lead', ...(asked[1] ? [asked[1]] : []), '--session', session],
29
+ { cwd: project, encoding: 'utf8' },
30
+ );
31
+ const said = (run.status === 0 ? run.stdout : run.stderr).trim();
32
+ let note =
33
+ run.status === 0
34
+ ? `code-kit: the person ran /code-kit:lead, so code-kit recorded it as they sent it. ${said}`
35
+ : `code-kit: the person ran /code-kit:lead, and code-kit couldn't record it: ${said}`;
36
+ // STRM-2: one lead holds the main checkout; another stream's lead works from a worktree of its own.
37
+ const holder = run.status === 0 && hasStreams(config) ? mainCheckoutLead(project) : null;
38
+ if (holder && holder.id !== session)
39
+ note += ` The ${holder.stream ?? 'project'} lead (${memberOf(holder)}) holds the main checkout, so lead from a worktree of your own on lead/${readSession(project, session)?.stream ?? 'work'} (EnterWorktree), unless this session already works in one.`;
40
+ process.stdout.write(
41
+ JSON.stringify({
42
+ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: note },
43
+ }),
44
+ );
@@ -127,6 +127,12 @@ export function laneOfFile(rel, config) {
127
127
  : null;
128
128
  }
129
129
 
130
+ /** STRM-10: each layer's owner in a project built as streams: its stream, or `core`; {} without streams. */
131
+ function ownersOf(config) {
132
+ if (!config.streams) return {};
133
+ return Object.fromEntries(config.layers.map((l) => [l.name, l.stream ?? 'core']));
134
+ }
135
+
130
136
  /**
131
137
  * MAP-1: a story's code: { story, layers, files: [{ path, layer, lane, imports }] }. `layers` are the
132
138
  * config's layers in their order, then `tests` and `other` where any file falls there; each file's
@@ -160,6 +166,8 @@ export function storyMap(root, story, config, from) {
160
166
  return {
161
167
  story: { id: story.id, title: story.title, lane: story.lane, state: story.state },
162
168
  layers,
169
+ // STRM-10: in a project built as streams, whose each layer is: a stream's module, or core.
170
+ owners: ownersOf(config),
163
171
  files,
164
172
  };
165
173
  }
@@ -255,6 +263,8 @@ export function projectMap(root, config, tracked, { depth = 3, most = 60 } = {})
255
263
  return {
256
264
  story: { id: PROJECT, title: 'The whole project', lane: null, state: null },
257
265
  layers,
266
+ // STRM-10: in a project built as streams, whose each layer is: a stream's module, or core.
267
+ owners: ownersOf(config),
258
268
  files,
259
269
  };
260
270
  }
@@ -662,7 +662,8 @@ export function board(view, els, on) {
662
662
  children: [
663
663
  statusLine(
664
664
  'build',
665
- 'Build',
665
+ // STRM-10: a stream's lead builds its own stream.
666
+ view.scope ? `Build: ${view.scope}` : 'Build',
666
667
  loopWord,
667
668
  progress ? `${progress.tested}/${progress.total}` : null,
668
669
  loopWord === 'moving'
@@ -1168,7 +1169,7 @@ export function board(view, els, on) {
1168
1169
  children: [
1169
1170
  statusLine(
1170
1171
  'lanes',
1171
- 'Lanes',
1172
+ view.scope ? `Lanes: ${view.scope}` : 'Lanes',
1172
1173
  atWork.length
1173
1174
  ? `${atWork.length} at work${needle ? ` · filter "${ui.search}"` : ''}`
1174
1175
  : 'all resting',
@@ -1245,6 +1246,15 @@ export function board(view, els, on) {
1245
1246
  ),
1246
1247
  ]
1247
1248
  : []),
1249
+ // STRM-10: the rest of the project, a line per other stream and one for the shared core lanes, and
1250
+ // what core holds of this stream's.
1251
+ ...(view.streams ?? []).map((l) =>
1252
+ text(l.text, {
1253
+ key: `stream-line-${l.key}`,
1254
+ wrap: 'truncate-end',
1255
+ ...(l.tone === 'note' ? { color: 'yellow' } : { dimColor: true }),
1256
+ }),
1257
+ ),
1248
1258
  ],
1249
1259
  });
1250
1260
 
@@ -1585,6 +1595,8 @@ export function bandOf(view, els, onAction) {
1585
1595
  flexDirection: 'row',
1586
1596
  columnGap: 1,
1587
1597
  children: [
1598
+ // STRM-10: whose build the line is, in a project built as streams.
1599
+ ...(view.scope ? [text(view.scope, { bold: true })] : []),
1588
1600
  ...(progress?.name ? [text(progress.name, { dimColor: true })] : []),
1589
1601
  ...(runs.length
1590
1602
  ? [
@@ -65,6 +65,8 @@ export function layout(map, width = 100) {
65
65
  // A gutter of GUTTER cells left of each column carries the imports between files of one layer.
66
66
  const columns = layers.map((layer, i) => ({
67
67
  layer,
68
+ // STRM-10: a column says whose layer it is, core or a stream's module.
69
+ label: map.owners?.[layer] ? `${layer} · ${map.owners[layer]}` : layer,
68
70
  x: GUTTER + i * (colW + COL_GAP),
69
71
  width: colW,
70
72
  }));
@@ -118,7 +120,7 @@ export function mapRows(map, { glow = {}, selected = null, width = 100 } = {}) {
118
120
  grid[y][x] = { ch, style, ...(lane ? { lane } : {}) };
119
121
  };
120
122
  for (const c of L.columns) {
121
- const label = fit(c.layer, c.width);
123
+ const label = fit(c.label ?? c.layer, c.width);
122
124
  [...label].forEach((ch, i) => put(c.x + i, 0, ch, 'dim'));
123
125
  }
124
126
  // Edges first, so the boxes draw over their ends: from the importer's side to the imported's.
@@ -248,7 +250,7 @@ export function mapSvg(map, { glow = {}, selected = null, tints = {}, width = 10
248
250
  const parts = [];
249
251
  for (const c of L.columns)
250
252
  parts.push(
251
- `<text x="${10 + c.x * CW}" y="${10 + RH * 0.8}" fill="#7f8c8d" font-size="11">${esc(c.layer)}</text>`,
253
+ `<text x="${10 + c.x * CW}" y="${10 + RH * 0.8}" fill="#7f8c8d" font-size="11">${esc(c.label ?? c.layer)}</text>`,
252
254
  );
253
255
  for (const f of map.files)
254
256
  for (const target of f.imports) {
@@ -109,6 +109,14 @@ import { goalOf, nextText } from './mission.mjs';
109
109
  import { contextOf, decisionCards, decisionKey, newDecisions } from './decisions.mjs';
110
110
  import { DEFAULT_TEAM_UI, TEAM_ID, teamFrame } from './teamview.mjs';
111
111
  import { glowOf, mapStoryOf, touchOf } from './codemap.mjs';
112
+ import {
113
+ scopeOf,
114
+ scopeWord,
115
+ scopedCheck,
116
+ scopedState,
117
+ scopedStatus,
118
+ streamLines,
119
+ } from './streamview.mjs';
112
120
  import { harnessSettings } from '../lib/harness.mjs';
113
121
  import {
114
122
  REVIEW_WAIT_MS,
@@ -377,7 +385,13 @@ export function register(on) {
377
385
  const check = parseJson(ran.stdout);
378
386
  const valid = Boolean(check?.valid);
379
387
  const status = valid ? await json('status') : null;
380
- const nextStep = valid ? await json('next') : null;
388
+ const nextStep = valid ? await json('next', '--session', session) : null;
389
+ // STRM-10: in a project built as streams, this session's views are its own streams'.
390
+ const streams =
391
+ valid && check.streams?.length
392
+ ? await json('streams', '--session', session).catch(() => null)
393
+ : null;
394
+ const scope = scopeOf(streams);
381
395
  const all = valid ? await json('requests') : null;
382
396
  // OWN-1: this session's decisions, and how many wait in each other session; null from a code-kit
383
397
  // that can't say, where every open decision shows.
@@ -443,11 +457,16 @@ export function register(on) {
443
457
  const atWork = agentsAtWork(await $.agent.list().catch(() => []));
444
458
  const before = { state: model.state, status: model.status, queue: model.queue };
445
459
  model = {
446
- state: projectState(check, status, nextStep, atWork),
460
+ state: scopedState(
461
+ projectState(scopedCheck(check, scope), scopedStatus(status, scope), nextStep, atWork),
462
+ scope,
463
+ ),
447
464
  requests,
448
465
  stops,
449
466
  queue,
450
- status,
467
+ status: scopedStatus(status, scope),
468
+ streams,
469
+ scope,
451
470
  timeline,
452
471
  adapters,
453
472
  check,
@@ -1381,7 +1400,18 @@ export function register(on) {
1381
1400
  return lease.mine;
1382
1401
  },
1383
1402
  // LOOP-10: the person moves the loop to this session; the other stops prompting its lead.
1384
- leadHere: async () => {
1403
+ leadHere: async (line) => {
1404
+ // STRM-10: a stream chosen to lead from here becomes this session's stream first.
1405
+ if (line?.stream) {
1406
+ const ran = await $.process
1407
+ .run(['node', cli, 'sessions', 'lead', line.stream, '--session', session], { cwd })
1408
+ .catch(() => ({ exitCode: 1, stderr: '', stdout: '' }));
1409
+ if (ran.exitCode !== 0) {
1410
+ notice = `This session couldn't lead ${line.stream}: ${firstLine(ran) || 'code-kit sessions lead failed'}.`;
1411
+ $.ui.invalidate('ui.render');
1412
+ return;
1413
+ }
1414
+ }
1385
1415
  if (!(await act.lead({ take: true }))) {
1386
1416
  notice = "This session couldn't take the loop: code-kit loop lead failed.";
1387
1417
  $.ui.invalidate('ui.render');
@@ -1816,7 +1846,9 @@ export function register(on) {
1816
1846
  }
1817
1847
  return act.submit(prompt, 'restart', story);
1818
1848
  }
1819
- const ran = await $.process.run(['node', cli, 'next', '--json'], { cwd });
1849
+ const ran = await $.process.run(['node', cli, 'next', '--json', '--session', session], {
1850
+ cwd,
1851
+ });
1820
1852
  // LOOP-13: a parked story stays out of the step until what it waits on moves.
1821
1853
  await act.unpark();
1822
1854
  // LOOP-9: never a story an agent is already at work on, building or reviewing it.
@@ -3162,6 +3194,8 @@ export function register(on) {
3162
3194
  {
3163
3195
  state,
3164
3196
  status: model.status ?? null,
3197
+ scope: scopeWord(model.scope),
3198
+ streams: streamLines(model.streams, model.scope),
3165
3199
  loop: loopView,
3166
3200
  needs,
3167
3201
  live,
@@ -3281,6 +3315,7 @@ export function register(on) {
3281
3315
  {
3282
3316
  state: stateNow(),
3283
3317
  status: model.status ?? null,
3318
+ scope: scopeWord(model.scope),
3284
3319
  loop: { ...loopNow(now), queue: model.queue ?? [] },
3285
3320
  needs: needsOf(linesNow(now)),
3286
3321
  leadBusy: Boolean(leadTurn),
@@ -0,0 +1,95 @@
1
+ // Streams in the mod (docs/specs/31-streams-and-platform.md, STRM-10): a stream's lead sees its own
2
+ // stream's build. The project's state is scoped to the streams this session leads (or works in), and
3
+ // the rest of the project is a line per other stream, and one for the core lanes they share.
4
+
5
+ /**
6
+ * STRM-10: what this session's views are scoped to, from `code-kit streams --json`: the streams it leads
7
+ * or works in, their lanes with the shared core lanes, their stories and their requirements. Null in a
8
+ * project without streams, or for a session in none, which sees the whole project.
9
+ */
10
+ export function scopeOf(streams) {
11
+ const mine = (streams?.streams ?? []).filter((s) => (streams.mine ?? []).includes(s.name));
12
+ if (!mine.length) return null;
13
+ return {
14
+ names: mine.map((s) => s.name),
15
+ label: mine.map((s) => s.label ?? s.name).join(', '),
16
+ lanes: new Set([...mine.flatMap((s) => s.lanes), ...(streams.shared ?? []).map((x) => x.lane)]),
17
+ stories: new Set(mine.flatMap((s) => s.stories ?? [])),
18
+ requirements: new Set(mine.flatMap((s) => s.requirements ?? [])),
19
+ };
20
+ }
21
+
22
+ /** STRM-10: `code-kit check --json` with only the scope's lanes, so the Lanes panel draws its own. */
23
+ export function scopedCheck(check, scope) {
24
+ if (!scope || !check?.lanes) return check;
25
+ return {
26
+ ...check,
27
+ lanes: Object.fromEntries(
28
+ Object.entries(check.lanes).filter(([name]) => scope.lanes.has(name)),
29
+ ),
30
+ };
31
+ }
32
+
33
+ /**
34
+ * STRM-10: `code-kit status --json` with only the scope's stories and requirements, so the Build bar,
35
+ * the milestone and the Trail count its own stream's.
36
+ */
37
+ export function scopedStatus(status, scope) {
38
+ if (!scope || !status) return status;
39
+ return {
40
+ ...status,
41
+ stories: (status.stories ?? []).filter((s) => scope.stories.has(s.id)),
42
+ requirements: (status.requirements ?? []).filter((r) => scope.requirements.has(r.id)),
43
+ };
44
+ }
45
+
46
+ /** STRM-10: the stories ready to start, less other streams': `next` gives a stream's lead its own. */
47
+ export function scopedState(state, scope) {
48
+ if (!scope || state?.kind !== 'ok') return state;
49
+ return { ...state, ready: state.ready.filter((r) => scope.stories.has(r.id)) };
50
+ }
51
+
52
+ /**
53
+ * STRM-10: the rest of the project, a line each: every other stream with its lead and what its lanes are
54
+ * on, then the core lanes the streams share with whose turn each is. And, for this session's streams,
55
+ * the stories core holds and what is theirs to decide for core. [{ key, text, tone }], tone 'dim' or
56
+ * 'note'.
57
+ */
58
+ export function streamLines(streams, scope) {
59
+ if (!streams?.streams?.length) return [];
60
+ const lines = [];
61
+ for (const s of streams.streams) {
62
+ if (scope?.names.includes(s.name)) {
63
+ for (const h of s.held ?? [])
64
+ lines.push({ key: `held-${h.story}`, text: h.why, tone: 'note' });
65
+ if (s.toDecide?.length)
66
+ lines.push({
67
+ key: `decide-${s.name}`,
68
+ text: `for core: ${s.toDecide.join(', ')} ${s.toDecide.length === 1 ? 'is' : 'are'} the ${s.label ?? s.name} lead's to decide`,
69
+ tone: 'note',
70
+ });
71
+ continue;
72
+ }
73
+ const at = (s.running ?? []).map((r) => `${r.lane} ${r.story ?? 'a story'}`);
74
+ lines.push({
75
+ key: `stream-${s.name}`,
76
+ text: `${s.label ?? s.name}${s.platform ? ' (platform)' : ''} · ${s.lead ? `led by ${s.lead.member}` : 'no lead'} · ${at.length ? at.join(', ') : 'no lane at work'}`,
77
+ tone: 'dim',
78
+ });
79
+ }
80
+ const shared = streams.shared ?? [];
81
+ if (shared.length)
82
+ lines.push({
83
+ key: 'shared',
84
+ text: `core, shared in turns: ${shared.map((x) => `${x.lane}${x.running ? ` on ${x.running}` : ''}${x.turn ? ` (${x.turn}'s turn last)` : ''}`).join(', ')}`,
85
+ tone: 'dim',
86
+ });
87
+ return lines;
88
+ }
89
+
90
+ /** STRM-10: the band's word for the scope: "play" heads the build line, so a lead knows whose it is. */
91
+ export const scopeWord = (scope) => (scope ? scope.label : null);
92
+
93
+ /** STRM-10: the streams with no lead, each offered as a stream to lead from here. */
94
+ export const leaderless = (streams) =>
95
+ (streams?.streams ?? []).filter((s) => !s.lead).map((s) => s.name);
@@ -301,6 +301,7 @@ export function bandLines({
301
301
  working = false,
302
302
  task = null,
303
303
  elsewhere = [],
304
+ streams = null,
304
305
  }) {
305
306
  // SESS-3: a working session's lines are only its own: no queue, reviews or team. The build's own
306
307
  // progress, the loop's state and the agents at work are the Build panel's and the band's one line
@@ -549,6 +550,15 @@ export function bandLines({
549
550
  text: `Milestone done: ${plural(loop.doneCount, 'story', 'stories')} merged`,
550
551
  actions: [{ id: 'dismissDone', label: 'Dismiss' }],
551
552
  });
553
+ else if ((loop?.state === 'elsewhere' || loop?.state === 'unled') && streams?.streams?.length)
554
+ // STRM-10: in a project built as streams, a stream to lead from here, each with who leads it now.
555
+ for (const s of streams.streams.filter((x) => !(streams.mine ?? []).includes(x.name)))
556
+ lines.push({
557
+ kind: 'loop',
558
+ text: `${s.label ?? s.name}: ${s.lead ? `led by ${s.lead.member}` : 'no session leads it'}`,
559
+ stream: s.name,
560
+ actions: [{ id: 'leadHere', label: `Lead ${s.name}` }],
561
+ });
552
562
  else if (loop?.state === 'elsewhere' || loop?.state === 'unled')
553
563
  // SESS-2: another session leads the project, or none does; this one never prompts its lead.
554
564
  lines.push({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.36.0",
3
+ "version": "0.37.0",
4
4
  "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
5
5
  "license": "MIT",
6
6
  "author": "Warren Langeveldt",
@@ -61,7 +61,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
61
61
  - `agent`: a kebab-case agent name, for example `api-engineer`;
62
62
  - `paths` and `exclude`: every path must have exactly one owner.
63
63
  - `label` (optional): what the lane delivers, in a few words ("Screens", "Tests"), when its name doesn't say it.
64
- - **`streams` (spec 31), only when the product has separate product lines:** the architecture says so (a core and a module per line), or, without specs, ask once: "Do separate teams, or sessions, build separate product lines of this product?" If not, leave `streams` out: one lead runs every lane, as before. If so:
64
+ - **`streams` (spec 31), only when the product has separate product lines:** when the architecture lays out a core and a module per line, draft them. When the brief, the specs or the plan name more than one product line or offering (for different users, on a shared platform), or there are no specs, ask once: "Do separate teams, or sessions, build separate product lines of this product?", naming the lines you found. If not, leave `streams` out: one lead runs every lane, as before. If so:
65
65
  - `docs.plan` is a folder (`docs/plan/`) and each stream has its own plan file in it;
66
66
  - `"streams": { "<line>": { "label", "lanes", "plan", "specs" } }`, each lane in exactly one stream: a line's lanes own its modules (`api-<line>`, `web-<line>`);
67
67
  - each module's layer gets `"stream": "<line>"`; core's layers have none. The import check then refuses a module importing another line's module, and core importing a module;
@@ -81,8 +81,8 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
81
81
  - **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
82
82
  - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
83
83
  - **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
84
- - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the four choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), `off`, or `vibe` (it keeps going on its own, and every product and project decision is the lead's: the specs for later milestones, the designs, CI, the standards, packages, weakened tests, merges and pushes; they're asked only for what nobody else can give, an account with a service provider, a key from one, a payment, or an act outside the repository). Say what vibe gives up: nobody but the lead reviews a decision before it's built on, and a push to the base can deploy. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes. With `vibe`, leave `approvals.delegate` out: vibe delegates everything, whatever it says, and the Settings tab shows every approval as the lead's.
85
- - **`approvals.delegate`, who decides what (HELM-1, WHO-1):** the person is the product owner; the lead decides everything technical, so lanes ask the lead, never the person. With no `approvals.delegate`, that's the default: the lead approves new packages (only when the story's requirements need them and they fit the spec, the principles and the architecture; npm packages must also pass the registry limits on licence, popularity and age), every protected change except the specs (`spec`), the screens' designs (`design`), CI (`ci`) and the kit, merges into the base, and weakened tests on a lane's branch after its review. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. Only if they do, draft `approvals.delegate` with exactly what the lead keeps (`{ "protected": [...], "merge": true, "tests": true, "dependencies": {} }`, leaving out what they keep), or `false` to keep everything. They can change it later in the Settings tab's Approvals section.
84
+ - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the four choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), `off`, or `vibe` (it keeps going on its own, and every product and project decision is the lead's: the specs for later milestones, the designs, CI, the standards, packages, weakened tests, merges and pushes; they're asked only for what nobody else can give, an account with a service provider, a key from one, a payment, or an act outside the repository). Say what vibe gives up: nobody but the lead reviews a decision before it's built on, and a push to the base can deploy. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes. With `vibe`, leave `approvals.delegate` out: vibe delegates everything, whatever it says, and `/harness`'s Approvals section shows every approval as the lead's.
85
+ - **`approvals.delegate`, who decides what (HELM-1, WHO-1):** the person is the product owner; the lead decides everything technical, so lanes ask the lead, never the person. With no `approvals.delegate`, that's the default: the lead approves new packages (only when the story's requirements need them and they fit the spec, the principles and the architecture; npm packages must also pass the registry limits on licence, popularity and age), every protected change except the specs (`spec`), the screens' designs (`design`), CI (`ci`) and the kit, merges into the base, and weakened tests on a lane's branch after its review. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. Only if they do, draft `approvals.delegate` with exactly what the lead keeps (`{ "protected": [...], "merge": true, "tests": true, "dependencies": {} }`, leaving out what they keep), or `false` to keep everything. They can change it later in `/harness`'s Approvals section.
86
86
  - **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so most stories don't need the session's model. Recommend `story`: each story runs on the model its `**Size:**` in the plan gives (Haiku for small, Sonnet for medium, Opus for large), raised to Opus for a security requirement, to Sonnet at least for a fix, and one step for each time its branch is sent back. Offer one model for every lane (`sonnet`) as the simpler choice, and say the lead, the reviewer and the security reviewer keep their own models either way. A lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "story" } }`, or leave it out for the session's model. A project set up before sizes existed has stories with none, which run on Sonnet until the lead sizes them.
87
87
  - **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their band and the pane's Needs you: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
88
88
  - **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
@@ -191,6 +191,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
191
191
  - the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
192
192
  - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
193
193
  - project standards, when the project has no `docs/standards.md`: suggest them as section 2's Standards describes, moving the engineering rules out of `docs/principles.md`, and protect the file.
194
+ - streams, when the config has no `streams` (whatever its `setup`) and the brief, the specs or the plan name more than one product line: ask the question section 2 gives, naming the lines, and on a yes draft them as section 4 describes.
194
195
  - a running budget, when the config has no `cost` (whatever its `setup`): ask the person for it as section 2 describes. Then cost what's already defined in the infrastructure files, or deployed, into `docs/costs.md`, a row per paid thing at its real size, and run `code-kit cost`. When it's over the budget, bring the person options that fit (spec-design's architecture step lists the kinds), each with what it gives up and what it saves a month, and record their choice in the brief's decision log; the stories that bring it within budget go in the plan.
195
196
  3. **Show the difference:**
196
197
 
@@ -201,7 +202,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
201
202
 
202
203
  `diff` lists lanes, layers, checks and rules that were added (`+`), removed (`-`) or changed (`~`), and how many files change owner, route by route. Explain each change in a sentence, with where it came from: the doc section, or the folder in the repository.
203
204
 
204
- 4. **Adding streams to a project that started as one (spec 31):** when the person now builds separate product lines, draft `streams` as in section 2, splitting each technical lane into a core lane and a lane per line, and each layer into core and a module per line. Where the code isn't split into those folders yet, don't move it in the update: write the move as stories (in the platform's plan, or the lead's own), lower layers first, a few files each, every story switching the code that imports what it moved, and say so in the diff. Until a story moves a file, the file stays with the lane that owns it today.
205
+ 4. **Adding streams to a project that started as one (spec 31):** when the person says they now build separate product lines, or answers yes to the question above, draft `streams` as in section 2, splitting each technical lane into a core lane and a lane per line, and each layer into core and a module per line. Where the code isn't split into those folders yet, don't move it in the update: write the move as stories (in the platform's plan, or the lead's own), lower layers first, a few files each, every story switching the code that imports what it moved, and say so in the diff. Until a story moves a file, the file stays with the lane that owns it today.
205
206
  5. **Also propose:**
206
207
  - agent files for new lanes, and updates to agents whose paths changed, and to the security reviewer when the specs' threat models changed;
207
208
  - **project skills**, by reading the recipes in the docs again and comparing them with `.claude/skills/`:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lead
3
- description: Make this Claude Code session the project's lead session (or, in a project built as streams, one stream's lead), where code-kit's loop runs and the plan's stories are dispatched from, when several sessions work one project. Says which session leads now and what moving the lead does, then gives the person the command that moves it. Use when the person says this session should lead, asks which session leads, or runs /code-kit:lead.
3
+ description: Make this Claude Code session the project's lead session (or, in a project built as streams, one stream's lead), where code-kit's loop runs and the plan's stories are dispatched from, when several sessions work one project. Running it moves the lead here as the person sends it; the skill confirms it and says what it means. Use when the person says this session should lead, asks which session leads, or runs /code-kit:lead.
4
4
  ---
5
5
 
6
6
  # Lead from this session
@@ -9,6 +9,14 @@ Several Claude Code sessions can work one project at once. One is the lead sessi
9
9
 
10
10
  The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root.
11
11
 
12
+ **When the person ran `/code-kit:lead`**, typing it was their choice: code-kit recorded this session as the lead (of the stream they named) as the prompt arrived, and its note in your context says so, or why it couldn't. Don't ask them to run anything. Run `who` to confirm, and tell them in a sentence or two what it means: which stream this session leads, its lanes and plan, and which session leads the rest. When the note says another lead holds the main checkout, move this session into a worktree of its own on the branch the note names (EnterWorktree) before you change anything. If the note says it couldn't (a stream that doesn't exist, say), tell them why and what the streams are.
13
+
14
+ ```bash
15
+ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" who
16
+ ```
17
+
18
+ **When the person asked in words** ("lead from this session"), and didn't run the command:
19
+
12
20
  1. See who leads now:
13
21
 
14
22
  ```bash
@@ -17,19 +25,9 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project
17
25
  ```
18
26
 
19
27
  2. If this session already leads, say so and stop.
20
- 3. Otherwise, tell the person what moving the lead does: this session starts running the loop and dispatching the plan's stories, and the session that led becomes a working session, which stops prompting its lead. Choosing the lead is theirs, so give them the command to run themselves (the hooks refuse it from an agent), or point them to **Lead from here** in the code-kit band:
28
+ 3. Otherwise, tell them what moving the lead does: this session starts running the loop and dispatching the plan's stories, and the session that led becomes a working session, which stops prompting its lead. Choosing the lead is theirs, and the hooks refuse it from an agent: they run `/code-kit:lead` (with the stream, in a project built as streams), or use **Lead from here** in the code-kit band.
21
29
 
22
- ```text
23
- ! node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sessions lead
24
- ```
25
-
26
- 4. Once they have, run `who` again and confirm this session leads.
27
-
28
- **A project built as streams** (`code-kit streams` lists them; spec 31) has a lead per stream, and they lead at once: each runs its own loop, dispatches only its own stream's lanes and stories, and writes only its own stream's plan and specs. The argument names the stream (`/code-kit:lead studio`). Give the person the command with it:
29
-
30
- ```text
31
- ! node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sessions lead <stream>
32
- ```
30
+ **A project built as streams** (`code-kit streams` lists them; spec 31) has a lead per stream, and they lead at once: each runs its own loop, dispatches only its own stream's lanes and stories, and writes only its own stream's plan and specs. The argument names the stream (`/code-kit:lead studio`).
33
31
 
34
32
  Moving one stream's lead leaves the other streams' leads as they are. The first lead works in the main checkout; every other stream's lead works in a worktree of its own (start the session with `claude --worktree`, or move it into one), on `lead/<stream>`, and its plan changes reach the base through the merge queue. A session that leads with no stream named leads every stream that has no lead of its own. A working session joins a stream with `sessions stream <name>`, the person's command too.
35
33