Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lnardev/opencode-config-agent/llms.txt

Use this file to discover all available pages before exploring further.

Spec-Driven Development (SDD) is a structured workflow for making substantial code changes with AI assistance. Rather than asking an AI to “just write the feature,” SDD enforces a deliberate pipeline: explore the codebase, propose the change, design the architecture, write detailed specifications, break down tasks, implement, verify, and archive. This prevents the most common failure mode of AI-assisted coding — writing code without understanding the system — by requiring every change to pass through documented, reviewable phases before a single line is written. SDD is built directly into OpenCode as a set of coordinated sub-agents, each responsible for exactly one phase. A central sdd-orchestrator agent manages the pipeline, delegating all real work to the appropriate sub-agent while maintaining a thin context thread across the session.

​
The 9 Phases

AgentPhaseDescription
sdd-initInitializeBootstrap SDD context, detect stack, testing capabilities, and conventions
sdd-exploreExploreInvestigate codebase, research ideas, compare approaches — no files created
sdd-proposeProposeCreate a structured change proposal with scope, risks, and rollback plan
sdd-designDesignTechnical design with architecture decisions, sequence diagrams, and rationale
sdd-specSpecDetailed specifications using Given/When/Then scenarios and RFC 2119 keywords
sdd-tasksTasksBreak down specs into hierarchical, session-sized implementation tasks
sdd-applyApplyExecute code changes from task definitions, with TDD cycle when enabled
sdd-verifyVerifyValidate implementation against specs; reports CRITICAL / WARNING / SUGGESTION
sdd-archiveArchiveArchive all artifacts, sync delta specs, and close the change

​
Dependency Graph

Each phase builds on the artifacts produced by previous phases. Spec and Design can run in parallel once the Proposal exists; Tasks require both before proceeding. 
proposal ──► spec ─────┐
    │                  ▼
    └──► design ──► tasks ──► apply ──► verify ──► archive
sdd-explore is optional but recommended. Running it before /sdd-new gives the proposal phase richer context about the existing codebase.

​
Artifact Storage

SDD artifacts (proposals, specs, designs, tasks, apply progress, verify reports) are stored in one of four backends. The orchestrator asks which mode you prefer at the start of each session.
ModeDescriptionBest For
engram (default)Fast, no files created. Artifacts live in a local SQLite database. Cross-session via MCP. Re-running a phase overwrites the previous version.Solo work, quick iteration
openspecFile-based. Creates an openspec/ directory with a full artifact trail that is committable and shareable.Teams, PRs, audit trail
hybridBoth backends — files for team sharing, engram for cross-session recovery. Higher token cost per operation.Cross-session recovery + team sharing
noneReturns results inline only. No persistence. All artifacts lost when the conversation ends.One-off exploration

​
The Orchestrator Role

The sdd-orchestrator is the primary agent you interact with. Its role is strictly that of a coordinator — it maintains the session state, decides which sub-agent to launch next, passes the right artifact references into each delegation, and synthesizes results for you to review. It never does phase work inline. This design keeps the orchestrator’s context small and precise. Real work (reading large codebases, writing code, running tests) is always delegated to a dedicated sub-agent with a fresh context window.

​
Delegation Decision Table

The orchestrator uses this table to decide whether to act inline or delegate:
ActionInlineDelegate
Read 1–3 files to decide or verify✅—
Read 4+ files to explore or understand—✅
Read as preparation for writing—✅ (together with the write)
Write atomic (one file, already know what to write)✅—
Write with analysis (multiple files, new logic)—✅
Bash for state (git, gh)✅—
Bash for execution (test, build, install)—✅
The orchestrator never reads 4+ files to understand the codebase inline, writes features across multiple files inline, or runs tests and builds inline. These always inflate context without benefit and are always delegated.

​
Next Steps

Workflow

Phase-by-phase breakdown of what each sub-agent reads, writes, and produces

Commands

Full reference for all SDD slash commands — skills and meta-commands

Execution Modes

Configure interactive vs. automatic execution and artifact storage options

Build docs developers (and LLMs) love

Get started for freeTalk to us