Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
An OpenSpec and OpenCode template with the proposal -> specs -> design -> adr -> tasks workflow enabled, plus optional collaboration workflows for teams that choose to adopt them.
Read the full walkthrough: Spec-Driven Development with OpenSpec and OpenCode.
Read the full walkthrough: SDD with Multi-Model Spec Review and Glossary
Clone this repository, open it with OpenCode, and start working from the bundled OpenSpec configuration, commands, skills, and schema.
Open your existing project with OpenCode and ask it to install the template:
Read and understand https://raw.githubusercontent.com/intent-driven-dev/intent-driven-template/refs/heads/main/INSTALL_TEMPLATE.md and follow the instructions there.
- OpenSpec for setup, proposal, specification, design, ADR, and task artifacts.
- Custom schemas from https://github.com/intent-driven-dev/openspec-schemas.
- A bundled local copy of the intent-driven custom schema from https://github.com/intent-driven-dev/openspec-schemas/tree/main/openspec/schemas/intent-driven for the full proposal -> specs -> design -> adr -> tasks lifecycle.
- OpenSpec git discipline so proposals land on main before apply, and implementation lands on main before archive.
- OpenCode skills for repeatable collaboration and implementation workflows, including C4 diagrams, ADR authoring, and OpenSpec lifecycle commands.
- Superpowers from https://github.com/obra/superpowers for guided practices such as brainstorming, planning, debugging, verification, worktrees, and subagent-driven parallel work.
- Superpowers can be disabled by removing the superpowers@git+https://github.com/obra/superpowers.git entry from the plugin array in opencode.json, then restarting OpenCode.
- A bundled test-driven-development skill plus senior-dev and senior-qa subagents in .opencode/agent/ for test-first implementation and acceptance-test work, routed via the context block in openspec/config.yaml.
- A grill-me style of rigorous design interrogation, inspired by https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md.
- ADRs for durable architectural decisions.
- C4 diagrams for communicating architecture boundaries and relationships.
- Gherkin-style requirements and scenarios for observable behaviour.
The bundled OpenSpec schema is a local copy of the intent-driven schema from https://github.com/intent-driven-dev/openspec-schemas/tree/main/openspec/schemas/intent-driven.
The intent-driven workflow moves through these artifacts in order:
proposal -> specs -> design -> adr -> tasks
- proposal captures why the change matters.
- specs describe observable behaviour with Gherkin-style scenarios.
- design explains the implementation approach and trade-offs.
- adr records durable architectural decisions.
- tasks turn the accepted intent, behaviour, design, and decisions into work.
openspec/config.yaml already selects the bundled intent-driven schema. Learn how to tailor artifact workflows in OpenSpec Custom Schemas.
Standard OpenSpec lifecycle skills in .opencode/skills/ — names are self-explanatory: openspec-new-change, openspec-propose, openspec-continue-change, openspec-explore, openspec-apply-change, openspec-verify-change, openspec-sync-specs, openspec-archive-change
| Skill | Location | Purpose | Enabled Or Updated By |
|---|---|---|---|
| openspec-bulk-apply-change | .opencode/skills/ | Applies multiple active changes concurrently in isolated worktrees with parallel verification. | Invoke directly with /opsx:bulk-apply command when applying multiple active openspec changes. |
| adversarial-authoring | .opencode/skills/ | Runs author and reviewer agents in sequence to reduce model bias in drafts. | Refer to the skill under rule in the rules section of openspec/config.yaml. |
| grill-me | .agents/skills/ | Interrogates plans and designs with probing questions to surface hidden assumptions. | Refer to this skill under rules section in openspec/config.yaml. |
| c4-diagrams | .agents/skills/ | Visualises system architecture using C4 model levels in ASCII or Mermaid. | Refer to this skill under design rule in openspec/config.yaml. |
| architectural-decision-records | .agents/skills/ | Captures architectural decisions with rationale, tradeoffs, and supersession chains. | Automatically invoked or can be explicilty referred to under adr rule in openspec/config.yaml. |
| gherkin-authoring | .agents/skills/ | Drafts and improves Gherkin scenarios for observable, domain-language behaviour. | Required by spec-as-source during the specs phase. |
| glossary | .agents/skills/ | Maintains business and technical terminology and companion glossary references for specification artifacts. | Can be referred to under proposal and/or design rule in openspec/config.yaml. |
| openspec-git-discipline | .agents/skills/ | Enforces that proposals reach main before apply, and implementation merges before archive. | Enabled through AGENTS.md. |
| spec-as-source | .agents/skills/ | Adds executable acceptance specifications to the intent-driven workflow. | Explicitly opt in by uncommenting both the specs and tasks rules in openspec/config.yaml. |
| acceptance-test-authoring | .agents/skills/ | Configures the acceptance runner, extraction, linting, and step definitions for spec-as-source. | Required by spec-as-source when configuring or changing acceptance-test infrastructure. |
| test-driven-development | .agents/skills/ | Guides strict red-green-refactor TDD: one behaviour per test, minimal implementation to pass, refactoring on green, with best-practice patterns and collaborator mocking guidance. | Loaded by the senior-dev agent in .opencode/agent/senior-dev.md; enable by uncommenting the context lines in openspec/config.yaml that route src work to senior-dev. |
Example configurations are available in openspec/config.yaml and AGENTS.md. You can comment/uncomment the skill references to enable them.
The spec-as-source skill is an opt-in layer on the intent-driven schema that uses fenced Gherkin in OpenSpec specifications as the source for generating acceptance tests. To enable spec-as-source capability add the skill reference under both the specs and tasks rules in openspec/config.yaml.
During specs, spec-as-source requires gherkin-authoring to author the fenced Gherkin scenarios. During tasks, it replaces the standard task template with acceptance-test-first work: configure and run the acceptance suite, then implement application work. Use acceptance-test-authoring to configure the runner, extraction, linting, and step definitions that execute the specifications. See Behavior-Driven Development and Spec-Driven Development with OpenSpec.
- Template overview: Spec-Driven Development with OpenSpec and OpenCode
- Schema customization: OpenSpec Custom Schemas
- Durable architecture: Architectural Decision Records with Spec-Driven Development using OpenSpec
- Multi-model review and glossary: SDD with Multi-Model Spec Review and Glossary
- Parallel implementation: OpenSpec, Git WorkTrees and OpenCode
- Spec-As-Source Spec-Driven Development: Behavior-Driven Development and Spec-Driven Development with OpenSpec
- Brownfield adoption: Spec-Driven Development with Brownfield Projects
- SDD + BDD + TDD: How TDD and BDD Actually Fit Into Spec-Driven Development
Specialist agents used within skills, in .opencode/agent/:
| Agent | Purpose |
|---|---|
| adversarial-author | Writes an initial draft of a specification artifact or design document. |
| adversarial-reviewer | Reviews the author's draft with challenges and improvement suggestions. |
| senior-dev | Implements src work test-first through strict red-green-refactor, following the test-driven-development skill. |
| senior-qa | Authors acceptance tests, step definitions, and runner configuration, following the acceptance-test-authoring skill. |