@warren-dean/code-kit 0.8.1 → 0.9.1

package/bin/code-kit.mjs

@@ -53,11 +53,20 @@ import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
 import { storyTimes } from '../hooks/lib/timeline.mjs';
-import { storyMap, trail } from '../hooks/lib/storymap.mjs';
+import { PROJECT, projectMap, storyMap, trail } from '../hooks/lib/storymap.mjs';
 import { journal } from '../hooks/lib/journal.mjs';
 import { dequeue, enqueue, lastMerged, readQueue, settle, waiting } from '../hooks/lib/queue.mjs';
 import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/harness.mjs';
 import { readLoop, writeLoop } from '../hooks/lib/loop-state.mjs';
+import {
+  claimChanges,
+  storyOfBranch,
+  syncBoard,
+  teamOf,
+  teamProvider,
+  whoami,
+} from '../hooks/lib/team.mjs';
+import { codeowners, decisionRecord, slugOf } from '../hooks/lib/teamfacts.mjs';
 import {
   APPROVAL_MINUTES,
   approvalLifetime,
@@ -101,7 +110,9 @@ const via = option('--via');
 const sessionId = option('--session');
 const minutesGiven = option('--minutes');
 const answerGiven = option('--answer');
-const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person'];
+const leaseGiven = option('--lease');
+const touchesGiven = option('--touches');
+const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person', '--fresh', '--peek'];
 const flag = (name) => args.includes(name);
 const writeBaseline = flag('--write');
 const [command, ...rest] = args.filter((a) => !FLAGS.includes(a));
@@ -148,6 +159,9 @@ function checkJson() {
   report.harnessSet = Object.keys(SETTINGS).filter((k) => settingOf(raw.harness, k) !== undefined);
   // Delegation is the base's, by the rules committed there: a branch can't grant itself merges.
   const delegation = mergeDelegation('.', config, file);
+  // TEAM-1: the team, with its defaults, and who the developer at this machine is.
+  report.team = teamOf(raw);
+  report.me = report.team ? whoami(resolve('.')) : null;
   report.delegatesMerge = delegation.delegated;
   report.firstMerge = delegation.first;
   out(JSON.stringify(report, null, 2));
@@ -164,6 +178,20 @@ function check() {
   for (const c of raw.checks ?? []) out(`Check ${c.name}: ${c.run.join(' && ')}`);
   if (!raw.docs?.specs) out('No docs.specs: lanes are not held to a spec-check report.');
   for (const name of load().config.adapters) out(`Adapter ${name}: active (see \`adapters\`)`);
+  const team = teamOf(raw);
+  if (team) {
+    const me = whoami(resolve('.'));
+    out(
+      `Team: ${team.techLead} is the tech lead; a claim is stale after ${team.staleDays} working day${team.staleDays === 1 ? '' : 's'} without a push; provider ${team.provider === 'github' ? 'GitHub' : team.provider.command}.`,
+    );
+    for (const [lane, owners] of Object.entries(team.owners))
+      out(`Lane ${lane} is owned by ${owners.join(', ')}`);
+    out(
+      me
+        ? `You are ${me}${me === team.techLead ? ', the tech lead' : ''}.`
+        : "You aren't signed in to GitHub (gh auth login), so claims and owners can't be checked.",
+    );
+  }
 }
 
 function who(paths) {
@@ -547,6 +575,10 @@ function mergeOne(branch, config, byPerson) {
         'conflict',
       );
     }
+    // TEAM-1: a merged story's claim ends, whoever merged it.
+    const team = teamOf(config);
+    const story = storyOfBranch(branch);
+    if (team && story) teamProvider(resolve('.'), team).release(story, { merged: true });
     // A lane agent's worktree has done its work once its branch is merged: removed when it holds
     // nothing uncommitted (the branch stays), so finished lanes don't pile up checkouts.
     let removed = '';
@@ -651,6 +683,18 @@ function queue() {
  */
 function mapCommand(id) {
   const { config, raw } = load();
+  // MAP-5: the whole project, by folder, for when no story is at work.
+  if (id === PROJECT) {
+    const map = projectMap(resolve('.'), config, tracked());
+    if (flag('--json')) return out(JSON.stringify(map, null, 2));
+    out(`The whole project (${map.files.length} folder(s)):`);
+    for (const layer of map.layers) {
+      out(`  ${layer}`);
+      for (const f of map.files.filter((x) => x.layer === layer))
+        out(`    ${f.path} (${f.files})${f.imports.length ? `  → ${f.imports.join(', ')}` : ''}`);
+    }
+    return;
+  }
   const { specs, plan } = config.docs ?? {};
   if (!specs || !plan)
     die('map needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
@@ -1209,6 +1253,230 @@ async function approve(given) {
   );
 }
 
+/** How long ago an ISO time was, in words: "3 hours ago". */
+function ago(iso) {
+  const minutes = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 60000));
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  return `${Math.round(hours / 24)} days ago`;
+}
+
+/**
+ * The team (TEAM-2, TEAM-3, TEAM-8): `team` says who's on it and what's claimed, intended and open;
+ * `team claim <story> [--lease globs]` and `team release <story>` change a claim through the provider.
+ */
+function teamCommand() {
+  const { raw } = load();
+  const team = teamOf(raw);
+  if (!team)
+    die(
+      'This project has no "team" in its config, so it has no claims or owners. Add "team": { "techLead": "<GitHub handle>" } to share them.',
+    );
+  const provider = teamProvider(resolve('.'), team);
+  const [sub, story] = rest;
+  const holderWords = (h) =>
+    `${h.story} is claimed by ${h.by} (${ago(h.at)}). Ask them, or the tech lead (${team.techLead}), to release it.`;
+  if (sub === 'claim') {
+    if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"]');
+    const lease = (leaseGiven ?? '')
+      .split(',')
+      .map((g) => g.trim())
+      .filter(Boolean);
+    const r = provider.claim(story, lease);
+    if (r.holder) die(holderWords(r.holder));
+    if (!r.ok) die(r.why);
+    return out(
+      `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}.`,
+    );
+  }
+  // TEAM-12: the plan mirrored onto the team's GitHub Project.
+  if (sub === 'board') {
+    if (!team.board)
+      die(
+        'This team has no board. Add "board": { "owner": "<user or organisation>", "number": <the Project\'s number> } to "team" in the config.',
+      );
+    const { config, raw: rawConfig } = load();
+    if (!rawConfig.docs?.plan)
+      die('The board mirrors the plan, and this project has no docs.plan.');
+    const status = buildStatus('.', config, base(config, false), tracked());
+    const state = provider.state();
+    const r = syncBoard(resolve('.'), team, status.stories, state.claims ?? []);
+    if (!r.ok) die(r.why);
+    return out(
+      `Board ${team.board.owner}/${team.board.number} synced: ${r.created} item${r.created === 1 ? '' : 's'} added, ${r.edited} field${r.edited === 1 ? '' : 's'} changed.`,
+    );
+  }
+  // TEAM-11: GitHub's CODEOWNERS from the config, so GitHub asks the right people to review.
+  if (sub === 'codeowners') {
+    const text = codeowners({
+      techLead: team.techLead,
+      leadPaths: raw.lead.paths,
+      lanes: raw.lanes,
+    });
+    if (!flag('--write')) return out(text.trimEnd());
+    mkdirSync(resolve('.github'), { recursive: true });
+    writeFileSync(resolve('.github/CODEOWNERS'), text);
+    return out(
+      "Wrote .github/CODEOWNERS. Commit it, and require code owners' review in a ruleset on the protected branch, so GitHub holds every pull request to it.",
+    );
+  }
+  // TEAM-9: the holder keeps a stale claim (the clock starts again); the tech lead reassigns one.
+  if (sub === 'keep') {
+    if (!story) die('code-kit team keep <story>');
+    const r = provider.claim(story);
+    if (r.holder) die(holderWords(r.holder));
+    if (!r.ok) die(r.why);
+    return out(
+      `Kept ${story}: it isn't stale until ${team.staleDays} more working day${team.staleDays === 1 ? '' : 's'} without a push.`,
+    );
+  }
+  if (sub === 'reassign') {
+    const to = rest[2];
+    if (!story || !to) die('code-kit team reassign <story> <GitHub handle>');
+    const r = provider.reassign(story, to);
+    if (!r.ok) die(r.why);
+    return out(`Reassigned ${story} from ${r.from} to ${r.to}, with its lease.`);
+  }
+  if (sub === 'release') {
+    if (!story) die('code-kit team release <story>');
+    const r = provider.release(story);
+    if (!r.ok) die(r.why ?? holderWords(r.holder));
+    return out(
+      r.released ? `Released ${story} (${r.claim.by}'s claim).` : `${story} isn't claimed.`,
+    );
+  }
+  // TEAM-6: what everyone did since you last looked; reading it marks it read, unless --peek.
+  if (sub === 'since') {
+    const root = resolve('.');
+    const seenFile = join(root, '.claude/state/team-seen.json');
+    let seen = null;
+    try {
+      seen = JSON.parse(readFileSync(seenFile, 'utf8'));
+    } catch {
+      // never looked: the last day
+    }
+    const from = seen ? Date.parse(seen.at) : Date.now() - 24 * 3600_000;
+    const state = provider.state({ fresh: true });
+    const activity = provider.since(from);
+    const changes =
+      seen && state.reachable !== false ? claimChanges(seen.claims, state.claims) : [];
+    const all = [...(activity ?? []), ...changes].sort((a, b) => a.at - b.at);
+    const people = {};
+    for (const e of all) (people[e.by] ??= []).push(e);
+    if (!flag('--peek')) {
+      mkdirSync(join(root, '.claude/state'), { recursive: true });
+      writeFileSync(
+        seenFile,
+        JSON.stringify({ at: new Date().toISOString(), claims: state.claims ?? [] }) + '\n',
+      );
+    }
+    if (flag('--json'))
+      return out(
+        JSON.stringify(
+          { since: new Date(from).toISOString(), github: activity !== null, people },
+          null,
+          2,
+        ),
+      );
+    out(
+      `Since ${seen ? ago(seen.at) : 'yesterday'}${activity === null ? " (GitHub's activity couldn't be read; claims only)" : ''}:`,
+    );
+    if (!all.length) return out('  Nothing new.');
+    for (const [who, list] of Object.entries(people))
+      out(`  ${who}${who === state.me ? ' (you)' : ''}: ${list.map((e) => e.text).join('; ')}.`);
+    return;
+  }
+  if (sub !== undefined)
+    die(
+      'code-kit team [--json] [--fresh] | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle>',
+    );
+  const state = provider.state({ fresh: flag('--fresh') });
+  if (flag('--json')) return out(JSON.stringify(state, null, 2));
+  const you = state.me
+    ? `You are ${state.me}${state.me === team.techLead ? ', the tech lead' : ''}.`
+    : "You aren't signed in to GitHub (gh auth login).";
+  out('Team mode is a preview: report anything that looks wrong.');
+  out(`Tech lead: ${team.techLead}. ${you}`);
+  if (state.reachable === false)
+    out(
+      `${state.why ?? "The shared repository can't be reached"}: claims and leases aren't checked until it can be; every other rule still holds.`,
+    );
+  if (state.github === false) out("GitHub's issues and pull requests couldn't be read (gh).");
+  for (const [lane, owners] of Object.entries(team.owners))
+    out(`Lane ${lane}: ${owners.join(', ')}`);
+  out(state.claims.length ? 'Claims:' : 'Nothing is claimed.');
+  for (const c of state.claims)
+    out(
+      `  ${c.story} by ${c.by}, ${ago(c.at)}${c.stale ? ` · stale, nothing since ${ago(c.active)}` : ''}${c.lease.length ? ` · leases ${c.lease.join(', ')}` : ''}`,
+    );
+  if (state.intents.length) out('Intents:');
+  for (const i of state.intents)
+    out(
+      `  #${i.id} ${i.about} (${i.by})${i.touches.length ? ` · touches ${i.touches.join(', ')}` : ''}`,
+    );
+  if (state.pulls.length) out('Open pull requests:');
+  for (const p of state.pulls)
+    out(`  #${p.number} ${p.title} (${p.by}, ${p.branch}${p.draft ? ', draft' : ''})`);
+}
+
+/**
+ * TEAM-5: `intend "<what and why>" [--touches globs]` raises an intent before any code, so the team sees
+ * a change of direction first; `intend agree|drop|duplicate <id> [--reason "…"]` is the tech lead's answer.
+ */
+function intendCommand() {
+  const { raw } = load();
+  const team = teamOf(raw);
+  if (!team) die('This project has no "team" in its config, so intents have nowhere to go.');
+  const provider = teamProvider(resolve('.'), team);
+  const [first, id] = rest;
+  // TEAM-10: an agreed intent, written where agents read it.
+  if (first === 'record') {
+    if (!/^\d+$/.test(id ?? '')) die('code-kit intend record <discussion number>');
+    const d = provider.intent(Number(id));
+    if (!d) die("GitHub can't be reached, so the intent can't be read.");
+    if (d.missing) die(`There's no intent #${id} in ${team.intents}.`);
+    if (!(d.closed && d.stateReason === 'RESOLVED'))
+      die(`Intent #${id} isn't agreed yet: only an agreed intent becomes a decision record.`);
+    const dir = raw.docs?.decisions ?? 'docs/decisions';
+    mkdirSync(resolve(dir), { recursive: true });
+    const existing = readdirSync(resolve(dir)).filter((f) => f.endsWith('.md'));
+    const already = existing.find((f) => read(join(dir, f)).includes(`**Discussion:** ${d.url}`));
+    if (already) return out(`Intent #${id} is already recorded: ${join(dir, already)}`);
+    const last = Math.max(0, ...existing.map((f) => Number(f.match(/^(\d+)-/)?.[1] ?? 0)));
+    const path = join(dir, `${String(last + 1).padStart(4, '0')}-${slugOf(d.title)}.md`);
+    writeFileSync(resolve(path), decisionRecord(d, team.techLead));
+    return out(
+      `Wrote ${path}. Commit it on a branch (lead/decision-${id}), push it and open a pull request, so it's reviewed and merged like any change; once merged, every agent reads it.`,
+    );
+  }
+  if (first === 'agree' || first === 'drop' || first === 'duplicate') {
+    if (!/^\d+$/.test(id ?? '')) die(`code-kit intend ${first} <issue number> [--reason "…"]`);
+    const outcome = { agree: 'agreed', drop: 'dropped', duplicate: 'duplicate' }[first];
+    const r = provider.settle(Number(id), outcome, reason ?? '');
+    if (!r.ok) die(r.why);
+    return out(
+      first === 'agree'
+        ? `Agreed intent #${id}: it's how the team goes now. Record it so every agent builds on it: code-kit intend record ${id}`
+        : first === 'drop'
+          ? `Dropped intent #${id}.`
+          : `Marked intent #${id} a duplicate.`,
+    );
+  }
+  const about = rest.join(' ').trim();
+  if (!about) die('code-kit intend "<what you\'ll change, and why>" [--touches "<glob>,<glob>"]');
+  const touches = (touchesGiven ?? '')
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  const r = provider.intend(about, touches);
+  if (!r.ok) die(r.why);
+  out(
+    `Raised intent #${r.intent.id}: ${about}${touches.length ? ` (touches ${touches.join(', ')})` : ''}. The team sees it now; the tech lead (${team.techLead}) agrees or drops it. ${r.intent.url}`,
+  );
+}
+
 /**
  * The lead loop's pause (LOOP-6): `loop` says whether the person paused it; `loop pause|resume`, the
  * person's act from the code-kit band, records it, so other tools' background work pauses with it.
@@ -1241,6 +1509,8 @@ const commands = {
   settings,
   hold: () => (rest.length === 1 ? hold(rest[0]) : usage()),
   queue,
+  team: teamCommand,
+  intend: intendCommand,
   story: () => (rest.length === 1 ? story(rest[0]) : usage()),
   map: () => (rest.length === 1 ? mapCommand(rest[0]) : usage()),
   trail: trailCommand,
@@ -1270,8 +1540,12 @@ function usage() {
       '              | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
       '              | queue [--json] | queue add|drop <branch> | queue rules | queue merge --delegated|--person\n' +
       '              | loop [--json] | loop pause|resume\n' +
-      '              | map <story> [--json] | trail [--json] | journal [--json]\n' +
-      '              | story <id> [--json] | timeline [--json]',
+      '              | map <story>|project [--json] | trail [--json] | journal [--json]\n' +
+      '              | story <id> [--json] | timeline [--json]\n' +
+      '              | team [--json] [--fresh] | team since [--json] [--peek]\n' +
+      '              | team claim <story> [--lease globs] | team keep|release <story>\n' +
+      '              | team reassign <story> <handle> | team codeowners [--write] | team board\n' +
+      '              | intend "<what and why>" [--touches globs] | intend agree|drop|duplicate <id> [--reason "…"] | intend record <id>',
   );
 }
 await (commands[command] ?? usage)();

package/hooks/guard-bash.mjs

@@ -12,6 +12,8 @@ import { addedPackages, dependencyApproval, isDependencyFile } from './lib/depen
 import { CODE_KIT, GIT, codeOf, commandsOf, runs } from './lib/shell.mjs';
 import { block, start } from './lib/hook.mjs';
 import { CONFIG_FILE } from './lib/config.mjs';
+import { laneOfBranch, storyOfBranch, teamOf, teamProvider, whoami } from './lib/team.mjs';
+import { matchesAny } from './lib/glob.mjs';
 import { noteBefore } from './lane-audit.mjs';
 import {
   APPROVAL_LOG,
@@ -166,6 +168,16 @@ if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+loop\s+(pause|resume)\b`)))
   block(
     `Blocked: pausing or resuming the lead loop is the person's own act, from the code-kit band or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// TEAM-9: handing someone's claim to someone else is the tech lead's own decision too.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+team\s+reassign\b`)))
+  block(
+    `Blocked: reassigning a claim is the tech lead's own decision, from their terminal or the code-kit pane. Tell them who holds it, since when, and who you'd suggest, and stop.\nCommand: ${cmd}`,
+  );
+// TEAM-5: agreeing or dropping an intent is the tech lead's own decision, from their terminal or the pane.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+intend\s+(agree|drop|duplicate)\b`)))
+  block(
+    `Blocked: agreeing or dropping an intent is the tech lead's own decision, from their terminal or the code-kit pane. Tell them what you'd recommend and why, and stop.\nCommand: ${cmd}`,
+  );
 // The harness settings are the person's to change, from the pane or their terminal.
 if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
   block(
@@ -266,6 +278,58 @@ if (writesHistory && config.branches.protected.includes(branch) && !settingUp) {
   );
 }
 
+// TEAM-1, TEAM-4: in a team, making a story's branch claims the story (the dispatch), refused when the
+// lane is someone else's or the story is already claimed; a commit on it grows the claim's lease with
+// what the branch changes. When the shared repository can't be reached, nothing here is checked.
+const team = teamOf(config);
+if (team) {
+  const me = whoami(project);
+  const made = commandsOf(cmd)
+    .map((c) =>
+      c.text.match(
+        new RegExp(
+          String.raw`^${GIT}(?:switch\s+(?:-c|--create)|checkout\s+-b|worktree\s+add\b.*?\s-b)\s+(\S+)`,
+        ),
+      ),
+    )
+    .find(Boolean)?.[1];
+  const story = storyOfBranch(made);
+  if (story && me) {
+    const lane = laneOfBranch(made);
+    const owners = team.owners[lane];
+    if (owners && !owners.includes(me))
+      block(
+        `Blocked: the ${lane} lane is ${owners.join(' and ')}'s, so ${story} is theirs to dispatch. Leave it for them, or ask the tech lead (${team.techLead}) to change the lane's owners.\nCommand: ${cmd}`,
+      );
+    const claimed = teamProvider(project, team).claim(story);
+    if (claimed.holder)
+      block(
+        `Blocked: ${story} is already claimed by ${claimed.holder.by}, so someone is building it. Pick another story, or ask ${claimed.holder.by} or the tech lead (${team.techLead}) to release it.\nCommand: ${cmd}`,
+      );
+  }
+  // The branch by name, which also works before its first commit.
+  const named = spawnSync('git', ['-C', root, 'symbolic-ref', '--short', '-q', 'HEAD'], {
+    encoding: 'utf8',
+  }).stdout?.trim();
+  const mine = storyOfBranch(named || branch);
+  if (commits && mine && me) {
+    const provider = teamProvider(project, team);
+    const claim = provider.state().claims?.find((c) => c.story === mine && c.by === me);
+    const base = config.branches.protected[0];
+    const since = spawnSync('git', ['-C', root, 'merge-base', 'HEAD', base], { encoding: 'utf8' });
+    const changed = (args) =>
+      spawnSync('git', ['-C', root, 'diff', '--name-only', ...args], { encoding: 'utf8' })
+        .stdout.split('\n')
+        .filter(Boolean);
+    const files = [
+      ...(since.status === 0 ? changed([since.stdout.trim()]) : []),
+      ...changed(['--cached']),
+    ];
+    const grown = files.filter((f) => !matchesAny(f, claim?.lease ?? []));
+    if (claim && grown.length) provider.claim(mine, grown);
+  }
+}
+
 // Kit files edited through the shell follow the same rule as edits through Write/Edit: a command that
 // names a kit file and writes, judged one simple command at a time, so a redirect elsewhere in the line
 // (`npm install > /tmp/log; ls .claude/skills`) isn't taken for a write to the kit. A write the shell

package/hooks/guard-paths.mjs

@@ -8,6 +8,8 @@ import { loadBaseline, newProblems } from './lib/baseline.mjs';
 import { CONFIG_FILE } from './lib/config.mjs';
 import { layerProblems } from './lib/layers.mjs';
 import { block, start } from './lib/hook.mjs';
+import { teamOf, teamProvider, teamRefusal, whoami } from './lib/team.mjs';
+import { spawnSync } from 'node:child_process';
 import {
   actorFor,
   projectWorktrees,
@@ -35,6 +37,23 @@ if (error) {
 const problem = writeProblem(actorFor(input, root, config), rel, root, config);
 if (problem) block(`Blocked: ${problem}`);
 
+// TEAM-1, TEAM-4: in a team, the tech lead's paths, other people's lanes, claims and leases.
+const team = teamOf(config);
+if (team) {
+  const branch = spawnSync('git', ['-C', root, 'symbolic-ref', '--short', '-q', 'HEAD'], {
+    encoding: 'utf8',
+  }).stdout?.trim();
+  const refusal = teamRefusal({
+    actor: actorFor(input, root, config),
+    rel,
+    branch,
+    config,
+    me: whoami(project),
+    state: teamProvider(project, team).state(),
+  });
+  if (refusal) block(`Blocked: ${refusal}`);
+}
+
 /** The file's text after this call, when the call carries enough to know it. */
 function textAfter(before) {
   const ti = input.tool_input ?? {};

package/hooks/lib/adapters/context-graph.mjs

@@ -120,6 +120,11 @@ export default {
     /** The command that opens Context Graph's pane on a file, given its path. */
     open: { command: 'graph' },
   },
+  // ONB-3: set up before the coding loop, so every lane's first edit already has the why behind it.
+  onboard: {
+    skill: 'context-graph:init',
+    why: 'Context Graph is installed but has no graph in this project yet. Set it up before any code is written, so every lane works from the why behind each file from its first edit.',
+  },
   setup: [
     '.gitignore: .ctx/archive/, .ctx/bench/, .ctx/models/ and .ctx/serve.json (ctx working files, never committed)',
     '.gitattributes: .ctx/decisions.ctx merge=union and .ctx/cards.ctx merge=union (lanes record decisions and cards on parallel branches; merging keeps them all)',

package/hooks/lib/adapters/index.mjs

@@ -11,6 +11,8 @@
 //             shell.block (`person: true` marks a person's act the lead may do for them under
 //             approvals.lead); restricted: commands only the lead and the listed lanes may run
 //   setup     lines for init to apply or tell the person: ignore files, merge drivers, instructions
+//   onboard   { skill, why }: the tool's own setup skill, which `next` runs before any coding when the
+//             config wants the tool ("adapters": { "<name>": true }) but it isn't set up here yet
 //   facts     what the tool knows of the lanes' work, for the mod's combined view: { available(root),
 //             lanes(root, { session }) → { [agent type or 'lead']: { withoutUnderstanding, cardsOwed } },
 //             files(root, paths) → { [path]: { rules } }, open: { command } (its view of a file) }
@@ -40,6 +42,16 @@ export function adapterFacts(raw, root, { session = null, paths = null } = {}) {
     }));
 }
 
+/**
+ * ONB-3: tools the config wants (`"adapters": { "<name>": true }`) that aren't set up in `root` yet,
+ * with each one's setup skill: [{ name, skill, why }].
+ */
+export function pendingSetup(raw, root) {
+  return ADAPTERS.filter(
+    (a) => raw?.adapters?.[a.name] === true && a.onboard && !a.detect(root),
+  ).map((a) => ({ name: a.name, ...a.onboard }));
+}
+
 /** The effective config with every active adapter's contributions merged in. */
 export function applyAdapters(config, raw, root) {
   const active = activeAdapters(raw, root);

package/hooks/lib/config.mjs

@@ -3,6 +3,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { harnessProblems, harnessSettings } from './harness.mjs';
+import { teamProblems } from './team.mjs';
 import { join } from 'node:path';
 import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
 
@@ -140,6 +141,13 @@ const isRegExp = (v) => {
   }
 };
 
+/**
+ * ONB-5: the version of init's setup. 2 adds project skills with the lane agents, the design gate for
+ * lanes with screens, a QA lane for end-to-end tests, and companions set up before coding (spec 17). A
+ * project set up before (no `setup`, or a lower one) is told what re-running init adds.
+ */
+export const SETUP_VERSION = 2;
+
 /** Every problem with a parsed config, as readable sentences; empty when it is valid. */
 export function validate(c) {
   if (!isObj(c)) return ['the config must be a JSON object'];
@@ -156,9 +164,14 @@ export function validate(c) {
     );
   };
   need(c.version === 1, '"version" must be 1');
+  need(
+    c.setup === undefined ||
+      (Number.isInteger(c.setup) && c.setup >= 1 && c.setup <= SETUP_VERSION),
+    `"setup" must be a whole number from 1 to ${SETUP_VERSION}: the version of init's setup the project has`,
+  );
   // A brownfield project may have no specs yet: then there is no spec-check gate.
   need(c.docs === undefined || isObj(c.docs), '"docs" must be an object');
-  for (const k of ['specs', 'principles', 'plan'])
+  for (const k of ['specs', 'principles', 'plan', 'decisions'])
     need(c.docs?.[k] === undefined || isStr(c.docs[k]), `"docs.${k}" must be a path`);
   need(isObj(c.lead) && isList(c.lead?.paths), '"lead.paths" must be a list of globs');
   need(
@@ -232,6 +245,7 @@ export function validate(c) {
     '"branches.protected" must be a list of branch names',
   );
   p.push(...harnessProblems(c.harness));
+  p.push(...teamProblems(c));
   return p;
 }
 

package/hooks/lib/next.mjs

@@ -5,7 +5,9 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { loadConfig, mergeDelegation } from './config.mjs';
-import { buildStatus, readStories, LEAD } from './plan.mjs';
+import { buildStatus, readStories, DESIGN, LEAD } from './plan.mjs';
+import { pendingSetup } from './adapters/index.mjs';
+import { CONFIG_FILE, SETUP_VERSION } from './config.mjs';
 import { readQueue, waiting } from './queue.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
@@ -138,6 +140,23 @@ export function nextStep(root, base) {
       `${plan} has no stories in the \`### ST-n\` form yet; spec-design writes the plan.`,
     );
 
+  // ONB-3: a companion the config wants is set up before any coding starts.
+  let raw = null;
+  try {
+    raw = JSON.parse(readFileSync(join(root, CONFIG_FILE), 'utf8'));
+  } catch {
+    // read and validated above; nothing to add
+  }
+  const [setup] = pendingSetup(raw, root);
+  if (setup) return result('setup', setup.why, { args: setup.skill });
+  // ONB-5: a project set up before setup did all of this is told what re-running init adds.
+  if ((raw?.setup ?? 1) < SETUP_VERSION)
+    attention.push(
+      "This project's code-kit setup predates what init now sets up: project skills with each lane agent, designs approved before screens are built, a QA lane for end-to-end tests, and companion tools set up before coding. Re-run /code-kit:init to add what's missing; it keeps everything that's still right and shows you the difference first.",
+    );
+  // ONB-1: a lane agent naming a skill that doesn't exist works without the recipe it was given.
+  for (const missing of missingSkills(root)) attention.push(missing);
+
   const from = base(config);
   if (!from)
     attention.push('The base branch has no commits yet, so story branches are read against HEAD.');
@@ -163,13 +182,17 @@ export function nextStep(root, base) {
   // A ready story with a gap (unknown lane, a requirement no spec defines) waits for the plan's fix.
   const defined = new Set(status.requirements.map((r) => r.id));
   const buildable = (s) =>
-    (Boolean(config.lanes[s.lane]) || s.lane === LEAD) &&
+    (Boolean(config.lanes[s.lane]) || s.lane === LEAD || s.lane === DESIGN) &&
     (s.requirements.length > 0 || s.noRequirements) &&
     s.requirements.every((r) => defined.has(r));
   const readyStories = status.stories.filter((s) => s.state === 'ready');
   // The lead's own stories are built by the lead, not dispatched to a lane agent.
   const forLead = readyStories.filter((s) => buildable(s) && s.lane === LEAD).map((s) => s.id);
-  const ready = readyStories.filter((s) => buildable(s) && s.lane !== LEAD).map((s) => s.id);
+  const ready = readyStories
+    .filter((s) => buildable(s) && s.lane !== LEAD && s.lane !== DESIGN)
+    .map((s) => s.id);
+  // ONB-2: design stories, designed with the person before any screen that depends on them is built.
+  const forDesign = readyStories.filter((s) => buildable(s) && s.lane === DESIGN).map((s) => s.id);
   const unbuildable = readyStories.filter((s) => !buildable(s)).map((s) => s.id);
   if (unbuildable.length)
     attention.push(
@@ -201,6 +224,7 @@ export function nextStep(root, base) {
   const then = [];
   // A sent-back story goes back to its lane with the review's findings, before new work starts.
   const toDispatch = [...fixes, ...ready];
+  if (review.length && forDesign.length) then.push({ step: 'design', args: forDesign.join(' ') });
   if (review.length && toDispatch.length)
     then.push({ step: 'dispatch', args: toDispatch.join(' ') });
   if (forLead.length) then.push({ step: 'lead', args: forLead.join(' ') });
@@ -209,6 +233,18 @@ export function nextStep(root, base) {
       args: review.join(' '),
       then,
     });
+  if (forDesign.length)
+    return result(
+      'design',
+      `${forDesign.join(', ')} ${forDesign.length === 1 ? 'designs' : 'design'} the screens before any code is written for them; the person approves each design.`,
+      {
+        args: forDesign.join(' '),
+        then: [
+          ...(toDispatch.length ? [{ step: 'dispatch', args: toDispatch.join(' ') }] : []),
+          ...(forLead.length ? [{ step: 'lead', args: forLead.join(' ') }] : []),
+        ],
+      },
+    );
   if (fixes.length)
     return result(
       'dispatch',
@@ -257,3 +293,39 @@ export function nextStep(root, base) {
     `All ${status.stories.length} stories are done; spec-design plans the next milestone or feature.`,
   );
 }
+
+/** The code-kit skills every agent may name without a project copy. */
+const KIT_SKILLS = (() => {
+  try {
+    return new Set(readdirSync(new URL('../../skills/', import.meta.url)));
+  } catch {
+    return new Set();
+  }
+})();
+
+/**
+ * ONB-1: lane agents naming skills under **Skills to use** that don't exist, in words: ["web-engineer
+ * names a skill that doesn't exist: new-screen"]. Plugin skills (`plugin:skill`) and code-kit's own are
+ * left alone.
+ */
+export function missingSkills(root) {
+  const dir = join(root, '.claude/agents');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+    const line = readFileSync(join(dir, file), 'utf8').match(/^\*\*Skills to use:\*\*(.*)$/m)?.[1];
+    if (!line) continue;
+    const missing = line
+      .split(',')
+      .map((n) => n.replace(/[`*]/g, '').trim())
+      .filter((n) => /^[a-z0-9][a-z0-9-]*$/.test(n))
+      .filter(
+        (n) => !KIT_SKILLS.has(n) && !existsSync(join(root, '.claude/skills', n, 'SKILL.md')),
+      );
+    if (missing.length)
+      out.push(
+        `${file.replace(/\.md$/, '')} names ${missing.length === 1 ? "a skill that doesn't" : "skills that don't"} exist: ${missing.join(', ')}. Write ${missing.length === 1 ? 'it' : 'them'} from the architecture's recipes (re-run init), or take ${missing.length === 1 ? 'it' : 'them'} off the agent.`,
+      );
+  }
+  return out;
+}