OpenCode Workflow Configuration

Production-ready OpenCode config combining custom agents, composable skills, reusable commands, custom tools, ambient instruction files, and Serena integration. Covers Go, Python, TypeScript, Kubernetes, Helm, Kustomize, Ansible, and GitHub Actions. Language-agnostic code workflows with a single brainstorm-plan-code-review-validate pipeline.

---

Quick Start

git clone <your-repo-url>
cd opencode-configurations
chmod +x install.sh
./install.sh

Installs to ~/.config/opencode/. First command to run:

/bootstrap

Then try:

/brainstorm add priority field to task model
/plan-change add priority field
/apply-change add priority field

---

Project Structure

opencode/
├── opencode.json          # Main configuration
├── AGENTS.md              # Global behavior and Serena policy
├── agents/                # 6 custom subagents
├── commands/              # 29 reusable workflow commands
├── skills/                # 28 composable execution units
├── tools/                 # 7 custom TypeScript tools
└── instructions/          # 7 ambient context files
examples/                  # Workflow prompts and expected outputs
install.sh                 # Portable installer

---

Components Overview

Component	Role
Agents	Who executes — specialized subagents for builder, review, debug, and platform tasks
Skills	How tasks are performed — composable units loaded on demand
Commands	Entry points — slash commands for common workflows
Tools	Structured operations — testing, linting, git, and config validation
Instructions	Ambient context — always-loaded language and convention guides

---

Agents

Agent	Role	Mode	Tier
builder	Code implementation with validation	primary	Performance
code-reviewer	Code review for correctness, safety, and test coverage	subagent	Balanced
incident-debugger	Incident triage and root-cause analysis	subagent	Balanced
platform-reviewer	K8s, Helm, Kustomize, Ansible, GitHub Actions, and platform review	subagent	Balanced
observability-reviewer	Metrics, logs, traces review	subagent	Balanced
ansible-reviewer	Ansible playbook, role, and inventory review	subagent	Balanced

---

Commands

Session

Command	Description
/bootstrap	Initialize Serena session and summarize repository context

Code Workflow

Command	Description
/brainstorm	Explore approaches, tradeoffs, and alternatives before planning
/plan-change	Plan a code change (language-agnostic, includes refactors)
/apply-change	Implement a code change with TDD (language-agnostic, includes refactors)
/code-review	Review code changes for correctness, style, safety, and test coverage
/validate	Run full validation pipeline (tests, lint, vulnerabilities)

Debugging

Command	Description
/debug-investigate	Investigate a bug without modifying files
/debug-fix	Implement a fix for an investigated bug (language-agnostic)

Ansible

Command	Description
/plan-ansible	Plan an Ansible change without modifying files

Review

Command	Description
/platform-review	Review Kubernetes and platform configuration (broad)
/ansible-review	Review Ansible playbooks and roles
/helm-review	Review Helm charts
/kustomize-review	Review Kustomize overlays
/gha-review	Review GitHub Actions workflows

Memory

Command	Description
/memory-list	List Serena memories
/memory-read	Read specific memories
/memory-write	Write approved memory
/memory-edit	Edit, rename, or move an existing memory
/memory-delete	Delete a memory
/memory-cleanup	Analyze memories for staleness, duplicates, and propose new ones

Config Authoring

Command	Description
/agent-draft	Draft a new agent definition
/agent-create	Create and save a new agent
/command-draft	Draft a new command
/command-create	Create and save a new command
/skill-draft	Draft a new skill
/skill-create	Create and save a new skill
/draft-agents	Draft AGENTS.md for a repository
/registry-index	Index skills, agents, and commands
/validate-config	Validate config structure and references

---

Custom Tools

Tool	Description
config-validator	Validate skills, agents, and commands structure
config-validator-cli	Standalone CLI for CI validation
test-runner	Run tests with structured results and coverage (Go, Python, TS)
lint-runner	Run linters with structured output (Go, Python, TS)
git-context	Structured git state in one call
dependency-check	Check outdated and vulnerable dependencies
serena-health	Check Serena MCP server readiness

---

Instructions

File	Description
common.md	Commit format, branch naming, PR conventions, workflow principles
model-tiers.md	Three-tier model strategy and provider setup guide
go.md	Go toolchain and conventions
python.md	Python toolchain, pytest, ruff, type hints
typescript.md	TypeScript toolchain, strict mode, Zod, MCP conventions
kubernetes.md	K8s validation, Helm, Kustomize, manifest conventions
ansible.md	Ansible toolchain, idempotency, vault, Molecule

---

Workflows

Code Workflow (any language)

/brainstorm → /plan-change → /apply-change → /code-review → /validate

The workflow is language-agnostic. Language detection is automatic — toolchain and conventions come from instruction files (go.md, python.md, typescript.md).

Bug Workflow

/debug-investigate → /debug-fix → /validate

Other Workflows

Workflow	Example
Session bootstrap	examples/bootstrap-session.md
Platform and infra review	examples/platform-review.md
Ansible review	examples/ansible-review.md
CI/CD review	examples/ci-review.md
Memory management	examples/memory-management.md

---

Model Configuration

Three tiers control which model handles each task:

Variable	Used by	Purpose
PERFORMANCE_TIER_MODEL	builder	High-capability tasks — implementation, complex refactors
BALANCED_TIER_MODEL	All reviewers, code-reviewer	Review, analysis, planning
LIGHT_TIER_MODEL	Utility tasks	Fast, low-cost operations

Replace the placeholder strings in opencode.json with your provider and model ID (e.g., anthropic/claude-opus-4-5, openai/gpt-4o). See instructions/model-tiers.md for the full configuration guide.

---

Serena Integration

Serena provides semantic code navigation and persistent project memory via MCP.

Memory taxonomy:

Category	Purpose
build-and-test/	Build commands, test runner setup, CI configs
repo-structure/	Directory layout, key packages, entry points
architecture-invariants/	Patterns that must not be broken
observability-conventions/	Logging, metrics, tracing standards
recurring-pitfalls/	Known failure modes and gotchas
local-dev-notes/	Environment-specific setup notes

Memory is context-aware — commands load relevant categories automatically. Use /memory-cleanup to check for staleness, duplicates, and propose new memories on a regular cadence.

---

Customization

Use the config authoring commands to extend this setup:

• /agent-draft + /agent-create — add a new specialized subagent
• /command-draft + /command-create — add a new workflow entry point
• /skill-draft + /skill-create — add a new composable skill

Run /validate-config after any structural change to check references and formatting.

---

Requirements

• OpenCode installed
• Serena CLI on PATH
• TypeScript runtime (Bun or Node with tsx) for custom tools
• Optional: Go toolchain (for Go workflows)
• Optional: Python with pytest and ruff (for Python workflows)
• Optional: Node.js / npm (for TypeScript workflows)
• Optional: kubectl, helm, kustomize (for platform review workflows)
• Optional: ansible, molecule (for Ansible review workflows)
• Optional: actionlint (for GitHub Actions review workflows)

---

Contributing

• Preserve workflow clarity and plan/execute separation
• Maintain naming patterns consistent with existing commands and skills
• Avoid mixing concerns across workflow types
• Run /validate-config before submitting changes

---

License

MIT