work-kit-cli 0.2.8 → 0.4.0

package/cli/src/commands/setup.ts

@@ -1,8 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
+import { spawnSync } from "node:child_process";
 import { doctorCommand } from "./doctor.js";
 import { bold, dim, green, yellow, red, cyan } from "../utils/colors.js";
+import { ensureKnowledgeDir, KNOWLEDGE_DIR, KNOWLEDGE_LOCK } from "../utils/knowledge.js";
+import { ensureGitignored } from "./init.js";
 
 const SKILLS_SOURCE = path.resolve(import.meta.dirname, "..", "..", "..", "skills");
 
@@ -69,6 +72,267 @@ 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 };
+}
+
+// ── Playwright detection / install ─────────────────────────────────
+//
+// Work-kit's Test phase requires a real E2E framework. We standardize on
+// Playwright. setup/upgrade detect whether the target project already has
+// it; if not, we offer to install it (and optionally scaffold a config).
+
+type PackageManager = "pnpm" | "yarn" | "npm";
+
+function detectPackageManager(projectDir: string): PackageManager {
+  if (fs.existsSync(path.join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(projectDir, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+function hasPlaywrightInstalled(projectDir: string): boolean {
+  const pkgPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    return Boolean(deps["@playwright/test"] || deps["playwright"]);
+  } catch {
+    return false;
+  }
+}
+
+function hasPlaywrightConfig(projectDir: string): boolean {
+  return ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs"]
+    .some((f) => fs.existsSync(path.join(projectDir, f)));
+}
+
+function runStreamed(cmd: string, args: string[], cwd: string): boolean {
+  const result = spawnSync(cmd, args, { cwd, stdio: "inherit" });
+  return result.status === 0;
+}
+
+function installPlaywrightPackage(pm: PackageManager, projectDir: string): boolean {
+  const args =
+    pm === "pnpm" ? ["add", "-D", "@playwright/test"] :
+    pm === "yarn" ? ["add", "-D", "@playwright/test"] :
+    ["install", "-D", "@playwright/test"];
+  console.error(`  ${dim(`$ ${pm} ${args.join(" ")}`)}`);
+  return runStreamed(pm, args, projectDir);
+}
+
+function installPlaywrightBrowsers(projectDir: string): boolean {
+  // Chromium-only — fastest install, covers most E2E needs.
+  console.error(`  ${dim("$ npx playwright install chromium")}`);
+  return runStreamed("npx", ["playwright", "install", "chromium"], projectDir);
+}
+
+function scaffoldPlaywrightConfig(pm: PackageManager, projectDir: string): boolean {
+  // `npm init playwright@latest` works regardless of pm (it just runs the create-playwright bin).
+  // Yarn/pnpm have their own equivalents but npm init is universally available.
+  console.error(`  ${dim("$ npm init playwright@latest -- --quiet --browser=chromium --no-examples")}`);
+  return runStreamed(
+    "npm",
+    ["init", "playwright@latest", "--", "--quiet", "--browser=chromium", "--no-examples"],
+    projectDir
+  );
+}
+
+async function ensurePlaywright(projectDir: string): Promise<void> {
+  console.error(`\nChecking Playwright (required for work-kit's E2E test step)...`);
+
+  // Non-Node project — nothing to do.
+  if (!fs.existsSync(path.join(projectDir, "package.json"))) {
+    console.error(`  ${dim("No package.json found — skipping Playwright setup.")}`);
+    return;
+  }
+
+  const pm = detectPackageManager(projectDir);
+  const installed = hasPlaywrightInstalled(projectDir);
+  const configured = hasPlaywrightConfig(projectDir);
+
+  if (installed && configured) {
+    console.error(`  ${green("\u2713")} Playwright already installed and configured.`);
+    return;
+  }
+
+  if (!installed) {
+    const answer = (await promptUser(`  Install Playwright (@playwright/test) via ${pm}? [y/N]: `)).toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.error(`  ${yellow("!")} Skipped. The wk-test E2E step will fail until Playwright is installed.`);
+      return;
+    }
+    if (!installPlaywrightPackage(pm, projectDir)) {
+      console.error(`  ${red("\u2717")} Failed to install @playwright/test.`);
+      return;
+    }
+    if (!installPlaywrightBrowsers(projectDir)) {
+      console.error(`  ${red("\u2717")} Failed to install Chromium browser.`);
+      return;
+    }
+    console.error(`  ${green("+")} Installed @playwright/test and Chromium.`);
+  }
+
+  if (!hasPlaywrightConfig(projectDir)) {
+    const answer = (await promptUser(`  No playwright.config found. Scaffold one now? [y/N]: `)).toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.error(`  ${yellow("!")} Skipped scaffolding. Create a playwright.config.ts before running wk-test.`);
+      return;
+    }
+    if (!scaffoldPlaywrightConfig(pm, projectDir)) {
+      console.error(`  ${red("\u2717")} Scaffolding failed. Run \`npm init playwright@latest\` manually.`);
+      return;
+    }
+    console.error(`  ${green("+")} Playwright config scaffolded.`);
+  }
+}
+
+// Project knowledge files (lessons/conventions/risks/workflow) are committed
+// to the repo. Only the lockfile is gitignored.
+function setupKnowledgeDir(projectDir: string): void {
+  console.error(`\nScaffolding ${KNOWLEDGE_DIR}/ (project knowledge files)...`);
+  try {
+    const { created } = ensureKnowledgeDir(projectDir);
+    if (created.length > 0) {
+      for (const f of created) {
+        console.error(`  ${green("+")} ${KNOWLEDGE_DIR}/${f}`);
+      }
+      console.error(`  ${yellow("!")} ${bold("These files are committed to your repo.")} Don't write secrets in them.`);
+      console.error(`  ${dim("work-kit redacts known secret shapes at write time, but the regex sweep is best-effort.")}`);
+    } else {
+      console.error(`  ${dim("Already scaffolded.")}`);
+    }
+    ensureGitignored(projectDir, `${KNOWLEDGE_DIR}/${KNOWLEDGE_LOCK}`);
+  } catch (err) {
+    console.error(`  ${red("\u2717")} ${(err as Error).message}`);
+  }
+}
+
 async function promptUser(question: string): Promise<string> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
   return new Promise((resolve) => {
@@ -142,6 +406,22 @@ 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}`);
+  }
+
+  // Ensure Playwright is available — wk-test's E2E step requires it.
+  await ensurePlaywright(projectDir);
+
+  // Scaffold the project-level knowledge directory.
+  setupKnowledgeDir(projectDir);
+
   // Run doctor against the target project
   console.error("\nRunning doctor...");
   const result = doctorCommand(projectDir);

package/cli/src/commands/status.ts

@@ -6,9 +6,10 @@ interface StatusOutput {
   branch: string;
   mode: string;
   classification?: string;
+  modelPolicy: 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 +27,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 };
   }
@@ -40,9 +41,10 @@ export function statusCommand(worktreeRoot?: string): StatusOutput {
     branch: state.branch,
     mode: state.mode,
     ...(state.classification && { classification: state.classification }),
+    modelPolicy: state.modelPolicy ?? "auto",
     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,11 +1,13 @@
 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, PhaseName } from "../state/schema.js";
 import { parseLocation } from "../state/helpers.js";
+import { resolveModel } from "../config/model-routing.js";
 import type { Action } from "../state/schema.js";
 
 interface WorkflowStatus {
   action: "workflow_status";
-  workflow: { step: string; status: string }[];
+  modelPolicy: string;
+  workflow: { step: string; status: string; model?: string }[];
 }
 
 export type WorkflowResult = Action | WorkflowStatus;
@@ -22,7 +24,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 +33,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 +47,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 +83,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) {
@@ -113,13 +115,21 @@ export function workflowCommand(opts: {
     return { action: "wait_for_user", message: `Removed ${opts.remove} from workflow.` };
   }
 
-  // No add/remove — show current workflow
+  // No add/remove — show current workflow with resolved model per step
   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",
-    }));
-
-  return { action: "workflow_status", workflow };
+    .map((s) => {
+      const model = resolveModel(state, s.phase as PhaseName, s.step);
+      return {
+        step: `${s.phase}/${s.step}`,
+        status: state.phases[s.phase]?.steps[s.step]?.status || "unknown",
+        ...(model && { model }),
+      };
+    });
+
+  return {
+    action: "workflow_status",
+    modelPolicy: state.modelPolicy ?? "auto",
+    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,54 @@
+// ── 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";
+
+// ── Knowledge ───────────────────────────────────────────────────────
+
+/**
+ * Project knowledge directory at the main repo root. Holds curated
+ * lessons/conventions/risks/workflow files. Committed to git; only
+ * KNOWLEDGE_LOCK is gitignored.
+ */
+export const KNOWLEDGE_DIR = ".work-kit-knowledge";
+export const KNOWLEDGE_LOCK = ".lock";
+
+// ── 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;