OpenCode Setup Guide

Personal reference for setting up OpenCode with spec-driven development tools.

This repo covers the shared OpenCode configuration (MCP servers, custom commands, skills) and integrations with two spec-driven workflow tools:

Tool	What it is	Install guide	Command reference
OpenSpec	Spec-driven dev via /opsx:* commands (Node.js)	openspec-install.md	openspec-commands.md
Spec-Kit	Spec-driven dev via /speckit.* commands (Python)	speckit-install.md	speckit-commands.md

Both tools follow the same philosophy: explore → specify → plan → implement → review. The shared OpenCode config works with either one.

---

Shared Prerequisites

• Node.js is required for the shared OpenCode config (repomix, memory, sequential-thinking)
• Docker is optional and only needed for shared /ast-* commands
• Python + uv are only needed if you are using Spec-Kit

---

Quick Start

1. Create the global OpenCode config directories:

   mkdir -p ~/.config/opencode/skills

2. Copy opencode.json to ~/.config/opencode/opencode.json (global config)
3. Copy the matching global AGENTS.md preset:
   • OpenSpec users: cp agents/openspec.md ~/.config/opencode/AGENTS.md
   • Spec-Kit users: cp agents/speckit.md ~/.config/opencode/AGENTS.md
4. Install skills (see below)
5. Follow the install guide for your spec tool (OpenSpec or Spec-Kit)

Project AGENTS.md remains an optional team-shared layer inside a repo. The presets in agents/ are personal global defaults for OpenCode.

---

Skills

Two review skills are included. Install them by symlinking into your OpenCode skills directory:

mkdir -p ~/.config/opencode/skills

# OpenSpec users
ln -sfn "$(pwd)/skills/spec-review" ~/.config/opencode/skills/spec-review

# Spec-Kit users
ln -sfn "$(pwd)/skills/spec-review-sk" ~/.config/opencode/skills/spec-review-sk

Skill	Purpose
spec-review	Post-implementation review for OpenSpec changes
spec-review-sk	Post-implementation review for Spec-Kit specs

Symlinks mean git pull automatically updates the skills.

See spec-review usage and spec-review-sk usage for details.

---

Config Files

File	Purpose	Install
opencode.json	Global config: MCP servers + custom commands	Copy to ~/.config/opencode/opencode.json
agents/openspec.md	Global AGENTS preset for OpenSpec workflows	Copy to ~/.config/opencode/AGENTS.md
agents/speckit.md	Global AGENTS preset for Spec-Kit workflows	Copy to ~/.config/opencode/AGENTS.md

---

Index

Document	What it covers
opencode-setup.md	MCP servers, tool design principles, workflow integration
openspec-install.md	Install OpenSpec, enable extended workflow profile, brownfield seeding
speckit-install.md	Install Spec-Kit, initialize in a project, write constitution
opencode-commands.md	All custom /repo-*, /ast-*, /gh-*, /c7-*, /mem-* commands and review skills
openspec-commands.md	All /opsx:* commands
speckit-commands.md	All /speckit.* commands
opencode-workflows.md	14 end-to-end workflows combining OpenCode with OpenSpec or Spec-Kit