work-kit-cli 0.2.8 → 0.4.0

package/cli/src/config/{phases.ts → workflow.ts}

@@ -1,15 +1,17 @@
 import {
   PhaseName,
-  SUBSTAGES_BY_PHASE,
+  PHASE_NAMES,
+  STEPS_BY_PHASE,
   Classification,
   WorkflowStep,
 } from "../state/schema.js";
+import { SKILL_DIR_PREFIX } from "./constants.js";
 
-// ── Phase Order ──────────────────────────────────────────────────────
+// ── Phase Order ─────────────────────────────────────────────────────
 
-export const PHASE_ORDER: PhaseName[] = ["plan", "build", "test", "review", "deploy", "wrap-up"];
+export const PHASE_ORDER: PhaseName[] = [...PHASE_NAMES];
 
-// ── Prerequisites ────────────────────────────────────────────────────
+// ── Prerequisites ───────────────────────────────────────────────────
 
 export const PHASE_PREREQUISITES: Record<PhaseName, PhaseName | null> = {
   plan: null,
@@ -20,15 +22,15 @@ export const PHASE_PREREQUISITES: Record<PhaseName, PhaseName | null> = {
   "wrap-up": "review", // or deploy if deploy was included
 };
 
-// ── Skill File Paths ─────────────────────────────────────────────────
+// ── Skill File Paths ────────────────────────────────────────────────
 
-export function skillFilePath(phase: PhaseName, subStage?: string): string {
-  const dir = `wk-${phase}`;
-  if (!subStage) return `.claude/skills/${dir}/SKILL.md`;
-  return `.claude/skills/${dir}/stages/${subStage}.md`;
+export function skillFilePath(phase: PhaseName, step?: string): string {
+  const dir = `${SKILL_DIR_PREFIX}${phase}`;
+  if (!step) return `.claude/skills/${dir}/SKILL.md`;
+  return `.claude/skills/${dir}/steps/${step}.md`;
 }
 
-// ── Auto-kit Default Workflows ───────────────────────────────────────
+// ── Auto-kit Default Workflows ──────────────────────────────────────
 
 type InclusionRule = "YES" | "skip" | "if UI" | "if DB" | "optional";
 
@@ -42,7 +44,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES", "wrap-up/knowledge": "skip",
   },
   "small-change": {
     "plan/clarify": "YES", "plan/investigate": "skip", "plan/sketch": "skip", "plan/scope": "skip",
@@ -53,7 +55,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES", "wrap-up/knowledge": "skip",
   },
   refactor: {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "skip", "plan/scope": "skip",
@@ -64,7 +66,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "YES",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES", "wrap-up/knowledge": "YES",
   },
   feature: {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
@@ -75,7 +77,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "YES", "review/performance": "skip",
     "review/compliance": "YES", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES", "wrap-up/knowledge": "YES",
   },
   "large-feature": {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
@@ -86,20 +88,35 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "YES", "review/performance": "YES",
     "review/compliance": "YES", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES", "wrap-up/knowledge": "YES",
   },
 };
 
-export function buildDefaultWorkflow(classification: Classification): WorkflowStep[] {
+export function buildDefaultWorkflow(
+  classification: Classification,
+  overrides?: { include?: string[]; exclude?: string[] }
+): WorkflowStep[] {
   const matrix = WORKFLOW_MATRIX[classification];
   const steps: WorkflowStep[] = [];
 
+  const forceInclude = new Set(overrides?.include ?? []);
+  const forceExclude = new Set(overrides?.exclude ?? []);
+
   for (const [key, rule] of Object.entries(matrix)) {
-    const [phase, subStage] = key.split("/") as [PhaseName, string];
-    // "YES" always included, "skip" excluded, conditional ones included by default (user can remove)
-    const included = rule === "YES" || rule === "if UI" || rule === "if DB";
-    if (rule !== "skip") {
-      steps.push({ phase, subStage, included });
+    const [phase, step] = key.split("/") as [PhaseName, string];
+    let included = rule === "YES" || rule === "if UI" || rule === "if DB";
+    if (forceInclude.has(key)) included = true;
+    if (forceExclude.has(key)) included = false;
+    // "skip" excluded by default, but project config may force-include
+    if (rule === "skip" && !forceInclude.has(key)) continue;
+    steps.push({ phase, step, included });
+  }
+
+  // Add any force-included steps not in the matrix
+  for (const ref of forceInclude) {
+    const [phase, step] = ref.split("/") as [PhaseName, string];
+    if (!steps.some(s => s.phase === phase && s.step === step)) {
+      steps.push({ phase, step, included: true });
     }
   }
 
@@ -109,8 +126,8 @@ export function buildDefaultWorkflow(classification: Classification): WorkflowSt
 export function buildFullWorkflow(): WorkflowStep[] {
   const steps: WorkflowStep[] = [];
   for (const phase of PHASE_ORDER) {
-    for (const subStage of SUBSTAGES_BY_PHASE[phase]) {
-      steps.push({ phase, subStage, included: true });
+    for (const step of STEPS_BY_PHASE[phase]) {
+      steps.push({ phase, step, included: true });
     }
   }
   return steps;

package/cli/src/context/prompt-builder.ts

@@ -2,27 +2,28 @@ import { WorkKitState, PhaseName } from "../state/schema.js";
 import { getContextFor } from "../config/agent-map.js";
 import { extractSection, extractTopSection } from "./extractor.js";
 import { readStateMd } from "../state/store.js";
-import { skillFilePath } from "../config/phases.js";
+import { skillFilePath } from "../config/workflow.js";
 import { redactIgnoredBlocks } from "./redactor.js";
+import { CLI_BINARY } from "../config/constants.js";
 
 /**
- * Build a complete agent prompt for a given phase/sub-stage.
+ * Build a complete agent prompt for a given phase/step.
  * Accepts optional pre-read stateMd to avoid repeated file reads in parallel scenarios.
  */
 export function buildAgentPrompt(
   worktreeRoot: string,
   state: WorkKitState,
   phase: PhaseName,
-  subStage: string,
+  step: string,
   stateMd?: string | null
 ): string {
-  const ctx = getContextFor(phase, subStage);
+  const ctx = getContextFor(phase, step);
   const md = stateMd ?? readStateMd(worktreeRoot);
-  const skill = skillFilePath(phase, subStage);
+  const skill = skillFilePath(phase, step);
 
   const parts: string[] = [];
 
-  parts.push(`# Agent: ${phase}/${subStage}`);
+  parts.push(`# Agent: ${phase}/${step}`);
   parts.push(`**Worktree:** ${worktreeRoot}`);
   parts.push(`**Slug:** ${state.slug}`);
   parts.push(`**Branch:** ${state.branch}`);
@@ -59,12 +60,12 @@ export function buildAgentPrompt(
   }
 
   parts.push(`## Output`);
-  parts.push(`Write your outputs to \`.work-kit/state.md\` under a section for this sub-stage.`);
+  parts.push(`Write your outputs to \`.work-kit/state.md\` under a section for this step.`);
 
-  if (subStage === "wrap-up") {
+  if (step === "wrap-up") {
     parts.push(`Follow the wrap-up skill file instructions for archiving and cleanup.`);
   } else {
-    parts.push(`When done, report your outcome so the orchestrator can run: \`npx work-kit-cli complete ${phase}/${subStage} --outcome <outcome>\``);
+    parts.push(`When done, report your outcome so the orchestrator can run: \`${CLI_BINARY} complete ${phase}/${step} --outcome <outcome>\``);
   }
 
   return redactIgnoredBlocks(parts.join("\n"));

package/cli/src/index.ts

@@ -17,8 +17,14 @@ import { observeCommand } from "./commands/observe.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { bootstrapCommand } from "./commands/bootstrap.js";
 import { cancelCommand } from "./commands/cancel.js";
+import { pauseCommand } from "./commands/pause.js";
+import { resumeCommand } from "./commands/resume.js";
+import { reportCommand } from "./commands/report.js";
+import { learnCommand } from "./commands/learn.js";
+import { extractCommand } from "./commands/extract.js";
 import { bold, green, yellow, red } from "./utils/colors.js";
-import type { Classification, PhaseName } from "./state/schema.js";
+import type { Classification, ModelPolicy, PhaseName } from "./state/schema.js";
+import { isModelPolicy } from "./state/schema.js";
 
 import { createRequire } from "node:module";
 
@@ -37,18 +43,27 @@ program
 program
   .command("init")
   .description("Create worktree and initialize state")
-  .requiredOption("--mode <mode>", "Workflow mode: full or auto")
+  .option("--mode <mode>", "Workflow mode: full or auto (default: from project config or 'full')")
   .requiredOption("--description <text>", "Description of the work")
   .option("--classification <type>", "Work classification (auto mode): bug-fix, small-change, refactor, feature, large-feature")
   .option("--gated", "Wait for user approval between phases (default: auto-proceed)")
+  .option("--model-policy <policy>", "Session model policy: auto, opus, sonnet, haiku, inherit (default: auto)")
   .option("--worktree-root <path>", "Override worktree root directory")
   .action((opts) => {
     try {
+      if (opts.modelPolicy !== undefined && !isModelPolicy(opts.modelPolicy)) {
+        console.error(JSON.stringify({
+          action: "error",
+          message: `Invalid --model-policy "${opts.modelPolicy}". Use one of: auto, opus, sonnet, haiku, inherit.`,
+        }));
+        process.exit(1);
+      }
       const result = initCommand({
-        mode: opts.mode as "full" | "auto",
+        mode: opts.mode as "full" | "auto" | undefined,
         description: opts.description,
         classification: opts.classification as Classification | undefined,
-        gated: opts.gated || false,
+        gated: opts.gated,
+        modelPolicy: opts.modelPolicy as ModelPolicy | undefined,
         worktreeRoot: opts.worktreeRoot,
       });
       console.log(JSON.stringify(result, null, 2));
@@ -78,7 +93,7 @@ program
 
 program
   .command("complete <target>")
-  .description("Mark a phase/sub-stage as complete (e.g., plan/clarify)")
+  .description("Mark a phase/step as complete (e.g., plan/clarify)")
   .option("--outcome <value>", "Outcome of the step (e.g., done, revise, broken, changes_requested)")
   .option("--worktree-root <path>", "Override worktree root")
   .action((target, opts) => {
@@ -144,8 +159,8 @@ program
 program
   .command("loopback")
   .description("Register a loop-back transition")
-  .requiredOption("--from <source>", "Source phase/sub-stage (e.g., review/handoff)")
-  .requiredOption("--to <target>", "Target phase/sub-stage (e.g., build/core)")
+  .requiredOption("--from <source>", "Source phase/step (e.g., review/handoff)")
+  .requiredOption("--to <target>", "Target phase/step (e.g., build/core)")
   .requiredOption("--reason <text>", "Reason for loop-back")
   .option("--worktree-root <path>", "Override worktree root")
   .action((opts) => {
@@ -241,8 +256,9 @@ program
   .command("observe")
   .description("Real-time dashboard of all active work items")
   .option("--repo <path>", "Main repository root")
+  .option("--all", "Observe every work-kit project found under ~/.claude/projects/")
   .action(async (opts) => {
-    await observeCommand({ mainRepo: opts.repo });
+    await observeCommand({ mainRepo: opts.repo, all: opts.all });
   });
 
 // ── uninstall ────────────────────────────────────────────────────────
@@ -260,9 +276,10 @@ program
   .command("bootstrap")
   .description("Detect work-kit state and output session orientation")
   .option("--json", "Output as JSON", true)
+  .option("--auto-resume", "If paused or stale, auto-flip to in-progress")
   .action((opts) => {
     try {
-      const result = bootstrapCommand();
+      const result = bootstrapCommand(undefined, { autoResume: opts.autoResume });
       console.log(JSON.stringify(result, null, 2));
     } catch (e: any) {
       console.error(JSON.stringify({ action: "error", message: e.message }));
@@ -270,6 +287,59 @@ program
     }
   });
 
+// ── pause ───────────────────────────────────────────────────────────
+
+program
+  .command("pause")
+  .description("Pause the active work-kit session")
+  .option("--reason <text>", "Optional reason for pausing")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = pauseCommand(opts.reason, opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.action === "error" ? 1 : 0);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── resume ──────────────────────────────────────────────────────────
+
+program
+  .command("resume")
+  .description("Resume a paused work-kit session (lists paused sessions when no slug is given)")
+  .option("--worktree-root <path>", "Override worktree root (resume session at exact path)")
+  .option("--slug <slug>", "Resume the paused session with this slug")
+  .action((opts) => {
+    try {
+      const result = resumeCommand({ worktreeRoot: opts.worktreeRoot, slug: opts.slug });
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.action === "error" ? 1 : 0);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── report ──────────────────────────────────────────────────────────
+
+program
+  .command("report")
+  .description("Show stats across completed work-kits")
+  .option("--json", "Output as JSON")
+  .option("--repo <path>", "Main repository root")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      reportCommand({ json: opts.json, repo: opts.repo, worktreeRoot: opts.worktreeRoot });
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
 // ── cancel ──────────────────────────────────────────────────────────
 
 program
@@ -287,4 +357,55 @@ program
     }
   });
 
+// ── learn ───────────────────────────────────────────────────────────
+
+program
+  .command("learn")
+  .description("Append a knowledge entry (lesson/convention/risk/workflow) to .work-kit-knowledge/")
+  .requiredOption("--type <type>", "Entry type: lesson, convention, risk, workflow")
+  .requiredOption("--text <text>", "Free-form text. Secrets are auto-redacted at write time.")
+  .option("--scope <glob>", "Optional path glob (stored, not yet used for filtering)")
+  .option("--phase <phase>", "Override session phase auto-fill")
+  .option("--step <step>", "Override session step auto-fill")
+  .option("--source <source>", "Override entry source label", "explicit-cli")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = learnCommand({
+        type: opts.type,
+        text: opts.text,
+        scope: opts.scope,
+        phase: opts.phase,
+        step: opts.step,
+        source: opts.source,
+        worktreeRoot: opts.worktreeRoot,
+      });
+      console.log(JSON.stringify(result, null, 2));
+      if (result.action === "error") process.exit(1);
+      if (result.redacted) {
+        console.error(yellow(`! Redacted ${result.redactedKinds?.length ?? 0} secret(s) before writing.`));
+      }
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── extract ─────────────────────────────────────────────────────────
+
+program
+  .command("extract")
+  .description("Parse current session's state.md + tracker.json and append entries to knowledge files")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = extractCommand({ worktreeRoot: opts.worktreeRoot });
+      console.log(JSON.stringify(result, null, 2));
+      if (result.action === "error") process.exit(1);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
 program.parse();