Spec-Driven Development - OpenCode

Template to bootstrap projects with Spec-Driven Development and AI agents on OpenCode.

What is it?

A template to kickstart projects with Spec-Driven Development on OpenCode. It consists of:

Piece	Description
templates/	Generic skeleton with the full SDD system: agents, commands, constitution, and feature templates. Ready to copy into a new project.
scaffold.sh	Interactive script that copies the template to a directory, asks for name/description, and replaces placeholders.

What is SDD?

SDD (Spec-Driven Development) is a workflow where you design first, then agents execute. Before writing code, you create a specification that defines what to build, why, and how to verify it.

Workflow

/sdd:spec-create "description"  →  creates the spec
           ↓
       review and edit the spec manually
           ↓
   /sdd:spec-implement NNN      →  agent implements
           ↓
   code-writer implements  →  code-reviewer reviews  →  you see the report
           ↓
       you decide: apply improvements? mark as implemented?

Commands

Command	What it does
/sdd:init	Initializes the SDD system: fills in constitution, AGENTS.md, and opencode.json
/sdd:spec-create "desc"	Creates a new feature specification
/sdd:spec-implement NNN	Implements a feature (code-writer → code-reviewer → report)
/sdd:status	Shows project progress
/sdd:constitution [section]	Queries the project constitution
/question "question"	Contextual tutor to learn while building

Agents

Agent	Role
sdd-agent	Orchestrator: coordinates the SDD workflow
code-writer	Implements features according to the spec
code-reviewer	Reviews code against the spec and constitution
tutor	Explains concepts and project code

Key Principle

You design, agents execute. The constitution sets immutable rules that agents must follow. You make the decisions; agents execute them and report back.

Quick start

macOS / Linux / WSL / Git Bash

curl -fsSL https://raw.githubusercontent.com/maavcode/opencode-sdd-template/main/scaffold.sh | bash

Windows (CMD or PowerShell)

On Windows, bash is not available natively. Use one of these:

Option A — Git Bash (recommended, included with Git for Windows):

curl -fsSL https://raw.githubusercontent.com/maavcode/opencode-sdd-template/main/scaffold.sh | bash

Option B — Clone the repo, then run scaffold.sh from Git Bash:

git clone https://github.com/maavcode/opencode-sdd-template.git
cd opencode-sdd-template
./scaffold.sh

What the script does

It will ask you:

1. Where to create the project
2. Template language (English or Spanish)
3. Project name and description

After that, just open OpenCode in that directory and run /sdd:init to finish configuring it.

Languages

The template is available in two languages:

• en-template — everything in English (AGENTS, agents, commands, constitution)
• es-template — agents and commands in English, documentation and placeholders in Spanish

Both are functionally identical. The script will let you choose when you run it.

Structure

opencode-sdd-template/
├── README.md
├── LICENSE
├── .gitignore
├── scaffold.sh
└── templates/
    ├── en-template/          # English template
    │   ├── AGENTS.md
    │   ├── opencode.json
    │   └── .opencode/
    │       ├── agents/       # 4 agents (code-writer, code-reviewer, sdd-agent, tutor)
    │       ├── commands/     # 6 commands (question + 5 sdd/ commands)
    │       └── sdd/          # Specification system
    │           ├── README.md
    │           ├── constitution/    # mission, tech-stack, roadmap
    │           └── features/
    │               └── 000-template-task/   # Feature template
    └── es-template/          # Spanish template (same structure)

What's inside each part?

AGENTS.md — instructions for the main agent. Defines stack, commands, structure, and SDD workflow.

opencode.json — OpenCode configuration. Points instructions to AGENTS.md and the constitution.

.opencode/agents/ — 4 specialized agents:

• sdd-agent — orchestrator of the SDD workflow
• code-writer — implements features following the spec
• code-reviewer — reviews code against spec and constitution
• tutor — explains concepts using real project code

.opencode/sdd/constitution/ — immutable project rules:

• mission.md — what we build, who it's for, principles, constraints
• tech-stack.md — technologies, structure, commands, conventions
• roadmap.md — Implemented, In Review, To Do, Next, Backlog

.opencode/sdd/features/000-template-task/ — template for new features:

• spec.md — what, why, acceptance criteria, out of scope
• plan.md — approach, implementation, decisions, risks
• tasks.md — atomic, ordered tasks

License

MIT © Mario Aguilar Avila (@maavcode)