@abdullahsahmad/work-kit 0.1.0

package/cli/src/observer/renderer.ts

@@ -0,0 +1,316 @@
+import { bold, dim, green, yellow, red, cyan, bgYellow } from "../utils/colors.js";
+import type { DashboardData, WorkItemView, CompletedItemView } from "./data.js";
+
+// ── Time Formatting ─────────────────────────────────────────────────
+
+function formatTimeAgo(dateStr: string): string {
+  const now = Date.now();
+  const then = new Date(dateStr).getTime();
+  if (isNaN(then)) return "unknown";
+
+  const diffMs = now - then;
+  const minutes = Math.floor(diffMs / 60000);
+  const hours = Math.floor(diffMs / 3600000);
+  const days = Math.floor(diffMs / 86400000);
+  const weeks = Math.floor(days / 7);
+
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  if (hours < 24) {
+    const remainMin = minutes % 60;
+    return remainMin > 0 ? `${hours}h ${remainMin}m ago` : `${hours}h ago`;
+  }
+  if (days < 7) return `${days}d ago`;
+  return `${weeks}w ago`;
+}
+
+// ── Box Drawing ─────────────────────────────────────────────────────
+
+function horizontalLine(width: number): string {
+  return "═".repeat(Math.max(0, width - 2));
+}
+
+function padRight(text: string, width: number): string {
+  // Strip ANSI codes for length calculation
+  const plainLen = stripAnsi(text).length;
+  const padding = Math.max(0, width - plainLen);
+  return text + " ".repeat(padding);
+}
+
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function centerText(text: string, width: number): string {
+  const plainLen = stripAnsi(text).length;
+  const totalPad = Math.max(0, width - plainLen);
+  const leftPad = Math.floor(totalPad / 2);
+  const rightPad = totalPad - leftPad;
+  return " ".repeat(leftPad) + text + " ".repeat(rightPad);
+}
+
+function boxLine(content: string, innerWidth: number): string {
+  return `║ ${padRight(content, innerWidth)} ║`;
+}
+
+function emptyBoxLine(innerWidth: number): string {
+  return `║ ${" ".repeat(innerWidth)} ║`;
+}
+
+// ── Progress Bar ────────────────────────────────────────────────────
+
+function renderProgressBar(
+  completed: number,
+  total: number,
+  percent: number,
+  label: string,
+  maxBarWidth: number
+): string {
+  const barWidth = Math.max(20, Math.min(40, maxBarWidth));
+  const filled = total > 0 ? Math.round((completed / total) * barWidth) : 0;
+  const empty = barWidth - filled;
+
+  const filledStr = green("█".repeat(filled));
+  const emptyStr = dim("░".repeat(empty));
+  const stats = `${label}  ${completed}/${total}  ${percent}%`;
+
+  return `${filledStr}${emptyStr}   ${stats}`;
+}
+
+// ── Phase Status Indicators ─────────────────────────────────────────
+
+function phaseIndicator(status: string): string {
+  switch (status) {
+    case "completed": return green("✓");
+    case "in-progress": return cyan("▶");
+    case "pending": return dim("·");
+    case "skipped": return dim("⊘");
+    case "failed": return red("✗");
+    default: return dim("·");
+  }
+}
+
+function statusDot(status: string): string {
+  switch (status) {
+    case "in-progress": return green("●");
+    case "paused": return yellow("○");
+    case "completed": return green("✓");
+    case "failed": return red("✗");
+    default: return dim("·");
+  }
+}
+
+// ── Render Work Item ────────────────────────────────────────────────
+
+function renderWorkItem(item: WorkItemView, innerWidth: number): string[] {
+  const lines: string[] = [];
+
+  const slugText = `${statusDot(item.status)} ${bold(item.slug)}`;
+  const branchText = dim(item.branch);
+  const slugPlainLen = stripAnsi(slugText).length;
+  const branchPlainLen = stripAnsi(branchText).length;
+  const gap1 = Math.max(2, innerWidth - slugPlainLen - branchPlainLen);
+  lines.push(slugText + " ".repeat(gap1) + branchText);
+
+  const modeText = item.mode + (item.classification ? ` (${item.classification})` : "");
+  const pausedBadge = item.status === "paused" ? "  " + bgYellow(" PAUSED ") : "";
+  const startedText = dim(`Started: ${formatTimeAgo(item.startedAt)}`);
+  const modeStr = `  ${modeText}${pausedBadge}`;
+  const modePlainLen = stripAnsi(modeStr).length;
+  const startedPlainLen = stripAnsi(startedText).length;
+  const gap2 = Math.max(2, innerWidth - modePlainLen - startedPlainLen);
+  lines.push(modeStr + " ".repeat(gap2) + startedText);
+
+  const phaseLabel = item.currentPhase
+    ? (item.currentSubStage ? `${item.currentPhase}/${item.currentSubStage}` : item.currentPhase)
+    : "—";
+  const barMaxWidth = Math.max(20, Math.min(40, innerWidth - 30));
+  lines.push("  " + renderProgressBar(
+    item.progress.completed,
+    item.progress.total,
+    item.progress.percent,
+    phaseLabel,
+    barMaxWidth
+  ));
+
+  const phaseStrs = item.phases.map(p => `${p.name} ${phaseIndicator(p.status)}`);
+  lines.push("  " + phaseStrs.join("  "));
+
+  if (item.loopbacks.count > 0) {
+    const lb = item.loopbacks;
+    let loopStr = `  ${cyan("⟳")} ${lb.count} loopback${lb.count > 1 ? "s" : ""}`;
+    if (lb.lastFrom && lb.lastTo) {
+      loopStr += `: ${lb.lastFrom} → ${lb.lastTo}`;
+    }
+    if (lb.lastReason) {
+      loopStr += ` (${lb.lastReason})`;
+    }
+    lines.push(loopStr);
+  }
+
+  return lines;
+}
+
+// ── Render Completed Item ───────────────────────────────────────────
+
+function renderCompletedItem(item: CompletedItemView, innerWidth: number): string {
+  const check = green("✓");
+  const slug = item.slug;
+  const pr = item.pr ? `  ${dim(item.pr)}` : "";
+  const date = item.completedAt ? `  ${dim(item.completedAt)}` : "";
+  const phases = item.phases ? `  ${dim(item.phases)}` : "";
+  const content = `${check} ${slug}${pr}${date}${phases}`;
+  return content;
+}
+
+// ── Main Render Function ────────────────────────────────────────────
+
+export function renderDashboard(
+  data: DashboardData,
+  width: number,
+  height: number,
+  scrollOffset: number = 0
+): string {
+  const maxWidth = Math.min(width, 120);
+  const innerWidth = maxWidth - 4; // account for "║ " and " ║"
+
+  const allLines: string[] = [];
+
+  // Top border
+  allLines.push(`╔${horizontalLine(maxWidth)}╗`);
+
+  let activeCount = 0, pausedCount = 0, failedCount = 0;
+  for (const item of data.activeItems) {
+    if (item.status === "in-progress") activeCount++;
+    else if (item.status === "paused") pausedCount++;
+    else if (item.status === "failed") failedCount++;
+  }
+
+  let headerRight = "";
+  if (activeCount > 0) headerRight += `${green("●")} ${activeCount} active`;
+  if (pausedCount > 0) headerRight += `  ${yellow("○")} ${pausedCount} paused`;
+  if (failedCount > 0) headerRight += `  ${red("✗")} ${failedCount} failed`;
+
+  const headerLeft = bold("  WORK-KIT OBSERVER");
+  const headerLeftLen = stripAnsi(headerLeft).length;
+  const headerRightLen = stripAnsi(headerRight).length;
+  const headerGap = Math.max(2, innerWidth - headerLeftLen - headerRightLen);
+  allLines.push(boxLine(headerLeft + " ".repeat(headerGap) + headerRight, innerWidth));
+
+  // Separator
+  allLines.push(`╠${horizontalLine(maxWidth)}╣`);
+
+  if (data.activeItems.length === 0 && data.completedItems.length === 0) {
+    // Empty state
+    allLines.push(emptyBoxLine(innerWidth));
+    allLines.push(boxLine(dim("  No active work items found."), innerWidth));
+    allLines.push(boxLine(dim("  Start a new work item with: work-kit init"), innerWidth));
+    allLines.push(emptyBoxLine(innerWidth));
+  } else {
+    // Active items
+    if (data.activeItems.length > 0) {
+      allLines.push(emptyBoxLine(innerWidth));
+
+      for (let i = 0; i < data.activeItems.length; i++) {
+        const item = data.activeItems[i];
+        const itemLines = renderWorkItem(item, innerWidth);
+        for (const line of itemLines) {
+          allLines.push(boxLine(line, innerWidth));
+        }
+        if (i < data.activeItems.length - 1) {
+          allLines.push(emptyBoxLine(innerWidth));
+        }
+      }
+
+      allLines.push(emptyBoxLine(innerWidth));
+    }
+
+    // Completed section
+    if (data.completedItems.length > 0) {
+      allLines.push(`╠${horizontalLine(maxWidth)}╣`);
+      allLines.push(boxLine(bold("  COMPLETED"), innerWidth));
+
+      const maxCompleted = 5;
+      const displayed = data.completedItems.slice(0, maxCompleted);
+      for (const item of displayed) {
+        const content = renderCompletedItem(item, innerWidth);
+        allLines.push(boxLine("  " + content, innerWidth));
+      }
+      if (data.completedItems.length > maxCompleted) {
+        allLines.push(boxLine(
+          dim(`  ... and ${data.completedItems.length - maxCompleted} more`),
+          innerWidth
+        ));
+      }
+    }
+  }
+
+  // Footer separator
+  allLines.push(`╠${horizontalLine(maxWidth)}╣`);
+
+  // Footer
+  const footerLeft = `  ${dim("q")} quit  ${dim("↑↓")} scroll  ${dim("r")} refresh`;
+  const timeStr = data.lastUpdated.toLocaleTimeString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+  const footerRight = dim(`Updated: ${timeStr}`);
+  const footerLeftLen = stripAnsi(footerLeft).length;
+  const footerRightLen = stripAnsi(footerRight).length;
+  const footerGap = Math.max(2, innerWidth - footerLeftLen - footerRightLen);
+  allLines.push(boxLine(footerLeft + " ".repeat(footerGap) + footerRight, innerWidth));
+
+  // Bottom border
+  allLines.push(`╚${horizontalLine(maxWidth)}╝`);
+
+  // Apply scrolling: figure out how many content lines we have vs available height
+  const totalLines = allLines.length;
+  const availableHeight = height;
+
+  if (totalLines <= availableHeight) {
+    // Everything fits, no scrolling needed
+    return allLines.join("\n") + "\n";
+  }
+
+  // Apply scroll offset
+  const maxScroll = Math.max(0, totalLines - availableHeight);
+  const clampedOffset = Math.min(scrollOffset, maxScroll);
+  const visibleLines = allLines.slice(clampedOffset, clampedOffset + availableHeight);
+
+  // Add scroll indicator if not showing everything
+  if (clampedOffset > 0 || clampedOffset + availableHeight < totalLines) {
+    const scrollPct = Math.round((clampedOffset / maxScroll) * 100);
+    const indicator = dim(` [${scrollPct}% scrolled]`);
+    if (visibleLines.length > 0) {
+      visibleLines[visibleLines.length - 1] = visibleLines[visibleLines.length - 1] + indicator;
+    }
+  }
+
+  return visibleLines.join("\n") + "\n";
+}
+
+// ── Terminal Control ────────────────────────────────────────────────
+
+export function enterAlternateScreen(): void {
+  process.stdout.write("\x1b[?1049h"); // enter alternate screen
+  process.stdout.write("\x1b[?25l");   // hide cursor
+}
+
+export function exitAlternateScreen(): void {
+  process.stdout.write("\x1b[?25h");   // show cursor
+  process.stdout.write("\x1b[?1049l"); // exit alternate screen
+}
+
+export function clearAndHome(): string {
+  return "\x1b[H\x1b[2J"; // move to top-left + clear screen
+}
+
+export function moveCursorHome(): string {
+  return "\x1b[H";
+}
+
+export function renderTooSmall(width: number, height: number): string {
+  const msg = `Terminal too small (${width}x${height}). Need at least 60x10.`;
+  return clearAndHome() + msg + "\n";
+}

package/cli/src/observer/watcher.ts

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverWorktrees } from "./data.js";
+
+export interface WatcherHandle {
+  stop: () => void;
+  getWorktrees: () => string[];
+}
+
+export function startWatching(
+  mainRepoRoot: string,
+  onUpdate: () => void
+): WatcherHandle {
+  const watchers = new Map<string, fs.FSWatcher>();
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let pollTimer: ReturnType<typeof setInterval> | null = null;
+  let stopped = false;
+  let cachedWorktrees: string[] = [];
+
+  function debouncedUpdate(): void {
+    if (stopped) return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      if (!stopped) onUpdate();
+    }, 50);
+  }
+
+  function watchStateFile(worktreeRoot: string): void {
+    if (watchers.has(worktreeRoot)) return;
+    const stateFile = path.join(worktreeRoot, ".work-kit", "state.json");
+    if (!fs.existsSync(stateFile)) return;
+
+    try {
+      const watcher = fs.watch(stateFile, { persistent: false }, () => {
+        debouncedUpdate();
+      });
+      watcher.on("error", () => {
+        watcher.close();
+        watchers.delete(worktreeRoot);
+      });
+      watchers.set(worktreeRoot, watcher);
+    } catch {
+      // File might not exist yet
+    }
+  }
+
+  function unwatchRemoved(currentSet: Set<string>): void {
+    for (const [wt, watcher] of watchers) {
+      if (!currentSet.has(wt)) {
+        watcher.close();
+        watchers.delete(wt);
+      }
+    }
+  }
+
+  function refreshWorktrees(): void {
+    if (stopped) return;
+    const current = discoverWorktrees(mainRepoRoot);
+    const currentSet = new Set(current);
+
+    // Only trigger update if worktree list actually changed
+    const changed = current.length !== cachedWorktrees.length
+      || current.some((wt, i) => wt !== cachedWorktrees[i]);
+
+    for (const wt of current) {
+      watchStateFile(wt);
+    }
+    unwatchRemoved(currentSet);
+
+    cachedWorktrees = current;
+
+    if (changed) {
+      debouncedUpdate();
+    }
+  }
+
+  // Initial setup
+  refreshWorktrees();
+
+  // Poll for new/removed worktrees every 5 seconds
+  pollTimer = setInterval(() => {
+    if (!stopped) refreshWorktrees();
+  }, 5000);
+
+  return {
+    stop() {
+      stopped = true;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      if (pollTimer) clearInterval(pollTimer);
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+      watchers.clear();
+    },
+    getWorktrees() {
+      return cachedWorktrees;
+    },
+  };
+}

package/cli/src/state/helpers.test.ts

@@ -0,0 +1,91 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { parseLocation, resetToLocation } from "./helpers.js";
+import type { WorkKitState, PhaseName, PhaseState, SubStageState } from "./schema.js";
+import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "./schema.js";
+
+function makeState(): WorkKitState {
+  const phases = {} as Record<PhaseName, PhaseState>;
+  for (const phase of PHASE_NAMES) {
+    const subStages: Record<string, SubStageState> = {};
+    for (const ss of SUBSTAGES_BY_PHASE[phase]) {
+      subStages[ss] = { status: "pending" };
+    }
+    phases[phase] = { status: "pending", subStages };
+  }
+  return {
+    version: 1,
+    slug: "test",
+    branch: "feature/test",
+    started: "2026-01-01",
+    mode: "full-kit",
+    status: "in-progress",
+    currentPhase: "plan",
+    currentSubStage: "clarify",
+    phases,
+    loopbacks: [],
+    metadata: { worktreeRoot: "/tmp/test", mainRepoRoot: "/tmp/test" },
+  };
+}
+
+describe("parseLocation", () => {
+  it("parses plan/clarify correctly", () => {
+    const loc = parseLocation("plan/clarify");
+    assert.deepStrictEqual(loc, { phase: "plan", subStage: "clarify" });
+  });
+
+  it("throws on invalid format (no slash)", () => {
+    assert.throws(() => parseLocation("invalid"), /Invalid location/);
+  });
+
+  it("throws on unknown phase", () => {
+    assert.throws(() => parseLocation("foobar/baz"), /Unknown phase/);
+  });
+
+  it("throws on unknown sub-stage", () => {
+    assert.throws(() => parseLocation("plan/nonexistent"), /Unknown sub-stage/);
+  });
+});
+
+describe("resetToLocation", () => {
+  it("resets target and later phases to pending", () => {
+    const state = makeState();
+
+    // Mark plan and build as completed
+    for (const ss of Object.values(state.phases.plan.subStages)) {
+      ss.status = "completed";
+      ss.completedAt = "2026-01-01";
+    }
+    state.phases.plan.status = "completed";
+    state.phases.plan.completedAt = "2026-01-01";
+
+    for (const ss of Object.values(state.phases.build.subStages)) {
+      ss.status = "completed";
+      ss.completedAt = "2026-01-02";
+    }
+    state.phases.build.status = "completed";
+    state.phases.build.completedAt = "2026-01-02";
+
+    // Reset to plan/blueprint
+    resetToLocation(state, { phase: "plan", subStage: "blueprint" });
+
+    // Sub-stages before blueprint should stay completed
+    assert.equal(state.phases.plan.subStages.clarify.status, "completed");
+    assert.equal(state.phases.plan.subStages.investigate.status, "completed");
+    assert.equal(state.phases.plan.subStages.sketch.status, "completed");
+    assert.equal(state.phases.plan.subStages.scope.status, "completed");
+    assert.equal(state.phases.plan.subStages["ux-flow"].status, "completed");
+    assert.equal(state.phases.plan.subStages.architecture.status, "completed");
+
+    // Blueprint and audit should be reset
+    assert.equal(state.phases.plan.subStages.blueprint.status, "pending");
+    assert.equal(state.phases.plan.subStages.audit.status, "pending");
+
+    // Plan phase should be in-progress
+    assert.equal(state.phases.plan.status, "in-progress");
+
+    // Build (later phase) should be reset
+    assert.equal(state.phases.build.status, "pending");
+    assert.equal(state.phases.build.subStages.core.status, "pending");
+  });
+});

package/cli/src/state/helpers.ts

@@ -0,0 +1,65 @@
+import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "./schema.js";
+import type { Location, PhaseName, WorkKitState } from "./schema.js";
+import { PHASE_ORDER } from "../config/phases.js";
+
+/**
+ * Parse "phase/sub-stage" string into a Location object.
+ * Validates that the phase is a known phase name and the sub-stage exists.
+ */
+export function parseLocation(input: string): Location {
+  const parts = input.split("/");
+  if (parts.length !== 2) {
+    throw new Error(`Invalid location "${input}". Expected format: phase/sub-stage (e.g., plan/clarify)`);
+  }
+  const [phase, subStage] = parts;
+  if (!PHASE_NAMES.includes(phase as PhaseName)) {
+    throw new Error(`Unknown phase "${phase}". Valid phases: ${PHASE_NAMES.join(", ")}`);
+  }
+  const validSubStages = SUBSTAGES_BY_PHASE[phase as PhaseName];
+  if (!validSubStages.includes(subStage)) {
+    throw new Error(`Unknown sub-stage "${subStage}" in phase "${phase}". Valid: ${validSubStages.join(", ")}`);
+  }
+  return { phase: phase as PhaseName, subStage };
+}
+
+/**
+ * Reset state from a target location forward: marks the target sub-stage
+ * and all subsequent sub-stages/phases as pending.
+ */
+export function resetToLocation(state: WorkKitState, location: Location): void {
+  const targetPhaseState = state.phases[location.phase];
+  if (!targetPhaseState) {
+    throw new Error(`Phase "${location.phase}" not found in state`);
+  }
+  if (!targetPhaseState.subStages[location.subStage]) {
+    throw new Error(`Sub-stage "${location.subStage}" not found in phase "${location.phase}"`);
+  }
+
+  let reset = false;
+  for (const [ss, ssState] of Object.entries(targetPhaseState.subStages)) {
+    if (ss === location.subStage) reset = true;
+    if (reset && ssState.status === "completed") {
+      ssState.status = "pending";
+      delete ssState.completedAt;
+      delete ssState.outcome;
+    }
+  }
+  targetPhaseState.status = "in-progress";
+
+  const targetPhaseIdx = PHASE_ORDER.indexOf(location.phase);
+  for (let i = targetPhaseIdx + 1; i < PHASE_ORDER.length; i++) {
+    const laterPhase = PHASE_ORDER[i];
+    const laterPhaseState = state.phases[laterPhase];
+    if (laterPhaseState.status === "completed") {
+      laterPhaseState.status = "pending";
+      delete laterPhaseState.completedAt;
+      for (const ssState of Object.values(laterPhaseState.subStages)) {
+        if (ssState.status === "completed") {
+          ssState.status = "pending";
+          delete ssState.completedAt;
+          delete ssState.outcome;
+        }
+      }
+    }
+  }
+}

package/cli/src/state/schema.ts

@@ -0,0 +1,113 @@
+// ── Phase & Sub-stage Types ──────────────────────────────────────────
+
+export const PHASE_NAMES = ["plan", "build", "test", "review", "deploy", "wrap-up"] as const;
+export type PhaseName = (typeof PHASE_NAMES)[number];
+
+export const PLAN_SUBSTAGES = ["clarify", "investigate", "sketch", "scope", "ux-flow", "architecture", "blueprint", "audit"] as const;
+export const BUILD_SUBSTAGES = ["setup", "migration", "red", "core", "ui", "refactor", "integration", "commit"] as const;
+export const TEST_SUBSTAGES = ["verify", "e2e", "validate"] as const;
+export const REVIEW_SUBSTAGES = ["self-review", "security", "performance", "compliance", "handoff"] as const;
+export const DEPLOY_SUBSTAGES = ["merge", "monitor", "remediate"] as const;
+export const WRAPUP_SUBSTAGES = ["wrap-up"] as const;
+
+export type PlanSubStage = (typeof PLAN_SUBSTAGES)[number];
+export type BuildSubStage = (typeof BUILD_SUBSTAGES)[number];
+export type TestSubStage = (typeof TEST_SUBSTAGES)[number];
+export type ReviewSubStage = (typeof REVIEW_SUBSTAGES)[number];
+export type DeploySubStage = (typeof DEPLOY_SUBSTAGES)[number];
+export type WrapUpSubStage = (typeof WRAPUP_SUBSTAGES)[number];
+
+export type SubStageName = PlanSubStage | BuildSubStage | TestSubStage | ReviewSubStage | DeploySubStage | WrapUpSubStage;
+
+export const SUBSTAGES_BY_PHASE: Record<PhaseName, readonly string[]> = {
+  plan: PLAN_SUBSTAGES,
+  build: BUILD_SUBSTAGES,
+  test: TEST_SUBSTAGES,
+  review: REVIEW_SUBSTAGES,
+  deploy: DEPLOY_SUBSTAGES,
+  "wrap-up": WRAPUP_SUBSTAGES,
+};
+
+// ── Classification ───────────────────────────────────────────────────
+
+export type Classification = "bug-fix" | "small-change" | "refactor" | "feature" | "large-feature";
+
+// ── Phase & Sub-stage State ──────────────────────────────────────────
+
+export type PhaseStatus = "pending" | "in-progress" | "completed" | "skipped";
+export type SubStageStatus = "pending" | "in-progress" | "completed" | "skipped";
+
+export interface SubStageState {
+  status: SubStageStatus;
+  outcome?: string;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+export interface PhaseState {
+  status: PhaseStatus;
+  subStages: Record<string, SubStageState>;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+// ── Loopback ─────────────────────────────────────────────────────────
+
+export interface Location {
+  phase: PhaseName;
+  subStage: string;
+}
+
+export interface LoopbackRecord {
+  from: Location;
+  to: Location;
+  reason: string;
+  timestamp: string;
+}
+
+// ── Workflow (auto-kit) ──────────────────────────────────────────────
+
+export interface WorkflowStep {
+  phase: PhaseName;
+  subStage: string;
+  included: boolean;
+}
+
+// ── Main State ───────────────────────────────────────────────────────
+
+export interface WorkKitState {
+  version: 1;
+  slug: string;
+  branch: string;
+  started: string;
+  mode: "full-kit" | "auto-kit";
+  classification?: Classification;
+  status: "in-progress" | "paused" | "completed" | "failed";
+  currentPhase: PhaseName | null;
+  currentSubStage: string | null;
+  phases: Record<PhaseName, PhaseState>;
+  workflow?: WorkflowStep[];
+  loopbacks: LoopbackRecord[];
+  metadata: {
+    worktreeRoot: string;
+    mainRepoRoot: string;
+  };
+}
+
+// ── Actions (CLI → Claude) ───────────────────────────────────────────
+
+export interface AgentSpec {
+  phase: PhaseName;
+  subStage: string;
+  skillFile: string;
+  agentPrompt: string;
+  outputFile?: string; // for parallel agents writing to separate files
+}
+
+export type Action =
+  | { action: "spawn_agent"; phase: PhaseName; subStage: string; skillFile: string; agentPrompt: string; onComplete: string }
+  | { action: "spawn_parallel_agents"; agents: AgentSpec[]; thenSequential?: AgentSpec; onComplete: string }
+  | { action: "wait_for_user"; message: string }
+  | { action: "loopback"; from: Location; to: Location; reason: string }
+  | { action: "complete"; message: string }
+  | { action: "error"; message: string; suggestion?: string };