work-kit-cli 0.2.0

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 };

package/cli/src/state/store.ts

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { WorkKitState } from "./schema.js";
+
+const STATE_DIR = ".work-kit";
+const STATE_FILE = "state.json";
+
+// ── Worktree Discovery ───────────────────────────────────────────────
+
+export function findWorktreeRoot(startDir?: string): string | null {
+  let dir = startDir || process.cwd();
+  while (true) {
+    if (fs.existsSync(path.join(dir, STATE_DIR, STATE_FILE))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function stateDir(worktreeRoot: string): string {
+  return path.join(worktreeRoot, STATE_DIR);
+}
+
+export function statePath(worktreeRoot: string): string {
+  return path.join(worktreeRoot, STATE_DIR, STATE_FILE);
+}
+
+export function stateMdPath(worktreeRoot: string): string {
+  return path.join(worktreeRoot, STATE_DIR, "state.md");
+}
+
+// ── Read / Write ─────────────────────────────────────────────────────
+
+export function stateExists(worktreeRoot: string): boolean {
+  return fs.existsSync(statePath(worktreeRoot));
+}
+
+export function readState(worktreeRoot: string): WorkKitState {
+  const filePath = statePath(worktreeRoot);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`No state.json found at ${filePath}`);
+  }
+  const raw = fs.readFileSync(filePath, "utf-8");
+  try {
+    return JSON.parse(raw) as WorkKitState;
+  } catch {
+    throw new Error(`Corrupted state.json at ${filePath}. File contains invalid JSON.`);
+  }
+}
+
+export function writeState(worktreeRoot: string, state: WorkKitState): void {
+  const dir = stateDir(worktreeRoot);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const target = statePath(worktreeRoot);
+  const tmp = target + "." + randomUUID().slice(0, 8) + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf-8");
+  fs.renameSync(tmp, target);
+}
+
+// ── State.md ─────────────────────────────────────────────────────────
+
+export function writeStateMd(worktreeRoot: string, content: string): void {
+  const dir = stateDir(worktreeRoot);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const target = stateMdPath(worktreeRoot);
+  const tmp = target + "." + randomUUID().slice(0, 8) + ".tmp";
+  fs.writeFileSync(tmp, content, "utf-8");
+  fs.renameSync(tmp, target);
+}
+
+export function readStateMd(worktreeRoot: string): string | null {
+  const filePath = stateMdPath(worktreeRoot);
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf-8");
+}

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

@@ -0,0 +1,105 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { validatePhasePrerequisites } from "./validators.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" },
+  };
+}
+
+function completePhase(state: WorkKitState, phase: PhaseName): void {
+  state.phases[phase].status = "completed";
+  state.phases[phase].completedAt = "2026-01-01";
+  for (const ss of Object.values(state.phases[phase].subStages)) {
+    ss.status = "completed";
+    ss.completedAt = "2026-01-01";
+  }
+}
+
+describe("validatePhasePrerequisites", () => {
+  it("plan has no prerequisites — valid", () => {
+    const state = makeState();
+    const result = validatePhasePrerequisites(state, "plan");
+    assert.equal(result.valid, true);
+  });
+
+  it("build with plan incomplete — invalid", () => {
+    const state = makeState();
+    const result = validatePhasePrerequisites(state, "build");
+    assert.equal(result.valid, false);
+    assert.equal(result.missingPrerequisite, "plan");
+  });
+
+  it("build with plan complete — valid", () => {
+    const state = makeState();
+    completePhase(state, "plan");
+    const result = validatePhasePrerequisites(state, "build");
+    assert.equal(result.valid, true);
+  });
+
+  it("deploy with review complete but handoff not approved — invalid", () => {
+    const state = makeState();
+    completePhase(state, "plan");
+    completePhase(state, "build");
+    completePhase(state, "test");
+    completePhase(state, "review");
+    // handoff completed but without "approved" outcome
+    state.phases.review.subStages.handoff.outcome = "pending_review";
+    const result = validatePhasePrerequisites(state, "deploy");
+    assert.equal(result.valid, false);
+  });
+
+  it("deploy with review complete and handoff approved — valid", () => {
+    const state = makeState();
+    completePhase(state, "plan");
+    completePhase(state, "build");
+    completePhase(state, "test");
+    completePhase(state, "review");
+    state.phases.review.subStages.handoff.outcome = "approved";
+    const result = validatePhasePrerequisites(state, "deploy");
+    assert.equal(result.valid, true);
+  });
+
+  it("wrap-up with review complete — valid", () => {
+    const state = makeState();
+    completePhase(state, "plan");
+    completePhase(state, "build");
+    completePhase(state, "test");
+    completePhase(state, "review");
+    const result = validatePhasePrerequisites(state, "wrap-up");
+    assert.equal(result.valid, true);
+  });
+
+  it("wrap-up with deploy in-progress — invalid", () => {
+    const state = makeState();
+    completePhase(state, "plan");
+    completePhase(state, "build");
+    completePhase(state, "test");
+    completePhase(state, "review");
+    state.phases.deploy.status = "in-progress";
+    const result = validatePhasePrerequisites(state, "wrap-up");
+    assert.equal(result.valid, false);
+    assert.equal(result.missingPrerequisite, "deploy");
+  });
+});

package/cli/src/state/validators.ts

@@ -0,0 +1,81 @@
+import { WorkKitState, PhaseName } from "./schema.js";
+import { PHASE_PREREQUISITES } from "../config/phases.js";
+
+export interface ValidationResult {
+  valid: boolean;
+  message: string;
+  missingPrerequisite?: PhaseName;
+}
+
+export function validatePhasePrerequisites(state: WorkKitState, phase: PhaseName): ValidationResult {
+  const prereq = PHASE_PREREQUISITES[phase];
+
+  if (!prereq) {
+    return { valid: true, message: `${phase} has no prerequisites` };
+  }
+
+  // Special case: wrap-up can proceed after review OR deploy
+  if (phase === "wrap-up") {
+    const reviewDone = state.phases.review.status === "completed";
+    const deployStatus = state.phases.deploy.status;
+
+    if (!reviewDone) {
+      return {
+        valid: false,
+        message: `wrap-up requires review to be complete. Current: ${state.phases.review.status}`,
+        missingPrerequisite: "review",
+      };
+    }
+
+    if (deployStatus === "in-progress") {
+      return {
+        valid: false,
+        message: `wrap-up requires deploy to finish first. Current: ${deployStatus}`,
+        missingPrerequisite: "deploy",
+      };
+    }
+
+    // deploy completed, skipped, or pending (never started) — all ok if review is done
+    return { valid: true, message: "Prerequisites met for wrap-up" };
+  }
+
+  // Special case: deploy requires review complete AND handoff approved
+  if (phase === "deploy") {
+    const reviewState = state.phases.review;
+    if (reviewState.status !== "completed") {
+      return {
+        valid: false,
+        message: `deploy requires review to be complete. Current: ${reviewState.status}`,
+        missingPrerequisite: "review",
+      };
+    }
+    const handoff = reviewState.subStages["handoff"];
+    if (!handoff) {
+      return {
+        valid: false,
+        message: `deploy requires review/handoff to exist and be approved. Handoff sub-stage not found.`,
+        missingPrerequisite: "review",
+      };
+    }
+    if (handoff.outcome !== "approved") {
+      return {
+        valid: false,
+        message: `deploy requires review/handoff outcome to be "approved". Current: ${handoff.outcome || "none"}`,
+        missingPrerequisite: "review",
+      };
+    }
+    return { valid: true, message: "Prerequisites met for deploy" };
+  }
+
+  // General case
+  const prereqState = state.phases[prereq];
+  if (prereqState.status !== "completed") {
+    return {
+      valid: false,
+      message: `${phase} requires ${prereq} to be complete. Current: ${prereqState.status}`,
+      missingPrerequisite: prereq,
+    };
+  }
+
+  return { valid: true, message: `Prerequisites met for ${phase}` };
+}

package/cli/src/utils/colors.ts

@@ -0,0 +1,12 @@
+const enabled = process.stdout.isTTY !== false && process.env.NO_COLOR === undefined;
+
+const code = (n: number) => enabled ? `\x1b[${n}m` : "";
+const reset = code(0);
+
+export const bold = (s: string) => `${code(1)}${s}${reset}`;
+export const dim = (s: string) => `${code(2)}${s}${reset}`;
+export const green = (s: string) => `${code(32)}${s}${reset}`;
+export const yellow = (s: string) => `${code(33)}${s}${reset}`;
+export const red = (s: string) => `${code(31)}${s}${reset}`;
+export const cyan = (s: string) => `${code(36)}${s}${reset}`;
+export const bgYellow = (s: string) => `${code(43)}${code(30)}${s}${reset}`;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "work-kit-cli",
+  "version": "0.2.0",
+  "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 sub-stages.",
+  "type": "module",
+  "bin": {
+    "work-kit": "cli/bin/work-kit.mjs",
+    "wk": "cli/bin/work-kit.mjs"
+  },
+  "files": [
+    "cli/bin/",
+    "cli/src/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "tsx cli/src/index.ts",
+    "doctor": "tsx cli/src/index.ts doctor",
+    "setup": "tsx cli/src/index.ts setup",
+    "build": "tsc --project cli/tsconfig.json",
+    "typecheck": "tsc --project cli/tsconfig.json --noEmit",
+    "test": "tsx --test cli/src/**/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AbdullahSAhmad/work-kit.git"
+  },
+  "keywords": [
+    "claude-code",
+    "workflow",
+    "skills",
+    "development"
+  ],
+  "author": "Abdullah Ahmad",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "tsx": "^4.19.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.2",
+    "typescript": "^5.8.3"
+  },
+  "bugs": {
+    "url": "https://github.com/AbdullahSAhmad/work-kit/issues"
+  },
+  "homepage": "https://github.com/AbdullahSAhmad/work-kit#readme"
+}

package/skills/auto-kit/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: auto-kit
+description: "Smart pipeline that analyzes the request and builds a dynamic workflow. Usage: /auto-kit <description> to start, /auto-kit to continue."
+user-invocable: true
+argument-hint: "[description]"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Work Orchestrator (Auto Mode)**. You analyze the request first, then build a tailored workflow with only the phases and sub-stages that are actually needed.
+
+Best for: bug fixes, small changes, refactors, or well-understood tasks.
+
+## Prerequisites
+
+Before starting, verify the CLI is installed:
+```bash
+npx work-kit-cli doctor
+```
+
+If `work-kit` is not found, ask the user to install it:
+> work-kit CLI is required but not installed. Install it with: `npm install -g work-kit-cli`
+
+Do not proceed until `doctor` reports all checks passed.
+
+## All Available Sub-stages
+
+These are the building blocks you pick from:
+
+- **Plan:** Clarify, Investigate, Sketch, Scope, UX Flow, Architecture, Blueprint, Audit
+- **Build:** Setup, Migration, Red, Core, UI, Refactor, Integration, Commit
+- **Test:** Verify, E2E, Validate
+- **Review:** Self-Review, Security, Performance, Compliance, Handoff
+- **Deploy:** Merge, Monitor, Remediate (optional)
+- **Wrap-up**
+
+## Starting New Work (`/auto-kit <description>`)
+
+### Step 1: Analyze
+
+Before creating the worktree, perform a quick analysis:
+
+1. **Read the description** — understand the type of work
+2. **Classify the work** into one of these categories:
+   - **bug-fix** — fixing broken behavior
+   - **small-change** — config tweak, copy change, minor adjustment
+   - **refactor** — restructuring without behavior change
+   - **feature** — new capability (small to medium scope)
+   - **large-feature** — new capability (large scope, multiple systems)
+3. **Scan the codebase** — quick look at affected areas (not a full investigation)
+4. **Build the workflow** — select only the sub-stages needed
+
+### Step 2: Build Dynamic Workflow
+
+Based on the classification, select sub-stages. Use this table as a starting point, then adjust based on the specific request:
+
+| Sub-stage              | bug-fix | small-change | refactor | feature | large-feature |
+|------------------------|---------|--------------|----------|---------|---------------|
+| **Plan: Clarify**      | YES     | YES          | YES      | YES     | YES           |
+| **Plan: Investigate**  | YES     | skip         | YES      | YES     | YES           |
+| **Plan: Sketch**       | skip    | skip         | skip     | YES     | YES           |
+| **Plan: Scope**        | skip    | skip         | skip     | YES     | YES           |
+| **Plan: UX Flow**      | skip    | skip         | skip     | if UI   | if UI         |
+| **Plan: Architecture** | skip    | skip         | skip     | YES     | YES           |
+| **Plan: Blueprint**    | skip    | skip         | skip     | YES     | YES           |
+| **Plan: Audit**        | skip    | skip         | skip     | skip    | YES           |
+| **Build: Setup**       | skip    | skip         | skip     | YES     | YES           |
+| **Build: Migration**   | skip    | skip         | skip     | if DB   | if DB         |
+| **Build: Red**         | YES     | skip         | skip     | YES     | YES           |
+| **Build: Core**        | YES     | YES          | YES      | YES     | YES           |
+| **Build: UI**          | if UI   | if UI        | if UI    | if UI   | if UI         |
+| **Build: Refactor**    | skip    | skip         | YES      | skip    | YES           |
+| **Build: Integration** | skip    | skip         | skip     | YES     | YES           |
+| **Build: Commit**      | YES     | YES          | YES      | YES     | YES           |
+| **Test: Verify**       | YES     | YES          | YES      | YES     | YES           |
+| **Test: E2E**          | skip    | skip         | skip     | if UI   | YES           |
+| **Test: Validate**     | YES     | skip         | skip     | YES     | YES           |
+| **Review: Self-Review**| YES     | YES          | YES      | YES     | YES           |
+| **Review: Security**   | skip    | skip         | skip     | YES     | YES           |
+| **Review: Performance**| skip    | skip         | YES      | skip    | YES           |
+| **Review: Compliance** | skip    | skip         | skip     | YES     | YES           |
+| **Review: Handoff**    | YES     | YES          | YES      | YES     | YES           |
+| **Deploy: Merge**      | YES     | YES          | YES      | YES     | YES           |
+| **Wrap-up**            | YES     | YES          | YES      | YES     | YES           |
+
+The table is a guide, not a rigid rule. Adjust based on the actual request:
+- A bug fix that touches auth → add Security review
+- A refactor that changes DB queries → add Migration, Performance review
+- A small-change that affects public API → add Investigate, Blueprint
+
+**Deploy and Wrap-up are MANDATORY and cannot be removed from any workflow.** Deploy handles syncing with the default branch, creating a PR, and merging it — fully autonomous, no user confirmation needed. Wrap-up archives the work history so past work is discoverable in future sessions. Always spawn real agents for both — never just mark them complete.
+
+### Step 3: Initialize
+
+1. Create a git worktree and initialize state with the CLI:
+   ```bash
+   git worktree add worktrees/<slug> -b feature/<slug>
+   cd worktrees/<slug>
+   npx work-kit-cli init --mode auto --description "<description>" --classification <classification>
+   ```
+2. Show the workflow to the user: `npx work-kit-cli workflow`
+3. User can adjust: `npx work-kit-cli workflow --add review/security` or `npx work-kit-cli workflow --remove test/e2e`
+4. **Wait for approval** — user can add/remove steps before proceeding
+5. Once approved, start the execution loop
+
+## Continuing Work (`/auto-kit` with no args)
+
+1. Find the active worktree — check `git worktree list` or look for `.work-kit/state.md`
+2. Run `npx work-kit-cli status` to see current state
+3. Run `npx work-kit-cli next` to get the next action
+4. Follow the execution loop below
+
+## Step Validation
+
+All validation is handled by the CLI. The `next` command enforces order, phase boundaries, and prerequisites automatically.
+
+To add/remove steps mid-work: `npx work-kit-cli workflow --add <phase/sub-stage>` or `--remove <phase/sub-stage>`. Completed steps cannot be removed.
+
+## Agent Architecture
+
+Same as full-kit: each phase runs as a **fresh agent** to keep context focused. The difference is that each agent only runs the sub-stages in the `## Workflow` checklist.
+
+```
+Orchestrator (main agent — you)
+│
+├── Agent: Plan (runs only Plan steps from Workflow)
+│   ├── reads: ## Description, ## Criteria, codebase
+│   └── writes: ### Plan: Final
+│
+├── Agent: Build (runs only Build steps from Workflow)
+│   ├── reads: ### Plan: Final, ## Criteria
+│   └── writes: ### Build: Final
+│
+├── Agent: Test (runs only Test steps from Workflow)
+│   ├── reads: ### Build: Final, ### Plan: Final, ## Criteria
+│   ├── Verify + E2E as parallel sub-agents (if both in workflow)
+│   ├── then Validate (if in workflow)
+│   └── writes: ### Test: Final
+│
+├── Agent: Review (runs only Review steps from Workflow)
+│   ├── reads: ### Plan: Final, ### Build: Final, ### Test: Final, ## Criteria
+│   ├── Self-Review, Security, Performance, Compliance as parallel sub-agents (whichever are in workflow)
+│   ├── then Handoff
+│   └── writes: ### Review: Final
+│
+├── Agent: Deploy (if in workflow)
+│   ├── reads: ### Review: Final, ### Build: Final
+│   └── writes: ### Deploy: Final
+│
+└── Agent: Wrap-up
+    ├── reads: full state.md
+    └── writes: summary + archive
+```
+
+### Agent Spawn Rules
+
+| Phase | Agent type | What it reads from state.md |
+|-------|-----------|----------------------------|
+| Plan | Single agent | `## Description`, `## Criteria`, codebase |
+| Build | Single agent | `### Plan: Final`, `## Criteria` |
+| Test: Verify | Sub-agent (parallel) | `### Build: Final`, `## Criteria` |
+| Test: E2E | Sub-agent (parallel) | `### Build: Final`, `### Plan: Final` |
+| Test: Validate | Sequential after above | `### Test: Verify`, `### Test: E2E`, `## Criteria` |
+| Review: Self-Review | Sub-agent (parallel) | `### Build: Final`, git diff |
+| Review: Security | Sub-agent (parallel) | `### Build: Final`, git diff |
+| Review: Performance | Sub-agent (parallel) | `### Build: Final`, git diff |
+| Review: Compliance | Sub-agent (parallel) | `### Plan: Final`, `### Build: Final`, git diff |
+| Review: Handoff | Sequential after above | All `### Review:` sections, `### Test: Final`, `## Criteria` |
+| Deploy | Single agent | `### Review: Final`, `### Build: Final` |
+| Wrap-up | Single agent | Full state.md |
+
+### Phase Handoff via Final Sections
+
+Each phase writes a `### <Phase>: Final` section — a self-contained summary. The next agent reads **only** the Final sections it needs.
+
+If a phase has fewer sub-stages in the workflow, the Final section still covers the same output — just with less detail where sub-stages were skipped.
+
+## Execution Loop
+
+The CLI manages all state transitions, prerequisites, and loopbacks. Follow this loop:
+
+1. Run `npx work-kit-cli next` to get the next action
+2. Parse the JSON response
+3. Follow the action type:
+   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. After the agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
+   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. Wait for all to complete. Then spawn `thenSequential` if provided. After all complete: `npx work-kit-cli complete <onComplete target>`
+   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `npx work-kit-cli next` again.
+   - **`loopback`**: Report the loopback to the user, then run `npx work-kit-cli next` to continue from the target.
+   - **`complete`**: Done — run wrap-up if not already done.
+   - **`error`**: Report the error and suggestion to the user. Stop.
+4. After each agent completes: `npx work-kit-cli complete <phase>/<sub-stage> --outcome <outcome>`
+5. Then `npx work-kit-cli next` again to continue
+
+## Loop-Back Rules
+
+Loop-backs only apply if the relevant step is in the workflow:
+
+- **Plan Audit** → "revise" → re-run Blueprint
+- **Build Refactor** → "broken" → re-run Core
+- **Review Handoff** → "changes_requested" → re-run Build (from Core)
+- **Deploy Merge** → "fix_needed" → re-run Build (from Core)
+- **Deploy Remediate** → "fix_and_redeploy" → re-run Build (from Core)
+
+On loop-back: uncheck the target step and any steps after it that need re-running. Add a `## Loop-back context` section to state.md with what needs to change and why.
+
+## Completion
+
+When all steps in `## Workflow` are checked:
+
+Run **Wrap-up** — read `.claude/skills/wrap-up.md` and follow its instructions. It handles writing the work-kit summary, committing it, and cleaning up the worktree.
+
+## Important
+
+- **Always work inside the worktree directory** — `cd worktrees/<slug>` before running any commands
+- **Commit state after each phase boundary** — `git add .work-kit/ && git commit -m "work-kit: complete <phase>"`
+- **Human stays in control** — stop between phases, don't auto-proceed
+- **One feature per session** — each session handles a single feature. To work on multiple features in parallel, use separate terminal sessions