OpenCode Workflow

A universal OpenCode workflow setup with specialized agents, skills, commands, and plugins for any software project.

What You Get

Component	Count	What It Does
Agents	7	Orchestrator + 6 specialists (security, tests, docs...)
Commands	12	/review, /commit, /architect, /rapid, /debug...
Skills	7	Domain knowledge for APIs, testing, architecture...
Plugins	5	Auto-format, security scans, notifications...

Quick Look

Your request ──► Orchestrator ──┬──► Code Reviewer    ──┐
                                ├──► Security Auditor ──┼──► Synthesized
                                ├──► Test Architect   ──┤    Report
                                └──► Debugger         ──┘
                                      (all parallel)

Installation

OpenCode looks for workflow files in .opencode/ inside your project directory. This repo uses different folder names (agents/ instead of agent/) so it's easier to browse on GitHub.

Full Install

# Clone the workflow
git clone https://github.com/CloudAI-X/opencode-workflow.git

# Create .opencode directory in your project
mkdir -p your-project/.opencode

# Copy all components (note: folder names change!)
cp -r opencode-workflow/agents your-project/.opencode/agent
cp -r opencode-workflow/commands your-project/.opencode/command
cp -r opencode-workflow/skills your-project/.opencode/skill
cp -r opencode-workflow/plugins your-project/.opencode/plugin

Partial Install

Don't need everything? Pick what you want:

# Just agents and commands (no plugins or skills)
cp -r opencode-workflow/agents your-project/.opencode/agent
cp -r opencode-workflow/commands your-project/.opencode/command

Folder Mapping

This Repository	Your Project
`agents/`	`.opencode/agent/`
`commands/`	`.opencode/command/`
`skills/`	`.opencode/skill/`
`plugins/`	`.opencode/plugin/`

Verify It Works

cd your-project
opencode
# Type / and Tab - should see commands like /review, /commit
# Press Tab repeatedly - should see Orchestrator as a primary agent
# Type @ and Tab - should see subagents like @code-reviewer

How to Use

Primary Agents (Tab to switch)

Press Tab to cycle between primary agents:

Agent	What It Does
build	Default. Full development work.
plan	Analysis only, no file changes.
orchestrator	Coordinates complex multi-step tasks.

Subagents (@mention)

Invoke specialists by mentioning them:

@security-auditor Check the auth module for vulnerabilities

@code-reviewer Review the changes I just made

Subagent	Focus	Has Bash?	Can Edit?
`@code-reviewer`	Quality, patterns, maintainability	No	No
`@debugger`	Bug investigation, root cause	Yes	No
`@security-auditor`	OWASP Top 10, vulnerabilities	No	No
`@refactorer`	Clean code, design patterns	No	Yes
`@test-architect`	Test strategy, coverage	No	Yes
`@docs-writer`	README, API docs, guides	No	Yes

Commands (/ to invoke)

Quick workflows for common tasks:

Command	What It Does
`/review`	Multi-perspective code review
`/commit`	Generate conventional commit message
`/architect`	High-level design session
`/rapid`	Fast iteration, minimal ceremony
`/debug`	Systematic bug investigation
`/refactor`	Code cleanup workflow
`/security-audit`	OWASP vulnerability check
`/test-design`	Plan test coverage
`/docs`	Generate documentation
`/parallel`	Run multiple tasks at once
`/verify-changes`	Lint → Type → Build → Test → Review
`/mentor`	Educational explanations

The Philosophy

Orchestrator Pattern

The orchestrator doesn't try to do everything itself. It follows a 6-phase workflow:

UNDERSTAND → PLAN → DELEGATE → INTEGRATE → VERIFY → DELIVER

Understand the request and context
Plan the approach, identify specialists needed
Delegate to subagents (in parallel when possible)
Integrate their findings into a coherent response
Verify the work meets requirements
Deliver the final result

Parallel Execution

This is the key insight: independent tasks should run simultaneously.

Five 30-second reviews take 30 seconds total, not 2.5 minutes.

The trick is putting all subagent calls in a single message. Separate messages = sequential. Single message with multiple calls = parallel.

Adversarial Verification

One reviewer misses things. Multiple reviewers with different mandates catch more:

Security auditor asks: "How can an attacker break this?"
Code reviewer asks: "Is this maintainable?"
Test architect asks: "Is this actually tested?"

The tension between perspectives surfaces important tradeoffs.

Guardrails Without Friction

Plugins protect without blocking your workflow:

security-scan: Blocks edits to .env, credentials, keys
auto-format: Runs Prettier/Black after edits (non-blocking)
verification: Reminds you to test after editing 3+ files
notifications: macOS notification when work finishes
parallel-guard: Educates about parallel execution patterns

Customization

Add Your Own Agent

Create your-project/.opencode/agent/my-agent.md:

---
description: What this agent does
mode: subagent
model: anthropic/claude-sonnet-4-20250514
tools:
  write: false
  edit: false
  bash: false
---
Your custom instructions here...

Add Your Own Command

Create your-project/.opencode/command/my-command.md:

---
description: What this command does
agent: build
---
Your command prompt here...

Use $ARGUMENTS for user input.

Add Your Own Skill

Create your-project/.opencode/skill/my-skill/SKILL.md:

---
name: my-skill
description: Domain knowledge for...
---
Knowledge content here...

Troubleshooting

Agents not appearing after Tab?

Check that .opencode/agent/ exists (singular agent, not agents)
Verify markdown files have proper YAML frontmatter with --- delimiters

Commands not showing with /?

Commands go in .opencode/command/ (singular)
File name becomes the command name (commit.md → /commit)

Plugins causing errors?

Check for TypeScript syntax errors
Plugins must export an async function returning a hooks object
Use optional chaining (?.) when accessing potentially undefined properties

Skills not loading?

Each skill needs its own folder with SKILL.md inside
The name field in frontmatter should match the folder name

Credits

Inspired by claude-workflow-v2 patterns. Built for OpenCode CLI.

Created by @cloudxdev

License

MIT

designing-apis