opencode-workflow

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

1. Understand the request and context
2. Plan the approach, identify specialists needed
3. Delegate to subagents (in parallel when possible)
4. Integrate their findings into a coherent response
5. Verify the work meets requirements
6. 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