@warren-dean/code-kit 0.22.1 → 0.24.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.
@@ -100,6 +100,8 @@ let reviewing = new Set(); // stories the person asked the lead to review (ACT-3
100
100
  let reviewTurn = null; // 'next' until the lead's review turn starts, then its id
101
101
  let approving = null; // the open Approve… confirmation: { request, reason, error }
102
102
  let result = null; // what the last merge reported
103
+ // REPORT-3: the reports a Send is filing now, off the band and the Decisions tab until it's done.
104
+ const sendingReports = new Set();
103
105
  let notice = null; // why the person's last act failed
104
106
  let teamSince = null; // TEAM-6: since you last looked, as read when the Team pane's tab opened
105
107
  let teamUi = { ...DEFAULT_TEAM_UI }; // TEAM-7: the Team pane's own state
@@ -116,6 +118,7 @@ const present = new Map(); // agent id (or 'main') → its presence for a hosted
116
118
  const held = new Map(); // tool_use_id → a call held for the person (HOLD-2)
117
119
  const denied = new Map(); // tool_use_id → a call Claude Code's own permission check refused (PERM-1)
118
120
  const briefLater = new Set(); // the brief's questions the person put off this session (ASK-4)
121
+ const worktreesKept = new Set(); // merged worktrees the person chose to keep this session (LEAN-8)
119
122
  let answering = null; // the open Answer… box: { kind: 'question' | 'brief', question, id?, path?, text, error }
120
123
  let where = null; // { cli, cwd, interactive }, from session start
121
124
  // The lead loop (spec 05): what it did, and what it waits on.
@@ -333,7 +336,9 @@ export function register(on) {
333
336
  ? mine('answer')
334
337
  : ((await json('ask')) ?? []).filter((q) => q.state === 'open');
335
338
  const reports = valid
336
- ? ((await json('report')) ?? []).filter((r) => r.state === 'draft')
339
+ ? ((await json('report')) ?? []).filter(
340
+ (r) => r.state === 'draft' && !sendingReports.has(r.id),
341
+ )
337
342
  : [];
338
343
  // TEAM-12: the plan mirrored onto the team's Project board, at most every 10 minutes, in the
339
344
  // background: a slow GitHub never holds up the band.
@@ -370,6 +375,10 @@ export function register(on) {
370
375
  reports,
371
376
  // ASK-4: the brief's open questions, less those put off this session.
372
377
  brief: (nextStep?.brief ?? []).filter((b) => !briefLater.has(b.question)),
378
+ // LEAN-8: merged worktrees still holding changes, less those kept this session.
379
+ worktrees: (nextStep?.worktrees ?? []).filter((w) => !worktreesKept.has(w.branch)),
380
+ // SCHED-3: the model each story offered to a lane runs on.
381
+ models: nextStep?.models ?? [],
373
382
  base: status?.base ?? null,
374
383
  // SESS-3, SESS-4: a working session's band holds its own, and its task.
375
384
  working: role === 'working',
@@ -745,16 +754,55 @@ export function register(on) {
745
754
  },
746
755
  // REPORT-3: the person sends a drafted report to code-kit's GitHub, or discards it.
747
756
  sendReport: async (line) => {
748
- const ran = await $.process.run(['node', cli, 'report', 'send', line.report.id], {
757
+ const { id } = line.report;
758
+ if (sendingReports.has(id)) return;
759
+ sendingReports.add(id);
760
+ await act.reload();
761
+ await $.ui.toast(`Sending ${id} to code-kit's GitHub…`);
762
+ try {
763
+ const ran = await $.process.run(['node', cli, 'report', 'send', id], {
764
+ cwd,
765
+ timeoutMs: 120000,
766
+ });
767
+ const text = `${ran.stdout}${ran.stderr}`.trim();
768
+ if (ran.exitCode === 0) await $.ui.toast(text);
769
+ else {
770
+ result = { ok: false, title: 'Report not sent', text };
771
+ await $.ui.open({ id: RESULT_ID, title: 'Report', focus: true, closeOnEscape: true });
772
+ }
773
+ } finally {
774
+ sendingReports.delete(id);
775
+ await act.reload();
776
+ }
777
+ },
778
+ // LEAN-8: the person keeps a merged worktree that still holds changes, or discards them.
779
+ keepWorktree: (line) => {
780
+ worktreesKept.add(line.worktree.branch);
781
+ model = {
782
+ ...model,
783
+ worktrees: (model.worktrees ?? []).filter((w) => w.branch !== line.worktree.branch),
784
+ };
785
+ $.ui.invalidate('ui.render');
786
+ },
787
+ discardWorktree: async (line) => {
788
+ const { branch } = line.worktree;
789
+ worktreesKept.add(branch);
790
+ model = {
791
+ ...model,
792
+ worktrees: (model.worktrees ?? []).filter((w) => w.branch !== branch),
793
+ };
794
+ $.ui.invalidate('ui.render');
795
+ const ran = await $.process.run(['node', cli, 'worktrees', 'discard', branch], {
749
796
  cwd,
750
797
  timeoutMs: 120000,
751
798
  });
752
- result = {
753
- ok: ran.exitCode === 0,
754
- title: ran.exitCode === 0 ? 'Report sent' : 'Report not sent',
755
- text: `${ran.stdout}${ran.stderr}`.trim(),
756
- };
757
- await $.ui.open({ id: RESULT_ID, title: 'Report', focus: true, closeOnEscape: true });
799
+ const text = `${ran.stdout}${ran.stderr}`.trim();
800
+ if (ran.exitCode === 0) await $.ui.toast(text);
801
+ else {
802
+ worktreesKept.delete(branch);
803
+ result = { ok: false, title: 'Worktree not removed', text };
804
+ await $.ui.open({ id: RESULT_ID, title: 'Worktree', focus: true, closeOnEscape: true });
805
+ }
758
806
  await act.reload();
759
807
  },
760
808
  discardReport: async (line) => {
@@ -1462,6 +1510,11 @@ export function register(on) {
1462
1510
  // LOOP-11: the lead's last reply first: one that waits on the person holds every step.
1463
1511
  await act.hear();
1464
1512
  if (loop.waiting && ['person', 'stopped'].includes(loop.waiting.kind)) return;
1513
+ // #59: a restart or hand-back for a story that has since merged is stale, and goes unasked.
1514
+ const finished = new Set(
1515
+ (model.state?.stories ?? []).filter((s) => s.state === 'done').map((s) => s.id),
1516
+ );
1517
+ loop.pending = loop.pending.filter((p) => !finished.has(p.story));
1465
1518
  if (loop.pending.length) {
1466
1519
  const { story, prompt } = loop.pending.shift();
1467
1520
  // Until the person has chosen how hands-off the loop is, or under propose, a restart is offered
@@ -2190,12 +2243,17 @@ export function register(on) {
2190
2243
  const file = where
2191
2244
  ? await $.fs.read(`${where.cwd}/.claude/agents/${e.subagentType}.md`).catch(() => null)
2192
2245
  : null;
2246
+ // SCHED-3: with the lane model `story`, the model `next` gave the story the call's description names.
2247
+ const story = String(e.description ?? '')
2248
+ .match(/\bST-\d+\b/i)?.[0]
2249
+ ?.toUpperCase();
2193
2250
  const chosen = laneModel({
2194
2251
  type: e.subagentType,
2195
2252
  model: e.model,
2196
2253
  lanes,
2197
2254
  setting,
2198
2255
  fileModel: typeof file === 'string' ? agentFileModel(file) : null,
2256
+ story: (model.models ?? []).find((m) => m.story === story)?.model ?? null,
2199
2257
  });
2200
2258
  return next(chosen ? { ...e, model: chosen } : e);
2201
2259
  }).catch(($, e, next) => next(e));
@@ -2244,10 +2302,10 @@ export function register(on) {
2244
2302
  const a = activityOf(e.agentId, await $.clock.now());
2245
2303
  a.handedBack = true;
2246
2304
  // LEAN-5: an agent that handed back at its limit: the lead carries its story on with a fresh one.
2247
- if (a.overflow && !a.continued && act) {
2305
+ const story = (model.state?.stories ?? []).find((s) => s.id === a.story);
2306
+ if (a.overflow && !a.continued && act && story?.state !== 'done') {
2248
2307
  a.continued = true;
2249
2308
  const agent = agentsSeen.get(e.agentId);
2250
- const story = (model.state?.stories ?? []).find((s) => s.id === a.story);
2251
2309
  loop.pending.push({
2252
2310
  story: a.story,
2253
2311
  prompt: continuePrompt({
@@ -82,6 +82,8 @@ function project() {
82
82
  answer: 'Merge',
83
83
  open: new Set<string>(),
84
84
  opened: [] as string[],
85
+ reportFails: false, // report send: GitHub refuses it
86
+ toasts: [] as string[],
85
87
  closed: [] as string[],
86
88
  prompts: [] as string[],
87
89
  acts: [] as string[][],
@@ -216,6 +218,18 @@ function stub(on: any, w: World) {
216
218
  return ran(0, 'Recorded.');
217
219
  }
218
220
  if (sub === 'ask') return ran(0, JSON.stringify(w.questions));
221
+ if (sub === 'worktrees' && argv[3] === 'discard') {
222
+ w.acts.push([...argv.slice(2)]);
223
+ w.next = {
224
+ ...w.next,
225
+ worktrees: (w.next.worktrees ?? []).filter((x: any) => x.branch !== argv[4]),
226
+ };
227
+ return ran(0, `Removed ${argv[4]}'s worktree.`);
228
+ }
229
+ if (sub === 'report' && argv[3] === 'send' && w.reportFails) {
230
+ w.acts.push([...argv.slice(2)]);
231
+ return ran(1, '', "GitHub didn't take it (HTTP 502).");
232
+ }
219
233
  if (sub === 'report' && ['send', 'discard'].includes(argv[3])) {
220
234
  w.acts.push([...argv.slice(2)]);
221
235
  w.reports = w.reports.map((r) =>
@@ -492,6 +506,10 @@ function stub(on: any, w: World) {
492
506
  return { value: undefined };
493
507
  });
494
508
  on('ui.panes', () => ({ value: [...w.open].map((id) => ({ id, title: id, isShown: true })) }));
509
+ on('ui.toast', ($: any, e: any) => {
510
+ w.toasts.push(e.text);
511
+ return { value: undefined };
512
+ });
495
513
  on('ui.open', ($: any, e: any) => {
496
514
  w.opened.push(e.id);
497
515
  w.open.add(e.id);
@@ -1902,8 +1920,83 @@ test('REPORT-3 a bug report an agent drafted waits for the person, who reads it
1902
1920
  await ui.find({ type: 'Text', text: '**What happened:** the card never showed' }),
1903
1921
  ).toBeDefined();
1904
1922
  await press($, 'decide-sendReport', PANE);
1905
- expect(w.acts).toContainEqual(['report', 'send', 'R-1']);
1906
- expect(w.opened).toContain('code-kit-result');
1923
+ expect(w.acts.filter((a: string[]) => a[0] === 'report' && a[1] === 'send')).toEqual([
1924
+ ['report', 'send', 'R-1'],
1925
+ ]);
1926
+ // Sent, it leaves the tab, and the result is a toast, not a pane to close.
1927
+ expect(w.toasts).toEqual([
1928
+ "Sending R-1 to code-kit's GitHub…",
1929
+ 'Filed https://github.com/o/code-kit/issues/9',
1930
+ ]);
1931
+ expect(await ui.find({ type: 'Text', text: '**What happened:** the card never showed' })).toBe(
1932
+ undefined,
1933
+ );
1934
+ expect(w.opened).not.toContain(RESULT);
1935
+ await ui.unmount();
1936
+ });
1937
+
1938
+ test('REPORT-3 a report GitHub refused stays to send again, and says why', async ($, on) => {
1939
+ const w = project();
1940
+ w.reportFails = true;
1941
+ w.reports = [
1942
+ {
1943
+ id: 'R-1',
1944
+ at: '2026-10-13T00:00:00Z',
1945
+ by: 'lead',
1946
+ title: 'Decisions tab misses a held call',
1947
+ fingerprint: 'ck-1',
1948
+ body: '**What happened:** the card never showed',
1949
+ state: 'draft',
1950
+ sent: null,
1951
+ },
1952
+ ];
1953
+ await start($, on, w);
1954
+ const band = await bandUi($);
1955
+ await press($, 'band-openDecision');
1956
+ await band.unmount();
1957
+ const ui = await pane($, PANE);
1958
+ await press($, 'decide-sendReport', PANE);
1959
+ expect(w.opened).toContain(RESULT);
1960
+ const result = await pane($, RESULT);
1961
+ expect(await result.find({ type: 'Text', text: /GitHub didn't take it/ })).toBeDefined();
1962
+ await result.unmount();
1963
+ expect(
1964
+ await ui.find({ type: 'Text', text: '**What happened:** the card never showed' }),
1965
+ ).toBeDefined();
1966
+ await ui.unmount();
1967
+ });
1968
+
1969
+ test('LEAN-8 a merged worktree still holding changes waits for the person, who keeps it or discards it', async ($, on) => {
1970
+ const w = project();
1971
+ w.next = {
1972
+ ...w.next,
1973
+ worktrees: [
1974
+ { branch: 'web/st-2', story: 'ST-2', changes: 2, files: [' M st2.txt', '?? notes.txt'] },
1975
+ { branch: 'api/st-3', story: 'ST-3', changes: 1, files: [' M a.ts'] },
1976
+ ],
1977
+ };
1978
+ await start($, on, w);
1979
+ const band = await bandUi($);
1980
+ expect(
1981
+ await band.find({
1982
+ type: 'Text',
1983
+ text: '2 merged worktrees still hold changes: web/st-2',
1984
+ }),
1985
+ ).toBeDefined();
1986
+ await press($, 'band-openDecision');
1987
+ await band.unmount();
1988
+ const ui = await pane($, PANE);
1989
+ expect(await ui.find({ type: 'Text', text: /\?\? notes\.txt/ })).toBeDefined();
1990
+ await press($, 'decide-discardWorktree', PANE);
1991
+ expect(w.acts).toContainEqual(['worktrees', 'discard', 'web/st-2']);
1992
+ expect(w.opened).not.toContain(RESULT);
1993
+ await press($, 'decide-keepWorktree', PANE);
1994
+ expect(w.acts.filter((a: string[]) => a[0] === 'worktrees')).toEqual([
1995
+ ['worktrees', 'discard', 'web/st-2'],
1996
+ ]);
1997
+ expect((await ui.findAll({ type: 'Text' })).some((t: any) => /api\/st-3/.test(t.text))).toBe(
1998
+ false,
1999
+ );
1907
2000
  await ui.unmount();
1908
2001
  });
1909
2002
 
@@ -2423,6 +2516,28 @@ test('LEAN-5 a lane agent past its context limit is told to wrap up, and its sto
2423
2516
  );
2424
2517
  });
2425
2518
 
2519
+ test('#59 an agent that hands back at its limit a story already merged and done is not carried on', async ($, on) => {
2520
+ const w = project();
2521
+ w.next = { step: 'wait', args: '', then: [] };
2522
+ w.stories = w.stories.map((s: any) => (s.id === 'ST-4' ? { ...s, state: 'done' } : s));
2523
+ w.agents = [
2524
+ { id: 'a1', type: 'web-engineer', description: 'ST-4 booking form', status: 'running' },
2525
+ ];
2526
+ const clock = await start($, on, w);
2527
+ await clock.advance(2000);
2528
+ await request($, 'a1', 300);
2529
+ await $.turn.complete({
2530
+ turnId: 't-a1',
2531
+ agentId: 'a1',
2532
+ answer: 'ST-4: committed, report written.',
2533
+ durationMs: 1,
2534
+ isAborted: false,
2535
+ } as any);
2536
+ await leadTurn($, 't-2');
2537
+ await settle(clock);
2538
+ expect(w.prompts.some((p: string) => /handed ST-4 back/.test(p))).toBe(false);
2539
+ });
2540
+
2426
2541
  test("LEAN-4 past compact.at the lead's context is compacted between turns, without asking", async ($, on) => {
2427
2542
  const w = project();
2428
2543
  const compacted: string[] = [];
@@ -3133,6 +3248,34 @@ test("SET-4 a lane agent starts on the lane model set; the lead's own choice, an
3133
3248
  ]);
3134
3249
  });
3135
3250
 
3251
+ test("SCHED-3 with the lane model story, a lane agent starts on the model next gave its story; the lead's own choice and an agent file's still win", async ($, on) => {
3252
+ const w = project();
3253
+ (w.check as any).harness = { agents: { lanes: { model: 'story' } } };
3254
+ w.next = {
3255
+ step: 'dispatch',
3256
+ args: 'ST-9',
3257
+ then: [],
3258
+ models: [{ story: 'ST-9', model: 'haiku', why: 'a small story' }],
3259
+ } as any;
3260
+ w.agentFiles['/work/.claude/agents/web-engineer.md'] =
3261
+ '---\nname: web-engineer\nmodel: opus\n---\n';
3262
+ await start($, on, w);
3263
+ await dispatch($, 'core-engineer');
3264
+ await dispatch($, 'core-engineer', 'sonnet');
3265
+ await dispatch($, 'web-engineer');
3266
+ await $.agent.spawn({
3267
+ prompt: 'ST-2 other',
3268
+ description: 'ST-2 other',
3269
+ subagentType: 'core-engineer',
3270
+ });
3271
+ expect(w.spawned.map((e) => [e.subagentType, e.model ?? null])).toEqual([
3272
+ ['core-engineer', 'haiku'],
3273
+ ['core-engineer', 'sonnet'],
3274
+ ['web-engineer', null],
3275
+ ['core-engineer', null],
3276
+ ]);
3277
+ });
3278
+
3136
3279
  test('SET-4 with no lane model set, lane agents start as Claude Code decides', async ($, on) => {
3137
3280
  const w = project();
3138
3281
  await start($, on, w);
@@ -729,6 +729,7 @@ export function bandLines({
729
729
  questions = [],
730
730
  brief = [],
731
731
  reports = [],
732
+ worktrees = [],
732
733
  working = false,
733
734
  task = null,
734
735
  elsewhere = [],
@@ -913,6 +914,15 @@ export function bandLines({
913
914
  { id: 'discardReport', label: 'Discard' },
914
915
  ],
915
916
  });
917
+ // LEAN-8: a merged worktree that still holds uncommitted changes: the person keeps it, or discards them.
918
+ if (worktrees.length && !working)
919
+ lines.push({
920
+ kind: 'worktree',
921
+ text: `${worktrees.length > 1 ? `${worktrees.length} merged worktrees still hold changes: ` : 'A merged worktree still holds changes: '}${worktrees[0].branch}`,
922
+ worktree: worktrees[0],
923
+ worktrees,
924
+ actions: [{ id: 'openDecision', label: 'Look…' }],
925
+ });
916
926
  // LOOP-7: the milestone is done; LOOP-6: the loop's own state, with Pause or Resume.
917
927
  if (loop?.state === 'done')
918
928
  lines.push({
@@ -1524,7 +1534,7 @@ export const SETTINGS_ID = 'code-kit-settings';
1524
1534
  const CHOICES = {
1525
1535
  autonomy: ['autonomous', 'propose', 'off'],
1526
1536
  'agents.reviewer.model': ['', 'haiku', 'sonnet', 'opus'],
1527
- 'agents.lanes.model': ['', 'haiku', 'sonnet', 'opus'],
1537
+ 'agents.lanes.model': ['', 'story', 'haiku', 'sonnet', 'opus'],
1528
1538
  'compact.milestone': ['ask', 'auto', 'off'],
1529
1539
  };
1530
1540
  const shown = (v) =>
@@ -1538,7 +1548,9 @@ const shown = (v) =>
1538
1548
  ? 'the lead'
1539
1549
  : v === 'person'
1540
1550
  ? 'you'
1541
- : String(v);
1551
+ : v === 'story'
1552
+ ? "each story's size"
1553
+ : String(v);
1542
1554
 
1543
1555
  /**
1544
1556
  * The Settings view: each setting from `code-kit settings --json` with a control, and, once one is
package/hooks/session.mjs CHANGED
@@ -1,8 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
  // SessionStart and SessionEnd (docs/specs/23-the-team.md): a session starting is recorded as a member
3
- // of the team, the lead session when no other live session leads (SESS-2); as it ends, it leads nothing
4
- // more, and the lanes its agents had claimed are free again (SCHED-1). Its task stays, stale (SESS-4).
3
+ // of the team, the lead session when no other live session leads (SESS-2), and the worktrees done with
4
+ // are pruned (docs/specs/20-lean-lead.md, LEAN-8); as it ends, it leads nothing more, and the lanes its
5
+ // agents had claimed are free again (SCHED-1). Its task stays, stale (SESS-4).
6
+ import { spawn } from 'node:child_process';
5
7
  import { readFileSync } from 'node:fs';
8
+ import { fileURLToPath } from 'node:url';
6
9
  import { loadConfig } from './lib/config.mjs';
7
10
  import { releaseSession } from './lib/laneclaims.mjs';
8
11
  import { endSession, startSession } from './lib/sessions.mjs';
@@ -17,7 +20,21 @@ try {
17
20
  const project = projectDir();
18
21
  const { config } = loadConfig(project);
19
22
  const session = input.session_id ?? null;
20
- if (config && session && process.argv[2] === 'start') startSession(project, session);
23
+ if (config && session && process.argv[2] === 'start') {
24
+ startSession(project, session);
25
+ // LEAN-8: the worktrees left done with since the last session go, in the background: a project with
26
+ // many of them never holds up a session's start.
27
+ spawn(
28
+ process.execPath,
29
+ [
30
+ fileURLToPath(new URL('../bin/code-kit.mjs', import.meta.url)),
31
+ 'worktrees',
32
+ 'prune',
33
+ '--quiet',
34
+ ],
35
+ { cwd: project, detached: true, stdio: 'ignore' },
36
+ ).unref();
37
+ }
21
38
  if (config && session && process.argv[2] === 'end') {
22
39
  endSession(project, session);
23
40
  releaseSession(project, session);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.22.1",
3
+ "version": "0.24.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",
@@ -50,7 +50,7 @@ The lease is the paths the story will create or change: its lane's folders for t
50
50
 
51
51
  One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief and "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout". A long-lived agent rereads its whole context on every step, which is most of what a build costs.
52
52
 
53
- Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
53
+ Start each story with the Agent tool: `subagent_type` is the lane's agent, `model` the one `code-kit next --json` gives the story in `models` (with the lane model `story`, each story's model follows its `**Size:**`, raised for a security requirement, a fix or a send-back; a story with no size runs on Sonnet, so size it in the plan first if it's plainly small or large), `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
54
54
 
55
55
  The brief is the agent's whole context. Write it so the agent needs nothing else:
56
56
 
@@ -75,7 +75,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
75
75
  - **`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.
76
76
  - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the three choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), or `off`. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes.
77
77
  - **`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.
78
- - **`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 Sonnet usually does the work well for much less than the session's model; recommend `sonnet`, and say the lead, the reviewer and the security reviewer keep the session's model. The mod sets it as each lane agent starts; a lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "sonnet" } }`, or leave it out for the session's model.
78
+ - **`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.
79
79
  - **`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 Decisions tab: 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.
80
80
  - **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
81
81
  - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
@@ -113,7 +113,7 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
113
113
  - a **QA lane** (`qa`, agent `test-engineer`) whenever the product has screens or journeys that cross lanes: it owns the end-to-end suites (for example `e2e/**` or `apps/*/e2e/**`), in the runner that suits each surface (Playwright for web, Maestro or Detox for mobile), and its command runs them. Nobody else owns these tests, so without it nothing proves a journey works across the lanes;
114
114
  - no lane for security: it owns no paths. init adds a read-only security reviewer that checks every story touching the threat models' sensitive parts, so security requirements are delivered by the lanes whose code they constrain;
115
115
  - milestones, each a usable increment;
116
- - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers, or `none` for a spike or a foundation that delivers none), `**Depends on:**` and `**Status:** todo` lines, and for a story that fixes a bug, `**Fixes:**` with what was broken. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
116
+ - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers, or `none` for a spike or a foundation that delivers none), `**Depends on:**`, `**Size:**` and `**Status:** todo` lines, and for a story that fixes a bug, `**Fixes:**` with what was broken. The size is your judgement of what the story asks of whoever builds it, and with the lane model `story` it picks the lane agent's model: `small` for one layer inside patterns the code already has and no new contract (copy, configuration, a field on an existing form, tests for code that exists), `large` for a new data model or migration, a contract other lanes build on, money, sign-in or concurrency, or a library the project hasn't used, and `medium` for the rest. Size by what could go wrong, not by how many lines it takes. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
117
117
  - sequencing: contracts and shared foundations first, as the lead's own stories (`**Lane:** lead`, built by the lead rather than dispatched), then work that can run in parallel. A lane runs one story at a time, so parallel work is stories in different lanes;
118
118
  - **slices**: group the stories that together make one feature someone could see working (a vertical slice across lanes, such as "Book a class") with a `**Slice:** <name>` line on each, in plan order, contract story first. A free lane builds the open slice's stories before the next slice's (`harness.slices.open`, 1 by default), so the feature in progress finishes and merges before the next one spreads across the lanes;
119
119
  - **a test story per journey**: for each main user journey, a story in the `qa` lane citing the journey's requirements and depending on the screen and service stories it goes through, so the journey is proven end to end as soon as its parts are built;
package/templates/plan.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Plan
2
2
 
3
- `code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement. A story that fixes a bug adds a fifth line, `**Fixes:** <what was broken, and where it was seen>`: `code-kit verify` then requires a test that fails without the fix and passes with it. A story that belongs to a slice (a feature that can be shown working, built across lanes) adds `**Slice:** <name>`: a lane takes the open slice's stories first.
3
+ `code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement. A story that fixes a bug adds a fifth line, `**Fixes:** <what was broken, and where it was seen>`: `code-kit verify` then requires a test that fails without the fix and passes with it. A story that belongs to a slice (a feature that can be shown working, built across lanes) adds `**Slice:** <name>`: a lane takes the open slice's stories first. `**Size:**` is `small` (one layer, inside patterns the code already has, no new contract), `medium` or `large` (a new data model or migration, a contract other lanes build on, money, sign-in or concurrency, or a library the project hasn't used); with `harness.agents.lanes.model` set to `story`, it picks the lane agent's model.
4
4
 
5
5
  ## Lanes
6
6
 
@@ -18,6 +18,7 @@
18
18
  **Requirements:** {{AREA-1, AREA-2}}
19
19
  **Depends on:** {{ST-n, or none}}
20
20
  **Slice:** {{the feature it's part of, or leave the line out}}
21
+ **Size:** {{small, medium or large}}
21
22
  **Status:** todo
22
23
 
23
24
  {{What gets built, in two or three sentences. The acceptance criteria are the cited requirements'.}}