OpenCode TDD Plugins

A suite of four modular OpenCode plugins for test-driven development: spec-refiner, tdd-workflow, build-workflow, and pr-agent. Use them independently or chain them together for a complete feature-delivery pipeline.

Installation

# macOS / Linux / Git Bash on Windows
./install.sh           # installs to ~/.config/opencode/
./install.sh project   # installs to .opencode/ in current project

# Windows PowerShell
.\install.ps1
.\install.ps1 -Mode project

Requires OpenCode and bun or npm for compiling custom tool files.

---

Plugin: spec-refiner

Takes a raw feature request and transforms it into a structured specification. Asks clarifying questions, identifies edge cases, and writes a dated spec file to specs/.

Command: /refine

# Colon syntax — name extracted before the colon
/refine char-freq: build a C# API that counts character occurrences in a string

# No colon — agent asks you for a name
/refine build a C# API that counts character occurrences in a string

Output: A spec file at specs/YYYY-MM-DD_NNN_feature-name.md with sections for Summary, Inputs, Outputs, Behavior, Examples, and Acceptance Criteria.

---

Plugin: tdd-workflow

Orchestrates a full TDD cycle: coverage analysis → RED (failing tests) → GREEN (implementation loop) → REFACTOR. Handles partially implemented features by classifying items as IMPLEMENTED, STUBBED, or MISSING.

Command: /tdd

# With a spec file reference
/tdd specs/2026-05-14_001_char-freq.md

# With short name (auto-resolved via glob)
/tdd char-freq

# With raw description (no spec)
/tdd build a C# API that sums a list of numbers

Workflow phases:

1. Locate spec — explicit path, glob short name, list specs/ directory, fall back to spec.md, or use raw description
2. Coverage analysis — scans codebase, classifies each item as IMPLEMENTED/STUBBED/MISSING
3. Detect existing tests — finds relevant tests for STUBBED/MISSING items
4. RED — spawns @test-writer, @test-reviewer, calls validate-red
5. GREEN — iteration loop (default 5): checkpoint → @implementer → run-tests → evaluate-progress
6. REFACTOR — spawns @refactorer, verifies tests still pass

---

Plugin: build-workflow

Chains spec-refiner and tdd-workflow sequentially: refines a specification, then implements it via TDD. On success, optionally spawns pr-agent to create a draft GitHub PR.

Command: /build

# Colon syntax — refines spec, then implements
/build char-freq: build a C# API that counts character occurrences in a string

# Reference an existing spec — skips refinement
/build specs/2026-05-14_001_char-freq.md

---

Plugin: pr-agent

Creates a draft GitHub Pull Request from local changes. Auto-detects changed files from git history (no file list required). Commits them to a feature branch (feat/<name>), pushes to GitHub, and opens a draft PR with the automatically-generated label.

Command: /pr

# Simple usage — detects changes from git automatically
/pr my-feature-name

# With optional spec context for richer PR body
/pr Spec path: specs/2026-05-14_001_char-freq.md Feature name: char-freq

Integration: Spawned automatically by /build after a successful TDD cycle (with user confirmation).

Authentication (one of the following):

1. OAuth device flow (recommended): Set GITHUB_CLIENT_ID to your GitHub OAuth App's Client ID (create one at https://github.com/settings/developers — no callback URL needed for device flow). The tool will open a browser prompt on first use and cache the token.

2. Personal access token: Set GITHUB_TOKEN with repo and pull-requests scopes.

Workflow:

1. Validates git remote and determines the feature name
2. Auto-detects changed files from git status and git history
3. Creates feature branch feat/<feature-name>
4. Stages all detected changed files (plus spec file if available)
5. Presents the planned commit and asks for user confirmation
6. On confirmation: commits, pushes, and creates a draft PR

---

Example: Building a C# Sum Endpoint

A session running the TDD workflow for a C# API that sums a list of numbers.

User invokes /tdd

/tdd I want to create a new application in C# that hosts a single endpoint.
That endpoint should take a list of numbers and return their sum.

What happens

Phase 1 — Locate spec: No spec file found, so the workflow uses the raw description.

Phase 2 — Coverage analysis: The project directory is empty — everything is MISSING. The analysis reports:

## Coverage Report
### MISSING (needs stubs + implementation)
- C# project with .csproj and Program.cs — nothing found
- Sum endpoint accepting a list of numbers — nothing found
- Controller/endpoint returning the sum — nothing found

Phase 3 — Detect existing tests: No test files found — proceeding to generate new ones.

Phase 4 — RED:

[PROGRESS] Generating tests (RED)...

• @test-writer creates a C# project with xUnit tests and stub implementations
• @test-reviewer verifies test quality
• validate-red confirms all tests fail against stub code

Phase 5 — GREEN implementation loop:

[PROGRESS] Iteration 1/5: Creating checkpoint...
[PROGRESS] Iteration 1/5: Spawning implementer...
[PROGRESS] Iteration 1/5: Running tests...

The implementer wires up the endpoint logic. On the first iteration, tests pass.

Phase 6 — REFACTOR:

[PROGRESS] Refactoring...

Refactorer cleans up code structure. Final test run confirms everything passes.

Result

## TDD Workflow Summary
- Feature: C# API with sum endpoint
- Coverage report: IMPLEMENTED: 0, STUBBED: 0, MISSING: 3
- New tests written: SumEndpoint.Tests/SumEndpointTest.cs
- Items implemented: C# project scaffold, sum calculation logic, endpoint binding
- Iterations: 1
- Result: SUCCESS
- Details: Created a .NET web API with a POST /sum endpoint. The endpoint
  accepts a JSON body containing a list of integers and returns their sum.
  Includes input validation for null/empty lists.

---

Architecture

                    ┌─────────────────────────┐
                    │      build-workflow      │  (orchestrator)
                    │     /build command       │
                    └──────┬──────────┬────────┘
                           │          │
                    ┌──────┘          └──────────┐
                    ▼                             ▼
           ┌──────────────────┐       ┌──────────────────────┐
           │   spec-refiner    │       │    tdd-workflow      │
           │  /refine command  │       │    /tdd command      │
           │                   │       │                      │
           │  Writes specs/    │       │  Agents:             │
           │  *.md files       │       │  test-writer         │
           └──────────────────┘       │  test-reviewer        │
                                      │  implementer          │
                                      │  refactorer           │
                                      │                      │
                                      │  Tools:              │
                                      │  run-tests           │
                                      │  parse-failures      │
                                      │  evaluate-progress   │
                                      │  validate-red        │
                                      │  checkpoint          │
                                      └──────────┬───────────┘
                                                 │ (on SUCCESS)
                                                 ▼
                                      ┌──────────────────────┐
                                      │      pr-agent         │
                                      │     /pr command       │
                                      │                      │
                                      │  Commits spec + code │
                                      │  Pushes feature br.  │
                                      │  Creates draft PR    │
                                      │  Auto-generates      │
                                      │  label               │
                                      └──────────────────────┘