work-kit-cli 0.2.7 → 0.3.0

package/cli/src/commands/report.ts

@@ -0,0 +1,217 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findWorktreeRoot, resolveMainRepoRoot } from "../state/store.js";
+import { TRACKER_DIR, ARCHIVE_DIR, INDEX_FILE } from "../config/constants.js";
+import {
+  PHASE_NAMES,
+  MODE_FULL,
+  MODE_AUTO,
+  type PhaseName,
+  type Classification,
+  type WorkKitState,
+} from "../state/schema.js";
+import { readJsonFile } from "../utils/json.js";
+import { durationMs, formatDurationMs } from "../utils/time.js";
+import { bold, cyan, dim, green, yellow } from "../utils/colors.js";
+
+const RECENT_LIMIT = 10;
+
+export interface PhaseStats {
+  runs: number;
+  avgDurationMs: number;
+  totalDurationMs: number;
+}
+
+export interface RecentEntry {
+  slug: string;
+  completedAt: string;
+  classification?: Classification;
+  mode: typeof MODE_FULL | typeof MODE_AUTO;
+  durationMs?: number;
+}
+
+export interface ReportData {
+  totalCompleted: number;
+  byClassification: Partial<Record<Classification | "unclassified", number>>;
+  byMode: Partial<Record<typeof MODE_FULL | typeof MODE_AUTO, number>>;
+  avgDurationMs: number;
+  totalLoopbacks: number;
+  loopbackRate: number;
+  perPhase: Record<PhaseName, PhaseStats>;
+  recent: RecentEntry[];
+  source: { mainRepoRoot: string; trackerDir: string };
+}
+
+function emptyPhaseStats(): PhaseStats {
+  return { runs: 0, avgDurationMs: 0, totalDurationMs: 0 };
+}
+
+export function collectReport(mainRepoRoot: string): ReportData {
+  const trackerDir = path.join(mainRepoRoot, TRACKER_DIR);
+  const archiveDir = path.join(trackerDir, ARCHIVE_DIR);
+
+  const data: ReportData = {
+    totalCompleted: 0,
+    byClassification: {},
+    byMode: {},
+    avgDurationMs: 0,
+    totalLoopbacks: 0,
+    loopbackRate: 0,
+    perPhase: PHASE_NAMES.reduce((acc, p) => {
+      acc[p] = emptyPhaseStats();
+      return acc;
+    }, {} as Record<PhaseName, PhaseStats>),
+    recent: [],
+    source: { mainRepoRoot, trackerDir },
+  };
+
+  let folders: string[];
+  try {
+    folders = fs.readdirSync(archiveDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch {
+    return data;
+  }
+
+  let totalRunDurationMs = 0;
+  let runsWithDuration = 0;
+  // Bounded min-heap-by-completedAt would be ideal; for ≤10 entries
+  // a simple sorted insertion is cheaper than a full sort at the end.
+  const keepRecent = (entry: RecentEntry) => {
+    data.recent.push(entry);
+    data.recent.sort((a, b) => (a.completedAt < b.completedAt ? 1 : -1));
+    if (data.recent.length > RECENT_LIMIT) data.recent.length = RECENT_LIMIT;
+  };
+
+  for (const folder of folders) {
+    const state = readJsonFile<WorkKitState>(path.join(archiveDir, folder, "tracker.json"));
+    if (!state) continue;
+
+    data.totalCompleted++;
+
+    const cls = state.classification ?? "unclassified";
+    data.byClassification[cls] = (data.byClassification[cls] ?? 0) + 1;
+    data.byMode[state.mode] = (data.byMode[state.mode] ?? 0) + 1;
+    data.totalLoopbacks += state.loopbacks?.length ?? 0;
+
+    let runDuration = 0;
+    let lastEnd: string | undefined;
+    for (const phase of PHASE_NAMES) {
+      const ps = state.phases[phase];
+      if (!ps || ps.status !== "completed") continue;
+      const d = durationMs(ps.startedAt, ps.completedAt);
+      data.perPhase[phase].runs++;
+      data.perPhase[phase].totalDurationMs += d;
+      runDuration += d;
+      if (ps.completedAt && (!lastEnd || ps.completedAt > lastEnd)) lastEnd = ps.completedAt;
+    }
+
+    if (runDuration > 0) {
+      totalRunDurationMs += runDuration;
+      runsWithDuration++;
+    }
+
+    keepRecent({
+      slug: state.slug,
+      completedAt: lastEnd ?? state.started,
+      classification: state.classification,
+      mode: state.mode,
+      durationMs: runDuration > 0 ? runDuration : undefined,
+    });
+  }
+
+  for (const phase of PHASE_NAMES) {
+    const s = data.perPhase[phase];
+    s.avgDurationMs = s.runs > 0 ? Math.round(s.totalDurationMs / s.runs) : 0;
+  }
+  data.avgDurationMs = runsWithDuration > 0 ? Math.round(totalRunDurationMs / runsWithDuration) : 0;
+  data.loopbackRate = data.totalCompleted > 0 ? data.totalLoopbacks / data.totalCompleted : 0;
+
+  return data;
+}
+
+export interface ReportOptions {
+  json?: boolean;
+  worktreeRoot?: string;
+  repo?: string;
+}
+
+export function reportCommand(options: ReportOptions = {}): ReportData {
+  const mainRepoRoot = options.repo
+    ? path.resolve(options.repo)
+    : resolveMainRepoRoot(options.worktreeRoot || findWorktreeRoot() || process.cwd());
+
+  const data = collectReport(mainRepoRoot);
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    return data;
+  }
+
+  const out: string[] = [];
+  out.push("");
+  out.push(bold("  WORK-KIT REPORT"));
+  out.push(dim(`  ${data.source.trackerDir}`));
+  out.push("");
+
+  if (data.totalCompleted === 0) {
+    out.push(dim("  No completed work-kits found."));
+    out.push("");
+    process.stderr.write(out.join("\n") + "\n");
+    return data;
+  }
+
+  out.push(`  ${cyan("Completed")}    ${bold(String(data.totalCompleted))}`);
+  out.push(`  ${cyan("Avg run")}      ${formatDurationMs(data.avgDurationMs)}`);
+  out.push(`  ${cyan("Loopbacks")}    ${data.totalLoopbacks} ${dim(`(${(data.loopbackRate * 100).toFixed(0)}% rate)`)}`);
+  out.push("");
+
+  const byClassEntries = Object.entries(data.byClassification);
+  if (byClassEntries.length > 0) {
+    out.push(bold("  By Classification"));
+    for (const [cls, count] of byClassEntries.sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
+      out.push(`    ${cls.padEnd(16)} ${count}`);
+    }
+    out.push("");
+  }
+
+  const byModeEntries = Object.entries(data.byMode);
+  if (byModeEntries.length > 0) {
+    out.push(bold("  By Mode"));
+    for (const [mode, count] of byModeEntries.sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
+      out.push(`    ${mode.padEnd(16)} ${count}`);
+    }
+    out.push("");
+  }
+
+  out.push(bold("  Avg Phase Duration"));
+  for (const phase of PHASE_NAMES) {
+    const s = data.perPhase[phase];
+    if (s.runs === 0) continue;
+    out.push(`    ${phase.padEnd(10)} ${formatDurationMs(s.avgDurationMs).padStart(7)} ${dim(`(${s.runs} runs)`)}`);
+  }
+  out.push("");
+
+  if (data.recent.length > 0) {
+    out.push(bold("  Recent"));
+    for (const r of data.recent) {
+      const date = r.completedAt.split("T")[0];
+      const cls = r.classification ? dim(` [${r.classification}]`) : "";
+      const dur = r.durationMs ? dim(` ${formatDurationMs(r.durationMs)}`) : "";
+      out.push(`    ${green("✓")} ${date}  ${r.slug}${cls}${dur}`);
+    }
+    out.push("");
+  }
+
+  const indexPath = path.join(data.source.trackerDir, INDEX_FILE);
+  if (fs.existsSync(indexPath)) {
+    out.push(dim(`  Full index: ${indexPath}`));
+  } else {
+    out.push(yellow(`  Note: ${INDEX_FILE} not found.`));
+  }
+  out.push("");
+
+  process.stderr.write(out.join("\n") + "\n");
+  return data;
+}

package/cli/src/commands/resume.ts

@@ -0,0 +1,38 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import { unpause } from "../state/helpers.js";
+import { CLI_BINARY } from "../config/constants.js";
+import type { Action } from "../state/schema.js";
+
+export function resumeCommand(worktreeRoot?: string): Action {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found." };
+  }
+
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return { action: "error", message: `${state.slug} is already completed.` };
+  }
+  if (state.status === "in-progress") {
+    return {
+      action: "resumed",
+      message: `${state.slug} is already in progress. Run \`${CLI_BINARY} next\` to continue.`,
+      phase: state.currentPhase,
+      step: state.currentStep,
+    };
+  }
+  if (state.status === "failed") {
+    return { action: "error", message: `${state.slug} is in failed state; cannot resume.` };
+  }
+
+  unpause(state);
+  writeState(root, state);
+
+  return {
+    action: "resumed",
+    message: `Resumed ${state.slug}. Run \`${CLI_BINARY} next\` to continue.`,
+    phase: state.currentPhase,
+    step: state.currentStep,
+  };
+}

package/cli/src/commands/setup.ts

@@ -69,6 +69,132 @@ function copySkills(targetDir: string): { copied: string[]; skipped: string[] }
   return { copied, skipped };
 }
 
+// ── Hooks installation ──────────────────────────────────────────────
+//
+// Writes marker files the observer polls to detect "blocked on user" state.
+// Each hook command carries a sentinel comment so setup can be re-run
+// idempotently — existing work-kit entries are stripped and re-added.
+
+const HOOK_SENTINEL = "# work-kit-hook";
+
+type HookEntry = { type: "command"; command: string };
+type HookMatcherGroup = { matcher?: string; hooks: HookEntry[] };
+type HookSettings = Record<string, HookMatcherGroup[]>;
+
+interface WorkKitHookSpec {
+  event: string;
+  matcher: string;
+  command: string;
+}
+
+// Markers live under the per-worktree `.work-kit/` state dir.
+// Hook commands run from Claude Code's CWD, which is the project/worktree root.
+const WK_HOOKS: WorkKitHookSpec[] = [
+  // PermissionRequest → agent blocked on a tool permission prompt
+  {
+    event: "PermissionRequest",
+    matcher: "",
+    command: `mkdir -p .work-kit && date -u +%s > .work-kit/awaiting-input ${HOOK_SENTINEL}`,
+  },
+  // AskUserQuestion tool call → agent explicitly asking the user
+  {
+    event: "PreToolUse",
+    matcher: "AskUserQuestion",
+    command: `mkdir -p .work-kit && date -u +%s > .work-kit/awaiting-input ${HOOK_SENTINEL}`,
+  },
+  {
+    event: "PostToolUse",
+    matcher: "AskUserQuestion",
+    command: `rm -f .work-kit/awaiting-input ${HOOK_SENTINEL}`,
+  },
+  // Any tool call → clear idle marker (agent is active again)
+  {
+    event: "PreToolUse",
+    matcher: "",
+    command: `rm -f .work-kit/idle ${HOOK_SENTINEL}`,
+  },
+  // Stop → turn ended. Write idle marker (soft signal); also clear
+  // any stale awaiting-input marker that wasn't paired with PostToolUse
+  // (e.g. permission prompt was denied).
+  {
+    event: "Stop",
+    matcher: "",
+    command: `mkdir -p .work-kit && date -u +%s > .work-kit/idle && rm -f .work-kit/awaiting-input ${HOOK_SENTINEL}`,
+  },
+];
+
+function stripWorkKitHooks(hooks: HookSettings): HookSettings {
+  const cleaned: HookSettings = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const cleanedGroups: HookMatcherGroup[] = [];
+    for (const group of groups) {
+      const cleanedEntries = (group.hooks || []).filter(
+        (h) => !(h.type === "command" && typeof h.command === "string" && h.command.includes(HOOK_SENTINEL))
+      );
+      if (cleanedEntries.length > 0) {
+        cleanedGroups.push({ ...group, hooks: cleanedEntries });
+      }
+    }
+    if (cleanedGroups.length > 0) {
+      cleaned[event] = cleanedGroups;
+    }
+  }
+  return cleaned;
+}
+
+function addWorkKitHooks(hooks: HookSettings): HookSettings {
+  const out: HookSettings = { ...hooks };
+  for (const spec of WK_HOOKS) {
+    const groups = out[spec.event] ? [...out[spec.event]] : [];
+    const entry: HookEntry = { type: "command", command: spec.command };
+    // Try to reuse an existing matcher group with the same matcher
+    const existingIdx = groups.findIndex((g) => (g.matcher ?? "") === spec.matcher);
+    if (existingIdx >= 0) {
+      groups[existingIdx] = {
+        ...groups[existingIdx],
+        hooks: [...(groups[existingIdx].hooks || []), entry],
+      };
+    } else {
+      groups.push({ matcher: spec.matcher, hooks: [entry] });
+    }
+    out[spec.event] = groups;
+  }
+  return out;
+}
+
+function installHooks(projectDir: string): { added: number; file: string } {
+  const settingsDir = path.join(projectDir, ".claude");
+  const settingsFile = path.join(settingsDir, "settings.json");
+
+  if (!fs.existsSync(settingsDir)) {
+    fs.mkdirSync(settingsDir, { recursive: true });
+  }
+
+  let settings: Record<string, unknown> = {};
+  if (fs.existsSync(settingsFile)) {
+    try {
+      const raw = fs.readFileSync(settingsFile, "utf-8");
+      settings = raw.trim() ? JSON.parse(raw) : {};
+    } catch (err) {
+      throw new Error(
+        `Failed to parse ${settingsFile}: ${(err as Error).message}. Fix or remove the file and re-run setup.`
+      );
+    }
+  }
+
+  const existingHooks: HookSettings =
+    (settings.hooks && typeof settings.hooks === "object" ? (settings.hooks as HookSettings) : {}) ?? {};
+
+  const stripped = stripWorkKitHooks(existingHooks);
+  const merged = addWorkKitHooks(stripped);
+
+  settings.hooks = merged;
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
+
+  return { added: WK_HOOKS.length, file: settingsFile };
+}
+
 async function promptUser(question: string): Promise<string> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
   return new Promise((resolve) => {
@@ -142,6 +268,16 @@ export async function setupCommand(targetPath?: string): Promise<void> {
     console.error(`  ${dim("Already up to date.")}`);
   }
 
+  // Install Claude Code hooks so the observer can detect "blocked on user" state
+  console.error(`\nInstalling Claude Code hooks into ${projectDir}/.claude/settings.json...`);
+  try {
+    const { added, file } = installHooks(projectDir);
+    console.error(`  ${green("+")} ${added} hook${added === 1 ? "" : "s"} merged into ${path.relative(projectDir, file) || file}`);
+    console.error(`  ${dim("Observer will now detect permission prompts and AskUserQuestion calls.")}`);
+  } catch (err) {
+    console.error(`  ${red("✗")} ${(err as Error).message}`);
+  }
+
   // Run doctor against the target project
   console.error("\nRunning doctor...");
   const result = doctorCommand(projectDir);

package/cli/src/commands/status.ts

@@ -8,7 +8,7 @@ interface StatusOutput {
   classification?: string;
   status: string;
   currentPhase: string | null;
-  currentSubStage: string | null;
+  currentStep: string | null;
   started: string;
   phases: Record<string, { status: string; completed: number; total: number; active: number }>;
   loopbackCount: number;
@@ -26,11 +26,11 @@ export function statusCommand(worktreeRoot?: string): StatusOutput {
   for (const phase of PHASE_NAMES) {
     const ps = state.phases[phase];
     let completed = 0, total = 0, active = 0;
-    for (const ss of Object.values(ps.subStages)) {
-      if (ss.status === "skipped") continue;
+    for (const s of Object.values(ps.steps)) {
+      if (s.status === "skipped") continue;
       total++;
-      if (ss.status === "completed") completed++;
-      else if (ss.status === "in-progress" || ss.status === "waiting") active++;
+      if (s.status === "completed") completed++;
+      else if (s.status === "in-progress" || s.status === "waiting") active++;
     }
     phases[phase] = { status: ps.status, completed, total, active };
   }
@@ -42,7 +42,7 @@ export function statusCommand(worktreeRoot?: string): StatusOutput {
     ...(state.classification && { classification: state.classification }),
     status: state.status,
     currentPhase: state.currentPhase,
-    currentSubStage: state.currentSubStage,
+    currentStep: state.currentStep,
     started: state.started,
     phases,
     loopbackCount: state.loopbacks.length,

package/cli/src/commands/uninstall.ts

@@ -2,9 +2,14 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { bold, dim, green, red, yellow } from "../utils/colors.js";
+import { PHASE_NAMES } from "../state/schema.js";
+import { SKILL_DIR_PREFIX } from "../config/constants.js";
+import { STATE_DIR, STATE_FILE } from "../state/store.js";
 
 const WORK_KIT_SKILLS = [
-  "full-kit", "auto-kit", "wk-plan", "wk-build", "wk-test", "wk-review", "wk-deploy", "wk-wrap-up",
+  "full-kit", "auto-kit", "cancel-kit", "pause-kit", "resume-kit",
+  ...PHASE_NAMES.map(p => `${SKILL_DIR_PREFIX}${p}`),
+  `${SKILL_DIR_PREFIX}bootstrap`,
 ];
 
 async function promptUser(question: string): Promise<string> {
@@ -52,9 +57,9 @@ export async function uninstallCommand(targetPath?: string): Promise<void> {
   }
 
   // Check for active state
-  const trackerFile = path.join(projectDir, ".work-kit", "tracker.json");
+  const trackerFile = path.join(projectDir, STATE_DIR, STATE_FILE);
   if (fs.existsSync(trackerFile)) {
-    console.error(yellow("\nWarning: Active work-kit state found (.work-kit/tracker.json)."));
+    console.error(yellow(`\nWarning: Active work-kit state found (${STATE_DIR}/${STATE_FILE}).`));
     console.error(yellow("Uninstalling will not remove in-progress state files."));
   }
 

package/cli/src/commands/workflow.ts

@@ -1,5 +1,5 @@
 import { readState, writeState, findWorktreeRoot } from "../state/store.js";
-import { SUBSTAGES_BY_PHASE, PHASE_NAMES } from "../state/schema.js";
+import { STEPS_BY_PHASE, PHASE_NAMES, MODE_AUTO } from "../state/schema.js";
 import { parseLocation } from "../state/helpers.js";
 import type { Action } from "../state/schema.js";
 
@@ -22,7 +22,7 @@ export function workflowCommand(opts: {
 
   const state = readState(root);
 
-  if (state.mode !== "auto-kit") {
+  if (state.mode !== MODE_AUTO) {
     return { action: "error", message: "Workflow management is only available in auto-kit mode." };
   }
 
@@ -31,13 +31,13 @@ export function workflowCommand(opts: {
   }
 
   if (opts.add) {
-    const { phase, subStage } = parseLocation(opts.add);
+    const { phase, step } = parseLocation(opts.add);
 
-    if (!PHASE_NAMES.includes(phase) || !SUBSTAGES_BY_PHASE[phase].includes(subStage)) {
+    if (!PHASE_NAMES.includes(phase) || !STEPS_BY_PHASE[phase].includes(step)) {
       return { action: "error", message: `Invalid step: ${opts.add}` };
     }
 
-    const existing = state.workflow.find((s) => s.phase === phase && s.subStage === subStage);
+    const existing = state.workflow.find((s) => s.phase === phase && s.step === step);
     if (existing) {
       if (existing.included) {
         return { action: "error", message: `${opts.add} is already in the workflow.` };
@@ -45,31 +45,31 @@ export function workflowCommand(opts: {
       existing.included = true;
     } else {
       const phaseIdx = PHASE_NAMES.indexOf(phase);
-      const subStageIdx = SUBSTAGES_BY_PHASE[phase].indexOf(subStage);
+      const stepIdx = STEPS_BY_PHASE[phase].indexOf(step);
 
       let insertIdx = state.workflow.length;
       for (let i = 0; i < state.workflow.length; i++) {
         const wi = state.workflow[i];
         const wiPhaseIdx = PHASE_NAMES.indexOf(wi.phase);
-        const wiSubIdx = SUBSTAGES_BY_PHASE[wi.phase].indexOf(wi.subStage);
+        const wiStepIdx = STEPS_BY_PHASE[wi.phase].indexOf(wi.step);
 
-        if (wiPhaseIdx > phaseIdx || (wiPhaseIdx === phaseIdx && wiSubIdx > subStageIdx)) {
+        if (wiPhaseIdx > phaseIdx || (wiPhaseIdx === phaseIdx && wiStepIdx > stepIdx)) {
           insertIdx = i;
           break;
         }
       }
 
-      state.workflow.splice(insertIdx, 0, { phase, subStage, included: true });
+      state.workflow.splice(insertIdx, 0, { phase, step, included: true });
     }
 
-    const currentSS = state.phases[phase].subStages[subStage];
-    if (currentSS?.status === "completed") {
+    const currentStep = state.phases[phase].steps[step];
+    if (currentStep?.status === "completed") {
       return { action: "error", message: `Cannot add ${opts.add} — it's already completed.` };
     }
-    if (!currentSS) {
-      state.phases[phase].subStages[subStage] = { status: "pending" };
-    } else if (currentSS.status === "skipped") {
-      currentSS.status = "pending";
+    if (!currentStep) {
+      state.phases[phase].steps[step] = { status: "pending" };
+    } else if (currentStep.status === "skipped") {
+      currentStep.status = "pending";
     }
 
     if (state.phases[phase].status === "skipped") {
@@ -81,28 +81,28 @@ export function workflowCommand(opts: {
   }
 
   if (opts.remove) {
-    const { phase, subStage } = parseLocation(opts.remove);
+    const { phase, step } = parseLocation(opts.remove);
 
-    const step = state.workflow.find((s) => s.phase === phase && s.subStage === subStage);
-    if (!step) {
+    const ws = state.workflow.find((s) => s.phase === phase && s.step === step);
+    if (!ws) {
       return { action: "error", message: `${opts.remove} is not in the workflow.` };
     }
 
-    const ssState = state.phases[phase]?.subStages[subStage];
-    if (ssState?.status === "completed") {
+    const stepState = state.phases[phase]?.steps[step];
+    if (stepState?.status === "completed") {
       return { action: "error", message: `Cannot remove ${opts.remove} — it's already completed.` };
     }
-    if (ssState?.status === "in-progress") {
+    if (stepState?.status === "in-progress") {
       return { action: "error", message: `Cannot remove ${opts.remove} — it's currently in progress.` };
     }
 
-    step.included = false;
+    ws.included = false;
 
-    if (ssState) {
-      ssState.status = "skipped";
+    if (stepState) {
+      stepState.status = "skipped";
     }
 
-    const allSkipped = Object.values(state.phases[phase].subStages).every(
+    const allSkipped = Object.values(state.phases[phase].steps).every(
       (s) => s.status === "skipped"
     );
     if (allSkipped) {
@@ -117,8 +117,8 @@ export function workflowCommand(opts: {
   const workflow = state.workflow
     .filter((s) => s.included)
     .map((s) => ({
-      step: `${s.phase}/${s.subStage}`,
-      status: state.phases[s.phase]?.subStages[s.subStage]?.status || "unknown",
+      step: `${s.phase}/${s.step}`,
+      status: state.phases[s.phase]?.steps[s.step]?.status || "unknown",
     }));
 
   return { action: "workflow_status", workflow };

package/cli/src/config/agent-map.ts

@@ -1,7 +1,7 @@
 import { PhaseName } from "../state/schema.js";
 
 /**
- * Maps each phase/sub-stage to the sections it needs from state.md.
+ * Maps each phase/step to the sections it needs from state.md.
  * "##" prefix = top-level section, "###" prefix = Final section.
  */
 
@@ -32,14 +32,14 @@ export const PHASE_CONTEXT: Record<PhaseName, AgentContext> = {
   },
 };
 
-// Sub-stage-level context (for parallel sub-agents that need specific sections)
-export const SUBSTAGE_CONTEXT: Record<string, AgentContext> = {
-  // Test sub-agents
+// Step-level context (for parallel sub-agents that need specific sections)
+export const STEP_CONTEXT: Record<string, AgentContext> = {
+  // Test steps
   "test/verify": { sections: ["### Build: Final", "## Criteria"] },
   "test/e2e": { sections: ["### Build: Final", "### Plan: Final"] },
   "test/validate": { sections: ["### Test: Verify", "### Test: E2E", "## Criteria"] },
 
-  // Review sub-agents
+  // Review steps
   "review/self-review": { sections: ["### Build: Final"], needsGitDiff: true },
   "review/security": { sections: ["### Build: Final"], needsGitDiff: true },
   "review/performance": { sections: ["### Build: Final"], needsGitDiff: true },
@@ -53,10 +53,10 @@ export const SUBSTAGE_CONTEXT: Record<string, AgentContext> = {
   },
 };
 
-export function getContextFor(phase: PhaseName, subStage?: string): AgentContext {
-  if (subStage) {
-    const key = `${phase}/${subStage}`;
-    if (SUBSTAGE_CONTEXT[key]) return SUBSTAGE_CONTEXT[key];
+export function getContextFor(phase: PhaseName, step?: string): AgentContext {
+  if (step) {
+    const key = `${phase}/${step}`;
+    if (STEP_CONTEXT[key]) return STEP_CONTEXT[key];
   }
   return PHASE_CONTEXT[phase];
 }

package/cli/src/config/constants.ts

@@ -0,0 +1,44 @@
+// ── Archive Paths ───────────────────────────────────────────────────
+
+export const TRACKER_DIR = ".work-kit-tracker";
+export const ARCHIVE_DIR = "archive";
+export const INDEX_FILE = "index.md";
+export const SUMMARY_FILE = "summary.md";
+
+// ── Git ─────────────────────────────────────────────────────────────
+
+export const BRANCH_PREFIX = "feature/";
+
+// ── Skills ──────────────────────────────────────────────────────────
+
+export const SKILL_DIR_PREFIX = "wk-";
+
+// ── CLI ─────────────────────────────────────────────────────────────
+
+/**
+ * Binary used in onComplete actions emitted to the orchestrator.
+ * Resolves on PATH after `npm install -g work-kit-cli`.
+ */
+export const CLI_BINARY = "work-kit";
+
+/**
+ * Fallback / install messaging form. Used in error and setup output.
+ */
+export const CLI_NPX_BINARY = "npx work-kit-cli";
+
+// ── Project Config ──────────────────────────────────────────────────
+
+/**
+ * Optional project-level config file. Lives at the main repo root and
+ * lets a project override workflow defaults, parallel groups, etc.
+ */
+export const PROJECT_CONFIG_FILE = ".work-kit-config.json";
+
+// ── Limits ──────────────────────────────────────────────────────────
+
+export const MAX_LOOPBACKS_PER_ROUTE = 2;
+
+// ── Staleness ───────────────────────────────────────────────────────
+
+/** Threshold (ms) after which an in-progress state is considered stale. */
+export const STALE_THRESHOLD_MS = 60 * 60 * 1000;