@abdullahsahmad/work-kit 0.1.0

package/cli/src/commands/setup.ts

@@ -0,0 +1,159 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { doctorCommand } from "./doctor.js";
+import { bold, dim, green, yellow, red, cyan } from "../utils/colors.js";
+
+const SKILLS_SOURCE = path.resolve(import.meta.dirname, "..", "..", "..", "skills");
+
+function findClaudeProjects(): { name: string; path: string }[] {
+  const claudeDir = path.join(process.env.HOME || process.env.USERPROFILE || "", ".claude", "projects");
+  if (!fs.existsSync(claudeDir)) return [];
+
+  const entries = fs.readdirSync(claudeDir, { withFileTypes: true });
+  const projects: { name: string; path: string }[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    // Convert directory name back to filesystem path: -home-user-project → /home/user/project
+    const projectPath = entry.name.replace(/^-/, "/").replace(/-/g, "/");
+    if (fs.existsSync(projectPath)) {
+      projects.push({ name: path.basename(projectPath), path: projectPath });
+    }
+  }
+
+  return projects.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function isClaudeProject(dir: string): boolean {
+  return fs.existsSync(path.join(dir, ".claude"));
+}
+
+function copySkills(targetDir: string): { copied: string[]; skipped: string[] } {
+  const skillsTarget = path.join(targetDir, ".claude", "skills");
+  const copied: string[] = [];
+  const skipped: string[] = [];
+
+  if (!fs.existsSync(SKILLS_SOURCE)) {
+    throw new Error(`Skills source not found at ${SKILLS_SOURCE}. Is work-kit installed correctly?`);
+  }
+
+  function copyDir(src: string, dest: string, prefix: string = "") {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      const label = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath, label);
+      } else {
+        if (fs.existsSync(destPath)) {
+          const srcContent = fs.readFileSync(srcPath, "utf-8");
+          const destContent = fs.readFileSync(destPath, "utf-8");
+          if (srcContent === destContent) {
+            skipped.push(label);
+            continue;
+          }
+        }
+        fs.copyFileSync(srcPath, destPath);
+        copied.push(label);
+      }
+    }
+  }
+
+  copyDir(SKILLS_SOURCE, skillsTarget);
+  return { copied, skipped };
+}
+
+async function promptUser(question: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function setupCommand(targetPath?: string): Promise<void> {
+  let projectDir: string;
+
+  if (targetPath) {
+    // Explicit path provided
+    projectDir = path.resolve(targetPath);
+    if (!fs.existsSync(projectDir)) {
+      console.error(`Directory not found: ${projectDir}`);
+      process.exit(1);
+    }
+  } else if (isClaudeProject(process.cwd())) {
+    // Current directory is a Claude project
+    projectDir = process.cwd();
+    console.error(`Installing to current project: ${bold(projectDir)}`);
+  } else {
+    // Discover Claude projects and let user pick
+    const projects = findClaudeProjects();
+
+    if (projects.length === 0) {
+      console.error("No Claude Code projects found on this machine.");
+      const manual = await promptUser("Enter project path: ");
+      if (!manual || !fs.existsSync(manual)) {
+        console.error("Invalid path. Exiting.");
+        process.exit(1);
+      }
+      projectDir = path.resolve(manual);
+    } else {
+      console.error("Found Claude Code projects:\n");
+      for (let i = 0; i < projects.length; i++) {
+        console.error(`  ${cyan(String(i + 1))}. ${projects[i].path}`);
+      }
+      console.error();
+
+      const answer = await promptUser("Install work-kit skills to (number or path): ");
+      const idx = parseInt(answer, 10);
+
+      if (!isNaN(idx) && idx >= 1 && idx <= projects.length) {
+        projectDir = projects[idx - 1].path;
+      } else if (fs.existsSync(answer)) {
+        projectDir = path.resolve(answer);
+      } else {
+        console.error("Invalid selection. Exiting.");
+        process.exit(1);
+      }
+    }
+  }
+
+  // Copy skills
+  console.error(`\nCopying skills to ${projectDir}/.claude/skills/...`);
+  const { copied, skipped } = copySkills(projectDir);
+
+  if (copied.length > 0) {
+    for (const f of copied) {
+      console.error(`  ${green("+")} ${f}`);
+    }
+  }
+  if (skipped.length > 0) {
+    console.error(`  (${skipped.length} files unchanged)`);
+  }
+  if (copied.length === 0 && skipped.length > 0) {
+    console.error(`  ${dim("Already up to date.")}`);
+  }
+
+  // Run doctor against the target project
+  console.error("\nRunning doctor...");
+  const result = doctorCommand(projectDir);
+  for (const check of result.checks) {
+    const icon = check.status === "pass" ? green("\u2713") : check.status === "warn" ? yellow("!") : red("\u2717");
+    console.error(`  ${icon} ${bold(check.name)}: ${check.message}`);
+  }
+
+  console.error();
+  if (result.ok) {
+    console.error(green(bold("Ready. Use /full-kit or /auto-kit in Claude Code.")));
+  } else {
+    console.error(red("Setup complete but some checks failed. Review the issues above."));
+  }
+}

package/cli/src/commands/status.ts

@@ -0,0 +1,50 @@
+import { PHASE_NAMES } from "../state/schema.js";
+import { readState, findWorktreeRoot } from "../state/store.js";
+
+interface StatusOutput {
+  slug: string;
+  branch: string;
+  mode: string;
+  classification?: string;
+  status: string;
+  currentPhase: string | null;
+  currentSubStage: string | null;
+  started: string;
+  phases: Record<string, { status: string; completed: number; total: number; active: number }>;
+  loopbackCount: number;
+}
+
+export function statusCommand(worktreeRoot?: string): StatusOutput {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    throw new Error("No work-kit state found. Run `work-kit init` first.");
+  }
+
+  const state = readState(root);
+
+  const phases: StatusOutput["phases"] = {};
+  for (const phase of PHASE_NAMES) {
+    const ps = state.phases[phase];
+    let completed = 0, total = 0, active = 0;
+    for (const ss of Object.values(ps.subStages)) {
+      if (ss.status === "skipped") continue;
+      total++;
+      if (ss.status === "completed") completed++;
+      else if (ss.status === "in-progress") active++;
+    }
+    phases[phase] = { status: ps.status, completed, total, active };
+  }
+
+  return {
+    slug: state.slug,
+    branch: state.branch,
+    mode: state.mode,
+    ...(state.classification && { classification: state.classification }),
+    status: state.status,
+    currentPhase: state.currentPhase,
+    currentSubStage: state.currentSubStage,
+    started: state.started,
+    phases,
+    loopbackCount: state.loopbacks.length,
+  };
+}

package/cli/src/commands/uninstall.ts

@@ -0,0 +1,89 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { bold, dim, green, red, yellow } from "../utils/colors.js";
+
+const WORK_KIT_SKILLS = [
+  "full-kit", "auto-kit", "plan", "build", "test", "review", "deploy", "wrap-up",
+];
+
+async function promptUser(question: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function removeDir(dir: string): boolean {
+  if (!fs.existsSync(dir)) return false;
+  fs.rmSync(dir, { recursive: true, force: true });
+  return true;
+}
+
+export async function uninstallCommand(targetPath?: string): Promise<void> {
+  const projectDir = targetPath ? path.resolve(targetPath) : process.cwd();
+  const skillsDir = path.join(projectDir, ".claude", "skills");
+
+  if (!fs.existsSync(skillsDir)) {
+    console.error(red("No .claude/skills/ directory found. Nothing to uninstall."));
+    process.exit(1);
+  }
+
+  // Check which work-kit skills are installed
+  const installed: string[] = [];
+  for (const skill of WORK_KIT_SKILLS) {
+    const skillPath = path.join(skillsDir, skill);
+    if (fs.existsSync(skillPath)) {
+      installed.push(skill);
+    }
+  }
+
+  if (installed.length === 0) {
+    console.error(dim("No work-kit skills found in this project."));
+    return;
+  }
+
+  console.error(`\nFound ${bold(String(installed.length))} work-kit skills in ${bold(projectDir)}:`);
+  for (const skill of installed) {
+    console.error(`  ${skill}/`);
+  }
+
+  // Check for active state
+  const stateFile = path.join(projectDir, ".work-kit", "state.json");
+  if (fs.existsSync(stateFile)) {
+    console.error(yellow("\nWarning: Active work-kit state found (.work-kit/state.json)."));
+    console.error(yellow("Uninstalling will not remove in-progress state files."));
+  }
+
+  const answer = await promptUser("\nRemove all work-kit skills? (y/N): ");
+  if (answer.toLowerCase() !== "y") {
+    console.error(dim("Cancelled."));
+    return;
+  }
+
+  // Remove skill directories
+  let removed = 0;
+  for (const skill of installed) {
+    const skillPath = path.join(skillsDir, skill);
+    if (removeDir(skillPath)) {
+      console.error(`  ${red("-")} ${skill}/`);
+      removed++;
+    }
+  }
+
+  console.error(`\n${green(bold(`Removed ${removed} work-kit skill(s).`))}`);
+
+  // Check if .claude/skills/ is now empty
+  if (fs.existsSync(skillsDir)) {
+    const remaining = fs.readdirSync(skillsDir);
+    if (remaining.length === 0) {
+      fs.rmdirSync(skillsDir);
+      console.error(dim("Removed empty .claude/skills/ directory."));
+    } else {
+      console.error(dim(`${remaining.length} other skill(s) remain in .claude/skills/.`));
+    }
+  }
+}

package/cli/src/commands/upgrade.ts

@@ -0,0 +1,12 @@
+import { setupCommand } from "./setup.js";
+
+export async function upgradeCommand(worktreeRoot?: string): Promise<void> {
+  const target = worktreeRoot || process.cwd();
+  // setupCommand already handles:
+  // - detecting .claude/ in current dir
+  // - copying skills (skipping unchanged)
+  // - running doctor
+  // Just add upgrade-specific messaging
+  console.error("Upgrading work-kit skills to latest version...\n");
+  await setupCommand(target);
+}

package/cli/src/commands/validate.ts

@@ -0,0 +1,34 @@
+import { readState, findWorktreeRoot } from "../state/store.js";
+import { validatePhasePrerequisites } from "../state/validators.js";
+import type { PhaseName } from "../state/schema.js";
+
+interface ValidateResult {
+  phase: PhaseName;
+  valid: boolean;
+  message: string;
+  missingPrerequisite?: PhaseName;
+  phaseStatus: string;
+}
+
+export function validateCommand(phase: PhaseName, worktreeRoot?: string): ValidateResult {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    throw new Error("No work-kit state found. Run `work-kit init` first.");
+  }
+
+  const state = readState(root);
+
+  if (!state.phases[phase]) {
+    throw new Error(`Unknown phase: ${phase}`);
+  }
+
+  const result = validatePhasePrerequisites(state, phase);
+
+  return {
+    phase,
+    valid: result.valid,
+    message: result.message,
+    missingPrerequisite: result.missingPrerequisite,
+    phaseStatus: state.phases[phase].status,
+  };
+}

package/cli/src/commands/workflow.ts

@@ -0,0 +1,125 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import { SUBSTAGES_BY_PHASE, PHASE_NAMES } from "../state/schema.js";
+import { parseLocation } from "../state/helpers.js";
+import type { Action } from "../state/schema.js";
+
+interface WorkflowStatus {
+  action: "workflow_status";
+  workflow: { step: string; status: string }[];
+}
+
+export type WorkflowResult = Action | WorkflowStatus;
+
+export function workflowCommand(opts: {
+  add?: string;
+  remove?: string;
+  worktreeRoot?: string;
+}): WorkflowResult {
+  const root = opts.worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found." };
+  }
+
+  const state = readState(root);
+
+  if (state.mode !== "auto-kit") {
+    return { action: "error", message: "Workflow management is only available in auto-kit mode." };
+  }
+
+  if (!state.workflow) {
+    return { action: "error", message: "No workflow defined in state." };
+  }
+
+  if (opts.add) {
+    const { phase, subStage } = parseLocation(opts.add);
+
+    if (!PHASE_NAMES.includes(phase) || !SUBSTAGES_BY_PHASE[phase].includes(subStage)) {
+      return { action: "error", message: `Invalid step: ${opts.add}` };
+    }
+
+    const existing = state.workflow.find((s) => s.phase === phase && s.subStage === subStage);
+    if (existing) {
+      if (existing.included) {
+        return { action: "error", message: `${opts.add} is already in the workflow.` };
+      }
+      existing.included = true;
+    } else {
+      const phaseIdx = PHASE_NAMES.indexOf(phase);
+      const subStageIdx = SUBSTAGES_BY_PHASE[phase].indexOf(subStage);
+
+      let insertIdx = state.workflow.length;
+      for (let i = 0; i < state.workflow.length; i++) {
+        const wi = state.workflow[i];
+        const wiPhaseIdx = PHASE_NAMES.indexOf(wi.phase);
+        const wiSubIdx = SUBSTAGES_BY_PHASE[wi.phase].indexOf(wi.subStage);
+
+        if (wiPhaseIdx > phaseIdx || (wiPhaseIdx === phaseIdx && wiSubIdx > subStageIdx)) {
+          insertIdx = i;
+          break;
+        }
+      }
+
+      state.workflow.splice(insertIdx, 0, { phase, subStage, included: true });
+    }
+
+    const currentSS = state.phases[phase].subStages[subStage];
+    if (currentSS?.status === "completed") {
+      return { action: "error", message: `Cannot add ${opts.add} — it's already completed.` };
+    }
+    if (!currentSS) {
+      state.phases[phase].subStages[subStage] = { status: "pending" };
+    } else if (currentSS.status === "skipped") {
+      currentSS.status = "pending";
+    }
+
+    if (state.phases[phase].status === "skipped") {
+      state.phases[phase].status = "pending";
+    }
+
+    writeState(root, state);
+    return { action: "wait_for_user", message: `Added ${opts.add} to workflow.` };
+  }
+
+  if (opts.remove) {
+    const { phase, subStage } = parseLocation(opts.remove);
+
+    const step = state.workflow.find((s) => s.phase === phase && s.subStage === subStage);
+    if (!step) {
+      return { action: "error", message: `${opts.remove} is not in the workflow.` };
+    }
+
+    const ssState = state.phases[phase]?.subStages[subStage];
+    if (ssState?.status === "completed") {
+      return { action: "error", message: `Cannot remove ${opts.remove} — it's already completed.` };
+    }
+    if (ssState?.status === "in-progress") {
+      return { action: "error", message: `Cannot remove ${opts.remove} — it's currently in progress.` };
+    }
+
+    step.included = false;
+
+    if (ssState) {
+      ssState.status = "skipped";
+    }
+
+    const allSkipped = Object.values(state.phases[phase].subStages).every(
+      (s) => s.status === "skipped"
+    );
+    if (allSkipped) {
+      state.phases[phase].status = "skipped";
+    }
+
+    writeState(root, state);
+    return { action: "wait_for_user", message: `Removed ${opts.remove} from workflow.` };
+  }
+
+  // No add/remove — show current workflow
+  const workflow = state.workflow
+    .filter((s) => s.included)
+    .map((s) => ({
+      step: `${s.phase}/${s.subStage}`,
+      status: state.phases[s.phase]?.subStages[s.subStage]?.status || "unknown",
+    }));
+
+  return { action: "workflow_status", workflow };
+}

package/cli/src/config/agent-map.ts

@@ -0,0 +1,62 @@
+import { PhaseName } from "../state/schema.js";
+
+/**
+ * Maps each phase/sub-stage to the sections it needs from state.md.
+ * "##" prefix = top-level section, "###" prefix = Final section.
+ */
+
+export interface AgentContext {
+  sections: string[];         // sections to extract from state.md
+  needsGitDiff?: boolean;     // whether the agent needs `git diff main...HEAD`
+}
+
+// Phase-level context (what the phase runner agent reads)
+export const PHASE_CONTEXT: Record<PhaseName, AgentContext> = {
+  plan: {
+    sections: ["## Description", "## Criteria"],
+  },
+  build: {
+    sections: ["### Plan: Final", "## Criteria", "## Description"],
+  },
+  test: {
+    sections: ["### Build: Final", "### Plan: Final", "## Criteria"],
+  },
+  review: {
+    sections: ["### Plan: Final", "### Build: Final", "### Test: Final", "## Criteria"],
+  },
+  deploy: {
+    sections: ["### Review: Final", "### Build: Final", "## Criteria"],
+  },
+  "wrap-up": {
+    sections: [], // reads full state.md
+  },
+};
+
+// Sub-stage-level context (for parallel sub-agents that need specific sections)
+export const SUBSTAGE_CONTEXT: Record<string, AgentContext> = {
+  // Test sub-agents
+  "test/verify": { sections: ["### Build: Final", "## Criteria"] },
+  "test/e2e": { sections: ["### Build: Final", "### Plan: Final"] },
+  "test/validate": { sections: ["### Test: Verify", "### Test: E2E", "## Criteria"] },
+
+  // Review sub-agents
+  "review/self-review": { sections: ["### Build: Final"], needsGitDiff: true },
+  "review/security": { sections: ["### Build: Final"], needsGitDiff: true },
+  "review/performance": { sections: ["### Build: Final"], needsGitDiff: true },
+  "review/compliance": { sections: ["### Plan: Final", "### Build: Final"], needsGitDiff: true },
+  "review/handoff": {
+    sections: [
+      "### Review: Self-Review", "### Review: Security",
+      "### Review: Performance", "### Review: Compliance",
+      "### Test: Final", "## Criteria",
+    ],
+  },
+};
+
+export function getContextFor(phase: PhaseName, subStage?: string): AgentContext {
+  if (subStage) {
+    const key = `${phase}/${subStage}`;
+    if (SUBSTAGE_CONTEXT[key]) return SUBSTAGE_CONTEXT[key];
+  }
+  return PHASE_CONTEXT[phase];
+}

package/cli/src/config/loopback-routes.ts

@@ -0,0 +1,45 @@
+import { PhaseName, Location } from "../state/schema.js";
+
+/**
+ * Defines when a completed sub-stage should trigger a loop-back
+ * based on its outcome.
+ */
+export interface LoopbackRoute {
+  from: Location;
+  triggerOutcome: string;
+  to: Location;
+  reason: string;
+}
+
+export const LOOPBACK_ROUTES: LoopbackRoute[] = [
+  {
+    from: { phase: "plan", subStage: "audit" },
+    triggerOutcome: "revise",
+    to: { phase: "plan", subStage: "blueprint" },
+    reason: "Audit found gaps — revising Blueprint",
+  },
+  {
+    from: { phase: "build", subStage: "refactor" },
+    triggerOutcome: "broken",
+    to: { phase: "build", subStage: "core" },
+    reason: "Refactor broke tests — re-running Core to fix",
+  },
+  {
+    from: { phase: "review", subStage: "handoff" },
+    triggerOutcome: "changes_requested",
+    to: { phase: "build", subStage: "core" },
+    reason: "Review requested changes — looping back to Build/Core",
+  },
+  {
+    from: { phase: "deploy", subStage: "merge" },
+    triggerOutcome: "fix_needed",
+    to: { phase: "build", subStage: "core" },
+    reason: "Merge blocked — fix needed in Build/Core",
+  },
+  {
+    from: { phase: "deploy", subStage: "remediate" },
+    triggerOutcome: "fix_and_redeploy",
+    to: { phase: "build", subStage: "core" },
+    reason: "Deployment issue — fix and redeploy from Build/Core",
+  },
+];