opencode-sdd

You describe what you want in vague terms. The plugin produces a complete, validated development plan — PRD, issues, implementation plans, and validation reports — with every phase running in a clean, isolated session.

Table of Contents

• The Problem
• The Solution
• Install
• The SDD Short Flow
• The PRD Long Flow
  • Auto-Implement
• Keeping Documentation Current
• Honorable Mentions
• Additional Resources

The Problem

AI coding agents are great at writing code, but they're terrible at planning code. You tell an agent “build a payment system” and it starts typing without requirements, architecture, or validation. By the time you realize it built the wrong it built the wrong thing, you’ve burned a session full of context and a pile of tokens.

The Solution

opencode-sdd is a tool that let's you have a proper workflow: plan everything before you build anything.

Install

Add opencode-sdd to the plugin array in your project's opencode.json (or opencode.jsonc):

{
    "$schema": "https://opencode.ai/config.json",
    "plugin": ["opencode-sdd"]
}

opencode installs the plugin from npm on startup. Restart opencode (or start a new session) to load it; the /sdd-*, /prd-* and /doc-* commands become available immediately.

The SDD Short Flow

For a small change you can analyze, implement, and verify in three commands. Each command runs with your current agent — no dedicated orchestrator is required.

1. Describe the change and produce a lightweight plan.
2. Implement the plan's tasks following the TDD flow.
3. Validate the result and write a report.

• /sdd-spec — analyze a problem and write SPECS_DIR/spec.md (problem analysis, affected files, proposed solution, and tasks).
• /sdd-implement — run the tasks defined in spec.md using the TDD flow (write failing test → verify failure → implement → verify pass).
• /sdd-validate — validate the implementation and write SPECS_DIR/validation.md.

If /sdd-validate reports an incomplete implementation, loop: /sdd-implement → /sdd-validate → /sdd-implement → /sdd-validate. Each revision marks the validation's issues as resolved and sets the overall status to Revised; re-run /sdd-validate until the overall status is Complete.

SPECS_DIR defaults to .sdd/.current/.

It's up to you whether you want to keep that directory in source control.

The PRD Long Flow

For a larger feature, drive requirements through validated implementation in six steps (plus an optional plan review). Each step runs in a clean session and produces the next artifact.

1. Write a product spec from a feature description.
2. Break the spec into independent vertical-slice issues.
3. Plan a single issue.
4. (Optional) Review that issue's plan before implementing it.
5. Implement that issue's plan.
6. Validate that issue against its plan.
7. Cross-validate every implemented issue.

• /prd-write — produce SPECS_DIR/prd.md from a feature description.
• /prd-to-issues — write vertical-slice issues under SPECS_DIR/issues/.
• /prd-issue-to-plan — write a plan for one issue.
• /prd-review-plan — (optional) review a plan across six dimensions; writes review.md and sets the plan's status to Approved or Needs Revision.
• /prd-implement-issue — run one issue's plan.
• /prd-validate-issue — validate one issue against its plan.
• /prd-validate — cross-validate all implemented issues and write SPECS_DIR/validation.md.

The two quality gates are iterative — you loop on them until the artifact passes:

• Plan review loop — /prd-issue-to-plan → /prd-review-plan → /prd-issue-to-plan → /prd-review-plan … Each revision marks the review's findings as resolved and sets the verdict to Revised; re-run /prd-review-plan until the verdict is Approved.
• Implementation validation loop — /prd-implement-issue → /prd-validate-issue → /prd-implement-issue → /prd-validate-issue … Each revision marks the validation's issues as resolved and sets the overall status to REVISED; re-run /prd-validate-issue until the overall status is COMPLETE.

Auto-Implement

Once the PRD and its issues exist (steps 1–2 above), /prd-auto-implement orchestrates the rest in a single session on the sdd-build orchestrator: it plans, reviews, implements, and validates every issue in numeric order, then runs the cross-cutting validation. It hard-stops if the PRD or issues are missing. Each review, validation, and cross-cutting loop is capped at MAX_ATTEMPTS (default 3) and escalates to you when it can't converge; re-running it after an interruption (crash, stop, or escalation) resumes where it left off without redoing completed work.

• /prd-auto-implement — orchestrate the full PRD implementation end-to-end. SPECS_DIR (default .sdd/.current/) sets where specs live; MAX_ATTEMPTS (default 3) caps every loop.

The full run can take hours depending on the number of issues. A HITL issue records its human decisions in a ## Human Decisions section, each tagged before-planning or before-implementation. The planner (prd-issue-to-plan) owns HITL: it asks those decisions at their gate (before-planning before it writes the plan, before-implementation after), and records your answers back in the issue. Under /prd-auto-implement it surfaces the questions to you, records your answers, and re-dispatches the planner. AFK issues proceed without asking.

Keeping Documentation Current

The doc-* commands update the project's standard documentation files to match the codebase. Run them after a change that affects the corresponding file.

• /doc-readme — update README.md to stay a user manual.
• /doc-development — update DEVELOPMENT.md (build and debug guide).
• /doc-deployment — update DEPLOYMENT.md.
• /doc-agents — update AGENTS.md (guidelines and project structure).
• /doc-changelog — add the Unreleased entry to CHANGELOG.md.

Honorable Mentions

• ascii-gif — used to generate the demo GIF in this README.
• spec-kit — this project was originally inspired by GitHub's Spec Kit, but is essentially a simplified version of it.

Additional Resources

• AGENTS.md — code guidelines, project structure, and the plugin surface contract.
• DEVELOPMENT.md — build and debug guide.
• CHANGELOG.md — release history.
• docs/e2e.md — how the mock-LLM e2e suite works, including the template-rewriting mechanism.