@abdullahsahmad/work-kit 0.1.0

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,49 @@
+{
+  "name": "@abdullahsahmad/work-kit",
+  "version": "0.1.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"
+  },
+  "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,214 @@
+---
+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 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**             | optional| optional     | optional | optional| optional      |
+| **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
+
+### 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 init --mode auto --description "<description>" --classification <classification>
+   ```
+2. Show the workflow to the user: `npx work-kit workflow`
+3. User can adjust: `npx work-kit workflow --add review/security` or `npx work-kit 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 status` to see current state
+3. Run `npx work-kit 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 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 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 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 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 next` again.
+   - **`loopback`**: Report the loopback to the user, then run `npx work-kit 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 complete <phase>/<sub-stage> --outcome <outcome>`
+5. Then `npx work-kit 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

package/skills/build/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: build
+description: "Run the Build phase — 8 sub-stages from Setup to Commit. Follows the Blueprint from Plan."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Lead Developer**. Execute the implementation plan from the Blueprint precisely.
+
+## Sub-stages (in order)
+
+1. **Setup** — Create branch, install deps, scaffold
+2. **Migration** — Database schema changes
+3. **Red** — Write failing tests first (TDD red phase)
+4. **Core** — Make tests pass — service layer, API, business logic (TDD green phase)
+5. **UI** — Components, pages, interactions
+6. **Refactor** — Improve code quality, keep tests green (TDD refactor phase)
+7. **Integration** — Wire everything together, verify full data flow
+8. **Commit** — Clean commits, push branch, create PR
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/build/stages/setup.md`)
+2. Reference the Blueprint in `.work-kit/state.md` — follow its steps for this layer
+3. Write actual code, run actual commands
+4. Update `.work-kit/state.md` with outputs
+5. Proceed to the next sub-stage
+
+## Key Principle
+
+**Follow the Blueprint.** The Plan phase already decided what to build and how. Your job is execution, not redesign. If you discover the Blueprint is wrong, note it and adapt minimally — don't redesign mid-build.
+
+## Recording
+
+Throughout every sub-stage, capture three things in the shared state.md sections:
+
+- **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
+- **`## Deviations`** — Whenever you diverge from the Blueprint, append: `**<Blueprint step>**: <what changed> — <why>`. Every deviation needs a reason.
+
+These feed into the final work-kit log summary. If you don't record them here, they're lost.
+
+## Loop-back
+
+If **Refactor** returns "broken" (tests failing after refactor):
+- Revert the refactoring that broke tests
+- Go back to **Core** to fix
+- Re-run **Refactor**
+- Max 2 loops, then proceed with tests passing (skip further refactoring)
+
+## Context Input
+
+This phase runs as a **fresh agent**. Read only these sections from `.work-kit/state.md`:
+- `### Plan: Final` — the Blueprint, Architecture, Scope, and Constraints
+- `## Criteria` — what "done" looks like
+- `## Description` — original request for context
+
+Do NOT read the Plan sub-stage working notes (Clarify, Investigate, Sketch, etc.) — they're consumed by Plan: Final.
+
+## Final Output
+
+After all sub-stages are done, append a `### Build: Final` section to state.md. This is the **only section the Test agent reads**.
+
+```markdown
+### Build: Final
+
+**PR:** #<number> — <title>
+**PR URL:** <url>
+**Branch:** feature/<slug>
+
+**What was built:**
+- <file>: <what was implemented>
+- ...
+
+**Test status:**
+- New tests: <count> (all passing)
+- Existing tests: all passing | <failures>
+
+**Deviations from Blueprint:**
+- <deviation and why — or "None">
+
+**Known issues:**
+- <anything the Test/Review agents should watch for — or "None">
+```
+
+Then:
+- Update state: `**Phase:** build (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete build"`

package/skills/build/stages/commit.md

@@ -0,0 +1,43 @@
+---
+description: "Build sub-stage: Create clean commits, push branch, create PR."
+---
+
+# Commit
+
+**Role:** Release Preparer
+**Goal:** Clean git history, push, and open a PR.
+
+## Instructions
+
+1. Review all changes with `git diff` and `git status`
+2. Stage changes in logical groups — don't dump everything in one commit
+3. Write clear commit messages:
+   - First line: imperative, under 72 chars (e.g., "Add avatar upload service and API endpoint")
+   - Body: explain what and why, not how
+4. Push the feature branch
+5. Create a pull request:
+   - Title: concise summary of the feature
+   - Body: description, what changed, how to test
+6. Record the PR URL
+
+## Output (append to state.md)
+
+```markdown
+### Build: Commit
+
+**Commits:**
+- `<hash>` — <message summary>
+- ...
+
+**Branch Pushed:** feature/<slug>
+**PR:** #<number> — <title>
+**PR URL:** <url>
+```
+
+## Rules
+
+- Don't include `.work-kit/` state files in the PR commits — commit those separately
+- Don't include unrelated changes
+- If there are secrets or env files staged, remove them
+- Prefer multiple focused commits over one giant commit
+- PR description should be useful to a reviewer — not a wall of text