@abdullahsahmad/work-kit 0.1.0

package/cli/src/config/phases.ts

@@ -0,0 +1,119 @@
+import {
+  PhaseName,
+  SUBSTAGES_BY_PHASE,
+  Classification,
+  WorkflowStep,
+} from "../state/schema.js";
+
+// ── Phase Order ──────────────────────────────────────────────────────
+
+export const PHASE_ORDER: PhaseName[] = ["plan", "build", "test", "review", "deploy", "wrap-up"];
+
+// ── Prerequisites ────────────────────────────────────────────────────
+
+export const PHASE_PREREQUISITES: Record<PhaseName, PhaseName | null> = {
+  plan: null,
+  build: "plan",
+  test: "build",
+  review: "test",
+  deploy: "review",
+  "wrap-up": "review", // or deploy if deploy was included
+};
+
+// ── Skill File Paths ─────────────────────────────────────────────────
+
+export function skillFilePath(phase: PhaseName, subStage?: string): string {
+  if (phase === "wrap-up") return ".claude/skills/wrap-up/SKILL.md";
+  if (!subStage) return `.claude/skills/${phase}/SKILL.md`;
+  return `.claude/skills/${phase}/stages/${subStage}.md`;
+}
+
+// ── Auto-kit Default Workflows ───────────────────────────────────────
+
+type InclusionRule = "YES" | "skip" | "if UI" | "if DB" | "optional";
+
+const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
+  "bug-fix": {
+    "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "skip", "plan/scope": "skip",
+    "plan/ux-flow": "skip", "plan/architecture": "skip", "plan/blueprint": "skip", "plan/audit": "skip",
+    "build/setup": "skip", "build/migration": "skip", "build/red": "YES", "build/core": "YES",
+    "build/ui": "if UI", "build/refactor": "skip", "build/integration": "skip", "build/commit": "YES",
+    "test/verify": "YES", "test/e2e": "skip", "test/validate": "YES",
+    "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
+    "review/compliance": "skip", "review/handoff": "YES",
+    "deploy/merge": "optional", "deploy/monitor": "optional", "deploy/remediate": "optional",
+    "wrap-up/wrap-up": "YES",
+  },
+  "small-change": {
+    "plan/clarify": "YES", "plan/investigate": "skip", "plan/sketch": "skip", "plan/scope": "skip",
+    "plan/ux-flow": "skip", "plan/architecture": "skip", "plan/blueprint": "skip", "plan/audit": "skip",
+    "build/setup": "skip", "build/migration": "skip", "build/red": "skip", "build/core": "YES",
+    "build/ui": "if UI", "build/refactor": "skip", "build/integration": "skip", "build/commit": "YES",
+    "test/verify": "YES", "test/e2e": "skip", "test/validate": "skip",
+    "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
+    "review/compliance": "skip", "review/handoff": "YES",
+    "deploy/merge": "optional", "deploy/monitor": "optional", "deploy/remediate": "optional",
+    "wrap-up/wrap-up": "YES",
+  },
+  refactor: {
+    "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "skip", "plan/scope": "skip",
+    "plan/ux-flow": "skip", "plan/architecture": "skip", "plan/blueprint": "skip", "plan/audit": "skip",
+    "build/setup": "skip", "build/migration": "skip", "build/red": "skip", "build/core": "YES",
+    "build/ui": "if UI", "build/refactor": "YES", "build/integration": "skip", "build/commit": "YES",
+    "test/verify": "YES", "test/e2e": "skip", "test/validate": "skip",
+    "review/self-review": "YES", "review/security": "skip", "review/performance": "YES",
+    "review/compliance": "skip", "review/handoff": "YES",
+    "deploy/merge": "optional", "deploy/monitor": "optional", "deploy/remediate": "optional",
+    "wrap-up/wrap-up": "YES",
+  },
+  feature: {
+    "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
+    "plan/ux-flow": "if UI", "plan/architecture": "YES", "plan/blueprint": "YES", "plan/audit": "skip",
+    "build/setup": "YES", "build/migration": "if DB", "build/red": "YES", "build/core": "YES",
+    "build/ui": "if UI", "build/refactor": "skip", "build/integration": "YES", "build/commit": "YES",
+    "test/verify": "YES", "test/e2e": "if UI", "test/validate": "YES",
+    "review/self-review": "YES", "review/security": "YES", "review/performance": "skip",
+    "review/compliance": "YES", "review/handoff": "YES",
+    "deploy/merge": "optional", "deploy/monitor": "optional", "deploy/remediate": "optional",
+    "wrap-up/wrap-up": "YES",
+  },
+  "large-feature": {
+    "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
+    "plan/ux-flow": "if UI", "plan/architecture": "YES", "plan/blueprint": "YES", "plan/audit": "YES",
+    "build/setup": "YES", "build/migration": "if DB", "build/red": "YES", "build/core": "YES",
+    "build/ui": "if UI", "build/refactor": "YES", "build/integration": "YES", "build/commit": "YES",
+    "test/verify": "YES", "test/e2e": "YES", "test/validate": "YES",
+    "review/self-review": "YES", "review/security": "YES", "review/performance": "YES",
+    "review/compliance": "YES", "review/handoff": "YES",
+    "deploy/merge": "optional", "deploy/monitor": "optional", "deploy/remediate": "optional",
+    "wrap-up/wrap-up": "YES",
+  },
+};
+
+export function buildDefaultWorkflow(classification: Classification): WorkflowStep[] {
+  const matrix = WORKFLOW_MATRIX[classification];
+  const steps: WorkflowStep[] = [];
+
+  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 });
+    }
+  }
+
+  return steps;
+}
+
+export function buildFullWorkflow(): WorkflowStep[] {
+  const steps: WorkflowStep[] = [];
+  for (const phase of PHASE_ORDER) {
+    for (const subStage of SUBSTAGES_BY_PHASE[phase]) {
+      // Deploy is optional by default
+      const included = phase !== "deploy";
+      steps.push({ phase, subStage, included });
+    }
+  }
+  return steps;
+}

package/cli/src/context/extractor.test.ts

@@ -0,0 +1,77 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { extractSection, extractTopSection } from "./extractor.js";
+
+const SAMPLE_MD = `# Title
+
+## Description
+This is the description content.
+It spans multiple lines.
+
+## Criteria
+- Criterion one
+- Criterion two
+
+### Sub Heading A
+Content A here.
+More content A.
+
+### Sub Heading B
+Content B here.
+
+## Decisions
+Some decisions.
+`;
+
+describe("extractSection", () => {
+  it("finds ### section by heading", () => {
+    const result = extractSection(SAMPLE_MD, "Sub Heading A");
+    assert.notEqual(result, null);
+    assert.ok(result!.includes("Content A here."));
+    assert.ok(result!.includes("More content A."));
+  });
+
+  it("stops at the next ### heading", () => {
+    const result = extractSection(SAMPLE_MD, "Sub Heading A");
+    assert.notEqual(result, null);
+    assert.ok(!result!.includes("Content B here."));
+  });
+
+  it("returns null for missing section", () => {
+    const result = extractSection(SAMPLE_MD, "Nonexistent");
+    assert.equal(result, null);
+  });
+
+  it("works when heading already includes ###", () => {
+    const result = extractSection(SAMPLE_MD, "### Sub Heading B");
+    assert.notEqual(result, null);
+    assert.ok(result!.includes("Content B here."));
+  });
+});
+
+describe("extractTopSection", () => {
+  it("finds ## section", () => {
+    const result = extractTopSection(SAMPLE_MD, "Description");
+    assert.notEqual(result, null);
+    assert.ok(result!.includes("This is the description content."));
+  });
+
+  it("stops at next ## section", () => {
+    const result = extractTopSection(SAMPLE_MD, "Description");
+    assert.notEqual(result, null);
+    assert.ok(!result!.includes("Criterion one"));
+  });
+
+  it("returns null for missing section", () => {
+    const result = extractTopSection(SAMPLE_MD, "Nonexistent");
+    assert.equal(result, null);
+  });
+
+  it("includes ### sub-sections within the ## section", () => {
+    const result = extractTopSection(SAMPLE_MD, "Criteria");
+    assert.notEqual(result, null);
+    assert.ok(result!.includes("Criterion one"));
+    assert.ok(result!.includes("Sub Heading A"));
+    assert.ok(result!.includes("Content A here."));
+  });
+});

package/cli/src/context/extractor.ts

@@ -0,0 +1,73 @@
+import { readStateMd } from "../state/store.js";
+
+/**
+ * Extract a specific ### section from state.md by heading.
+ * Returns the content between the heading and the next ### heading (or end of file).
+ */
+export function extractSection(stateMd: string, heading: string): string | null {
+  // Normalize heading — ensure it starts with ###
+  const prefix = heading.startsWith("###") ? heading : `### ${heading}`;
+  const lines = stateMd.split("\n");
+  let capturing = false;
+  const captured: string[] = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith(prefix)) {
+      capturing = true;
+      captured.push(line);
+      continue;
+    }
+    if (capturing && line.trim().startsWith("### ")) {
+      break; // Hit next section
+    }
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+
+  return captured.length > 0 ? captured.join("\n").trim() : null;
+}
+
+/**
+ * Extract a ## section (top-level section like Description, Criteria).
+ */
+export function extractTopSection(stateMd: string, heading: string): string | null {
+  const prefix = heading.startsWith("##") ? heading : `## ${heading}`;
+  const lines = stateMd.split("\n");
+  let capturing = false;
+  const captured: string[] = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith(prefix) && !line.trim().startsWith("### ")) {
+      capturing = true;
+      captured.push(line);
+      continue;
+    }
+    if (capturing && line.trim().startsWith("## ") && !line.trim().startsWith("### ")) {
+      break;
+    }
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+
+  return captured.length > 0 ? captured.join("\n").trim() : null;
+}
+
+/**
+ * Extract multiple sections from state.md.
+ */
+export function extractSections(worktreeRoot: string, sectionNames: string[]): Record<string, string | null> {
+  const stateMd = readStateMd(worktreeRoot);
+  if (!stateMd) return {};
+
+  const result: Record<string, string | null> = {};
+  for (const name of sectionNames) {
+    if (name.startsWith("### ") || !name.startsWith("## ")) {
+      result[name] = extractSection(stateMd, name);
+    } else {
+      result[name] = extractTopSection(stateMd, name);
+    }
+  }
+  return result;
+}

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

@@ -0,0 +1,70 @@
+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";
+
+/**
+ * Build a complete agent prompt for a given phase/sub-stage.
+ * Accepts optional pre-read stateMd to avoid repeated file reads in parallel scenarios.
+ */
+export function buildAgentPrompt(
+  worktreeRoot: string,
+  state: WorkKitState,
+  phase: PhaseName,
+  subStage: string,
+  stateMd?: string | null
+): string {
+  const ctx = getContextFor(phase, subStage);
+  const md = stateMd ?? readStateMd(worktreeRoot);
+  const skill = skillFilePath(phase, subStage);
+
+  const parts: string[] = [];
+
+  parts.push(`# Agent: ${phase}/${subStage}`);
+  parts.push(`**Worktree:** ${worktreeRoot}`);
+  parts.push(`**Slug:** ${state.slug}`);
+  parts.push(`**Branch:** ${state.branch}`);
+  parts.push(`**Mode:** ${state.mode}`);
+  parts.push("");
+
+  parts.push(`## Instructions`);
+  parts.push(`Read and follow the skill file: \`${skill}\``);
+  parts.push("");
+
+  if (phase === "wrap-up" && md) {
+    parts.push(`## Full State`);
+    parts.push(md);
+    parts.push("");
+  } else if (md && ctx.sections.length > 0) {
+    parts.push(`## Context from state.md`);
+    parts.push("");
+
+    for (const sectionName of ctx.sections) {
+      const content = sectionName.startsWith("### ")
+        ? extractSection(md, sectionName)
+        : extractTopSection(md, sectionName);
+      if (content) {
+        parts.push(content);
+        parts.push("");
+      }
+    }
+  }
+
+  if (ctx.needsGitDiff) {
+    parts.push(`## Git Diff`);
+    parts.push(`Run \`git diff main...HEAD\` to review the changes.`);
+    parts.push("");
+  }
+
+  parts.push(`## Output`);
+  parts.push(`Write your outputs to \`.work-kit/state.md\` under a section for this sub-stage.`);
+
+  if (subStage === "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 complete ${phase}/${subStage} --outcome <outcome>\``);
+  }
+
+  return parts.join("\n");
+}

package/cli/src/engine/loopbacks.test.ts

@@ -0,0 +1,33 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { checkLoopback } from "./loopbacks.js";
+
+describe("checkLoopback", () => {
+  it("plan/audit with 'revise' loops back to plan/blueprint", () => {
+    const result = checkLoopback("plan", "audit", "revise");
+    assert.notEqual(result, null);
+    assert.deepStrictEqual(result!.to, { phase: "plan", subStage: "blueprint" });
+    assert.ok(result!.reason.length > 0);
+  });
+
+  it("plan/audit with 'proceed' returns null (no loopback)", () => {
+    const result = checkLoopback("plan", "audit", "proceed");
+    assert.equal(result, null);
+  });
+
+  it("review/handoff with 'changes_requested' loops back to build/core", () => {
+    const result = checkLoopback("review", "handoff", "changes_requested");
+    assert.notEqual(result, null);
+    assert.deepStrictEqual(result!.to, { phase: "build", subStage: "core" });
+  });
+
+  it("build/core with 'done' returns null", () => {
+    const result = checkLoopback("build", "core", "done");
+    assert.equal(result, null);
+  });
+
+  it("returns null when outcome is undefined", () => {
+    const result = checkLoopback("plan", "audit");
+    assert.equal(result, null);
+  });
+});

package/cli/src/engine/loopbacks.ts

@@ -0,0 +1,32 @@
+import { PhaseName, Location } from "../state/schema.js";
+import { LOOPBACK_ROUTES } from "../config/loopback-routes.js";
+
+interface LoopbackResult {
+  to: Location;
+  reason: string;
+}
+
+/**
+ * Check if completing a sub-stage with a given outcome should trigger a loop-back.
+ */
+export function checkLoopback(
+  phase: PhaseName,
+  subStage: string,
+  outcome?: string
+): LoopbackResult | null {
+  if (!outcome) return null;
+
+  const route = LOOPBACK_ROUTES.find(
+    (r) =>
+      r.from.phase === phase &&
+      r.from.subStage === subStage &&
+      r.triggerOutcome === outcome
+  );
+
+  if (!route) return null;
+
+  return {
+    to: route.to,
+    reason: route.reason,
+  };
+}

package/cli/src/engine/parallel.ts

@@ -0,0 +1,60 @@
+import type { PhaseName, WorkKitState } from "../state/schema.js";
+
+/**
+ * Defines which sub-stages run in parallel and which runs sequentially after.
+ */
+export interface ParallelGroup {
+  parallel: string[];          // sub-stages that run concurrently
+  thenSequential?: string;     // sub-stage that runs after all parallel complete
+}
+
+/**
+ * Parallel group definitions per phase.
+ */
+const PARALLEL_GROUPS: Record<string, ParallelGroup> = {
+  test: {
+    parallel: ["verify", "e2e"],
+    thenSequential: "validate",
+  },
+  review: {
+    parallel: ["self-review", "security", "performance", "compliance"],
+    thenSequential: "handoff",
+  },
+};
+
+/**
+ * Check if a sub-stage triggers a parallel group.
+ * Triggers on any parallel member that is the first non-skipped one in the group.
+ * Returns null if the sub-stage is not a parallel trigger or the group doesn't apply.
+ */
+export function getParallelGroup(phase: PhaseName, subStage: string, state?: WorkKitState): ParallelGroup | null {
+  const group = PARALLEL_GROUPS[phase];
+  if (!group) return null;
+
+  if (!group.parallel.includes(subStage)) return null;
+
+  // Find the first non-skipped parallel member
+  if (state) {
+    const phaseState = state.phases[phase];
+    const firstActive = group.parallel.find((ss) => {
+      const ssState = phaseState?.subStages[ss];
+      return ssState && ssState.status !== "skipped" && ssState.status !== "completed";
+    });
+    // Only trigger if this sub-stage is the first active parallel member
+    if (firstActive !== subStage) return null;
+  } else {
+    // No state provided — fall back to first-member trigger
+    if (group.parallel[0] !== subStage) return null;
+  }
+
+  return group;
+}
+
+/**
+ * Check if a sub-stage is a parallel member (part of a group, not necessarily trigger).
+ */
+export function isParallelMember(phase: PhaseName, subStage: string): boolean {
+  const group = PARALLEL_GROUPS[phase];
+  if (!group) return false;
+  return group.parallel.includes(subStage);
+}

package/cli/src/engine/phases.ts

@@ -0,0 +1,23 @@
+import { PhaseName } from "../state/schema.js";
+
+// ── Phase-level Wait Points ──────────────────────────────────────────
+// After completing these phases, the orchestrator should wait for user
+// confirmation before proceeding to the next phase.
+
+export const WAIT_AFTER_PHASE: Set<PhaseName> = new Set([
+  "plan",    // User reviews the blueprint before build
+  "build",   // User reviews the PR before test
+  "test",    // User reviews test results before review
+  "review",  // User reviews the ship decision before deploy
+]);
+
+// ── Phase Display Names ──────────────────────────────────────────────
+
+export const PHASE_DISPLAY_NAMES: Record<PhaseName, string> = {
+  plan: "Plan",
+  build: "Build",
+  test: "Test",
+  review: "Review",
+  deploy: "Deploy",
+  "wrap-up": "Wrap-up",
+};

package/cli/src/engine/transitions.test.ts

@@ -0,0 +1,117 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { nextSubStageInPhase, isPhaseComplete, determineNextStep } from "./transitions.js";
+import type { WorkKitState, PhaseName, PhaseState, SubStageState } from "../state/schema.js";
+import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "../state/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("nextSubStageInPhase", () => {
+  it("returns first pending sub-stage", () => {
+    const state = makeState();
+    const result = nextSubStageInPhase(state, "plan");
+    assert.equal(result, "clarify");
+  });
+
+  it("returns null when all complete or skipped", () => {
+    const state = makeState();
+    for (const ss of Object.values(state.phases.plan.subStages)) {
+      ss.status = "completed";
+    }
+    const result = nextSubStageInPhase(state, "plan");
+    assert.equal(result, null);
+  });
+
+  it("skips completed sub-stages and returns next pending", () => {
+    const state = makeState();
+    state.phases.plan.subStages.clarify.status = "completed";
+    state.phases.plan.subStages.investigate.status = "completed";
+    const result = nextSubStageInPhase(state, "plan");
+    assert.equal(result, "sketch");
+  });
+});
+
+describe("isPhaseComplete", () => {
+  it("returns true when all complete or skipped", () => {
+    const state = makeState();
+    for (const ss of Object.values(state.phases.plan.subStages)) {
+      ss.status = "completed";
+    }
+    assert.equal(isPhaseComplete(state, "plan"), true);
+  });
+
+  it("returns true with mix of completed and skipped", () => {
+    const state = makeState();
+    let first = true;
+    for (const ss of Object.values(state.phases.plan.subStages)) {
+      ss.status = first ? "skipped" : "completed";
+      first = false;
+    }
+    assert.equal(isPhaseComplete(state, "plan"), true);
+  });
+
+  it("returns false when some sub-stages are pending", () => {
+    const state = makeState();
+    assert.equal(isPhaseComplete(state, "plan"), false);
+  });
+});
+
+describe("determineNextStep", () => {
+  it("returns complete when state is completed", () => {
+    const state = makeState();
+    state.status = "completed";
+    const step = determineNextStep(state);
+    assert.equal(step.type, "complete");
+  });
+
+  it("returns phase-boundary when no current phase", () => {
+    const state = makeState();
+    state.currentPhase = null;
+    const step = determineNextStep(state);
+    assert.equal(step.type, "phase-boundary");
+    assert.equal(step.phase, "plan");
+  });
+
+  it("returns sub-stage for current phase with pending work", () => {
+    const state = makeState();
+    state.currentPhase = "plan";
+    state.phases.plan.status = "in-progress";
+    const step = determineNextStep(state);
+    assert.equal(step.type, "sub-stage");
+    assert.equal(step.phase, "plan");
+    assert.equal(step.subStage, "clarify");
+  });
+
+  it("returns wait-for-user when current phase is complete", () => {
+    const state = makeState();
+    state.currentPhase = "plan";
+    for (const ss of Object.values(state.phases.plan.subStages)) {
+      ss.status = "completed";
+    }
+    const step = determineNextStep(state);
+    assert.equal(step.type, "wait-for-user");
+    assert.equal(step.phase, "build");
+  });
+});