openspec-tdd

openspec-tdd

Adds a TDD gate to OpenSpec — a new opsx:tdd command that sits between opsx:propose and opsx:apply.

OpenSpec generates BDD scenarios in specs/**/*.md but jumps straight to implementation — no test-first step exists. This plugin adds one. And it does it with real failing tests, not expect.fail("TDD Red Phase") placeholders.

Why real red, not placeholder red

A naive TDD gate writes placeholder tests:

it("renders the cast button when the ability is in range", () => {
  expect.fail("TDD Red Phase: Implementation missing")
})

This is a false red. It proves nothing, gets fully rewritten at green, and — if anyone forgets to come back — leaves the feature with zero real coverage.

openspec-tdd writes a solid red instead:

import { AbilityCard } from "./ability-card" // ← does not exist yet → import = RED

it("renders the cast button when the ability is in range", () => {
  vi.mocked(usePartyAtom).mockReturnValue({ ap: 3, range: 2 } as never)
  const { screen } = render(<AbilityCard id="fireball" distance={1} />)
  expect(screen.getByTestId("ability-cast-btn")).toBeInTheDocument()
})

This fails for the right reason (the component / testid doesn't exist yet), defines the data-testid contract opsx:apply must satisfy, and turns green by implementing — no test rewrite. It guards against regressions from the very first commit.

What you get

A new opsx:tdd skill that:

• reads directly from specs/**/*.md — source of truth, not a parsed summary
• translates every #### Scenario: THEN clause into a real failing assertion
• runs the suite and confirms RED fails for the right reason (missing impl, not a typo)
• reports the new data-testid contract for the apply phase
• marks unreachable branches / unknowable values as honest it.skip gaps, never forced fails
• regenerates tests automatically when specs change — re-run and stay in sync

Installation

For Humans

Option 1: Let your agent do it (Recommended)

Copy and paste this prompt to your LLM agent (Claude Code, OpenCode, Cursor, etc.):

Install openspec-tdd by following the instructions here:
https://raw.githubusercontent.com/yuritoledo/openspec-tdd/main/README.md

Option 2: Manual Installation

Claude Code

/plugin marketplace add yuritoledo/openspec-tdd
/plugin install openspec-tdd@yuritoledo

OpenCode

git clone https://github.com/yuritoledo/openspec-tdd.git
cp -r openspec-tdd/plugins/openspec-tdd/skills/opsx-tdd ~/.config/opencode/skills/opsx-tdd

The skill is picked up automatically on the next OpenCode session.

Pi

Option A: With Claude Plugins (recommended if you use Claude Code):

pi install npm:pi-claude-plugins

Then install the plugin once in Claude Code:

/plugin install openspec-tdd@yuritoledo

Pi imports it automatically on subsequent runs.

Option B: Direct copy (no Claude Plugins required):

git clone https://github.com/yuritoledo/openspec-tdd.git
cp -r openspec-tdd/plugins/openspec-tdd/skills/opsx-tdd .pi/skills/opsx-tdd
rm -rf openspec-tdd

The skill is loaded automatically on the next session. Add skills: ["opsx-tdd"] to .pi/config.yaml if Pi doesn't pick it up.

The skill is named opsx:tdd in all three environments.

For LLM Agents

If you are an AI agent tasked with installing this plugin, follow these steps:

IMPORTANT: Do NOT run npm install or any package manager. This is a skill, not a package.

1. Claude Code — Instruct the user to run these slash commands in-chat:

   /plugin marketplace add yuritoledo/openspec-tdd
   /plugin install openspec-tdd@yuritoledo
   

2. OpenCode — Clone the repo and copy the skill to OpenCode's skill directory:

   git clone https://github.com/yuritoledo/openspec-tdd.git
   cp -r openspec-tdd/plugins/openspec-tdd/skills/opsx-tdd ~/.config/opencode/skills/opsx-tdd
   rm -rf openspec-tdd
   

3. Pi — Two options:

   Option A: With Claude Plugins

   pi install npm:pi-claude-plugins
   

   Then ask the user to run \/plugin install openspec-tdd@yuritoledo` in Claude Code once. Pi imports it automatically on subsequent runs.

   Option B: Direct copy (no Claude Plugins) Clone and copy the skill directory:

   git clone https://github.com/yuritoledo/openspec-tdd.git
   cp -r openspec-tdd/plugins/openspec-tdd/skills/opsx-tdd .pi/skills/opsx-tdd
   rm -rf openspec-tdd
   

4. Verify — The skill is named opsx:tdd in all environments. Inform the user that opsx:tdd has been installed and is ready to use.

Workflow

opsx:propose  →  opsx:tdd (this — solid red)  →  opsx:apply (green)  →  opsx:verify

Configuration

Zero config by default — the skill detects your test runner and conventions from CLAUDE.md/AGENTS.md and package.json (vitest, jest, bun test, or node:test). To pin them, drop a .openspec-tdd.json at your repo root (see examples/.openspec-tdd.json):

{
  "testRunner": "npx vitest run",
  "renderHelper": "@/test/render",
  "canonicalTest": "src/components/example.test.tsx",
  "testIdQuery": "getByTestId"
}

Docs

• examples/before-after.md — spec input → generated test → report
• Per-runner / non-React / e2e guidance lives in the skill's references/

Contributing

See CONTRIBUTING.md. Core rule: keep it solid-RED, never hardcode a stack.

License

MIT