Master AI‑Driven TDD in 6 Steps with OpenSpec + Superpowers

Why This Workflow Exists

When using AI coding assistants, many developers end up with code that runs but does not meet the intended behavior because the prompt fails to specify what to write and how to write it. The solution separates these concerns.

Evolution from v1 to v3

v1 – Complete failure : a single task contained an entire feature (RED+GREEN), so the AI completed the implementation in one step. The root cause was inappropriate task granularity.

v2 – Four‑layer protection :

Atomic tasks.md (each task = one TDD phase)

Sub‑agent isolation

Two‑stage review (spec review then code review)

Evidence‑driven verification

In a Mini‑Markdown project, 26 atomic tasks triggered 27 sub‑agent dispatches; three layers passed, one review layer was skipped, yielding 10/15 test coverage.

v3 – Consolidated improvements :

Chinese‑language schema with fully localized instruction fields

Honest time estimate (12 tasks took 1 h 4 min)

Explicit enumeration of known issues (e.g., tasks 8 and 10 were skipped)

The core principle remains: OpenSpec governs "what" to write, Superpowers governs "how" to write it, linked by the instruction text in schema.yaml .

Six‑Step Practical Guide

Step 1 – Project Initialization

# Create project directory
mkdir my-tdd-project && cd my-tdd-project
# Initialise git
git init
# Initialise Node.js + Jest (TypeScript example)
npm init -y
npm install --save-dev jest ts-jest @types/jest typescript
# Configure test script
npm pkg set scripts.test="jest"

Verify that openspec/ and changes/ directories are created.

Step 2 – Create the TDD Schema

Create the directory structure and the following files (paths shown for clarity):

# Directory
mkdir -p openspec/schemas/tdd-driven-v2/templates

# schema.yaml (excerpt)
name: tdd-driven-v2
version: 2
description: 原子化 TDD 工作流，子代理隔离执行，证据驱动验证
artifacts:
  - id: proposal
    generates: proposal.md
    description: 变更提案——为什么做、期望什么行为
    template: proposal.md
    instruction: |
      创建一份变更提案，说明为什么要做这个改动。
      必须用 WHEN/THEN 格式列出每一个可测试行为：
        - WHEN <function>(<input>) 被调用 THEN 结果为 <expected>
  - id: specs
    generates: specs/**/*.md
    description: 行为规格——用场景描述期望行为
    template: spec.md
    instruction: |
      用 GIVEN/WHEN/THEN 格式编写行为规格：
        - 每个场景必须可独立测试
        - 覆盖：正常路径、边界情况、错误处理
  - id: design
    generates: design.md
    description: 技术设计——怎么实现、测试策略
    template: design.md
    instruction: |
      编写技术设计方案，说明如何实现。
  - id: tasks
    generates: tasks.md
    description: 原子化 TDD 任务列表
    template: tasks.md
    instruction: |
      关键要求：将工作拆分为原子化 TDD 任务。
      每个任务必须是且仅是一个 TDD 阶段（RED / GREEN / REFACTOR）。
  - id: plans
    generates: plan.md
    description: 执行计划——每步对应一个任务，附验证命令
    template: plan.md
    instruction: |
      创建详细的执行计划。每个计划步骤必须精确对应 tasks.md 中的一个任务。

# config.yaml (excerpt)
schema: tdd-driven-v2
context: |
  技术栈：TypeScript + Node.js
  测试框架：Jest
  测试运行命令：npx jest
  项目说明：<替换为你的项目描述>
  核心函数签名：<替换为核心函数签名>
  所有生产代码必须有对应的测试。
rules:
  proposal:
    - 用 WHEN/THEN 格式列出每一个可测试行为
    - 不要描述实现细节
  specs:
    - 每个场景使用 GIVEN/WHEN/THEN 格式
    - 每个场景必须可独立测试
  design:
    - 必须指定精确的测试文件路径
    - 必须指定每个文件的测试策略
  tasks:
    - 必须使用 "- [ ]" 复选框格式
    - 每个任务仅包含一个 TDD 阶段
    - 任务严格交替 RED → GREEN → (REFACTOR)
  plans:
    - 每个计划步骤精确对应一个任务
    - 必须指定验证命令和预期证据

The schema enforces atomic tasks, sub‑agent isolation, and evidence‑driven verification.

Step 3 – Generate the Specification (propose)

In Claude Code, run:

/opsx:propose "给 Todo API 加上任务优先级功能"

The AI extracts the change name add-todo-priority and creates five artifacts: proposal.md – WHY and WHEN/THEN list specs/ – GIVEN/WHEN/THEN scenarios design.md – file structure & test strategy tasks.md – atomic RED/GREEN tasks plan.md – mapping of tasks to execution steps

Before proceeding, manually review the three core files (proposal, design, tasks) for completeness, correct task granularity, and proper RED→GREEN alternation.

Step 4 – Execute the Implementation (apply)

After approval, run:

/opsx:apply add-todo-priority

The AI reads the apply instruction, dispatches a sub‑agent for each task, and performs a two‑stage review (spec compliance then code quality). In the Todo‑API example:

12 atomic tasks (6 × RED+GREEN) triggered 34 sub‑agent calls.

Result: 13 tests passed, coverage 95.38%.

Duration: ~1 h 4 min (mostly sub‑agent orchestration overhead).

If the sub‑agent mode is skipped, remind the AI to use superpowers:subagent-driven-development instead of inline.

Step 5 – Manual Acceptance

Run the test suite and verify coverage:

npm test
npx jest --coverage

Check that all checkboxes in tasks.md are ticked, that the test results match the WHEN/THEN list, and that the file structure aligns with design.md. If any check fails, either let the AI fix the issue or intervene manually.

Step 6 – Archive the Change

When acceptance succeeds, run:

/opsx:archive add-todo-priority

The AI moves openspec/changes/add-todo-priority/ to an archive folder with a date prefix, e.g., openspec/changes/archive/2026-05-06-add-todo-priority/, and outputs a summary.

Known Issues and Mitigations

Skipped reviews : Tasks 8 and 10 were observed to bypass the spec‑reviewer. After apply, verify each task’s review log and manually review any missing ones.

Insufficient test coverage : Only 10 of 15 behaviors were covered in v2. Cross‑check the WHEN/THEN list in proposal.md against the test suite and add missing tests.

Unexpected file‑structure changes : AI may merge files. Accept if functionality is correct; otherwise, adjust design.md and re‑run apply.

No git commits during apply : Sub‑agent mode does not perform git add/commit. After apply, run

git add -A && git commit -m "feat: implement add-todo-priority via OpenSpec + Superpowers"

.

High time cost : Sub‑agent orchestration adds ~30 s per task. For simple changes, edit plan.md to use inline execution mode.

Interface consistency : Separate files may define divergent type definitions. Manually verify shared interfaces after apply.

Applicability Analysis

Suitable scenarios :

Pure function libraries and utility modules

CRUD‑style REST APIs

CLI tools

Data transformation pipelines

Use with caution :

Frontend UI components (behaviors hard to express in WHEN/THEN)

Features that heavily depend on external services (databases, third‑party APIs)

Rapid prototyping where the overhead of schema setup outweighs benefits

Advanced Tips

Reuse the schema : Copy openspec/schemas/tdd-driven-v2/ and adjust only config.yaml for a new project.

Enrich context : The more detailed the context (function signatures, existing utilities), the higher the automation success rate in the propose phase.

Invest 5 minutes in post‑propose review : Verifying tasks.md prevents costly re‑runs during apply.

Conclusion

The OpenSpec + Superpowers TDD workflow enforces a clear division of labor: OpenSpec defines what to build, Superpowers enforces how to build it. Over three iterations the process matured from a failed monolithic approach (v1) to a robust, reusable schema (v3) that delivers high test coverage and traceable changes at the cost of additional orchestration time. Developers seeking disciplined, AI‑augmented development for backend services can adopt this six‑step method, tailoring the schema and execution mode to balance speed and quality.