@warren-dean/code-kit 0.8.1 → 0.9.1

package/hooks/mod/register.test.ts

@@ -154,6 +154,8 @@ function project() {
     map: null as any, // `code-kit map <story> --json`
     trail: null as any, // `code-kit trail --json`
     journal: { events: [] as any[] }, // `code-kit journal --json`
+    team: null as any, // `code-kit team --json`, for a team's project
+    teamSince: { people: {} } as any, // `code-kit team since --json`
     holdWaits: false, // false: the hold ends at once, as if timed out (tests about cards, not hold)
     waiting: new Map<string, (answer: string) => void>(),
   };
@@ -194,6 +196,19 @@ function stub(on: any, w: World) {
     if (sub === 'map') return ran(w.map ? 0 : 1, JSON.stringify(w.map));
     if (sub === 'trail') return ran(w.trail ? 0 : 1, JSON.stringify(w.trail));
     if (sub === 'journal') return ran(0, JSON.stringify(w.journal));
+    if (sub === 'team' && argv[3] === 'since') {
+      w.acts.push([...argv.slice(2)]);
+      return ran(0, JSON.stringify(w.teamSince));
+    }
+    if (sub === 'team' && ['keep', 'release', 'board'].includes(argv[3])) {
+      w.acts.push([...argv.slice(2)]);
+      return ran(0, '');
+    }
+    if (sub === 'team') return ran(w.team ? 0 : 1, JSON.stringify(w.team));
+    if (sub === 'intend') {
+      w.acts.push([...argv.slice(2)]);
+      return ran(0, '');
+    }
     if (sub === 'loop' && ['pause', 'resume'].includes(argv[3])) {
       w.acts.push([...argv.slice(2)]);
       w.loopPaused = argv[3] === 'pause';
@@ -2465,13 +2480,18 @@ test('TRACE-2 selecting a cell, by keys or the list, shows its spec, stories wit
   expect(JSON.stringify((await ui.find({ key: 'cell-BOOK-21' }))?.children)).toMatch(
     /"inverse":true/,
   );
+  // The list holds the selected requirement's spec: payments' twenty, none of booking's.
+  const options = (await ui.find({ key: 'map-select' }))?.props.options ?? [];
+  expect(options.length).toBe(20);
+  expect(options.every((o: any) => Number(o.value.split('-')[1]) > 20)).toBe(true);
+  await $.ui.select({ plugin: 'code-kit', key: 'map-select', value: 'BOOK-40', requestId: PANE });
+  expect((await ui.find({ key: 'map-detail' }))?.text).toMatch(/No story delivers it yet/);
+  await press($, 'row-prev', PANE);
   await $.ui.select({ plugin: 'code-kit', key: 'map-select', value: 'BOOK-3', requestId: PANE });
   const detail = (await ui.find({ key: 'map-detail' }))?.text ?? '';
   expect(detail).toMatch(/docs\/spec\/01-booking.md · done and tested/);
   expect(detail).toMatch(/ST-4 Booking form · web · in progress · web\/st-4/);
   expect(detail).toMatch(/apps\/web\/b3.test.ts/);
-  await $.ui.select({ plugin: 'code-kit', key: 'map-select', value: 'BOOK-40', requestId: PANE });
-  expect((await ui.find({ key: 'map-detail' }))?.text).toMatch(/No story delivers it yet/);
   await ui.unmount();
 });
 
@@ -2879,3 +2899,212 @@ test('the lead reads orchestrating while its turn runs, and idle once it ends; a
   expect((await ui.find({ key: 'lane-lead' }))?.text).toMatch(/lead\s*idle/);
   await ui.unmount();
 });
+
+// --- teams (spec 16) ---------------------------------------------------------------------------------
+
+/** A team's state as `code-kit team --json` reports it, seen by `me`. */
+function teamOf(me: string) {
+  const at = '2026-10-06T09:00:00.000Z'; // a Tuesday
+  return {
+    at,
+    reachable: true,
+    github: true,
+    me,
+    techLead: 'alex',
+    owners: { web: ['sam'] },
+    staleDays: 3,
+    claims: [
+      { story: 'ST-4', by: 'sam', at, active: at, stale: true, lease: ['apps/web/booking/**'] },
+      {
+        story: 'ST-9',
+        by: 'kim',
+        at,
+        active: at,
+        stale: false,
+        lease: ['apps/web/booking/form.tsx'],
+      },
+    ],
+    intents: [
+      {
+        id: 12,
+        by: 'kim',
+        about: 'Split the booking form',
+        touches: ['apps/web/**'],
+        at,
+        url: 'u',
+        state: 'open',
+      },
+    ],
+    pulls: [
+      {
+        number: 14,
+        title: 'Booking list',
+        by: 'kim',
+        branch: 'web/st-9',
+        draft: false,
+        updated: at,
+        url: 'u',
+      },
+    ],
+  };
+}
+
+test('TEAM-7 and TEAM-9 the band names what of the team needs you: your stale claim, a collision, an intent touching yours, a review in your lane', async ($, on) => {
+  const w = project();
+  w.team = teamOf('sam');
+  (w.check as any).team = { techLead: 'alex' };
+  (w.check as any).lanes.web.paths = ['apps/web/**'];
+  await start($, on, w);
+  const band = await bandUi($);
+  expect(
+    await band.find({ type: 'Text', text: 'Still on ST-4? Nothing on it since Tuesday' }),
+  ).toBeDefined();
+  expect(
+    await band.find({ type: 'Text', text: "ST-4 and kim's ST-9 both change apps/web/booking/**" }),
+  ).toBeDefined();
+  expect(
+    await band.find({ type: 'Text', text: 'kim intends: Split the booking form (touches yours)' }),
+  ).toBeDefined();
+  expect(
+    await band.find({
+      type: 'Text',
+      text: "kim's #14 Booking list is in your web lane and waits for your review",
+    }),
+  ).toBeDefined();
+  await press($, 'band-keepClaim');
+  expect(w.acts).toContainEqual(['team', 'keep', 'ST-4']);
+  await band.unmount();
+});
+
+test('TEAM-5 the tech lead sees every open intent with Agree and Drop, which act as them', async ($, on) => {
+  const w = project();
+  w.team = teamOf('alex');
+  (w.check as any).team = { techLead: 'alex' };
+  await start($, on, w);
+  const band = await bandUi($);
+  expect(
+    await band.find({ type: 'Text', text: 'kim intends: Split the booking form' }),
+  ).toBeDefined();
+  expect(await band.find({ type: 'Text', text: /Still on/ })).toBeUndefined();
+  await press($, 'band-agreeIntent');
+  expect(w.acts).toContainEqual([
+    'intend',
+    'agree',
+    '12',
+    '--reason',
+    'agreed in the code-kit pane',
+  ]);
+  // TEAM-10: then the lead records it where agents read it, through a pull request.
+  expect(
+    w.prompts.some((p) => p.includes('intend record 12') && p.includes('lead/decision-12')),
+  ).toBe(true);
+  await band.unmount();
+});
+
+test("TEAM-8 when the shared repository can't be reached the band says so as a note", async ($, on) => {
+  const w = project();
+  w.team = { ...teamOf('sam'), reachable: false, claims: [], intents: [], pulls: [] };
+  (w.check as any).team = { techLead: 'alex' };
+  await start($, on, w);
+  const band = await bandUi($);
+  expect(
+    await band.find({
+      type: 'Text',
+      text: "team: the shared repository can't be reached, so claims aren't checked",
+    }),
+  ).toBeDefined();
+  expect(await band.find({ type: 'Text', text: 'note' })).toBeDefined();
+  await band.unmount();
+});
+
+test('TEAM-6 and TEAM-7 the Team tab: since you last looked, then each person with their lanes, claims, pulls and intents', async ($, on) => {
+  const w = project();
+  w.team = teamOf('sam');
+  w.teamSince = {
+    since: '2026-10-10T00:00:00Z',
+    github: true,
+    people: { kim: [{ at: 1, by: 'kim', kind: 'pushed', text: 'pushed 2 commits to web/st-9' }] },
+  };
+  (w.check as any).team = { techLead: 'alex' };
+  await start($, on, w);
+  await lanes($);
+  const ui = await pane($, PANE);
+  expect((await ui.find({ key: 'tab-team' }))?.props.hotkey).toBe('8');
+  await press($, 'tab-team', PANE);
+  expect(w.acts).toContainEqual(['team', 'since', '--json']);
+  expect((await ui.find({ key: 'team-since' }))?.text).toMatch(
+    /kim: pushed 2 commits to web\/st-9/,
+  );
+  expect((await ui.find({ key: 'team-person-alex' }))?.text).toMatch(/alex · tech lead/);
+  expect((await ui.find({ key: 'team-person-sam' }))?.text).toMatch(
+    /sam · you · owns web[\s\S]*ST-4 · stale since Tuesday/,
+  );
+  expect((await ui.find({ key: 'team-person-kim' }))?.text).toMatch(
+    /#14 Booking list \(web\/st-9\)[\s\S]*intends: Split the booking form/,
+  );
+  await press($, 'team-release-ST-4', PANE);
+  expect(w.acts).toContainEqual(['team', 'release', 'ST-4']);
+  await ui.unmount();
+});
+
+test('TEAM-7 without a team there is no Team tab', async ($, on) => {
+  const w = project();
+  await start($, on, w);
+  await lanes($);
+  const ui = await pane($, PANE);
+  expect(await ui.find({ key: 'tab-team' })).toBeUndefined();
+  await ui.unmount();
+});
+
+test('TEAM-12 with a board, the mod syncs it in the background, at most every 10 minutes', async ($, on) => {
+  const w = project();
+  w.team = teamOf('sam');
+  (w.check as any).team = { techLead: 'alex', board: { owner: 'o', number: 3 } };
+  const clock = await start($, on, w);
+  const syncs = () => w.acts.filter((a) => a[0] === 'team' && a[1] === 'board').length;
+  expect(syncs()).toBe(1);
+  await clock.advance(60000);
+  expect(syncs()).toBe(1);
+  await clock.advance(10 * 60000);
+  expect(syncs()).toBe(2);
+});
+
+test('TRACE-2 a project with more requirements than a list holds still draws its trail', async ($, on) => {
+  const w = project();
+  w.requirements = Array.from({ length: 134 }, (_, i) => ({
+    id: `AILA-${i + 1}`,
+    title: `Requirement ${i + 1}`,
+    file: 'docs/spec/03-aila.md',
+    removed: false,
+    state: 'todo',
+    stories: ['ST-4'],
+    tests: [],
+  }));
+  await start($, on, w);
+  await lanes($);
+  const ui = await pane($, PANE);
+  await press($, 'tab-map', PANE);
+  expect((await ui.find({ key: 'map-select' }))?.props.options.length).toBe(64);
+  await ui.unmount();
+});
+
+test('MAP-5 with no story at work, the code map shows the whole project, by folder', async ($, on) => {
+  const w = project();
+  w.stories = w.stories.map((s) => ({ ...s, state: 'ready' }));
+  w.map = {
+    story: { id: 'project', title: 'The whole project', lane: null, state: null },
+    layers: ['other'],
+    files: [
+      { path: 'apps/web/src', layer: 'other', lane: 'web', imports: ['packages/core'], files: 12 },
+      { path: 'packages/core', layer: 'other', lane: 'core', imports: [], files: 4 },
+    ],
+  };
+  await start($, on, w);
+  await lanes($);
+  const ui = await pane($, PANE);
+  await press($, 'tab-code', PANE);
+  expect((await ui.find({ key: 'map-story-project' }))?.props.variant).toBe('primary');
+  expect(await ui.find({ type: 'Text', text: /hasn't changed any code yet/ })).toBeUndefined();
+  expect(JSON.stringify(await ui.find({ key: 'map-stories' }))).toMatch(/Whole project/);
+  await ui.unmount();
+});

package/hooks/mod/teamview.mjs

@@ -0,0 +1,243 @@
+// Teams in the mod (docs/specs/16-teams.md, TEAM-7, TEAM-9), the pure parts: what of the team's state
+// needs this person, as band lines, and the Team tab. It reads `code-kit team --json` and
+// `code-kit team since --json`; the CLI and the hooks do the rest.
+import { globsOverlap, laneOfBranch } from '../lib/teamfacts.mjs';
+
+const day = (iso) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime())
+    ? 'a while'
+    : d.toLocaleDateString('en-AU', { weekday: 'long', timeZone: 'UTC' });
+};
+
+/** What the person owns or is building: their lanes' paths and their claims' leases. */
+function yoursOf(team, lanes = {}) {
+  const owned = Object.entries(team.owners ?? {})
+    .filter(([, people]) => people.includes(team.me))
+    .flatMap(([lane]) => lanes[lane]?.paths ?? []);
+  const leased = team.claims.filter((c) => c.by === team.me).flatMap((c) => c.lease);
+  return [...owned, ...leased];
+}
+
+const overlapping = (globs, others) => [
+  ...new Set(globs.filter((g) => others.some((o) => globsOverlap(g, o)))),
+];
+
+/**
+ * TEAM-7, TEAM-9: band lines for what of the team needs this person, and only that: their stale
+ * claims (Keep or Release), a claim of theirs sharing files with someone else's, intents touching what
+ * they own or lease (every open intent, for the tech lead, with Agree and Drop), and reviews in lanes
+ * they own. `team` is `code-kit team --json`; `lanes` the config's lanes, for their paths.
+ */
+export function teamLines(team, lanes = {}) {
+  if (!team) return [];
+  const lines = [];
+  if (team.reachable === false)
+    lines.push({
+      kind: 'teamDown',
+      text: "team: the shared repository can't be reached, so claims aren't checked",
+      actions: [],
+    });
+  const me = team.me;
+  if (!me) return lines;
+  const mine = team.claims.filter((c) => c.by === me);
+  for (const c of mine.filter((x) => x.stale))
+    lines.push({
+      kind: 'teamStale',
+      text: `Still on ${c.story}? Nothing on it since ${day(c.active)}`,
+      claim: c,
+      story: { id: c.story },
+      actions: [
+        { id: 'keepClaim', label: 'Keep' },
+        { id: 'releaseClaim', label: 'Release' },
+      ],
+    });
+  for (const c of mine)
+    for (const o of team.claims.filter((x) => x.by !== me)) {
+      const shared = overlapping(c.lease, o.lease);
+      if (shared.length)
+        lines.push({
+          kind: 'teamCollision',
+          text: `${c.story} and ${o.by}'s ${o.story} both change ${shared.join(', ')}`,
+          claim: c,
+          other: o,
+          story: { id: c.story },
+          actions: [{ id: 'team', label: 'Team' }],
+        });
+    }
+  const yours = yoursOf(team, lanes);
+  const leading = me === team.techLead;
+  for (const i of team.intents.filter((x) => x.by !== me)) {
+    const touched = overlapping(i.touches, yours);
+    if (!leading && !touched.length) continue;
+    lines.push({
+      kind: 'teamIntent',
+      text: `${i.by} intends: ${i.about}${touched.length ? ' (touches yours)' : ''}`,
+      intent: i,
+      actions: leading
+        ? [
+            { id: 'agreeIntent', label: 'Agree' },
+            { id: 'dropIntent', label: 'Drop' },
+            { id: 'team', label: 'Team' },
+          ]
+        : [{ id: 'team', label: 'Team' }],
+    });
+  }
+  for (const p of team.pulls.filter((x) => x.by !== me && !x.draft)) {
+    const lane = laneOfBranch(p.branch);
+    if (lane && team.owners?.[lane]?.includes(me))
+      lines.push({
+        kind: 'teamReview',
+        text: `${p.by}'s #${p.number} ${p.title} is in your ${lane} lane and waits for your review`,
+        pull: p,
+        actions: [{ id: 'team', label: 'Team' }],
+      });
+  }
+  return lines;
+}
+
+/** The people on the team, the tech lead first, then everyone named by an owner, claim, intent or pull. */
+export function peopleOf(team) {
+  const named = [
+    team.techLead,
+    ...Object.values(team.owners ?? {}).flat(),
+    ...team.claims.map((c) => c.by),
+    ...team.intents.map((i) => i.by),
+    ...team.pulls.map((p) => p.by),
+    team.me,
+  ].filter(Boolean);
+  return [...new Set(named)];
+}
+
+/**
+ * TEAM-6, TEAM-7: the Team tab: since you last looked, then each person with the lanes they own, their
+ * claims (stale ones marked, with Keep and Release for yours), their pull requests and their intents
+ * (Agree and Drop for the tech lead). `on.onNeed(id, line)` acts as the band's buttons do.
+ */
+export function teamTab(team, since, { Box, Text, Button }, on) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  if (!team) return [];
+  const rows = [];
+  if (team.reachable === false)
+    rows.push(
+      text(
+        "The shared repository can't be reached: claims and leases aren't checked until it can be.",
+        {
+          color: 'yellow',
+        },
+      ),
+    );
+  const sincePeople = Object.entries(since?.people ?? {});
+  rows.push(text('Since you last looked', { bold: true }));
+  rows.push(
+    Box({
+      key: 'team-since',
+      flexDirection: 'column',
+      children: sincePeople.length
+        ? sincePeople.map(([who, events]) =>
+            Box({
+              key: `since-${who}`,
+              children: [
+                text(
+                  `  ${who}${who === team.me ? ' (you)' : ''}: ${events.map((e) => e.text).join('; ')}`,
+                  {
+                    wrap: 'wrap',
+                  },
+                ),
+              ],
+            }),
+          )
+        : [text('  Nothing new.', { dimColor: true })],
+    }),
+  );
+  for (const who of peopleOf(team)) {
+    const lanes = Object.entries(team.owners ?? {})
+      .filter(([, people]) => people.includes(who))
+      .map(([lane]) => lane);
+    const claims = team.claims.filter((c) => c.by === who);
+    const pulls = team.pulls.filter((p) => p.by === who);
+    const intents = team.intents.filter((i) => i.by === who);
+    const role = [
+      who === team.techLead ? 'tech lead' : null,
+      who === team.me ? 'you' : null,
+      lanes.length ? `owns ${lanes.join(', ')}` : null,
+    ].filter(Boolean);
+    const items = [
+      ...claims.map((c) =>
+        Box({
+          key: `team-claim-${c.story}`,
+          flexDirection: 'row',
+          columnGap: 1,
+          children: [
+            text(
+              `  ${c.story}${c.stale ? ` · stale since ${day(c.active)}` : ''}${c.lease.length ? ` · ${c.lease.join(', ')}` : ''}`,
+              { wrap: 'truncate-end', ...(c.stale ? { color: 'yellow' } : {}) },
+            ),
+            ...(who === team.me && c.stale
+              ? [
+                  Button({
+                    key: `team-keep-${c.story}`,
+                    label: 'Keep',
+                    onPress: () => on.onNeed('keepClaim', { kind: 'teamStale', claim: c }),
+                  }),
+                  Button({
+                    key: `team-release-${c.story}`,
+                    label: 'Release',
+                    onPress: () => on.onNeed('releaseClaim', { kind: 'teamStale', claim: c }),
+                  }),
+                ]
+              : []),
+          ],
+        }),
+      ),
+      ...pulls.map((p) =>
+        Box({
+          key: `team-pull-${p.number}`,
+          children: [
+            text(`  #${p.number} ${p.title} (${p.branch}${p.draft ? ', draft' : ''})`, {
+              wrap: 'truncate-end',
+            }),
+          ],
+        }),
+      ),
+      ...intents.map((i) =>
+        Box({
+          key: `team-intent-${i.id}`,
+          flexDirection: 'row',
+          columnGap: 1,
+          children: [
+            text(`  intends: ${i.about}${i.touches.length ? ` · ${i.touches.join(', ')}` : ''}`, {
+              wrap: 'truncate-end',
+              color: 'cyan',
+            }),
+            ...(team.me === team.techLead && i.by !== team.me
+              ? [
+                  Button({
+                    key: `team-agree-${i.id}`,
+                    label: 'Agree',
+                    onPress: () => on.onNeed('agreeIntent', { kind: 'teamIntent', intent: i }),
+                  }),
+                  Button({
+                    key: `team-drop-${i.id}`,
+                    label: 'Drop',
+                    onPress: () => on.onNeed('dropIntent', { kind: 'teamIntent', intent: i }),
+                  }),
+                ]
+              : []),
+          ],
+        }),
+      ),
+    ];
+    rows.push(
+      Box({
+        key: `team-person-${who}`,
+        flexDirection: 'column',
+        children: [
+          text(`${who}${role.length ? ` · ${role.join(' · ')}` : ''}`, { bold: true }),
+          ...(items.length ? items : [text('  nothing open', { dimColor: true })]),
+        ],
+      }),
+    );
+  }
+  return rows;
+}

package/hooks/mod/view.mjs

@@ -9,6 +9,7 @@ const LEAD = 'lead';
 /** A CLI run's stdout as JSON, or null when it printed none. */
 import { BAR, POSE_GLYPH, rasterCells, runs, sprite, spriteSvg, timelineSvg } from './art.mjs';
 import { missionLines, nextText } from './mission.mjs';
+import { teamLines } from './teamview.mjs';
 
 export function parseJson(stdout) {
   try {
@@ -688,6 +689,7 @@ export function bandLines({
   live = {},
   nextStep = null,
   combined = null,
+  team = null,
 }) {
   const lines = [];
   // MISSION-1: the goal, now, next and the agents at work, above what needs the person.
@@ -808,6 +810,8 @@ export function bandLines({
       branch: next.branch,
       actions: [{ id: 'mergeQueue', label: 'Merge' }],
     });
+  // TEAM-7, TEAM-9: what of the team needs this person.
+  lines.push(...teamLines(team, check?.lanes ?? {}));
   // LOOP-7: the milestone is done; LOOP-6: the loop's own state, with Pause or Resume.
   if (loop?.state === 'done')
     lines.push({
@@ -941,7 +945,7 @@ export function band(lines, { Box, Text, Button }, onAction) {
 }
 
 /** Band lines that inform rather than ask: they never need the person's answer. */
-const NOTE_KINDS = new Set(['usage', 'paused', 'finish', 'done']);
+const NOTE_KINDS = new Set(['usage', 'paused', 'finish', 'done', 'teamDown']);
 
 /** The Approve… confirmation (ACT-1): what it grants, to whom, for how long, and the reason. */
 export function approvePane(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "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",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/design/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: design
+description: Design a design story's screens with the person before any of them is built, and record each approved design so its screen can be coded. Reads the screens the specs list, designs them in the project's design tool (Paper, Figma, Pencil) or as design files under design/, shows them, iterates on the person's feedback, and adds each approved screen to the design register the design gate reads. Use when code-kit next or the loop gives the design step, when a lane was refused for a screen whose design isn't approved, or runs /code-kit:design [story IDs].
+---
+
+# Design before code
+
+A screen is designed and approved before anyone builds it. The design gate refuses a lane writing a screen file until the design register lists it, and the plan's screen stories depend on their design story, so nothing is dispatched early. Designing is the lead's work with the person: you propose, they decide.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
+
+## 1. What to design
+
+For each story given (`**Lane:** design` in the plan):
+
+- read the requirements it cites and the `## Screens` section of their specs: each screen, what it shows, what the person can do there, and its empty, loading and error states;
+- read the architecture for the design tool and the folders screens live in, and the principles for the brand, theme and accessibility targets;
+- look at the designs already approved (`design/register.json` and what it links to), so the new screens match them.
+
+If the specs don't list the screens, or leave a state out, ask the person now rather than inventing it.
+
+## 2. Design
+
+Use the project's design tool:
+
+- **A design tool connected to this session** (Paper, Figma, Pencil, whichever the architecture names, or the one the person uses): design each screen there, one artboard per screen and state, with the project's tokens.
+- **None:** write each screen as a static HTML and CSS file under `design/<area>/<screen>.html`, at the sizes the product targets (phone, desktop), opened in the browser to check it.
+
+Use the spec's own content: the real labels, fields, messages and limits from its requirements, never lorem ipsum or placeholder screens. Every state the spec lists gets a design. Follow the principles for theme (light and dark, if both), type, spacing and accessibility.
+
+## 3. Show it and iterate
+
+Show the person each screen (a screenshot, or the file to open) with one line on what it does and which requirements it serves. Ask what to change. Make the changes and show them again until they say a screen is approved. A screen they want rethought goes back to step 2; one that needs the spec changed goes to `/code-kit:spec-design` first.
+
+## 4. Record the approved designs
+
+For each approved screen, add an entry to the register, naming the code file the lane will write (from the architecture's folders and the project's routing):
+
+```json
+{
+  "screens": [
+    {
+      "file": "apps/web/app/bookings/page.tsx",
+      "design": "design/bookings/list.html",
+      "story": "ST-2",
+      "approved": "2026-10-11"
+    }
+  ]
+}
+```
+
+The register is protected by the `design` approval, which is the person's: writing it is refused until they approve, and in a session with the code-kit mod the write waits in the band for their Approve. Give the approval a reason in their words ("bookings list and detail, as shown"). Then commit the designs and the register on `design/st-<n>`, and review and merge it like the lead's own story. Once it's merged, `code-kit next` dispatches the screen stories that waited on it.
+
+## 5. Report
+
+Say which screens were approved, which are still open and why, and what's dispatched next.

package/skills/dispatch/SKILL.md

@@ -17,7 +17,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project
 node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" status
 ```
 
-A story is **ready** when its dependencies are done and nobody has started it. `status` also lists gaps between the specs and the plan; a story with a gap (an unknown lane, a requirement no spec defines) isn't dispatched until the lead fixes the plan. Stories in the `lead` lane are never dispatched: the lead builds them itself.
+A story is **ready** when its dependencies are done and nobody has started it. `status` also lists gaps between the specs and the plan; a story with a gap (an unknown lane, a requirement no spec defines) isn't dispatched until the lead fixes the plan. Stories in the `lead` lane are never dispatched: the lead builds them itself. Nor are design stories (`**Lane:** design`): the lead designs them with the person (`/code-kit:design`), and the screen stories that depend on them wait until their designs are approved and merged.
 
 If the project has no `docs.plan`, or the plan has no stories in the `### ST-n` form (`${CLAUDE_PLUGIN_ROOT}/templates/plan.md`), stop and suggest the spec-design skill.
 
@@ -40,6 +40,14 @@ Commit everything the lanes need first. Each lane branches from the lead's branc
 
 ## 3. Brief and start each lane
 
+**In a team** (the config has `team`): claim each story before you brief its agent, leasing what it will change, so nobody else's agents build on the same files meanwhile:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,<glob>"
+```
+
+The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
+
 Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background. Start every story in the batch in the same message so they run in parallel.
 
 The brief is the agent's whole context. Write it so the agent needs nothing else: