Embedding Superpowers TDD with OpenSpec Schema: 3 Injection Points & 4 Layers (Half Effective)

Overview

This guide shows how to embed Test‑Driven Development (TDD) discipline into an OpenSpec workflow by creating a custom tdd-driven schema. The schema injects instruction, rules and context into each artifact (proposal, specs, design, tasks, plans) so that the propose phase generates TDD‑oriented documentation. The apply phase then executes the generated plan, but because instruction is a textual prompt, the AI does not strictly follow a RED‑GREEN‑REFACTOR loop.

Step 1 – Create the Custom Schema

1.1 Directory layout

# Create schema directory
mkdir -p openspec/schemas/tdd-driven/templates

1.2 Injection points

OpenSpec defines three injection points that are overlaid in the order context → rules → instruction → template: instruction – defined in each artifact entry of schema.yaml; applied only to the current artifact when the AI generates it. rules – defined in openspec/config.yaml; applied only to artifacts whose id matches the rule key (e.g., rules.specs). context – also in config.yaml; shared by all artifacts.

1.3 Core schema.yaml

The file declares the artifact DAG and embeds TDD requirements in the instruction field. A shortened excerpt:

name: tdd-driven
version: 1
description: Spec‑driven workflow with TDD discipline embedded at every artifact stage

artifacts:
- id: proposal
  generates: proposal.md
  template: proposal.md
  instruction: |
    Create a proposal that explains WHY this change is needed.
    Focus on the problem, not the solution.
    TDD REQUIREMENT:
      - Identify testable behaviors this change will introduce
      - List acceptance criteria in WHEN/THEN format
      - Do NOT describe implementation details
  requires: []

- id: specs
  generates: specs/**/*.md
  template: spec.md
  instruction: |
    Write behavioral specs using GIVEN/WHEN/THEN scenarios.
    TDD REQUIREMENT:
      - Each scenario must be independently testable
      - Reference existing patterns before inventing new ones
  requires: [proposal]

- id: design
  generates: design.md
  template: design.md
  instruction: |
    Create a technical design explaining HOW to implement.
    TDD REQUIREMENT:
      - Identify test files that need to be created or modified
      - Specify test strategy (unit, integration, e2e)
      - Design must support incremental testing
  requires: [proposal]

- id: tasks
  generates: tasks.md
  template: tasks.md
  instruction: |
    Break work into tasks following TDD order:
    1. Write failing test
    2. Write minimal implementation to pass
    3. Refactor
    4. Commit
  requires: [specs, design]

- id: plans
  generates: plan.md
  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 using 2‑5 minute micro‑tasks.
  requires: [tasks]

1.4 Template files

Empty skeletons are created for each artifact; the AI fills them based on the injected instruction.

# Create empty template files
touch openspec/schemas/tdd-driven/templates/proposal.md
touch openspec/schemas/tdd-driven/templates/spec.md
touch openspec/schemas/tdd-driven/templates/design.md
touch openspec/schemas/tdd-driven/templates/tasks.md
touch openspec/schemas/tdd-driven/templates/plan.md

Example proposal.md template:

# Proposal

## Problem
<!-- Describe the problem to solve -->

## Testable Behaviors
<!-- WHEN/THEN format list -->

## Acceptance Criteria
<!-- Acceptance standards -->

1.5 Project configuration ( openspec/config.yaml )

schema: tdd-driven

context: |
  Tech stack: TypeScript, Node.js, Jest
  Testing framework: Jest
  API style: RESTful
  All new code must have corresponding tests.

rules:
  proposal:
    - Include testable acceptance criteria
    - Use WHEN/THEN format for expected behaviors
  specs:
    - Use GIVEN/WHEN/THEN format
    - Each scenario must be independently testable
    - Reference existing patterns before inventing new ones
  tasks:
    - Order tasks by TDD cycle: test → implement → refactor
    - Each task must have a test description and expected behavior
  plans:
    - Break each task into 2‑5 minute micro‑steps
    - Every step must produce a testable outcome

1.6 Initialise OpenSpec

# Initialise with Claude as the AI tool
openspec init --tools claude

Step 2 – Propose a Change

A Todo‑CRUD change is used as a concrete scenario.

# Create a new change named "todo-crud"
/opsx:propose todo-crud

The command triggers OpenSpec to generate the five artifacts in DAG order: proposal → specs → design → tasks → plans. The plans artifact automatically calls the Superpowers writing‑plans skill (if installed).

2.1 Comparison with the built‑in spec‑driven schema

Proposal now contains WHEN/THEN testable behaviors.

Specs are forced to use GIVEN/WHEN/THEN format.

Design includes explicit test file and strategy information.

Tasks list includes test description, expected behavior, and follow the RED‑GREEN‑REFACTOR order.

A plans artifact is generated, containing micro‑tasks.

Apply pre‑condition switches from tasks (built‑in) to plans (custom).

2.2 Inspecting generated instructions

# Show the full instruction set for the specs artifact
openspec instructions specs --change todo-crud --json

The JSON output contains four sections: <context>, <rules>, <instruction>, and <template>. Missing sections indicate a misplaced config.yaml.

Step 3 – Apply (Execute the TDD Loop)

3.1 Run apply

# Execute the plan
/opsx:apply todo-crud

During execution the AI loads the Superpowers executing‑plans skill and follows the content of plan.md.

3.2 Observed behaviour

All source files and test files are written in a single pass (e.g., src/store.ts, test/store.test.ts). npm test is run; some tests initially fail.

The AI edits the code to fix failures and re‑runs the tests until they pass.

The final code is committed.

This is not a strict RED‑GREEN‑REFACTOR cycle; the AI does not write a failing test first, then minimal code, then refactor. The instruction field is a soft constraint, so manual verification is required.

3.3 Mid‑process verification

# Check change status
openspec status --change todo-crud

Typical output shows all five artifacts marked complete, but the internal task checklist may remain unchecked because the AI completed everything at once.

Change: todo-crud
Schema: tdd-driven
Progress: 5/5 artifacts complete
[x] proposal
[x] design
[x] specs
[x] tasks
[x] plans

Inspecting git log confirms that feature and test changes are committed together, e.g.:

feat: add Express server entry point
feat: add global error handler middleware
feat: implement Todo CRUD routes
feat: add in‑memory Todo store
feat: add Todo type with timestamps

Troubleshooting

Issue 1 – AI skips TDD steps

Symptom: Tests and implementation are written together or tests are missing.

Cause: instruction is only a textual prompt.

Mitigation:

Add stricter rules in config.yaml, e.g.,

Never create a .ts file without a corresponding .test.ts file

.

Split tasks into finer‑grained items, each covering only RED or GREEN.

Strengthen the apply‑phase instruction, e.g.,

STOP if no failing test exists before writing production code

.

Issue 2 – plan.md truncated

Symptom: Generated plan is incomplete.

Cause: Output exceeds the model’s token limit.

Mitigation:

Limit micro‑tasks, e.g.,

Maximum 15 micro‑tasks per plan. Split into multiple phases if needed.

Reduce the scope of the change during the proposal stage.

Issue 3 – PRECHECK failure (Superpowers missing)

Symptom: The PRECHECK line aborts because the writing‑plans skill is unavailable.

Solution: Verify the skill with /superpowers in Claude Code, or remove the PRECHECK line and the skill reference from the plans instruction.

Issue 4 – Want pure instruction without Superpowers

If Superpowers is not installed or another AI tool is used, delete the PRECHECK line and the superpowers:writing-plans reference. The schema’s textual instructions work with any LLM.

Complete File List

openspec/
├── config.yaml          # Project configuration
└── schemas/
    └── tdd-driven/
        ├── schema.yaml          # Core artifact DAG + instructions
        └── templates/
            ├── proposal.md
            ├── spec.md
            ├── design.md
            ├── tasks.md
            └── plan.md

Conclusion

Effectiveness

Propose (planning) – ✅ Effective. The custom schema changes the content and format of specs, tasks and plans (e.g., WHEN/THEN scenarios, explicit test strategy, micro‑tasks).

Apply (execution) – ❌ Not effective for strict TDD. The AI writes implementation and tests together, runs the test suite, and then edits code until tests pass. The RED‑GREEN‑REFACTOR loop is not enforced because instruction is a soft textual constraint.

When to use

✅ To obtain more structured specs, tasks and plans from AI.

✅ To enforce a consistent artifact format across a team.

✅ To manage complex change workflows with OpenSpec’s DAG.

❌ When a strict, automated RED‑GREEN‑REFACTOR cycle is required – the current instruction mechanism cannot guarantee it.

Key insight

OpenSpec defines what to generate, while Superpowers (or any AI tool) defines how to execute. The four‑layer injection ( context → rules → instruction → template) bridges the two without modifying source code. Dependencies act as enablers, not gatekeepers, so the apply phase remains flexible but still needs manual verification for true TDD compliance.