OpenSpec + Superpowers TDD v2：4 层防护叠加 26 个原子任务，27 次 subagent 实测 3/4 通过

Task 1: 创建 Todo 接口
  Test description: 验证 POST /todos 返回 201
  Expected behavior: 接受 title 参数并返回 todo 对象
  Implementation notes: 实现 POST /todos 路由

- [ ] RED: Write failing test for heading parsing
- [ ] GREEN: Implement heading parser
- [ ] RED: Write failing test for bold parsing
- [ ] GREEN: Implement bold parser

- [ ] Implement Markdown parser — support headings, bold, italic

openspec/
├── schemas/
│   └── tdd-driven-v2/
│       ├── schema.yaml        # 工作流定义
│       └── templates/
│           ├── proposal.md
│           ├── spec.md
│           ├── design.md
│           ├── tasks.md
│           └── plan.md
├── config.yaml                # 项目配置（注意：在 openspec/ 根目录下）
├── changes/                   # 变更记录（openspec init 自动创建）
└── specs/                     # 规范目录（openspec init 自动创建）

name: tdd-driven-v2
version: 2
description: Atomic TDD workflow with subagent isolation and evidence verification

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial change proposal with testable behaviors
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.

      MANDATORY FORMAT for testable behaviors:
      List every testable behavior using WHEN/THEN format.

      Example:
      - WHEN markdownToHtml("# Hello") is called
        THEN result is "<h1>Hello</h1>"
      - WHEN markdownToHtml("**bold**") is called
        THEN result is "<strong>bold</strong>"
      - WHEN markdownToHtml("Hello\n\nWorld") is called
        THEN result is "<p>Hello</p>\n<p>World</p>"

      Do NOT describe implementation details.
      Focus on WHAT should happen, not HOW.
    requires: []

  - id: specs
    generates: specs/**/*.md
    description: Behavioral specifications
    template: spec.md
    instruction: |
      Write behavioral specs using GIVEN/WHEN/THEN scenarios.

      Rules:
      - Each scenario must be independently testable
      - Cover: happy path, edge cases, error cases
      - Express expected behavior, not implementation
      - Reference existing patterns before creating new ones
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Technical design with test strategy
    template: design.md
    instruction: |
      Create a technical design explaining HOW to implement.

      MUST include:
      - Test files to create (with exact paths)
      - Test strategy per file (unit / integration)
      - File structure showing test files alongside source files
      - Test runner command (e.g., npm test)
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Atomic TDD task list
    template: tasks.md
    instruction: |
      CRITICAL: Break work into ATOMIC TDD tasks.
      Each task is EXACTLY ONE TDD phase (RED, GREEN, or REFACTOR).

      MANDATORY FORMAT — use checkbox syntax for every task:

      ### Feature: [feature name]

      - [ ] RED: Write failing test — [具体测试什么行为]
      - [ ] GREEN: Implement — [最小实现描述，引用对应的 RED 任务]
      - [ ] REFACTOR: Clean up — [清理描述]（可选，不是每个 GREEN 都需要）

      Rules:
      1. NEVER combine RED and GREEN in one task
      2. Every GREEN task must reference its corresponding RED test
      3. Every task MUST use "- [ ]" checkbox format — no other format allowed
      4. Tasks alternate: RED → GREEN → (REFACTOR) → RED → GREEN → ...
      5. No task should take more than 2-5 minutes
      6. Do NOT group by feature — group by TDD phase order

      Example of correct output:

      - [ ] RED: Write failing test for heading parsing — create markdown.test.ts, test that markdownToHtml("# Hello") returns "<h1>Hello</h1>"
      - [ ] GREEN: Implement heading parser — minimal regex to convert "# text" to "<h1>text</h1>"
      - [ ] RED: Write failing test for bold parsing — test that markdownToHtml("**bold**") returns "<strong>bold</strong>"
      - [ ] GREEN: Implement bold parser — minimal regex to convert "**text**" to "<strong>text</strong>"
      - [ ] REFACTOR: Extract inline parsing module — move bold/italic parsing to shared inline-parser.ts

      Example of WRONG output (do NOT do this):

      - [ ] Implement Markdown parser — support headings, bold, italic, links with tests  ← WRONG: combines everything
    requires:
      - specs
      - design

  - id: plans
    generates: plan.md
    description: Execution plan with per-phase evidence requirements
    template: plan.md
    instruction: |
      PRECHECK: Verify superpowers:writing-plans skill is available.
      If not available, STOP and report the missing skill.

      Create a detailed execution plan. Each plan step maps to EXACTLY ONE task from tasks.md.

      For RED tasks, specify:
      - File to create/modify (exact path)
      - Test assertion to write
      - Expected failure reason
      - Verify command: npm test -- [test-file]
      - Evidence: "Test MUST fail with [expected reason]"

      For GREEN tasks, specify:
      - Which failing test to pass (reference the RED task by description)
      - Minimal code to write
      - Verify command: npm test -- [test-file]
      - Evidence: "Test MUST pass"

      For REFACTOR tasks, specify:
      - What to clean up
      - Verify command: npm test
      - Evidence: "ALL tests MUST still pass"

      After plan is created, append this section:

      ---
      ## Execution Mode Selection

      REQUIRED: Use superpowers:subagent-driven-development skill for execution.

      DO NOT use executing-plans or inline execution.
      Reason: Atomic TDD tasks require subagent isolation.
      Each task is a single TDD phase — one subagent per phase.
    requires:
      - tasks

apply:
  requires: [plans]
  tracks: tasks.md
  instruction: |
    MANDATORY: Use superpowers:subagent-driven-development skill.
    DO NOT use executing-plans or inline execution.

    Execution rules:
    1. Each task is an atomic TDD phase — dispatch ONE subagent per task
    2. NEVER dispatch multiple implementation subagents in parallel
    3. Tasks MUST be executed in order — do not skip or reorder

    Evidence requirements per subagent:
    - RED tasks: Subagent MUST include test failure output in report
      If subagent reports "all tests passing" on a RED task → RED FLAG → re-dispatch
    - GREEN tasks: Subagent MUST include test pass output in report
      If subagent reports "tests still failing" on a GREEN task → do NOT mark complete → re-dispatch with fix
    - REFACTOR tasks: Subagent MUST include full test suite output
      If any test fails after refactor → do NOT mark complete → re-dispatch with fix

    After each task:
    1. Spec reviewer checks: Did subagent build exactly what was requested? Nothing more, nothing less?
    2. Code quality reviewer checks: Is code clean, tested, maintainable?
    3. Only after BOTH reviewers approve → mark task complete in tasks.md (- [ ] → - [x])
    4. Proceed to next task

    After all tasks complete:
    1. Run full test suite
    2. Verify all specs are satisfied
    3. Check for TODO markers

# Proposal: {{change_name}}

## Problem
<!-- 描述要解决的问题 -->

## Testable Behaviors
<!-- WHEN/THEN 格式列出每一个可测试行为 -->

## Acceptance Criteria
<!-- 验收标准 -->

# Spec: {{change_name}}

## Scenarios

### Scenario 1: [name]
- GIVEN: [前置条件]
- WHEN: [操作]
- THEN: [期望结果]

<!-- Repeat for each scenario -->

# Design: {{change_name}}

## File Structure
<!-- 列出要创建的文件，包括测试文件 -->

## Test Strategy
<!-- 每个 test 文件的测试策略 -->

## Implementation Notes
<!-- 实现要点 -->

# Tasks: {{change_name}}

## Atomic TDD Task List

<!-- 每个 task 只能是一个 TDD 阶段 -->
<!-- 必须使用 checkbox 格式 -->

### [AI fills feature name]

- [ ] RED: ...
- [ ] GREEN: ...
- [ ] REFACTOR: ...

# Execution Plan: {{change_name}}

## Micro-tasks

### Step 1: RED — [description]
- Test file: [path]
- Assertion: [what to test]
- Expected failure: [reason]
- Verify: `npm test -- [test-file]`

### Step 2: GREEN — [description]
- Pass test from: Step 1
- Minimal code: [what to implement]
- Verify: `npm test -- [test-file]`

<!-- Repeat for each task -->

schema: tdd-driven-v2

context: |
  Tech stack: TypeScript, Node.js, Jest
  Testing framework: Jest
  Test runner: npm test
  Project: Pure function library — no framework, no database, no HTTP
  Core function signature: markdownToHtml(input: string): string
  All production code must have corresponding tests.

rules:
  proposal:
    - List every testable behavior in WHEN/THEN format
    - Do not describe implementation
  specs:
    - Use GIVEN/WHEN/THEN format for every scenario
    - Each scenario must be independently testable
  design:
    - Must specify exact test file paths
    - Must specify test strategy per file
  tasks:
    - MUST use checkbox format "- [ ]" for every task
    - Each task is exactly ONE TDD phase (RED, GREEN, or REFACTOR)
    - Tasks must alternate RED → GREEN → (optional REFACTOR)
    - GREEN tasks must reference their corresponding RED task
  plans:
    - Each plan step maps to exactly one task
    - Must specify verify command and expected evidence

# 0. 初始化 git（后续验证需要 git log）
git init

# 1. 初始化项目
mkdir mini-markdown && cd mini-markdown
npm init -y
npm install --save-dev jest ts-jest @types/jest typescript

# 2. 初始化 OpenSpec（生成 openspec/changes/、openspec/specs/ 和工具适配目录）
# 初学者建议用 --tools claude，只安装 Claude Code 适配，避免生成 29 个不需要的工具目录
openspec init --tools claude

# 3. 手动创建 Schema 目录和配置文件
mkdir -p openspec/schemas/tdd-driven-v2/templates
# 将 schema.yaml 放到 openspec/schemas/tdd-driven-v2/
# 将 config.yaml 放到 openspec/（注意：在 openspec/ 根目录下，不在 schemas/ 里）
# 将模板文件放到 openspec/schemas/tdd-driven-v2/templates/

openspec schema validate tdd-driven-v2
# 注意：会先显示 "Note: Schema commands are experimental and may change."
# 这是 CLI 的常规提示，不影响验证结果

# 在 Claude Code 中执行
/opsx:propose mini-markdown

### Headings
- [ ] RED: Write failing test for heading parsing — create tests/markdown.test.ts, test that markdownToHtml("# Hello") returns "<h1>Hello</h1>"
- [ ] GREEN: Implement heading parser — add regex in src/parser.ts to convert "^# (.+)" to "<h1>$1</h1>", export from src/index.ts

### Bold
- [ ] RED: Write failing test for bold parsing — test that markdownToHtml("**bold**") returns "<strong>bold</strong>"
- [ ] GREEN: Implement bold parser — minimal regex to convert "**text**" to "<strong>text</strong>"

openspec instructions tasks --change mini-markdown --json

# 在 Claude Code 中执行
/opsx:apply mini-markdown

Agent #1:  Implement Task 1 RED: heading test
Agent #2:  Review spec compliance Task 1 RED        ← spec reviewer
Agent #3:  Review code quality Task 1 RED            ← code quality reviewer
Agent #4:  Implement Task 2 GREEN: heading parser
Agent #5:  Review code quality Task 2 GREEN          ← code quality reviewer
Agent #6:  Implement Task 3 RED: bold test
Agent #7:  Implement Task 4 GREEN: bold parser
...（后续 task 只有实现 subagent，无审查）
Agent #27: Implement Task 26 GREEN: image parser

#4  Tests: 2 failed, 11 passed — RED（bold test 失败）
#5  Tests: 5 failed, 8 passed  — RED（多个新 test 失败）
#14 Tests: 1 failed, 10 passed — 最后一个 RED
#15 Tests: 10 passed           — 最终 GREEN

# 检查 tasks.md 的 checkbox 是否被逐步勾选
cat openspec/changes/mini-markdown/tasks.md

# 检查 git log 是否有交替的 test/feat 提交
git log --oneline

# 运行全量测试
npm test