opsx:tdd

Write real failing test files from a change's specs/**/*.md and confirm a solid RED — tests that exercise the true contract and fail only because the implementation is missing — before implementation begins. Never expect.fail("TDD Red Phase") placeholders: those prove nothing, get fully rewritten at green, and leave the feature with zero real coverage.

Reads directly from the canonical spec files. Re-run after a spec change and tests regenerate from source-of-truth automatically.

Input: Optionally specify a change name. If omitted, infer from conversation context or prompt.

Steps

1. Discover project conventions (do this first — never hardcode)

   This plugin runs in any repo. Detect the host project's testing setup, in priority order:

   1. .openspec-tdd.json at repo root, if present. Fields (all optional):

      {
        "testRunner": "npx vitest run",   // command to run a single test file
        "renderHelper": "@/test/render",  // import path for the project's custom render()
        "canonicalTest": "src/example.test.tsx", // a file to mirror for imports/mocks
        "testIdQuery": "getByTestId",     // how the project queries test ids
        "testFileGlob": "**/*.test.{ts,tsx}"
      }
      

   2. CLAUDE.md / AGENTS.md / .cursorrules — read for testing conventions, the canonical-reference test file, render-helper location, and selector rules.
   3. package.json — infer the runner from scripts.test / devDependencies (vitest → npx vitest run; jest → npx jest; bun → bun test; otherwise node --test). Infer React/Testing-Library presence from deps.
   4. Fallback defaults — bare vitest, plain testing-library render, getByTestId.

   Announce what you detected: "Runner: · Render helper: <path|none> · Canonical ref: <file|none>". See references/frameworks.md for per-runner commands and references/non-react.md / references/e2e.md for non-component scenarios.

2. Select the change

   If a name is provided, use it. Otherwise:

   • Infer from conversation context
   • Auto-select if only one active change exists
   • If ambiguous, run openspec list --json and use AskUserQuestion tool to let user select

   Announce: "Using change: "

3. Parse scenarios from specs

   find openspec/changes/<name>/specs -name "*.md" 2>/dev/null
   

   If no specs/**/*.md exist in the change, stop:

   "No spec files found in openspec/changes/<name>/specs/. Run opsx:propose first to generate specs with #### Scenario: blocks, then re-run /opsx:tdd."

   Parse every specs/**/*.md file. For each file:

   a. Extract scenarios — collect every #### Scenario: block with its parent ### Requirement: name and its WHEN / THEN lines.

   If a file has no #### Scenario: blocks, skip it and note it in the report.

   b. Derive the test file path — in priority order:

   1. design.md Implementation Map: scan openspec/changes/<name>/design.md for a markdown table with columns Capability, File (or similar). Extract the row matching this capability's name.

      | `ability-card` | `features/combat/AbilityCard.tsx` | `AbilityCard` |
      

   2. design.md file path mentions: scan design.md for any .ts / .tsx paths that mention the capability name or a related module.
   3. Project search: find . \( -name "*.ts" -o -name "*.tsx" \) | grep -v node_modules | grep -i <capability> — pick the best match (non-test file).
   4. Prompt the user: use AskUserQuestion with the capability name and a list of candidate paths found. Never guess silently.

   Test file = implementation file path with .test.ts / .test.tsx extension, same directory. Example: features/combat/AbilityCard.tsx → features/combat/AbilityCard.test.tsx.

   c. Translate THEN clauses to assertion intent — for each scenario, capture the full THEN text. Step 4 uses this to write the real assertion body.