@curdx/flow 1.1.2 → 1.1.4

package/cli/init.js

@@ -8,6 +8,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import {
   color,
   log,
@@ -17,6 +18,13 @@ import {
   runSync,
 } from "./utils.js";
 
+// When installed via npm, this file lives at <pkg>/cli/init.js; the templates
+// that ship with the npm package live at <pkg>/templates/. Always prefer those
+// over plugin-cache templates so the version installed via npm controls which
+// template language/content wins (plugin cache may lag behind npm releases).
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const NPM_PKG_TEMPLATES = path.join(__dirname, "..", "templates");
+
 export async function init(args = []) {
   const force = args.includes("--force");
   const target = args.find((a) => !a.startsWith("--")) || process.cwd();
@@ -157,10 +165,18 @@ export async function init(args = []) {
 // ---------- Helpers ----------
 
 /**
- * Find the latest installed templates directory in plugin cache.
- * Returns null if plugin not installed.
+ * Resolve the templates directory. Priority:
+ *   1. npm package's own templates/ (shipped with this CLI version — authoritative)
+ *   2. Latest Claude Code plugin cache (fallback for local-dev / unbundled runs)
+ *   3. null → embedded fallback in embeddedTemplate() below
  */
 async function findLatestTemplatesDir() {
+  // 1. npm package ships its own templates (highest priority — never stale)
+  if (existsSync(NPM_PKG_TEMPLATES)) {
+    return NPM_PKG_TEMPLATES;
+  }
+
+  // 2. Claude Code plugin cache (for local-dev where pkg root is the plugin root)
   const pluginBase = pluginCacheDir();
   try {
     const versions = await fs.readdir(pluginBase);

package/cli/utils.js

@@ -5,8 +5,17 @@
 
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-
-export const VERSION = "1.1.1";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// Read version dynamically from package.json so `curdx-flow --version` always
+// reflects the installed package version (avoids drift after npm version bumps).
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgJson = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf-8")
+);
+export const VERSION = pkgJson.version;
 
 // ---------- Color helpers (no chalk dep) ----------
 const isTTY = process.stdout.isTTY && process.env.TERM !== "dumb";
@@ -238,8 +247,8 @@ export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-f
 // detection + self-healing: create a symlink to the user-level bun install
 // in a PATH-visible directory.
 
-import { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
+// `existsSync` and `join` already imported at the top of this file.
 
 const HOME = process.env.HOME || "";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "files": [
     "bin/",
     "cli/",
+    "templates/",
     "README.md"
   ],
   "engines": {

package/templates/CONTEXT.md.tmpl

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — User Preferences and Decisions
+
+> CurDX-Flow Context — your coding, design, and interaction preferences. Agents read this to understand your taste.
+
+---
+
+## Code Style Preferences
+
+- **Indentation**: <!-- 2 spaces / 4 spaces / Tab -->
+- **Quotes**: <!-- single / double -->
+- **Semicolons**: <!-- always / never / asi -->
+- **Naming**: <!-- camelCase / snake_case / PascalCase -->
+- **Comment density**: <!-- minimal / when non-obvious / generous -->
+
+## Architecture Preferences
+
+- **Error handling**: <!-- try/catch / Result type / panics -->
+- **Async pattern**: <!-- async/await / promises / callbacks -->
+- **Dependency injection**: <!-- constructor / service locator / none -->
+- **Testing style**: <!-- TDD / test-after / integration-heavy -->
+
+## UI/UX Preferences
+
+- **Design style**: <!-- minimalist / brutalist / corporate / playful -->
+- **Color scheme**: <!-- light / dark / auto / specific palette -->
+- **Typography**: <!-- system / Inter / Space Grotesk / other -->
+- **Density**: <!-- spacious / compact / mixed -->
+- **Animation**: <!-- none / purposeful / expressive -->
+
+## Communication Preferences
+
+- **Language**: <!-- Simplified Chinese / English / bilingual -->
+- **Verbosity**: <!-- terse / balanced / verbose -->
+- **Explanation depth**: <!-- surface / mechanism / first-principles -->
+- **When to ask**: <!-- ask at any fork / only on major decisions / be autonomous -->
+
+## Tooling Preferences
+
+- **Package manager**: <!-- npm / pnpm / yarn / bun -->
+- **Runtime**: <!-- node / bun / deno -->
+- **Test framework**: <!-- vitest / jest / other -->
+- **Linter**: <!-- eslint / biome / other -->
+- **Commit convention**: <!-- conventional / gitmoji / free -->
+
+## Special Requirements
+
+<!-- Rules specific to this project -->
+
+- TODO:
+
+---
+
+_Generated by `/flow-init` on {{CREATED_DATE}}. Update to match your actual preferences._

package/templates/PROJECT.md.tmpl

@@ -0,0 +1,59 @@
+# {{PROJECT_NAME}}
+
+> CurDX-Flow project vision — 500 lines max, loaded on every session
+
+---
+
+## One-line Description
+
+<!-- In one sentence, state what this project is, for whom, and what problem it solves -->
+
+TODO: fill in the one-line description of the project
+
+## Why This Project Exists
+
+<!-- Background, motivation, pain points to solve -->
+
+TODO:
+
+## Core Users
+
+<!-- Who will use it? Their typical scenarios? -->
+
+TODO:
+
+## Success Criteria
+
+<!-- 3-5 verifiable metrics (e.g. "first response < 100ms", "weekly active users > 1000") -->
+
+1. TODO:
+2. TODO:
+3. TODO:
+
+## Tech Stack (with Rationale)
+
+<!-- Write the reasoning for each choice to avoid future second-guessing -->
+
+| Layer | Choice | Rationale |
+|---|-----|------|
+| Frontend | TODO | TODO |
+| Backend | TODO | TODO |
+| Database | TODO | TODO |
+| Deployment | TODO | TODO |
+
+## Out of Scope (Scope Guard)
+
+<!-- Explicitly list what does not belong in this project, to prevent scope creep -->
+
+- ✗ TODO:
+- ✗ TODO:
+
+## Constraints
+
+<!-- Budget, time, team size, compliance, etc. -->
+
+- TODO:
+
+---
+
+_Generated by `/flow-init` on {{CREATED_DATE}}. Maintainer: {{USER_NAME}}_

package/templates/ROADMAP.md.tmpl

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}} — Roadmap
+
+> CurDX-Flow ROADMAP — phase plan and success criteria. Works alongside `.flow/specs/*`: ROADMAP sets direction, specs handle concrete implementation.
+
+---
+
+## Current Version: v0.1 (MVP)
+
+**Goal**: <!-- one sentence -->
+
+TODO: describe the minimum viable product to deliver in v0.1.
+
+### Success Criteria (v0.1)
+
+<!-- Must be verifiable -->
+
+- [ ] TODO:
+- [ ] TODO:
+- [ ] TODO:
+
+### Phases
+
+<!-- List in development order -->
+
+#### Phase 1 — TODO
+- Goal:
+- Related spec: `specs/<name>`
+- Completion criteria:
+
+#### Phase 2 — TODO
+- Goal:
+- Completion criteria:
+
+---
+
+## Next Version: v0.2
+
+**Theme**: TODO
+
+No details yet.
+
+---
+
+## Vision (12 months)
+
+TODO: describe what this project should look like one year from now.
+
+---
+
+_Initialized on {{CREATED_DATE}}. The roadmap is a statement of intent, not a commitment._

package/templates/STATE.md.tmpl

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — Cross-Session State
+
+> CurDX-Flow STATE — explicit decision log + important context. Agents read this file at the start of every session.
+>
+> Division of labor with claude-mem: claude-mem captures everything automatically; STATE.md only records **decisions you and the agent explicitly agreed on**.
+
+---
+
+## Key Decisions
+
+<!--
+Format: D-NN | YYYY-MM-DD | decision | why
+Once a decision is recorded, subsequent agents must explicitly note "I challenge D-NN" before violating it.
+-->
+
+<!-- Example (delete on init):
+- **D-01** | 2026-04-19 | Use JWT instead of session cookie | Support cross-origin SPA
+- **D-02** | 2026-04-19 | bcrypt cost factor = 12 | Balance 10K QPS performance with security
+-->
+
+No decisions yet.
+
+## Blockers
+
+<!-- Items currently blocking progress, and who/what is being waited on -->
+
+No blockers.
+
+## Open Questions
+
+<!-- Questions that need user answers or investigation -->
+
+None yet.
+
+## Important Context
+
+<!-- Long-standing context the agent should remember, not quite at "decision" level -->
+
+None yet.
+
+## Milestones
+
+<!-- Project-level major milestones -->
+
+None yet.
+
+---
+
+_Initialized on {{CREATED_DATE}}. This file will grow as the project evolves._

package/templates/config.json.tmpl

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://raw.githubusercontent.com/wdx/curdx-flow/main/schemas/config.schema.json",
+  "version": "1.0",
+  "mode": "standard",
+  "_mode_options": "sketch | fast | standard | enterprise | autonomous",
+
+  "execution": {
+    "strategy": "auto",
+    "_strategy_options": "auto | subagent | stop-hook | wave | linear",
+    "max_parallel": 5,
+    "subagent_threshold": 8
+  },
+
+  "gates": {
+    "always_on": [
+      "karpathy-gate",
+      "verification-gate"
+    ],
+    "standard_mode": [
+      "tdd-gate",
+      "coverage-audit-gate",
+      "simplicity-gate"
+    ],
+    "enterprise_mode": [
+      "adversarial-review-gate",
+      "edge-case-gate",
+      "hard-gate",
+      "security-gate"
+    ]
+  },
+
+  "specs": {
+    "directories": ["./.flow/specs"],
+    "default_task_size": "fine",
+    "_task_size_options": "fine (40-60 tasks) | coarse (10-20 tasks)"
+  },
+
+  "addons": {
+    "pua": {
+      "enabled": false,
+      "style": "alibaba",
+      "_style_options": "alibaba | bytedance | huawei | tencent | baidu | pdd | meituan | jd | xiaomi | netflix | musk | jobs | amazon",
+      "auto_trigger": "on-failure"
+    }
+  },
+
+  "created": "{{CREATED_DATE}}"
+}

package/templates/design.md.tmpl

@@ -0,0 +1,163 @@
+---
+spec: {{SPEC_NAME}}
+phase: design
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+depends_on: requirements.md
+---
+
+# Technical Design: {{SPEC_NAME}}
+
+> Conclusions from the flow-architect agent using at least 8 rounds of `sequential-thinking` reasoning.
+> This document freezes the technical choices. Subsequent tasks / implementation strictly follow this design.
+
+---
+
+## Design Overview (one paragraph)
+
+<!-- One-sentence summary of the architecture -->
+
+## Architecture Decisions
+
+<!-- Each major decision gets an ID and is written to the decisions array in .flow/STATE.md -->
+
+### AD-01: ...
+- **Decision**: Use X instead of Y
+- **Rationale**: ...
+- **Trade-off**: Accepted [downside] in exchange for [upside]
+- **sequentialthinking rounds**: rounds 3-5
+
+### AD-02: ...
+
+## System Architecture Diagram
+
+```mermaid
+flowchart TB
+  <!-- actual data flow generated by flow-architect -->
+  User[User] --> API[API Gateway]
+  API --> Auth[Auth Service]
+  Auth --> DB[(Database)]
+```
+
+## Component Design
+
+<!-- Each component is independently testable. Interfaces are explicit. -->
+
+### Component: {{COMP_NAME_1}}
+- **Responsibility**: ...
+- **Input**:
+  ```ts
+  interface Input {
+    field: Type;
+  }
+  ```
+- **Output**:
+  ```ts
+  interface Output {
+    field: Type;
+  }
+  ```
+- **Dependencies**: Component X, Library Y
+- **Errors**:
+  - `ErrorCode.X` — when ... happens
+  - `ErrorCode.Y` — when ... happens
+
+### Component: {{COMP_NAME_2}}
+<!-- ... -->
+
+## Data Model
+
+<!-- Database schema / data structures -->
+
+### Entity: ...
+```sql
+CREATE TABLE ... (
+  id UUID PRIMARY KEY,
+  ...
+);
+```
+
+### Or TypeScript types:
+```ts
+interface Entity {
+  id: string;
+  ...
+}
+```
+
+## State Machine (if applicable)
+
+```mermaid
+stateDiagram-v2
+  [*] --> Pending
+  Pending --> Active: approve
+  Pending --> Rejected: reject
+  Active --> Completed: finish
+```
+
+## Error Path Design
+
+<!-- Full flow on failure -->
+
+| Scenario | Upstream Behavior | System Response | User-visible |
+|-----|--------|---------|---------|
+| DB connection lost | retry 3 times | return 503 | "Temporarily unavailable, retry in 1 minute" |
+| Rate limit hit | none | return 429 | "Too many requests, retry in 60 seconds" |
+
+## API Contract
+
+<!-- If this is an API project -->
+
+```yaml
+POST /api/v1/...
+Request:
+  body:
+    field: string
+Response:
+  200:
+    body:
+      field: string
+  400:
+    body:
+      error: string
+```
+
+## Test Matrix
+
+| Layer | Coverage | Tool |
+|---|-----|------|
+| Unit | All pure functions | vitest |
+| Integration | Between components | vitest + supertest |
+| E2E | Complete user flows | playwright / chrome-devtools MCP |
+
+### Key Test Scenarios
+1. Happy path: ...
+2. Edge case 1: ...
+3. Error recovery: ...
+
+## Suggested Implementation Order
+
+<!-- Reference for decomposition in the tasks phase -->
+
+1. Build skeleton first (Component A → empty implementation)
+2. Then wire up the real logic (core logic of Component A)
+3. Connect DB (persistence for Component A)
+4. Then do Component B ...
+
+## Risks and Mitigations
+
+| Risk | Level | Mitigation |
+|-----|-----|------|
+| ... | medium | ... |
+
+## Defer to Implementation
+
+<!-- Decisions not worth spending time on in the design phase -->
+
+- Logging library choice → reuse project's existing one during implementation
+- Caching strategy → no caching initially, adjust based on data after launch
+
+---
+
+_Generated by flow-architect agent on {{CREATED_DATE}}. After user reviews and approves AD-01~N, proceed to the tasks phase._

package/templates/progress.md.tmpl

@@ -0,0 +1,58 @@
+# Progress Log: {{SPEC_NAME}}
+
+> Living document. The agent appends here every time a task is completed / a gotcha is discovered / a decision is made.
+>
+> On resume after an interruption, the agent reads this file to rebuild context.
+
+---
+
+## Reality Check (current actual state)
+
+<!-- At the start of each session, the agent reconciles: expected state vs actual state -->
+
+**Last updated**: {{CREATED_DATE}}
+
+- Current phase: research
+- Current task: N/A (tasks phase not yet entered)
+- Blockers: none
+
+## Completed Tasks
+
+<!-- List of completed tasks -->
+
+_(not yet started)_
+
+## Learnings
+
+<!-- Things the agent discovered during execution that are worth remembering (useful for similar future situations) -->
+
+### Gotchas
+_(none)_
+
+### Patterns that worked
+_(none)_
+
+### Approaches that didn't work
+_(none)_
+
+## Decisions Made Here
+
+<!-- Technical decisions made within this spec (major decisions should be synced to .flow/STATE.md) -->
+
+_(none)_
+
+## Next Steps
+
+<!-- What to do next. Must be filled in before ending the session. -->
+
+- [ ] Enter the research phase: run `/flow-research`
+
+## Questions for User
+
+<!-- Questions that need user answers -->
+
+_(none)_
+
+---
+
+_Spec initialized on {{CREATED_DATE}}._

package/templates/requirements.md.tmpl

@@ -0,0 +1,94 @@
+---
+spec: {{SPEC_NAME}}
+phase: requirements
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+depends_on: research.md
+---
+
+# Requirements Spec: {{SPEC_NAME}}
+
+> **Recommended direction from the research phase**: {{RESEARCH_CONCLUSION}}
+>
+> This phase: translate "technically feasible" into "concrete behaviors users benefit from".
+
+---
+
+## User Stories
+
+<!-- Each story follows the format: As X, I want Y, so that Z -->
+
+### US-01: ...
+**As** [user role],
+**I want** [capability],
+**so that** [business value].
+
+**Acceptance criteria**:
+- AC-1.1: [verifiable behavior]
+- AC-1.2: [verifiable behavior]
+- AC-1.3: [edge case handling]
+
+### US-02: ...
+<!-- ... -->
+
+## Functional Requirements
+
+<!-- FR-NN format. Each FR must be a verifiable statement of "the system must X". -->
+
+- **FR-01**: The system must ...
+- **FR-02**: The system must ...
+- **FR-03**: ...
+
+## Non-Functional Requirements
+
+### Performance
+- **NFR-P-01**: [e.g. P95 response time < 200ms]
+- **NFR-P-02**: ...
+
+### Security
+- **NFR-S-01**: ...
+- **NFR-S-02**: ...
+
+### Maintainability
+- **NFR-M-01**: ...
+
+### Compatibility
+- **NFR-C-01**: ...
+
+## Edge Cases and Error Handling
+
+<!-- Must be explicit: what happens on failure? how are abnormal inputs handled? -->
+
+| Scenario | Expected behavior |
+|-----|--------|
+| Network disconnected | ... |
+| Database exception | ... |
+| Invalid input | ... |
+| Concurrent conflict | ... |
+
+## Out of Scope
+
+<!-- Karpathy principle 2: simplicity first. Explicitly list "not this time" to prevent scope creep. -->
+
+- ✗ Feature A — deferred to the next version
+- ✗ Feature B — out of budget
+- ✗ Feature C — needs its own spec
+
+## Success Metrics
+
+<!-- Must be quantifiable -->
+
+- Metric 1: [e.g. user signup completion rate > 80%]
+- Metric 2: [e.g. complaint rate < 1%]
+
+## Open Questions
+
+<!-- Questions that need user answers -->
+
+1. **Question 1**: ...
+2. **Question 2**: ...
+
+---
+
+_Generated by flow-product-designer agent on {{CREATED_DATE}}. After user review, proceed to the design phase._

package/templates/research.md.tmpl

@@ -0,0 +1,114 @@
+---
+spec: {{SPEC_NAME}}
+phase: research
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+---
+
+# Research Report: {{SPEC_NAME}}
+
+> **Goal**: {{SPEC_GOAL}}
+>
+> Output of this phase. Subsequent requirements / design / tasks are all based on the conclusions of this document.
+
+---
+
+## Prior Experience (from claude-mem)
+
+<!--
+flow-researcher first calls mcp__claude_mem__search to retrieve relevant history.
+If there are relevant observations, summarize them here; if not, write "(first research on this topic)".
+-->
+
+{{CLAUDE_MEM_FINDINGS}}
+
+## Problem Understanding
+
+<!-- Translate the user's goal into technical language. Explicitly list assumptions. -->
+
+### Core Problem
+<!-- One-line description of what we are solving -->
+
+### Explicit Assumptions
+<!-- Karpathy principle 1: think before coding. List all assumptions for the user to confirm -->
+- Assumption 1: ...
+- Assumption 2: ...
+
+### Known Constraints
+- Tech stack:
+- Budget / time:
+- Team capability:
+- Compliance requirements:
+
+## Technical Solution Space
+
+<!-- List 2-3 possible approaches with their pros and cons. Pick one in the design phase. -->
+
+### Option A: ...
+- **Pros**:
+- **Cons**:
+- **Complexity**: low / medium / high
+- **Docs (context7 queries)**:
+  - `library-name@version`: ...
+
+### Option B: ...
+- **Pros**:
+- **Cons**:
+- **Complexity**: low / medium / high
+
+### Option C (optional): ...
+
+## Existing Code Analysis
+
+<!-- Codebase scan results. Which existing modules can be reused? Which need to be new? -->
+
+### Reusable Modules
+- `path/to/existing-module.ts` — ...
+
+### Modules to Create
+- `path/to/new-module.ts` — ...
+
+### Modules to Modify
+- `path/to/modify.ts` — ...
+
+## Latest Documentation Summary (context7)
+
+<!-- Latest APIs / best practices found by flow-researcher via mcp__context7__* -->
+
+### {{LIBRARY_1}}
+- Version:
+- Relevant APIs:
+- Gotchas / changes:
+
+### {{LIBRARY_2}}
+- ...
+
+## Feasibility Assessment
+
+<!-- Explicitly answer: can this be done? how hard is it? -->
+
+- **Feasibility**: ✓ feasible / ⚠ risky / ✗ not recommended
+- **Estimated complexity**: 1-10
+- **Main risks**:
+  - Risk 1: ...
+  - Risk 2: ...
+
+## Recommended Direction
+
+<!-- Research conclusion: which option is recommended and why. If multiple options need discussion, explain here. -->
+
+**Recommendation**: Option ?
+**Rationale**:
+**To confirm in the design phase**:
+
+## Open Questions
+
+<!-- Questions the research phase couldn't answer, to be deferred to later phases or asked of the user -->
+
+1. ...
+2. ...
+
+---
+
+_Generated by flow-researcher agent on {{CREATED_DATE}}. Subsequent phases continue from this document._

package/templates/tasks.md.tmpl

@@ -0,0 +1,141 @@
+---
+spec: {{SPEC_NAME}}
+phase: tasks
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+depends_on: design.md
+task_size: fine
+---
+
+# Task Breakdown: {{SPEC_NAME}}
+
+> POC-First 5 Phases: **work → refactor → test → quality gates → PR lifecycle**.
+>
+> Each task includes: `Do`, `Files`, `Done-when`, `Verify`, `Commit`. Verifiable via automation.
+
+---
+
+## Marker Rules
+
+- `[ ]` TODO / `[x]` done
+- `[P]` parallel-safe (can be dispatched in parallel within the same wave)
+- `[VERIFY]` quality checkpoint (run by the flow-verifier agent)
+- `[SEQUENTIAL]` must be serial (breaks the parallel group)
+
+---
+
+## Phase 1: Make It Work (POC)
+
+> Goal: get it running end-to-end. Hardcoding is acceptable; skip tests.
+
+- [ ] **1.1** [P] Initialize module skeleton
+  - **Do**: create `src/{{MODULE}}/` directory, add `index.ts`, `types.ts`
+  - **Files**: `src/{{MODULE}}/index.ts`, `src/{{MODULE}}/types.ts`
+  - **Done when**: directory exists, `import {} from './{{MODULE}}'` does not error
+  - **Verify**: `npx tsc --noEmit`
+  - **Commit**: `feat({{MODULE}}): initialize module skeleton`
+  - _Requirements_: FR-01
+
+- [ ] **1.2** [P] ...
+  - **Do**: ...
+  - **Files**: ...
+  - **Done when**: ...
+  - **Verify**: ...
+  - **Commit**: ...
+  - _Requirements_: ...
+  - _Design_: AD-01
+
+- [ ] **1.3** [VERIFY] End-to-end POC verification
+  - **Do**: run the happy path manually, confirm the core scenario works
+  - **Verify**: `curl http://localhost:3000/... | jq`
+  - **Done when**: returns expected data (edge cases may still be wrong)
+
+## Phase 2: Refactoring
+
+> Goal: clean up the code structure. Behavior unchanged.
+
+- [ ] **2.1** Extract duplicated logic
+  - **Do**: ...
+  - **Verify**: `npx tsc --noEmit && git diff --stat`
+  - **Commit**: `refactor({{MODULE}}): extract common logic`
+
+- [ ] **2.2** [VERIFY] Refactor does not break behavior
+  - **Verify**: rerun the manual test from Phase 1
+  - **Done when**: all outputs match
+
+## Phase 3: Testing (TDD red / green / yellow)
+
+> Rule: tests first. Let the test fail first (RED), then implement (GREEN), then clean up (YELLOW).
+
+- [ ] **3.1** [RED] Write failing tests — unit
+  - **Do**: write unit tests for core functions
+  - **Files**: `src/{{MODULE}}/*.test.ts`
+  - **Verify**: `npm test -- src/{{MODULE}}` — expected to fail
+  - **Commit**: `test({{MODULE}}): red - add unit tests for core logic`
+
+- [ ] **3.2** [GREEN] Make tests pass
+  - **Do**: fix the implementation so the tests from 3.1 pass
+  - **Verify**: `npm test -- src/{{MODULE}}` — all green
+  - **Commit**: `feat({{MODULE}}): green - satisfy unit tests`
+
+- [ ] **3.3** [YELLOW] Refactor and clean up
+  - **Do**: clean up the implementation, tests still pass
+  - **Commit**: `refactor({{MODULE}}): yellow - clean implementation`
+
+- [ ] **3.4** [RED → GREEN → YELLOW] Integration tests
+  - <!-- Repeat the TDD cycle -->
+
+- [ ] **3.5** [VERIFY] Coverage check
+  - **Verify**: `npm test -- --coverage` — core logic > 80%
+
+## Phase 4: Quality Gates
+
+> Full local checks. Last gate before CI.
+
+- [ ] **4.1** TypeScript strict check
+  - **Verify**: `npx tsc --strict --noEmit` — 0 errors
+  - **Commit**: `chore({{MODULE}}): tsc strict passes`
+
+- [ ] **4.2** Lint
+  - **Verify**: `npx eslint src/{{MODULE}}` — 0 errors, 0 warnings
+
+- [ ] **4.3** All tests pass
+  - **Verify**: `npm test` — all green
+
+- [ ] **4.4** [VERIFY] Final health check
+  - **Do**: flow-verifier agent performs goal-driven reverse verification
+  - **Done when**: every FR-XX and AC-X.Y has a corresponding automated verification
+
+## Phase 5: PR Lifecycle
+
+- [ ] **5.1** Generate PR
+  - **Do**: `/flow-ship` creates the PR
+  - **Done when**: PR URL returned, description is clear
+
+- [ ] **5.2** Respond to review feedback
+  - **Do**: iterate until approved
+  - **Verify**: CI all green
+
+- [ ] **5.3** Merge
+  - **Do**: `/flow-land`
+  - **Verify**: the main branch contains all commits for this spec
+
+---
+
+## Coverage Audit
+
+<!-- Final step for flow-planner: confirm every FR / AC / AD / D has a corresponding task -->
+
+| Requirement ID | Task(s) | Status |
+|--------|---------|------|
+| FR-01 | 1.2, 3.1 | ✓ |
+| FR-02 | ... | ⚠ uncovered — needs adding |
+| AD-01 | 1.1 | ✓ |
+| D-05 (STATE.md) | ... | ✓ |
+
+**Uncovered items must be handled**: add a task or document the deferral reason in STATE.md.
+
+---
+
+_Generated by flow-planner agent on {{CREATED_DATE}}. N tasks total, estimated X hours._