@abdullahsahmad/work-kit 0.1.0

package/cli/src/commands/init.ts

@@ -0,0 +1,184 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, SUBSTAGES_BY_PHASE, WorkflowStep, Classification } from "../state/schema.js";
+import { writeState, writeStateMd, stateExists } from "../state/store.js";
+import { buildFullWorkflow, buildDefaultWorkflow, skillFilePath } from "../config/phases.js";
+import type { Action } from "../state/schema.js";
+
+function toSlug(description: string): string {
+  return description
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .slice(0, 40)
+    .replace(/-+$/, "");
+}
+
+function buildPhases(workflow?: WorkflowStep[]): Record<PhaseName, PhaseState> {
+  const phases = {} as Record<PhaseName, PhaseState>;
+
+  for (const phase of PHASE_NAMES) {
+    const subStages: Record<string, { status: "pending" | "skipped" }> = {};
+    const allSubStages = SUBSTAGES_BY_PHASE[phase];
+
+    for (const ss of allSubStages) {
+      if (workflow) {
+        const step = workflow.find((s) => s.phase === phase && s.subStage === ss);
+        subStages[ss] = { status: step?.included ? "pending" : "skipped" };
+      } else {
+        subStages[ss] = { status: "pending" };
+      }
+    }
+
+    // Check if entire phase is skipped (all sub-stages skipped)
+    const allSkipped = Object.values(subStages).every((s) => s.status === "skipped");
+    phases[phase] = {
+      status: allSkipped ? "skipped" : "pending",
+      subStages,
+    };
+  }
+
+  return phases;
+}
+
+function generateStateMd(slug: string, branch: string, mode: string, description: string, classification?: string, workflow?: WorkflowStep[]): string {
+  const title = slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const date = new Date().toISOString().split("T")[0];
+
+  let md = `# ${title}
+
+**Slug:** ${slug}
+**Branch:** ${branch}
+**Started:** ${date}
+**Mode:** ${mode}
+`;
+
+  if (classification) {
+    md += `**Classification:** ${classification}\n`;
+  }
+
+  md += `**Phase:** plan
+**Sub-stage:** clarify
+**Status:** in-progress
+
+## Description
+${description}
+`;
+
+  if (workflow) {
+    md += `\n## Workflow\n`;
+    for (const step of workflow) {
+      if (step.included) {
+        const label = `${step.phase.charAt(0).toUpperCase() + step.phase.slice(1)}: ${step.subStage.charAt(0).toUpperCase() + step.subStage.slice(1)}`;
+        md += `- [ ] ${label}\n`;
+      }
+    }
+  }
+
+  md += `
+## Criteria
+<!-- Added during Plan/Clarify, checked off during test/review -->
+
+## Decisions
+<!-- Append here whenever you choose between real alternatives -->
+<!-- Format: **<context>**: chose <X> over <Y> — <why> -->
+
+## Deviations
+<!-- Append here whenever implementation diverges from the Blueprint -->
+<!-- Format: **<Blueprint step>**: <what changed> — <why> -->
+`;
+
+  return md;
+}
+
+export function initCommand(options: {
+  mode: "full" | "auto";
+  description: string;
+  classification?: Classification;
+  worktreeRoot?: string;
+}): Action {
+  const { mode, description, classification } = options;
+  const worktreeRoot = options.worktreeRoot || process.cwd();
+
+  // Guard: don't overwrite existing state
+  if (stateExists(worktreeRoot)) {
+    return {
+      action: "error",
+      message: "State already exists in this directory. Use `work-kit status` to check current state.",
+      suggestion: "To start fresh, delete .work-kit/state.json first.",
+    };
+  }
+
+  // Auto mode requires classification
+  if (mode === "auto" && !classification) {
+    return {
+      action: "error",
+      message: "Auto mode requires --classification (bug-fix, small-change, refactor, feature, large-feature).",
+    };
+  }
+
+  // Validate mode
+  if (mode !== "full" && mode !== "auto") {
+    return {
+      action: "error",
+      message: `Invalid mode "${mode}". Use "full" or "auto".`,
+    };
+  }
+
+  const slug = toSlug(description);
+  const branch = `feature/${slug}`;
+  const modeLabel = mode === "full" ? "full-kit" : "auto-kit";
+
+  // Build workflow
+  let workflow: WorkflowStep[] | undefined;
+  if (mode === "auto" && classification) {
+    workflow = buildDefaultWorkflow(classification);
+  } else if (mode === "full") {
+    workflow = buildFullWorkflow();
+  }
+
+  // Find first active sub-stage
+  let firstPhase: PhaseName = "plan";
+  let firstSubStage = "clarify";
+
+  if (workflow) {
+    const first = workflow.find((s) => s.included);
+    if (first) {
+      firstPhase = first.phase;
+      firstSubStage = first.subStage;
+    }
+  }
+
+  // Build state
+  const state: WorkKitState = {
+    version: 1,
+    slug,
+    branch,
+    started: new Date().toISOString().split("T")[0],
+    mode: modeLabel,
+    ...(classification && { classification }),
+    status: "in-progress",
+    currentPhase: firstPhase,
+    currentSubStage: firstSubStage,
+    phases: buildPhases(workflow),
+    ...(mode === "auto" && workflow && { workflow }),
+    loopbacks: [],
+    metadata: {
+      worktreeRoot,
+      mainRepoRoot: worktreeRoot, // will be set properly by caller
+    },
+  };
+
+  // Write state files
+  writeState(worktreeRoot, state);
+  writeStateMd(worktreeRoot, generateStateMd(slug, branch, modeLabel, description, classification, workflow));
+
+  return {
+    action: "spawn_agent",
+    phase: firstPhase,
+    subStage: firstSubStage,
+    skillFile: skillFilePath(firstPhase, firstSubStage),
+    agentPrompt: `You are starting the ${firstPhase} phase. Begin with the ${firstSubStage} sub-stage. Read the skill file and follow its instructions. Write outputs to .work-kit/state.md.`,
+    onComplete: `npx work-kit complete ${firstPhase}/${firstSubStage}`,
+  };
+}

package/cli/src/commands/loopback.ts

@@ -0,0 +1,64 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import { parseLocation, resetToLocation } from "../state/helpers.js";
+import type { Action } from "../state/schema.js";
+
+const MAX_LOOPBACKS_PER_ROUTE = 2;
+
+export function loopbackCommand(opts: {
+  from: string;
+  to: string;
+  reason: string;
+  worktreeRoot?: string;
+}): Action {
+  const root = opts.worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found." };
+  }
+
+  const state = readState(root);
+  const from = parseLocation(opts.from);
+  const to = parseLocation(opts.to);
+
+  if (!state.phases[from.phase]?.subStages[from.subStage]) {
+    return { action: "error", message: `Invalid source: ${opts.from}` };
+  }
+  if (!state.phases[to.phase]?.subStages[to.subStage]) {
+    return { action: "error", message: `Invalid target: ${opts.to}` };
+  }
+
+  // Can't loop back to a skipped sub-stage
+  if (state.phases[to.phase].subStages[to.subStage].status === "skipped") {
+    return { action: "error", message: `Cannot loop back to ${opts.to} — it is skipped.` };
+  }
+
+  // Enforce max loopback count per route
+  const sameRouteCount = state.loopbacks.filter(
+    (lb) => lb.from.phase === from.phase && lb.from.subStage === from.subStage
+      && lb.to.phase === to.phase && lb.to.subStage === to.subStage
+  ).length;
+  if (sameRouteCount >= MAX_LOOPBACKS_PER_ROUTE) {
+    return {
+      action: "error",
+      message: `Max loopback count (${MAX_LOOPBACKS_PER_ROUTE}) reached for ${opts.from} → ${opts.to}. Proceeding with noted caveats.`,
+    };
+  }
+
+  state.loopbacks.push({
+    from,
+    to,
+    reason: opts.reason,
+    timestamp: new Date().toISOString(),
+  });
+
+  resetToLocation(state, to);
+  state.currentPhase = to.phase;
+  state.currentSubStage = to.subStage;
+  writeState(root, state);
+
+  return {
+    action: "loopback",
+    from,
+    to,
+    reason: opts.reason,
+  };
+}

package/cli/src/commands/next.ts

@@ -0,0 +1,172 @@
+import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
+import { determineNextStep } from "../engine/transitions.js";
+import { validatePhasePrerequisites } from "../state/validators.js";
+import { buildAgentPrompt } from "../context/prompt-builder.js";
+import { getParallelGroup } from "../engine/parallel.js";
+import { skillFilePath } from "../config/phases.js";
+import type { Action, PhaseName, WorkKitState } from "../state/schema.js";
+
+export function nextCommand(worktreeRoot?: string): Action {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found. Run `work-kit init` first." };
+  }
+
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return { action: "complete", message: "Work-kit is already complete." };
+  }
+
+  if (state.status === "failed") {
+    return { action: "error", message: "Work-kit is in failed state.", suggestion: "Review the state and restart." };
+  }
+
+  const step = determineNextStep(state);
+
+  switch (step.type) {
+    case "complete":
+      return { action: "complete", message: step.message! };
+
+    case "wait-for-user":
+      return { action: "wait_for_user", message: step.message! };
+
+    case "phase-boundary": {
+      const phase = step.phase!;
+
+      const validation = validatePhasePrerequisites(state, phase);
+      if (!validation.valid) {
+        return {
+          action: "error",
+          message: validation.message,
+          suggestion: `Complete ${validation.missingPrerequisite} first.`,
+        };
+      }
+
+      state.currentPhase = phase;
+      state.phases[phase].status = "in-progress";
+      state.phases[phase].startedAt = new Date().toISOString();
+
+      const subStages = Object.entries(state.phases[phase].subStages);
+      const firstActive = subStages.find(([_, ss]) => ss.status === "pending");
+
+      if (!firstActive) {
+        return { action: "error", message: `No pending sub-stages in ${phase}` };
+      }
+
+      const [subStage] = firstActive;
+      state.currentSubStage = subStage;
+      state.phases[phase].subStages[subStage].status = "in-progress";
+      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      writeState(root, state);
+
+      return buildSpawnAction(root, state, phase, subStage);
+    }
+
+    case "sub-stage": {
+      const phase = step.phase!;
+      const subStage = step.subStage!;
+
+      state.currentPhase = phase;
+      state.currentSubStage = subStage;
+      if (state.phases[phase].status === "pending") {
+        state.phases[phase].status = "in-progress";
+        state.phases[phase].startedAt = new Date().toISOString();
+      }
+      state.phases[phase].subStages[subStage].status = "in-progress";
+      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      writeState(root, state);
+
+      return buildSpawnAction(root, state, phase, subStage);
+    }
+
+    default:
+      return { action: "error", message: `Unknown step type: ${step.type}` };
+  }
+}
+
+function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, subStage: string): Action {
+  // Read state.md once for all prompt builds
+  const stateMd = readStateMd(root);
+  const parallelGroup = getParallelGroup(phase, subStage, state);
+
+  if (parallelGroup) {
+    const agents = parallelGroup.parallel
+      .filter((ss) => {
+        const ssState = state.phases[phase].subStages[ss];
+        return ssState && ssState.status !== "skipped" && ssState.status !== "completed";
+      })
+      .map((ss) => ({
+        phase,
+        subStage: ss,
+        skillFile: skillFilePath(phase, ss),
+        agentPrompt: buildAgentPrompt(root, state, phase, ss, stateMd),
+        outputFile: `.work-kit/${phase}-${ss}.md`,
+      }));
+
+    // If all parallel members were filtered out, fall through to single agent
+    if (agents.length === 0) {
+      // Skip to thenSequential if it exists, otherwise nothing to do
+      if (parallelGroup.thenSequential) {
+        const seqSS = parallelGroup.thenSequential;
+        return {
+          action: "spawn_agent",
+          phase,
+          subStage: seqSS,
+          skillFile: skillFilePath(phase, seqSS),
+          agentPrompt: buildAgentPrompt(root, state, phase, seqSS, stateMd),
+          onComplete: `npx work-kit complete ${phase}/${seqSS}`,
+        };
+      }
+      return { action: "error", message: `No active sub-stages in parallel group for ${phase}` };
+    }
+
+    // If only 1 agent remains, run as single agent (no need for parallel)
+    if (agents.length === 1 && !parallelGroup.thenSequential) {
+      const agent = agents[0];
+      return {
+        action: "spawn_agent",
+        phase: agent.phase,
+        subStage: agent.subStage,
+        skillFile: agent.skillFile,
+        agentPrompt: agent.agentPrompt,
+        onComplete: `npx work-kit complete ${agent.phase}/${agent.subStage}`,
+      };
+    }
+
+    for (const agent of agents) {
+      state.phases[phase].subStages[agent.subStage].status = "in-progress";
+      state.phases[phase].subStages[agent.subStage].startedAt = new Date().toISOString();
+    }
+
+    const thenSequential = parallelGroup.thenSequential
+      ? {
+          phase,
+          subStage: parallelGroup.thenSequential,
+          skillFile: skillFilePath(phase, parallelGroup.thenSequential),
+          agentPrompt: buildAgentPrompt(root, state, phase, parallelGroup.thenSequential, stateMd),
+        }
+      : undefined;
+
+    writeState(root, state);
+
+    return {
+      action: "spawn_parallel_agents",
+      agents,
+      thenSequential,
+      onComplete: `npx work-kit complete ${phase}/${parallelGroup.thenSequential || parallelGroup.parallel[parallelGroup.parallel.length - 1]}`,
+    };
+  }
+
+  const skill = skillFilePath(phase, subStage);
+  const prompt = buildAgentPrompt(root, state, phase, subStage, stateMd);
+
+  return {
+    action: "spawn_agent",
+    phase,
+    subStage,
+    skillFile: skill,
+    agentPrompt: prompt,
+    onComplete: `npx work-kit complete ${phase}/${subStage}`,
+  };
+}

package/cli/src/commands/observe.ts

@@ -0,0 +1,144 @@
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  renderDashboard,
+  enterAlternateScreen,
+  exitAlternateScreen,
+  moveCursorHome,
+  renderTooSmall,
+} from "../observer/renderer.js";
+import { collectDashboardData } from "../observer/data.js";
+import { startWatching } from "../observer/watcher.js";
+
+function findMainRepoRoot(startDir: string): string {
+  // Find the git toplevel
+  try {
+    const result = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: startDir,
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    return result.trim();
+  } catch {
+    return startDir;
+  }
+}
+
+export async function observeCommand(opts: { mainRepo?: string }): Promise<void> {
+  const mainRepoRoot = opts.mainRepo
+    ? path.resolve(opts.mainRepo)
+    : findMainRepoRoot(process.cwd());
+
+  let scrollOffset = 0;
+  let cleanedUp = false;
+
+  function cleanup(): void {
+    if (cleanedUp) return;
+    cleanedUp = true;
+
+    // Restore terminal
+    exitAlternateScreen();
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+      try { process.stdin.setRawMode(false); } catch { /* ignore */ }
+    }
+    process.stdin.removeAllListeners("data");
+  }
+
+  function render(): void {
+    const width = process.stdout.columns || 80;
+    const height = process.stdout.rows || 24;
+
+    if (width < 60 || height < 10) {
+      process.stdout.write(renderTooSmall(width, height));
+      return;
+    }
+
+    const data = collectDashboardData(mainRepoRoot, watcher.getWorktrees());
+    const frame = moveCursorHome() + renderDashboard(data, width, height, scrollOffset);
+    process.stdout.write(frame);
+  }
+
+  // Enter alternate screen
+  enterAlternateScreen();
+
+  // Set up signal handlers
+  const onSignal = () => {
+    cleanup();
+    process.exit(0);
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  let watcher!: ReturnType<typeof startWatching>;
+
+  try {
+    // Set up file watching (before initial render so worktrees are cached)
+    watcher = startWatching(mainRepoRoot, () => {
+      render();
+    });
+
+    // Initial render
+    render();
+
+    // Handle terminal resize
+    process.stdout.on("resize", () => {
+      render();
+    });
+
+    // Set up keyboard input
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding("utf-8");
+
+      await new Promise<void>((resolve) => {
+        process.stdin.on("data", (key: string) => {
+          // Ctrl+C
+          if (key === "\x03") {
+            watcher.stop();
+            resolve();
+            return;
+          }
+
+          // 'q' to quit
+          if (key === "q" || key === "Q") {
+            watcher.stop();
+            resolve();
+            return;
+          }
+
+          // 'r' to refresh
+          if (key === "r" || key === "R") {
+            scrollOffset = 0;
+            render();
+            return;
+          }
+
+          // Up arrow: \x1b[A
+          if (key === "\x1b[A") {
+            scrollOffset = Math.max(0, scrollOffset - 1);
+            render();
+            return;
+          }
+
+          // Down arrow: \x1b[B
+          if (key === "\x1b[B") {
+            scrollOffset++;
+            render();
+            return;
+          }
+        });
+      });
+    } else {
+      // Non-TTY: just keep running until interrupted
+      await new Promise<void>((resolve) => {
+        process.on("SIGINT", () => {
+          watcher.stop();
+          resolve();
+        });
+      });
+    }
+  } finally {
+    cleanup();
+  }
+}