OpenCode Installation

OpenCode provides full sub-agent support via its Task tool, plus native slash command support. This is one of the most feature-complete installations.

Prerequisites

OpenCode installed and configured
Git installed for cloning the repository
Access to ~/.config/opencode/ directory

Installation Steps

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite

Run the installer

./scripts/install.sh
# Choose option 2: OpenCode

./scripts/install.sh --agent opencode

This installs:

Skills to ~/.config/opencode/skills/sdd-*/
Commands to ~/.config/opencode/commands/sdd-*.md

You should see output like:

Installing skills for OpenCode...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ~/.config/opencode/skills

Installing OpenCode commands...
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-new
  ✓ sdd-continue
  ✓ sdd-ff
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  8 commands installed → ~/.config/opencode/commands

Add orchestrator agent config

ACTION REQUIRED: Without this step, /sdd-* commands won’t work.

Open your OpenCode config:

code ~/.config/opencode/opencode.json

Merge the agent block from examples/opencode/opencode.json into your existing config.

View agent configuration

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "sdd-orchestrator": {
      "mode": "all",
      "description": "SDD Orchestrator - delegates spec-driven development to sub-agents",
      "prompt": "SPEC-DRIVEN DEVELOPMENT (SDD) ORCHESTRATOR\n...\n",
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": true
      }
    }
  }
}

You can either:

Add to existing agent: Append SDD instructions to your primary agent’s prompt
Create dedicated agent: Copy sdd-orchestrator definition as-is

Recommended: Keep your everyday agent (e.g., gentleman) as primary, and add sdd-orchestrator as a separate agent with mode: "all". Switch between them using the agent picker (Tab).

Verify installation

Start OpenCode in any project:

opencode .

Use the agent picker (Tab key) and select sdd-orchestrator.Type:

/sdd-init

Expected response:

Launching sdd-init sub-agent to bootstrap project context...
✓ Detected stack: [your project's stack]
✓ SDD initialized

Configuration Locations

Skills

~/.config/opencode/skills/sdd-*/9 skill folders + _shared/ conventions

Commands

~/.config/opencode/commands/sdd-*.md8 slash command definitions

Agent Config

~/.config/opencode/opencode.jsonOrchestrator agent configuration

Agent Configuration Options

Option 1: Dedicated SDD Agent (Recommended)

{
  "agent": {
    "gentleman": {
      "mode": "primary",
      "description": "Your everyday coding assistant",
      "prompt": "..."
    },
    "sdd-orchestrator": {
      "mode": "all",
      "description": "SDD Orchestrator",
      "prompt": "[SDD orchestrator instructions]"
    }
  }
}

Usage:

Use Tab to switch to sdd-orchestrator when starting SDD workflows
Use Tab to switch back to gentleman for day-to-day coding

Option 2: Combined Agent

{
  "agent": {
    "gentleman": {
      "mode": "primary",
      "description": "Coding assistant with SDD support",
      "prompt": "[Your existing prompt]\n\n[SDD orchestrator instructions]"
    }
  }
}

Usage:

All capabilities available in one agent
No need to switch agents

Slash Commands

OpenCode’s native slash command support makes SDD commands discoverable:

Command	File	Purpose
`/sdd-init`	`~/.config/opencode/commands/sdd-init.md`	Initialize SDD context
`/sdd-explore`	`~/.config/opencode/commands/sdd-explore.md`	Investigate an idea
`/sdd-new`	`~/.config/opencode/commands/sdd-new.md`	Start a new change
`/sdd-continue`	`~/.config/opencode/commands/sdd-continue.md`	Run next phase
`/sdd-ff`	`~/.config/opencode/commands/sdd-ff.md`	Fast-forward planning
`/sdd-apply`	`~/.config/opencode/commands/sdd-apply.md`	Implement tasks
`/sdd-verify`	`~/.config/opencode/commands/sdd-verify.md`	Validate implementation
`/sdd-archive`	`~/.config/opencode/commands/sdd-archive.md`	Archive completed change

Commands are auto-discovered by OpenCode. Type / to see all available commands.

Example Usage

Switch to SDD Orchestrator

# Press Tab key in OpenCode
# Select: sdd-orchestrator
# Confirm selection

Initialize SDD

You: /sdd-init

Orchestrator: Launching sdd-init sub-agent...
              ✓ Detected stack: Next.js + TypeScript + Prisma
              ✓ Project: my-saas
              ✓ Artifact store: engram (Engram detected)
              
              SDD initialized. Ready to start building.

Start a New Feature

You: /sdd-new add-user-profiles

Orchestrator: Launching explorer sub-agent...
              ✓ Current auth: NextAuth.js with JWT
              ✓ User model: id, email, name (basic fields)
              ✓ No profile routes detected
              
              Launching proposal sub-agent...
              ✓ Proposal created: sdd/add-user-profiles/proposal
              
              Summary:
              - Add user profile pages with bio, avatar, social links
              - Scope: Profile model extension, upload handling, UI routes
              - Rollback: Drop profile fields, remove upload bucket
              
              Ready to continue with specs and design?

Fast-Forward Planning

You: /sdd-ff add-user-profiles

Orchestrator: Running all planning phases...
              
              ✓ Specs: 5 requirements, 12 scenarios
              ✓ Design: Profile schema, S3 uploads, tRPC endpoints
              ✓ Tasks: 4 phases, 11 tasks
              
              All planning complete. Run /sdd-apply to implement.

How Sub-Agent Delegation Works

OpenCode’s Task tool enables fresh-context sub-agents:

// Orchestrator launches sub-agent
Task(
  subagent_type: 'general',
  prompt: `
    Read the skill at ~/.config/opencode/skills/sdd-propose/SKILL.md
    and follow its instructions to create a proposal for: add-user-profiles
    
    Context:
    - Project: my-saas
    - Stack: Next.js + TypeScript + Prisma
    - Artifact store: engram
  `
)

Each sub-agent:

Starts with fresh context (no orchestrator history)
Reads skill instructions from file
Executes phase work (analyze code, write specs, implement, etc.)
Returns structured result to orchestrator
Orchestrator shows summary and asks user to proceed

Artifact Storage

engram (Recommended)
openspec
none

# Auto-detected if Engram MCP server is available
artifact_store:
  mode: engram

Benefits:

Repository stays clean (no openspec/ directory)
Persistent across projects
Fast search and recovery
Automatic deduplication

Naming convention:

title:     sdd/add-user-profiles/proposal
topic_key: sdd/add-user-profiles/proposal
type:      architecture
project:   my-saas

# Only when you explicitly request file artifacts
artifact_store:
  mode: openspec

Structure:

openspec/
├── config.yaml              # Project context
├── specs/                   # Current system specs
└── changes/
    ├── add-user-profiles/   # Active change
    │   ├── proposal.md
    │   ├── specs/          # Delta specs
    │   ├── design.md
    │   └── tasks.md
    └── archive/            # Completed changes

# Ephemeral mode - no persistence
artifact_store:
  mode: none

Results returned inline. No files written. Good for:

Quick exploration
Privacy-sensitive projects
CI/CD environments

Verification Checklist

Check skills directory

ls ~/.config/opencode/skills/sdd-*/

Should show 9 directories + _shared/:

_shared/
sdd-apply/  sdd-design/  sdd-init/  sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/

Check commands directory

ls ~/.config/opencode/commands/sdd-*.md

Should show 8 command files:

sdd-apply.md  sdd-continue.md  sdd-ff.md  sdd-new.md
sdd-archive.md  sdd-explore.md  sdd-init.md  sdd-verify.md

Verify agent config

cat ~/.config/opencode/opencode.json | grep sdd-orchestrator

Should return match if agent is configured.

Test in OpenCode

opencode .
# Press Tab → select sdd-orchestrator
# Type: /sdd-init

Should recognize command and launch sub-agent.

Troubleshooting

Command not found

Problem: /sdd-init shows “command not found”Solutions:

Check commands are in ~/.config/opencode/commands/sdd-*.md
Restart OpenCode to reload command index
Verify file permissions allow reading
Try typing / to see if other commands appear

Agent not available

Problem: sdd-orchestrator doesn’t appear in agent pickerSolutions:

Verify agent definition in ~/.config/opencode/opencode.json
Check JSON syntax is valid (no trailing commas)
Ensure mode: "all" or mode: "primary" is set
Restart OpenCode

Sub-agent doesn't launch

Problem: Commands run inline instead of launching sub-agentsSolutions:

Verify orchestrator prompt mentions Task tool
Check skill paths in agent config: ~/.config/opencode/skills/sdd-*/SKILL.md
Ensure OpenCode version supports Task tool
Review orchestrator instructions: should explicitly use Task tool

Artifacts not saving

Problem: Results shown but not persistedSolutions:

Check artifact_store mode in orchestrator output
If engram mode: verify Engram MCP server is running
If openspec mode: check write permissions in project directory
If none mode: persistence is intentionally disabled

Next Steps

Quick Start

Learn the SDD workflow

Commands Reference

Complete command documentation

Agent Configuration

Advanced agent setup options

Engram Integration

Set up recommended persistence

Get Started

Installation

Guides

Commands

Prerequisites

Installation Steps

Configuration Locations

Skills

Commands

Agent Config

Agent Configuration Options

Option 1: Dedicated SDD Agent (Recommended)

Option 2: Combined Agent

Slash Commands

Example Usage

Switch to SDD Orchestrator

Initialize SDD

Start a New Feature

Fast-Forward Planning

How Sub-Agent Delegation Works

Artifact Storage

Verification Checklist

Troubleshooting

Next Steps

Quick Start

Commands Reference

Agent Configuration

Engram Integration

​Prerequisites

​Installation Steps

​Configuration Locations

Skills

Commands

Agent Config

​Agent Configuration Options

​Option 1: Dedicated SDD Agent (Recommended)

​Option 2: Combined Agent

​Slash Commands

​Example Usage

​Switch to SDD Orchestrator

​Initialize SDD

​Start a New Feature

​Fast-Forward Planning

​How Sub-Agent Delegation Works

​Artifact Storage

​Verification Checklist

​Troubleshooting

​Next Steps

Quick Start

Commands Reference

Agent Configuration

Engram Integration

Prerequisites

Installation Steps

Configuration Locations

Agent Configuration Options

Option 1: Dedicated SDD Agent (Recommended)

Option 2: Combined Agent

Slash Commands

Example Usage

Switch to SDD Orchestrator

Initialize SDD

Start a New Feature

Fast-Forward Planning

How Sub-Agent Delegation Works

Artifact Storage

Verification Checklist

Troubleshooting

Next Steps