dev-workflow 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cfvargas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# dev-workflow
+
+CLI tool that installs the **Spec Driven Development (SDD)** workflow skill into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) projects.
+
+SDD is a structured development cycle: define **what** you want before writing code, then implement from specifications. Each phase produces a persistent artifact that the next session consumes.
+
+```
+SPEC → PLAN → IMPLEMENT → VERIFY
+```
+
+## Install
+
+```bash
+npm i -g dev-workflow
+```
+
+Requires Node.js >= 18.
+
+## Usage
+
+### Initialize
+
+Install the SDD skill into your Claude Code configuration:
+
+```bash
+dev-workflow init          # global (default)
+dev-workflow init --local  # current project only
+```
+
+### Update
+
+Update the skill files to the latest version:
+
+```bash
+dev-workflow update
+```
+
+### Status
+
+Check where the skill is installed:
+
+```bash
+dev-workflow status
+```
+
+## How it works
+
+Once installed, the `/dev-workflow` slash command becomes available in Claude Code. It guides you through four phases:
+
+1. **SPEC** — Define what the feature does (functional requirements, edge cases, acceptance criteria)
+2. **PLAN** — Translate the spec into ordered tasks with file maps and architecture decisions
+3. **IMPLEMENT** — Build each task iteratively: RED → GREEN → REFACTOR, with user review between tasks
+4. **VERIFY** — Lint, type-check, commit, and open a PR
+
+Each phase can run in a separate session — the artifacts travel, not the context.
+
+## License
+
+MIT

package/bin/dev-workflow.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { init, update } from "../src/init.js";
+import { getInstallations, resolveGlobalDir } from "../src/utils.js";
+import { askInstallScope, formatWarning } from "../src/prompt.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = new Set(args.slice(1));
+const isLocal = flags.has("--local");
+
+if (command === "--version" || command === "-v") {
+  const pkg = JSON.parse(
+    await readFile(path.resolve(__dirname, "../package.json"), "utf-8")
+  );
+  console.log(pkg.version);
+} else if (command === "--help" || command === "-h" || !command) {
+  console.log(`Usage: dev-workflow <command> [options]
+
+Commands:
+  init      Install the SDD workflow skill (global by default)
+  update    Update the skill files to the latest version
+  status    Show where the skill is installed
+
+Options:
+  --local    Install/update in the current project instead of globally
+  --version  Show version number
+  --help     Show this help message`);
+} else if (command === "init") {
+  await handleInit();
+} else if (command === "update") {
+  await handleUpdate();
+} else if (command === "status") {
+  await handleStatus();
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "dev-workflow --help" for usage information.');
+  process.exit(1);
+}
+
+async function handleInit() {
+  const cwd = process.cwd();
+  const installations = await getInstallations(cwd);
+  const scope = isLocal ? "local" : "global";
+
+  if (installations.local && installations.global) {
+    console.log(formatWarning());
+    const chosen = await askInstallScope();
+    if (chosen === "both") {
+      await init(cwd, { scope: "local", confirm: true });
+      await init(cwd, { scope: "global", confirm: true });
+    } else {
+      await init(cwd, { scope: chosen, confirm: true });
+    }
+  } else {
+    await init(cwd, { scope });
+    if (scope === "local" && installations.global) {
+      console.log(formatWarning());
+    }
+  }
+}
+
+async function handleUpdate() {
+  const cwd = process.cwd();
+  const installations = await getInstallations(cwd);
+
+  if (!installations.local && !installations.global) {
+    console.error("No installation found. Run `dev-workflow init` first.");
+    process.exit(1);
+  }
+
+  if (installations.local && installations.global) {
+    console.log(formatWarning());
+    const chosen = await askInstallScope();
+    if (chosen === "both") {
+      await update(cwd, { scope: "local" });
+      await update(cwd, { scope: "global" });
+    } else {
+      await update(cwd, { scope: chosen });
+    }
+  } else if (installations.local) {
+    await update(cwd, { scope: "local" });
+  } else {
+    await update(cwd, { scope: "global" });
+  }
+}
+
+async function handleStatus() {
+  const cwd = process.cwd();
+  const installations = await getInstallations(cwd);
+  const globalDir = resolveGlobalDir();
+  const localDir = path.join(cwd, ".claude/skills/dev-workflow");
+
+  if (!installations.local && !installations.global) {
+    console.log("dev-workflow is not installed.");
+    return;
+  }
+
+  if (installations.local && installations.global) {
+    console.log(`Installations found:`);
+    console.log(`  local:  ${localDir} (active — local takes precedence)`);
+    console.log(`  global: ${globalDir}`);
+  } else if (installations.local) {
+    console.log(`Installed locally (active): ${localDir}`);
+  } else {
+    console.log(`Installed globally (active): ${globalDir}`);
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "dev-workflow",
+  "version": "1.3.0",
+  "description": "CLI tool that installs the Spec Driven Development (SDD) workflow skill into Claude Code projects",
+  "type": "module",
+  "bin": {
+    "dev-workflow": "./bin/dev-workflow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest"
+  },
+  "keywords": [
+    "claude-code",
+    "sdd",
+    "spec-driven-development",
+    "workflow",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cfvargas/dev-workflow.git"
+  },
+  "author": "cfvargas",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  }
+}

package/src/init.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { copyTemplates, resolveGlobalDir } from "./utils.js";
+
+const SKILL_DIR = ".claude/skills/dev-workflow";
+
+function resolveTargetDir(projectDir, scope) {
+  if (scope === "global") return resolveGlobalDir();
+  return path.join(projectDir, SKILL_DIR);
+}
+
+async function exists(targetDir) {
+  try {
+    await fs.access(path.join(targetDir, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function init(projectDir, options = {}) {
+  const scope = options.scope || "local";
+  const targetDir = resolveTargetDir(projectDir, scope);
+  const alreadyExists = await exists(targetDir);
+
+  if (!alreadyExists) {
+    await copyTemplates(targetDir);
+    return;
+  }
+
+  if (options.confirm === true) {
+    await copyTemplates(targetDir);
+  }
+}
+
+export async function update(projectDir, options = {}) {
+  const scope = options?.scope;
+
+  if (scope) {
+    const targetDir = resolveTargetDir(projectDir, scope);
+    const alreadyExists = await exists(targetDir);
+    if (!alreadyExists) {
+      throw new Error(
+        "No installation found. Run `dev-workflow init` first."
+      );
+    }
+    await copyTemplates(targetDir);
+    return;
+  }
+
+  // Legacy behavior: update local
+  const targetDir = path.join(projectDir, SKILL_DIR);
+  await copyTemplates(targetDir);
+}

package/src/prompt.js

@@ -0,0 +1,34 @@
+import readline from "node:readline";
+
+const OPTIONS = {
+  1: "local",
+  2: "global",
+  3: "both",
+};
+
+export function askInstallScope({ input, output } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: input || process.stdin,
+      output: output || process.stdout,
+    });
+
+    const prompt = [
+      "Both local and global installations found.",
+      "  1) local",
+      "  2) global (default)",
+      "  3) both",
+      "Choose [1/2/3]: ",
+    ].join("\n");
+
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      resolve(OPTIONS[trimmed] || "global");
+    });
+  });
+}
+
+export function formatWarning() {
+  return "Warning: local installation takes precedence over global.";
+}

package/src/utils.js

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, "../templates");
+const SKILL_DIR = ".claude/skills/dev-workflow";
+
+const TEMPLATE_FILES = [
+  "SKILL.md",
+  "references/phase-1-spec.md",
+  "references/phase-2-plan.md",
+  "references/phase-3-implement.md",
+  "references/phase-4-verify.md",
+];
+
+export async function copyTemplates(targetDir) {
+  for (const file of TEMPLATE_FILES) {
+    const src = path.join(TEMPLATES_DIR, file);
+    const dest = path.join(targetDir, file);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.copyFile(src, dest);
+  }
+}
+
+export function resolveGlobalDir() {
+  return path.join(os.homedir(), SKILL_DIR);
+}
+
+export async function getInstallations(projectDir) {
+  const localPath = path.join(projectDir, SKILL_DIR, "SKILL.md");
+  const globalPath = path.join(resolveGlobalDir(), "SKILL.md");
+
+  const [local, global] = await Promise.all([
+    fs.access(localPath).then(() => true, () => false),
+    fs.access(globalPath).then(() => true, () => false),
+  ]);
+
+  return { local, global };
+}
+
+export async function skillExists(targetDir) {
+  try {
+    await fs.access(path.join(targetDir, SKILL_DIR, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/templates/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: dev-workflow
+description: >
+  Use when the user explicitly asks to run the Spec Driven Development workflow (SDD) / structured dev-workflow,
+  e.g. they say "dev-workflow", "SDD", "workflow", or use /dev-workflow. Do NOT use for
+  generic feature requests like "build X" unless they explicitly requested the workflow.
+license: MIT
+compatibility: Any project with tests, git, and CLAUDE.md
+metadata:
+  version: "1.0"
+  tags: workflow, sdd, tdd, development, planning, testing, spec-driven
+---
+
+# Spec Driven Development Workflow
+
+You are orchestrating a structured development cycle based on Spec Driven Development (SDD). The core idea: define WHAT you want before writing code, then implement from structured specifications. Each phase produces a persistent artifact that the next session consumes — the files travel, not the context.
+
+## Project Detection
+
+Before starting, read the project's `CLAUDE.md` (or `AGENTS.md`) to determine:
+
+| Setting | Examples | Default |
+|---------|----------|---------|
+| Base branch | `develop`, `main`, `master` | `main` |
+| Test command | `npm test`, `pytest`, `cargo test` | `npm test` |
+| Lint command | `npm run lint`, `ruff check` | `npm run lint` |
+| Type check | `npm run typescript`, `mypy .` | Skip if N/A |
+| Test runner (watch) | `vitest`, `jest --watch` | `vitest` |
+| Commit format | conventional, project-specific | conventional |
+| Versioning | semver, calver, none | none |
+| Milestones | per-version, per-sprint, none | none |
+| Releases | GitHub releases, tags only, none | none |
+| Project skills | `.claude/skills/` entries | — |
+
+## Complexity Triage
+
+Not every task needs the full 4-phase ceremony. Classify the task before starting:
+
+**Simple** — bugfix, config change, small tweak, single-file change:
+→ Skip Phase 1. Flow: `PLAN → IMPLEMENT → VERIFY`
+→ Phase 2 (PLAN) still creates the feature branch — no code touches the base branch directly.
+
+**Standard** — new feature, multi-file change, domain logic, anything where "obvious" business rules aren't obvious:
+→ Full flow: `SPEC → PLAN → IMPLEMENT → VERIFY`
+
+When in doubt, go Standard. The cost of a spec you didn't need is low. The cost of ambiguity in implementation is high.
+
+## Naming Convention
+
+Phase 1 defines a `<feature-name>` (e.g., `add-ssl-filters`, `fix-pagination`). This name is used consistently:
+
+- **Directory:** `docs/workflow/<feature-name>/`
+- **Branch:** `feature/<feature-name>`
+
+Phase 1 creates the directory. Phase 2 creates the git branch matching it.
+
+## Workflow Overview
+
+```
+Phase 1: SPEC      →  docs/workflow/<feature-name>/SPEC.md   →  User reviews
+Phase 2: PLAN      →  docs/workflow/<feature-name>/PLAN.md   →  User reviews + branch
+Phase 3: IMPLEMENT →  Per-task loop: RED → GREEN → REFACTOR → User reviews each task
+Phase 4: VERIFY    →  Lint + Types + Commit/PR               →  Done
+```
+
+Phase 3 is iterative: it cycles through each task in the plan one at a time. For each task, it writes failing tests (RED), implements until they pass (GREEN), refactors, and then presents the results for user review before moving to the next task. This prevents large code dumps and gives the user control at every step.
+
+Each phase can run in a **separate session** with fresh context. The artifact from the previous phase is the only input needed.
+
+## Phase Detection
+
+When starting a session, detect the current phase by checking state in `docs/workflow/<feature-name>/`:
+
+1. **No workflow directory** or directory exists but no `SPEC.md` and no `PLAN.md` → **Start Phase 1** (standard) or **Phase 2** (simple — user confirms)
+2. **`SPEC.md` exists, no `PLAN.md`** → **Start Phase 2**
+3. **`PLAN.md` exists, not all tasks are implemented** → **Start Phase 3** (check which tasks still need tests/implementation)
+4. **All tasks implemented and tests pass** → **Start Phase 4**
+
+**Simple flow without SPEC:** If `PLAN.md` exists and its header shows `Complexity: simple` with no `SPEC.md`, this is expected — skip Phase 1 detection.
+
+**Phase 3 resume:** Phase 3 is iterative — it may span multiple sessions. When resuming, check which tasks from PLAN.md already have passing tests and implementation. Pick up from the next incomplete task.
+
+**Ambiguous states:**
+- Test files exist but have syntax/import errors → still Phase 3 (fix the tests for that task)
+- Test files exist and pass but no implementation code → the tests may be wrong, investigate before advancing
+- Multiple workflow directories exist → ask the user which feature to continue
+
+## Phase Instructions
+
+Each phase has detailed instructions in a reference file. Read ONLY the reference for the current phase — loading all phases wastes context.
+
+| Phase | Reference | Input | Output |
+|-------|-----------|-------|--------|
+| 1. SPEC | `references/phase-1-spec.md` | User request | `SPEC.md` + directory |
+| 2. PLAN | `references/phase-2-plan.md` | `SPEC.md` | `PLAN.md` + git branch |
+| 3. IMPLEMENT | `references/phase-3-implement.md` | `PLAN.md` + `SPEC.md` | Per-task: tests + code + refactor, user-reviewed |
+| 4. VERIFY | `references/phase-4-verify.md` | All tasks passing | Commit/PR |
+
+## Rules
+
+- **Artifacts are the source of truth.** Every decision lives in SPEC.md or PLAN.md, not in conversation context.
+- **Branch before code.** Every task — simple or standard — must have a `feature/<name>` branch created before any code is written. Never commit directly to the base branch.
+- **Tests before code.** Always. Within each task, write failing tests before implementation.
+- **User reviews each task.** In Phase 3, the user reviews after each task's RED → GREEN → REFACTOR cycle — not just at the end of the phase.
+- **Read CLAUDE.md first.** Every project has different commands, conventions, and skills.
+- **One phase per session.** Keep context clean. The user can continue in the same session if they want, but the default is one phase per session.
+
+## Abort Protocol
+
+If the user wants to abandon a workflow at any point:
+
+1. **Ask for confirmation** — "Are you sure? This will clean up the branch and workflow artifacts."
+2. **Clean up the branch** (if created):
+   ```bash
+   git checkout <base-branch>
+   git branch -D feature/<feature-name>
+   ```
+3. **Remove workflow artifacts:**
+   ```bash
+   rm -rf docs/workflow/<feature-name>
+   ```
+4. **Confirm cleanup** — list what was removed so the user knows the state is clean.
+
+If the user wants to **pause** (not abort), just stop. The artifacts persist and Phase Detection will pick up where they left off in a future session.

package/templates/references/phase-1-spec.md

@@ -0,0 +1,95 @@
+# Phase 1: SPEC — What, Not How
+
+**Goal:** Define the feature functionally. Technology-agnostic. No implementation decisions.
+
+**Input:** User's request or ticket description.
+
+**Output:** `docs/workflow/<feature-name>/SPEC.md` + directory created
+
+## Why a Separate Spec?
+
+When functional requirements and technical decisions are mixed in the same document, the agent juggles two concerns simultaneously. Technical decisions create branching paths that compound ambiguity. A pure functional spec gives a clear objective without premature implementation choices. It also defines expected behavior for edge cases before anyone writes a line of code.
+
+## Steps
+
+### 1. Explore the Codebase
+
+Investigate the domain area relevant to the task:
+- Identify what already exists vs what's new
+- Understand existing business rules and entities
+- Check for related types, validations, and patterns
+- Load relevant project-specific skills from `.claude/skills/`
+
+### 2. Eliminate Ambiguity
+
+Ask clarifying questions about things you cannot resolve by reading the code. Group questions together. Focus on the "silent decisions" that agents normally guess wrong:
+
+- Authorization — who can do this?
+- Idempotency — what happens if the action is repeated?
+- Edge cases — empty states, errors, limits, concurrent access
+- Scope — which specific system/component is involved?
+- Existing behavior — does this replace or extend something?
+
+### 3. Define Feature Name and Create Directory
+
+Derive a short, descriptive kebab-case name from the task (e.g., `add-ssl-filters`, `fix-pagination-bug`). This name will be used for both the directory and the git branch in Phase 2.
+
+```bash
+mkdir -p docs/workflow/<feature-name>
+```
+
+### 4. Write the Spec
+
+Save to `docs/workflow/<feature-name>/SPEC.md`:
+
+```markdown
+# Spec: <Feature Name>
+
+## Purpose
+One paragraph: what this feature does and why it exists.
+
+## Use Cases
+- As a [role], I want to [action] so that [benefit]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+(functional requirements — not technical decisions)
+
+## Edge Cases
+- What happens when [scenario]?
+- What happens if [error condition]?
+(every edge case you can identify — this is where ambiguity hides)
+
+## Acceptance Criteria
+
+Given [precondition]
+When [action]
+Then [expected result]
+
+Given [precondition]
+When [action]
+Then [expected result]
+
+(one block per behavior — these drive the RED step in Phase 3's per-task loop)
+
+## Out of Scope
+- Things this feature explicitly does NOT do
+```
+
+### 5. Present for Review
+
+Show the spec to the user. The spec is not ready until the user approves it.
+
+Common review questions:
+- Are there edge cases missing?
+- Are the acceptance criteria complete?
+- Is anything listed that should be out of scope (or vice versa)?
+
+## Exit Criteria
+
+- Feature name defined (e.g., `add-ssl-filters`)
+- Directory created at `docs/workflow/<feature-name>/`
+- `SPEC.md` written inside that directory
+- User has reviewed and approved the spec
+- The user can close this session and start Phase 2 in a new one

package/templates/references/phase-2-plan.md

@@ -0,0 +1,120 @@
+# Phase 2: PLAN — How to Build It
+
+**Goal:** Translate the spec into a technical implementation plan with ordered, self-contained tasks. Create the feature branch.
+
+**Input:** `docs/workflow/<feature-name>/SPEC.md` (read it first). If Phase 1 was skipped (simple task), gather context from the user's request.
+
+**Output:** `docs/workflow/<feature-name>/PLAN.md` + git branch `feature/<feature-name>` created.
+
+## Steps
+
+### 1. Identify the Feature
+
+Find the existing workflow directory in `docs/workflow/`. The directory name IS the feature name (set in Phase 1).
+
+If Phase 1 was skipped (simple task), define the feature name now and create the directory:
+```bash
+mkdir -p docs/workflow/<feature-name>
+```
+
+### 2. Read the Spec
+
+Read `docs/workflow/<feature-name>/SPEC.md`. Understand every requirement, edge case, and acceptance criterion before making technical decisions.
+
+### 3. Create the Feature Branch
+
+The branch name matches the directory name. Check if the branch already exists first:
+
+```bash
+git checkout <base-branch>
+git pull origin <base-branch>
+
+# Check if branch exists locally
+if git show-ref --verify --quiet refs/heads/feature/<feature-name>; then
+  # Branch exists — switch to it and rebase on latest base
+  git checkout feature/<feature-name>
+  git rebase <base-branch>
+else
+  git checkout -b feature/<feature-name>
+fi
+```
+
+If the branch exists from a previous attempt, inform the user and ask whether to continue from the existing branch or start fresh (`git branch -D` + recreate).
+
+### 4. Research the Codebase
+
+Make the architectural decisions:
+- Which layers does this touch? (domain, application, infrastructure, UI)
+- Which existing patterns to follow? (find similar features and use them as reference)
+- What files need to be created vs modified?
+- What are the dependencies and contracts?
+- Load relevant project-specific skills from `.claude/skills/`
+
+### 5. Write the Plan
+
+Save to `docs/workflow/<feature-name>/PLAN.md`:
+
+```markdown
+# Plan: <Feature Name>
+
+> Spec: [SPEC.md](./SPEC.md)
+> Branch: `feature/<name>`
+> Complexity: simple | standard
+
+## Architecture Decisions
+- Which layers this touches and why
+- Patterns to follow (with file references)
+- Dependencies and contracts
+
+## File Map
+Files that will be created or modified, organized by task.
+
+## Tasks
+
+Tasks are ordered: test tasks FIRST, then implementation, then refactoring.
+Each task is self-contained — the agent executing it should not need to guess or search for missing context.
+
+### Task 1: <Descriptive Name>
+**Type:** test | implementation | refactor
+**Files:**
+- Create: `exact/path/to/file.ts`
+- Modify: `exact/path/to/existing.ts`
+- Test: `tests/exact/path/to/file.test.ts`
+
+**Acceptance Criteria** (from spec):
+- Given X, When Y, Then Z
+
+**Steps:**
+- [ ] Step 1 (one action, 2-5 min max)
+- [ ] Step 2
+- [ ] Step 3
+
+### Task 2: <Descriptive Name>
+...
+
+## Testing Strategy
+- Which acceptance criteria map to which tests
+- Mocking strategy (what to mock, what to hit real)
+- Edge cases from spec that need explicit test coverage
+```
+
+### 6. Review the Plan
+
+Before presenting to the user, self-check:
+- Are there too many tasks? 3 tasks is better than 7 if 3 covers it.
+- Is the agent creating unnecessary abstractions?
+- Do test tasks come before implementation tasks?
+- Does each task have all the context it needs embedded?
+- Are acceptance criteria from the spec mapped to specific tasks?
+
+### 7. Present for Review
+
+Show the plan to the user. The plan is the last checkpoint before code gets written — it's worth spending time making sure it's pragmatic.
+
+## Exit Criteria
+
+- Feature branch `feature/<feature-name>` created from base branch
+- `PLAN.md` is written at `docs/workflow/<feature-name>/PLAN.md`
+- Tasks ordered: tests first, then implementation, then refactoring
+- User has reviewed and approved the plan
+- The user can close this session and start Phase 3 in a new one

package/templates/references/phase-3-implement.md

@@ -0,0 +1,134 @@
+# Phase 3: IMPLEMENT — Iterative RED → GREEN → REFACTOR
+
+**Goal:** For each task in the plan, follow the TDD cycle: write failing tests (RED), implement until they pass (GREEN), refactor, and then review with the user before moving on. This keeps changes small, reviewable, and correctable.
+
+**Input:** `docs/workflow/<feature-name>/PLAN.md` and `docs/workflow/<feature-name>/SPEC.md` (read both first).
+
+**Output:** All tasks implemented with passing tests, reviewed incrementally by the user.
+
+## Precondition
+
+The plan must exist and be approved. If `PLAN.md` doesn't exist, go back to Phase 2.
+
+You must be on the feature branch (`feature/<feature-name>`), NOT on the base branch. If you are on the base branch, go back to Phase 2 to create the branch before writing any code.
+
+## The Iteration Loop
+
+Work through tasks **one at a time**, in the order defined in PLAN.md. For each task:
+
+```
+┌──────────────────────────────────────────────┐
+│  Task N                                      │
+│                                              │
+│  1. RED     — Write tests (they fail)        │
+│  2. GREEN   — Implement (tests pass)         │
+│  3. REFACTOR — Clean up code, review quality │
+│  4. REVIEW  — User checks & gives feedback   │
+│     ├─ OK → next task                        │
+│     └─ Feedback → adjust, re-verify          │
+└──────────────────────────────────────────────┘
+```
+
+Do NOT jump ahead to the next task until the user approves the current one. This is the core principle: small iterations with feedback between each one.
+
+## Step 1: RED — Write Failing Tests
+
+Write ONLY the test files for the current task. Do NOT write any implementation code. Do NOT write tests for other tasks.
+
+Each Given/When/Then from the acceptance criteria should map to at least one test case. Test names should describe the expected behavior, not the implementation detail.
+
+After writing each test file, run ONLY the tests you wrote:
+```bash
+<test-command> <path-to-test-file>
+```
+
+Confirm they FAIL as expected. Failures must be because the feature doesn't exist — not syntax errors or broken imports. If a test fails for the wrong reason, fix it before continuing.
+
+### Verify RED
+
+- [ ] Tests exist and are syntactically correct
+- [ ] Tests FAIL (not pass, not error)
+- [ ] Failures are because the feature doesn't exist
+- [ ] Test names clearly describe expected behavior
+- [ ] Only the current task's acceptance criteria are covered
+
+**Hard gate:** All of the above must be true before moving to the BUILD step.
+
+## Step 2: GREEN — Implement
+
+Write the MINIMUM implementation code to make the current task's tests pass. Do not add features beyond what the tests require. Do not touch code related to other tasks.
+
+After writing implementation code, run ONLY the current task's tests:
+```bash
+<test-command> <path-to-test-file>
+```
+
+Confirm ALL tests pass. Do NOT run lint or type checks — those run in Phase 4.
+
+### Verify GREEN
+
+- [ ] All current task's tests pass
+- [ ] Implementation follows project patterns
+- [ ] No features beyond what tests require
+- [ ] Previously passing tests from earlier tasks still pass
+
+## Step 3: REFACTOR & REVIEW
+
+Once the current task's tests pass, clean up the code before presenting it to the user.
+
+### 3a. Refactor
+
+Review the current task's files for:
+- Code smells and duplication
+- Naming clarity
+- Patterns that don't match project conventions
+- Unnecessary complexity
+- Security concerns
+
+If issues are found, fix them. After each change, re-run the tests to confirm they still pass.
+
+### 3b. Review with User
+
+Present the current task's results:
+
+- **What was done:** Brief summary of the task
+- **Tests written:** List of test cases and what they verify
+- **Code written:** Files created/modified
+- **Refactor notes:** What was cleaned up (if anything)
+- **Test results:** Passing confirmation
+
+Then ask:
+
+> "Task N is done — tests pass and code is cleaned up. Any feedback or adjustments before moving to the next task?"
+
+**If the user has feedback:**
+1. Apply the changes
+2. Re-run the task's tests to confirm everything still passes
+3. Present the updated results
+4. Ask again if they're satisfied
+
+**If the user approves:**
+1. **Commit the task** — stage the test and implementation files for the current task and create a commit using the project's commit format (from CLAUDE.md). The commit message should reference the task (e.g., `feat(auth): add token validation - task 2/5`). Do NOT include workflow artifacts (`docs/workflow/`).
+2. Move to the next task and repeat from Step 1.
+
+## Task Progress Tracking
+
+Keep the user oriented by showing progress at each step:
+
+```
+Task 2/5: Add validation logic
+  ✓ Tests written (3 test cases)
+  ✓ Implementation complete
+  ✓ Refactored
+  → Waiting for your review
+
+Task 1/5: Create user model  ✓ Committed (a1b2c3d)
+```
+
+## Exit Criteria
+
+- All tasks from the plan have been implemented
+- Each task was reviewed, approved, and committed individually
+- All tests pass
+- Refactor done per task (not deferred to the end)
+- Ready for Phase 4 (VERIFY)

package/templates/references/phase-4-verify.md

@@ -0,0 +1,84 @@
+# Phase 4: VERIFY — Quality Gates + Delivery
+
+**Goal:** Pass all quality checks and deliver the work.
+
+**Input:** Code from Phase 3 with all tests passing.
+
+**Output:** Committed code or pull request.
+
+## Steps
+
+### 1. Run Full Verification Suite
+
+Run all quality checks sequentially:
+
+```bash
+<test-command> && <lint-command> && <type-check-command>
+```
+
+All must pass. If anything fails, fix it and re-run. Do not proceed with failures.
+
+### 2. Present Summary
+
+Show the user:
+- What was implemented (link back to the spec's purpose)
+- Files created and modified
+- Test coverage added (which acceptance criteria are covered)
+- Any decisions made during implementation that deviated from the plan
+
+### 3. Deliver
+
+Ask the user how to proceed:
+
+1. **Commit and create PR** — stage source and test files, commit with conventional format, push and create PR
+2. **Review changes first** — let the user inspect the diff before committing
+3. **Make adjustments** — address any final feedback
+
+**When committing:**
+- NEVER include workflow artifacts (`docs/workflow/`)
+- Only stage source code and test files
+- Use the commit format from the project's CLAUDE.md
+
+### 4. Release & Milestone
+
+Check the project's `CLAUDE.md` for versioning, milestone, and release conventions. If conventions are defined, follow them. If they are NOT defined (or `CLAUDE.md` doesn't exist), ask the user:
+
+> "Would you like to set up a milestone and release for this PR? (yes/no)"
+
+If the user says no, skip to the next step.
+
+**Version bump:**
+- Bump the version in the appropriate file (e.g., `package.json`, `Cargo.toml`, `pyproject.toml`) according to the versioning scheme (semver: PATCH for fixes, MINOR for features, MAJOR for breaking changes).
+- If the project has no versioning convention, ask the user what version to use.
+- This should already be part of the PR from Phase 3. If not, add it now.
+
+**Milestone:**
+- Check if open milestones exist in the repo.
+- If one or more exist, show them to the user and ask: assign this PR to an existing milestone, or create a new one?
+- If none exist, create a new milestone matching the version (e.g., `v1.2.0`) and assign the PR.
+
+**After merge:**
+- If the milestone has remaining open issues/PRs, do NOT create the release yet — the milestone is still in progress. Inform the user.
+- If the milestone is now fully closed (all issues/PRs done), create a GitHub release with the version tag (e.g., `v1.2.0`). Write release notes summarizing everything in the milestone, not just this PR.
+
+### 5. Clean Up Workflow Artifacts
+
+After the code is committed/PR is created, offer to clean up the workflow directory:
+
+```bash
+rm -rf docs/workflow/<feature-name>
+```
+
+If `docs/workflow/` is now empty, remove it too:
+```bash
+rmdir docs/workflow 2>/dev/null
+```
+
+The user may choose to keep artifacts for reference — ask before deleting. If kept, they should NOT be committed (they're already in `.gitignore` or excluded via the "NEVER include workflow artifacts" rule).
+
+## Exit Criteria
+
+- All quality checks pass (tests, lint, types)
+- Code is committed or PR is created
+- Workflow artifacts cleaned up (or user chose to keep them)
+- Workflow complete