@warren-dean/code-kit 0.8.0 → 0.9.0

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(
@@ -180,11 +203,15 @@ export function nextStep(root, base) {
   // the person does, and always the first merge, which brings code-kit's rules onto the base.
   const delegation = queued.length ? mergeDelegation(root, config) : { delegated: false };
   const leadMerges = delegation.delegated && config.harness.autonomy === 'autonomous';
+  // SETUP-2: a base with no rules committed (a project set up before setup committed them there): the
+  // lead puts the approved rules onto it, and the queue merges under them from then on.
   if (queued.length && delegation.first)
-    attention.push(
-      `${queued[0]} passed review and is next to merge. ${delegation.into} has no code-kit config committed yet, so this first merge, which brings the rules onto it, is the person's (code-kit queue merge --person, or Merge in the code-kit band); after it, the lead merges.`,
+    return result(
+      'rules',
+      `${queued[0]} passed review and is next to merge, but ${delegation.into} has no code-kit rules committed yet. Put the rules the person approved onto it (code-kit queue rules); then the queue merges under them.`,
+      { args: delegation.into },
     );
-  else if (queued.length && !leadMerges)
+  if (queued.length && !leadMerges)
     attention.push(
       `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
     );
@@ -197,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(' ') });
@@ -205,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',
@@ -227,6 +267,12 @@ export function nextStep(root, base) {
       'wait',
       `${building.join(', ')} ${building.length === 1 ? 'is' : 'are'} being built; nothing else can start until one finishes. A lane that stopped without finishing is dispatched again.`,
     );
+  // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan.
+  if (queued.length)
+    return result(
+      'wait',
+      `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} to be merged; the stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`,
+    );
   if (unbuildable.length)
     return result(
       'spec-design',
@@ -247,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;
+}

package/hooks/lib/plan.mjs

@@ -14,6 +14,8 @@ const STORY_HEADING = /^###\s+(ST-\d+)\b\s*(.*)$/;
 const REQUIREMENT_HEADING = /^###\s+((?!ST-)[A-Z][A-Z0-9]*-\d+)\b\s*(.*)$/;
 export const STATES = ['todo', 'in progress', 'review', 'done'];
 export const LEAD = 'lead';
+/** ONB-2: the pseudo-lane for design stories, which the lead designs with the person before any screen is built. */
+export const DESIGN = 'design';
 // Test files, by the usual conventions. Tests name the requirement IDs they prove.
 const TEST =
   /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
@@ -185,7 +187,7 @@ export function traceProblems(requirements, stories, lanes) {
     if (storyIds.has(s.id)) problems.push(`${s.id} is in the plan more than once`);
     storyIds.add(s.id);
     if (!s.lane) problems.push(`${s.id} has no **Lane:**`);
-    else if (s.lane !== LEAD && !lanes.includes(s.lane))
+    else if (s.lane !== LEAD && s.lane !== DESIGN && !lanes.includes(s.lane))
       problems.push(`${s.id} names an unknown lane "${s.lane}"`);
     if (!s.requirements.length && !s.noRequirements)
       problems.push(`${s.id} cites no requirements (write "none" if it delivers none)`);

package/hooks/lib/storymap.mjs

@@ -153,3 +153,65 @@ export function trail(root, status, from) {
       };
     });
 }
+
+/** The code map of no story in particular: the whole project. */
+export const PROJECT = 'project';
+
+/**
+ * MAP-5: the whole project's code, for when no story is at work: its folders (`depth` deep, shallower
+ * when that makes more than `most`) by the layer most of their files sit in, with the imports between
+ * folders. The same shape as a story's map, each node a folder with its file count.
+ */
+export function projectMap(root, config, tracked, { depth = 3, most = 60 } = {}) {
+  const code = tracked.filter(isCode);
+  const set = new Set(code);
+  const aliases = config.importAliases ?? {};
+  const folderAt = (d) => (rel) => {
+    const parts = rel.split('/');
+    return parts.length === 1 ? '.' : parts.slice(0, Math.min(d, parts.length - 1)).join('/');
+  };
+  let d = depth;
+  while (d > 1 && new Set(code.map(folderAt(d))).size > most) d -= 1;
+  const folderOf = folderAt(d);
+  const nodes = new Map();
+  for (const rel of code) {
+    const path = folderOf(rel);
+    const node = nodes.get(path) ?? {
+      path,
+      lane: laneOfFile(rel, config),
+      layers: new Map(),
+      imports: new Set(),
+      files: 0,
+    };
+    nodes.set(path, node);
+    const layer = TEST.test(rel) ? 'tests' : (layerOf(rel, config.layers)?.name ?? 'other');
+    node.layers.set(layer, (node.layers.get(layer) ?? 0) + 1);
+    node.files += 1;
+    let source = '';
+    try {
+      source = readFileSync(join(root, rel), 'utf8');
+    } catch {
+      // unreadable: no imports
+    }
+    for (const spec of importsOf(source)) {
+      const target = resolveIn(spec, rel, aliases, set);
+      if (target && folderOf(target) !== path) node.imports.add(folderOf(target));
+    }
+  }
+  const files = [...nodes.values()]
+    .map((n) => ({
+      path: n.path,
+      layer: [...n.layers.entries()].sort((a, b) => b[1] - a[1])[0][0],
+      lane: n.lane,
+      imports: [...n.imports].sort(),
+      files: n.files,
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const used = new Set(files.map((f) => f.layer));
+  const layers = [...config.layers.map((l) => l.name), 'tests', 'other'].filter((l) => used.has(l));
+  return {
+    story: { id: PROJECT, title: 'The whole project', lane: null, state: null },
+    layers,
+    files,
+  };
+}