@abdullahsahmad/work-kit 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# work-kit
+
+Structured development workflow for [Claude Code](https://claude.com/claude-code). Two modes, 6 phases, 27 sub-stages — orchestrated by a TypeScript CLI with reusable skill files.
+
+## Installation
+
+**One-step setup** (recommended):
+
+```bash
+npx work-kit setup
+```
+
+This auto-detects Claude Code projects in your workspace and installs the skill files. If multiple projects are found, it lists them for you to choose.
+
+**Global install**:
+
+```bash
+npm install -g work-kit
+```
+
+## Quick start
+
+```bash
+# 1. Set up work-kit in your project
+npx work-kit setup
+
+# 2. In Claude Code, start a workflow
+/full-kit add user avatar upload    # strict, all phases
+/auto-kit fix login redirect bug    # dynamic, only needed stages
+```
+
+## Modes
+
+### `/full-kit <description>`
+
+Runs every phase and sub-stage in strict order. No shortcuts.
+
+Best for: large features, new systems, maximum rigor.
+
+### `/auto-kit <description>`
+
+Classifies the request (bug-fix, small-change, refactor, feature, large-feature) and builds a dynamic workflow with only the sub-stages needed.
+
+Best for: bug fixes, small changes, refactors, well-understood tasks.
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `init <description>` | Initialize a new workflow with a task description |
+| `next` | Advance to the next sub-stage |
+| `complete` | Mark the current sub-stage as complete |
+| `status` | Show current workflow state (phase, sub-stage, progress) |
+| `context` | Generate context summary for the current phase |
+| `validate` | Validate state integrity and phase prerequisites |
+| `loopback` | Route back to a previous stage (max 2 per route) |
+| `workflow` | Display the full workflow plan |
+| `doctor` | Run environment health checks (supports `--json`) |
+| `setup` | Install work-kit skills into a Claude Code project |
+
+## Phases
+
+| Phase | Sub-stages | Agent |
+|-------|-----------|-------|
+| **Plan** | Clarify, Investigate, Sketch, Scope, UX Flow, Architecture, Blueprint, Audit | Single |
+| **Build** | Setup, Migration, Red, Core, UI, Refactor, Integration, Commit | Single |
+| **Test** | Verify, E2E, Validate | Verify + E2E parallel, then Validate |
+| **Review** | Self-Review, Security, Performance, Compliance, Handoff | 4 parallel reviewers, then Handoff |
+| **Deploy** | Merge, Monitor, Remediate | Single (optional) |
+| **Wrap-up** | Summary + Archive | Single |
+
+## Architecture
+
+### Context management
+
+Each phase runs as a **fresh agent**. The Build agent doesn't carry Plan's investigation notes — no context bloat.
+
+Phases communicate through **Final sections** in `.work-kit/state.md`. Each phase writes a `### <Phase>: Final` section that the next phase reads.
+
+### State management
+
+Dual state files in `.work-kit/`:
+
+- **state.json** — state machine (current phase, sub-stage, transitions, loop-back counts)
+- **state.md** — content (working notes, Final sections, accumulated context)
+
+All writes are atomic to prevent state corruption.
+
+### Parallel agents
+
+- **Test phase**: Verify and E2E run in parallel, then Validate runs sequentially
+- **Review phase**: Self-Review, Security, Performance, and Compliance run as 4 parallel reviewers, then Handoff runs sequentially
+
+### Loop-back routing
+
+Any stage can route back to a previous stage. Each route is enforced with a max count of 2 to prevent infinite loops.
+
+### Validation
+
+- **full-kit**: phase-level prerequisites (Plan before Build before Test...)
+- **auto-kit**: step-level validation against the `## Workflow` checklist
+- Both modes refuse to skip ahead
+
+### Output
+
+```
+.claude/work-kit/
+  2026-04-03-avatar-upload.md        # distilled summary
+  archive/
+    2026-04-03-avatar-upload.md      # full state.md copy
+  index.md                           # log of all completed work
+```
+
+## Repo structure
+
+```
+work-kit/
+  cli/
+    src/
+      commands/       # CLI command implementations
+      config/         # Configuration and defaults
+      context/        # Context generation for phases
+      engine/         # Workflow engine and transitions
+      state/          # State machine and file management
+      index.ts        # Entry point
+  skills/
+    full-kit/SKILL.md   # /full-kit orchestrator
+    auto-kit/SKILL.md   # /auto-kit orchestrator
+    plan/SKILL.md       # Plan phase runner
+    plan/stages/        # 8 stage files
+    build/SKILL.md      # Build phase runner
+    build/stages/       # 8 stage files
+    test/SKILL.md       # Test phase runner
+    test/stages/        # 3 stage files
+    review/SKILL.md     # Review phase runner
+    review/stages/      # 5 stage files
+    deploy/SKILL.md     # Deploy phase runner
+    deploy/stages/      # 3 stage files
+    wrap-up/SKILL.md    # Final summary + cleanup
+  package.json
+```
+
+## Requirements
+
+- Node.js >= 18
+- Git
+- [Claude Code](https://claude.com/claude-code)

package/cli/bin/work-kit.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const entry = resolve(__dirname, "..", "src", "index.ts");
+
+try {
+  execFileSync(
+    process.execPath,
+    ["--import", "tsx", entry, ...process.argv.slice(2)],
+    { stdio: "inherit" }
+  );
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/cli/src/commands/complete.ts

@@ -0,0 +1,123 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import { isPhaseComplete } from "../engine/transitions.js";
+import { checkLoopback } from "../engine/loopbacks.js";
+import { PHASE_ORDER } from "../config/phases.js";
+import { parseLocation, resetToLocation } from "../state/helpers.js";
+import type { Action, PhaseName } from "../state/schema.js";
+
+export function completeCommand(target: string, outcome?: string, 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);
+  const { phase, subStage } = parseLocation(target);
+
+  // Validate phase exists
+  if (!state.phases[phase]) {
+    return { action: "error", message: `Unknown phase: ${phase}` };
+  }
+
+  // Validate sub-stage exists
+  const ssState = state.phases[phase].subStages[subStage];
+  if (!ssState) {
+    return { action: "error", message: `Unknown sub-stage: ${phase}/${subStage}` };
+  }
+
+  // Validate sub-stage is in a completable state
+  if (ssState.status === "completed") {
+    return { action: "error", message: `${phase}/${subStage} is already completed.` };
+  }
+  if (ssState.status === "skipped") {
+    return { action: "error", message: `${phase}/${subStage} is skipped and cannot be completed. Add it to the workflow first.` };
+  }
+
+  // Mark sub-stage complete
+  ssState.status = "completed";
+  ssState.completedAt = new Date().toISOString();
+  if (outcome) {
+    ssState.outcome = outcome;
+  }
+
+  // Check for loop-back triggers
+  const loopback = checkLoopback(phase, subStage, outcome);
+  if (loopback) {
+    // Enforce max 2 loopbacks per route
+    const sameRouteCount = state.loopbacks.filter(
+      (lb) => lb.from.phase === phase && lb.from.subStage === subStage
+        && lb.to.phase === loopback.to.phase && lb.to.subStage === loopback.to.subStage
+    ).length;
+
+    if (sameRouteCount >= 2) {
+      // Max reached — proceed without looping back, note the caveat
+      writeState(root, state);
+      return {
+        action: "wait_for_user",
+        message: `${phase}/${subStage} triggered loopback (outcome: ${outcome}) but max loopback count (2) reached for this route. Proceeding with noted caveats.`,
+      };
+    }
+
+    state.loopbacks.push({
+      from: { phase, subStage },
+      to: loopback.to,
+      reason: loopback.reason,
+      timestamp: new Date().toISOString(),
+    });
+
+    resetToLocation(state, loopback.to);
+    state.currentPhase = loopback.to.phase;
+    state.currentSubStage = loopback.to.subStage;
+
+    writeState(root, state);
+
+    return {
+      action: "loopback",
+      from: { phase, subStage },
+      to: loopback.to,
+      reason: loopback.reason,
+    };
+  }
+
+  // Check if the phase is now complete
+  if (isPhaseComplete(state, phase)) {
+    state.phases[phase].status = "completed";
+    state.phases[phase].completedAt = new Date().toISOString();
+
+    // Find next phase
+    const phaseIdx = PHASE_ORDER.indexOf(phase);
+    const nextPhases = PHASE_ORDER.slice(phaseIdx + 1);
+    let nextPhase: PhaseName | null = null;
+
+    for (const np of nextPhases) {
+      if (state.phases[np].status !== "skipped") {
+        nextPhase = np;
+        break;
+      }
+    }
+
+    if (!nextPhase) {
+      state.status = "completed";
+      state.currentPhase = null;
+      state.currentSubStage = null;
+      writeState(root, state);
+      return { action: "complete", message: "All phases complete. Work-kit finished." };
+    }
+
+    state.currentPhase = null;
+    state.currentSubStage = null;
+    writeState(root, state);
+
+    return {
+      action: "wait_for_user",
+      message: `${phase} phase complete. Ready to start ${nextPhase}. Proceed?`,
+    };
+  }
+
+  writeState(root, state);
+
+  return {
+    action: "wait_for_user",
+    message: `${phase}/${subStage} complete${outcome ? ` (outcome: ${outcome})` : ""}. Run \`npx work-kit next\` to continue.`,
+  };
+}

package/cli/src/commands/completions.ts

@@ -0,0 +1,137 @@
+const BASH_COMPLETIONS = `\
+_work_kit_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="init next complete status context validate loopback workflow doctor setup upgrade completions"
+
+  if [ \$COMP_CWORD -eq 1 ]; then
+    COMPREPLY=(\$(compgen -W "\$commands" -- "\$cur"))
+    return
+  fi
+
+  local cmd="\${COMP_WORDS[1]}"
+  case "\$cmd" in
+    complete|context|validate)
+      local phases="plan/clarify plan/investigate plan/sketch plan/scope plan/ux-flow plan/architecture plan/blueprint plan/audit build/setup build/migration build/red build/core build/ui build/refactor build/integration build/commit test/verify test/e2e test/validate review/self-review review/security review/performance review/compliance review/handoff deploy/merge deploy/monitor deploy/remediate"
+      COMPREPLY=(\$(compgen -W "\$phases" -- "\$cur"))
+      ;;
+    init)
+      COMPREPLY=(\$(compgen -W "--mode --description --classification --worktree-root" -- "\$cur"))
+      ;;
+    completions)
+      COMPREPLY=(\$(compgen -W "bash zsh fish" -- "\$cur"))
+      ;;
+  esac
+}
+complete -F _work_kit_completions work-kit`;
+
+const ZSH_COMPLETIONS = `\
+#compdef work-kit
+
+_work_kit() {
+  local -a commands phases init_opts shells
+
+  commands=(
+    'init:Create worktree and initialize state'
+    'next:Get the next action to perform'
+    'complete:Mark a phase/sub-stage as complete'
+    'status:Show current state summary'
+    'context:Extract Final sections needed for a phase agent'
+    'validate:Check prerequisites for a phase'
+    'loopback:Register a loop-back transition'
+    'workflow:Manage auto-kit dynamic workflow'
+    'doctor:Check CLI installation and environment health'
+    'setup:Install work-kit skills into a project'
+    'upgrade:Upgrade work-kit'
+    'completions:Output shell completions'
+  )
+
+  phases=(
+    'plan/clarify' 'plan/investigate' 'plan/sketch' 'plan/scope'
+    'plan/ux-flow' 'plan/architecture' 'plan/blueprint' 'plan/audit'
+    'build/setup' 'build/migration' 'build/red' 'build/core'
+    'build/ui' 'build/refactor' 'build/integration' 'build/commit'
+    'test/verify' 'test/e2e' 'test/validate'
+    'review/self-review' 'review/security' 'review/performance'
+    'review/compliance' 'review/handoff'
+    'deploy/merge' 'deploy/monitor' 'deploy/remediate'
+  )
+
+  init_opts=(
+    '--mode[Workflow mode]:mode:(full auto)'
+    '--description[Description of the work]:text:'
+    '--classification[Work classification]:type:(bug-fix small-change refactor feature large-feature)'
+    '--worktree-root[Override worktree root directory]:path:_files -/'
+  )
+
+  shells=(bash zsh fish)
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'work-kit command' commands
+    return
+  fi
+
+  case \$words[2] in
+    complete|context|validate)
+      _describe -t phases 'phase' phases
+      ;;
+    init)
+      _arguments \$init_opts
+      ;;
+    completions)
+      _describe -t shells 'shell' shells
+      ;;
+  esac
+}
+
+compdef _work_kit work-kit`;
+
+const FISH_COMPLETIONS = `\
+# Disable file completions by default
+complete -c work-kit -f
+
+# Top-level commands
+complete -c work-kit -n '__fish_use_subcommand' -a 'init' -d 'Create worktree and initialize state'
+complete -c work-kit -n '__fish_use_subcommand' -a 'next' -d 'Get the next action to perform'
+complete -c work-kit -n '__fish_use_subcommand' -a 'complete' -d 'Mark a phase/sub-stage as complete'
+complete -c work-kit -n '__fish_use_subcommand' -a 'status' -d 'Show current state summary'
+complete -c work-kit -n '__fish_use_subcommand' -a 'context' -d 'Extract Final sections needed for a phase agent'
+complete -c work-kit -n '__fish_use_subcommand' -a 'validate' -d 'Check prerequisites for a phase'
+complete -c work-kit -n '__fish_use_subcommand' -a 'loopback' -d 'Register a loop-back transition'
+complete -c work-kit -n '__fish_use_subcommand' -a 'workflow' -d 'Manage auto-kit dynamic workflow'
+complete -c work-kit -n '__fish_use_subcommand' -a 'doctor' -d 'Check CLI installation and environment health'
+complete -c work-kit -n '__fish_use_subcommand' -a 'setup' -d 'Install work-kit skills into a project'
+complete -c work-kit -n '__fish_use_subcommand' -a 'upgrade' -d 'Upgrade work-kit'
+complete -c work-kit -n '__fish_use_subcommand' -a 'completions' -d 'Output shell completions'
+
+# Phase completions for complete, context, validate
+set -l phase_cmds 'complete context validate'
+set -l phases 'plan/clarify' 'plan/investigate' 'plan/sketch' 'plan/scope' 'plan/ux-flow' 'plan/architecture' 'plan/blueprint' 'plan/audit' 'build/setup' 'build/migration' 'build/red' 'build/core' 'build/ui' 'build/refactor' 'build/integration' 'build/commit' 'test/verify' 'test/e2e' 'test/validate' 'review/self-review' 'review/security' 'review/performance' 'review/compliance' 'review/handoff' 'deploy/merge' 'deploy/monitor' 'deploy/remediate'
+for phase in \$phases
+  complete -c work-kit -n "__fish_seen_subcommand_from \$phase_cmds" -a "\$phase"
+end
+
+# init options
+complete -c work-kit -n '__fish_seen_subcommand_from init' -l mode -d 'Workflow mode' -ra 'full auto'
+complete -c work-kit -n '__fish_seen_subcommand_from init' -l description -d 'Description of the work'
+complete -c work-kit -n '__fish_seen_subcommand_from init' -l classification -d 'Work classification' -ra 'bug-fix small-change refactor feature large-feature'
+complete -c work-kit -n '__fish_seen_subcommand_from init' -l worktree-root -d 'Override worktree root directory'
+
+# completions subcommand
+complete -c work-kit -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'`;
+
+export function completionsCommand(shell: string): void {
+  switch (shell) {
+    case "bash":
+      console.log(BASH_COMPLETIONS);
+      break;
+    case "zsh":
+      console.log(ZSH_COMPLETIONS);
+      break;
+    case "fish":
+      console.log(FISH_COMPLETIONS);
+      break;
+    default:
+      console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+      process.exit(1);
+  }
+}

package/cli/src/commands/context.ts

@@ -0,0 +1,41 @@
+import { readState, readStateMd, findWorktreeRoot } from "../state/store.js";
+import { getContextFor } from "../config/agent-map.js";
+import { extractSection, extractTopSection } from "../context/extractor.js";
+import type { PhaseName } from "../state/schema.js";
+
+interface ContextResult {
+  phase: PhaseName;
+  sections: Record<string, string | null>;
+  needsGitDiff: boolean;
+}
+
+export function contextCommand(phase: PhaseName, worktreeRoot?: string): ContextResult {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    throw new Error("No work-kit state found. Run `work-kit init` first.");
+  }
+
+  const state = readState(root);
+  const stateMd = readStateMd(root);
+
+  if (!stateMd) {
+    throw new Error("No state.md found.");
+  }
+
+  const ctx = getContextFor(phase);
+  const sections: Record<string, string | null> = {};
+
+  for (const sectionName of ctx.sections) {
+    if (sectionName.startsWith("### ")) {
+      sections[sectionName] = extractSection(stateMd, sectionName);
+    } else {
+      sections[sectionName] = extractTopSection(stateMd, sectionName);
+    }
+  }
+
+  return {
+    phase,
+    sections,
+    needsGitDiff: !!ctx.needsGitDiff,
+  };
+}

package/cli/src/commands/doctor.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { findWorktreeRoot, readState } from "../state/store.js";
+
+interface Check {
+  name: string;
+  status: "pass" | "fail" | "warn";
+  message: string;
+}
+
+export function doctorCommand(worktreeRoot?: string): { ok: boolean; checks: Check[] } {
+  const checks: Check[] = [];
+
+  // 1. Node.js version
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1), 10);
+  if (major >= 18) {
+    checks.push({ name: "node", status: "pass", message: `Node.js ${nodeVersion}` });
+  } else {
+    checks.push({ name: "node", status: "fail", message: `Node.js ${nodeVersion} — requires >= 18` });
+  }
+
+  // 2. Skills installed
+  const cwd = worktreeRoot || process.cwd();
+  const skillsDir = path.join(cwd, ".claude", "skills");
+  const requiredSkills = ["full-kit", "auto-kit"];
+  for (const skill of requiredSkills) {
+    const skillPath = path.join(skillsDir, skill, "SKILL.md");
+    if (fs.existsSync(skillPath)) {
+      checks.push({ name: `skill:${skill}`, status: "pass", message: `${skill}/SKILL.md found` });
+    } else {
+      checks.push({ name: `skill:${skill}`, status: "fail", message: `${skill}/SKILL.md not found at ${skillPath}` });
+    }
+  }
+
+  // 3. Phase skill files
+  const phases = ["plan", "build", "test", "review", "deploy", "wrap-up"];
+  let phasesMissing = 0;
+  for (const phase of phases) {
+    const phasePath = path.join(skillsDir, phase, "SKILL.md");
+    if (!fs.existsSync(phasePath)) {
+      phasesMissing++;
+    }
+  }
+  if (phasesMissing === 0) {
+    checks.push({ name: "skill:phases", status: "pass", message: `All ${phases.length} phase skills found` });
+  } else {
+    checks.push({ name: "skill:phases", status: "fail", message: `${phasesMissing} phase skill(s) missing from ${skillsDir}` });
+  }
+
+  // 4. Git available
+  try {
+    const gitVersion = execFileSync("git", ["--version"], { encoding: "utf-8" }).trim();
+    checks.push({ name: "git", status: "pass", message: gitVersion });
+  } catch {
+    checks.push({ name: "git", status: "fail", message: "git not found in PATH" });
+  }
+
+  // 5. State file health (if in a worktree)
+  const root = worktreeRoot ? worktreeRoot : findWorktreeRoot();
+  if (root) {
+    try {
+      const state = readState(root);
+      if (state.version === 1 && state.slug && state.status) {
+        checks.push({ name: "state", status: "pass", message: `Active work-kit: "${state.slug}" (${state.status})` });
+      } else {
+        checks.push({ name: "state", status: "warn", message: "state.json exists but has unexpected structure" });
+      }
+    } catch (e: any) {
+      checks.push({ name: "state", status: "warn", message: `state.json error: ${e.message}` });
+    }
+  } else {
+    checks.push({ name: "state", status: "pass", message: "No active worktree (OK — run `work-kit init` to start)" });
+  }
+
+  const ok = checks.every((c) => c.status !== "fail");
+  return { ok, checks };
+}

package/cli/src/commands/init.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { initCommand } from "./init.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+});
+
+describe("initCommand", () => {
+  it("creates state.json and state.md", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Add user login",
+      worktreeRoot: tmp,
+    });
+
+    assert.ok(fs.existsSync(path.join(tmp, ".work-kit", "state.json")));
+    assert.ok(fs.existsSync(path.join(tmp, ".work-kit", "state.md")));
+
+    const state = JSON.parse(
+      fs.readFileSync(path.join(tmp, ".work-kit", "state.json"), "utf-8")
+    );
+    assert.equal(state.slug, "add-user-login");
+    assert.equal(state.status, "in-progress");
+    assert.equal(state.currentPhase, "plan");
+  });
+
+  it("returns spawn_agent action", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    const result = initCommand({
+      mode: "full",
+      description: "Add user login",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(result.action, "spawn_agent");
+  });
+
+  it("blocks double init", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "First init",
+      worktreeRoot: tmp,
+    });
+
+    const result = initCommand({
+      mode: "full",
+      description: "Second init",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("already exists"));
+    }
+  });
+
+  it("auto mode requires classification", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    const result = initCommand({
+      mode: "auto",
+      description: "Some task",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("classification"));
+    }
+  });
+
+  it("auto mode with classification succeeds", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    const result = initCommand({
+      mode: "auto",
+      description: "Fix login bug",
+      classification: "bug-fix",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(result.action, "spawn_agent");
+
+    const state = JSON.parse(
+      fs.readFileSync(path.join(tmp, ".work-kit", "state.json"), "utf-8")
+    );
+    assert.equal(state.mode, "auto-kit");
+    assert.equal(state.classification, "bug-fix");
+  });
+});