OpenCode Dev Workflow

Multi-agent development pipeline for OpenCode with planning, building, testing, review, and merge stages.

Quick Install (Copy & Paste to OpenCode)

I want to install the workflow from https://github.com/Naab2k3/opencode-dev-workflow. Please:
1. Create agents/ directory in OpenCode config directory
2. Copy all files from repo agents/ into it
3. Copy entire skills/ directory from repo into config skills/
4. Copy opencode.json.md as opencode.json in config directory
5. Edit workspace paths in opencode.json to match your environment
6. Run npm install in config directory

Quick Start

# 1. Clone this repo
git clone <repo-url> opencode-workflow

# 2. Copy config to your OpenCode config directory
# Linux/macOS:
cp opencode.json ~/.config/opencode/opencode.json
cp -r agents ~/.config/opencode/
cp -r skills ~/.config/opencode/

# Windows:
Copy-Item opencode.json $env:APPDATA\opencode\
Copy-Item -Recurse agents $env:APPDATA\opencode\
Copy-Item -Recurse skills $env:APPDATA\opencode\

# 3. Edit opencode.json to set your workspace paths and MCP servers

# 4. Install dependencies
cd ~/.config/opencode && npm install
# or on Windows:
cd $env:APPDATA\opencode && npm install

Workflow Overview

TASK (>2h)
    │
    ▼
┌─────────────┐
│  @plan      │  → PRD + .plan.md + Issues
└──────┬──────┘
       ▼
┌─────────────┐
│  @build     │  → Code + PR → auto dispatch @test
└──────┬──────┘
       ▼
┌─────────────┐
│  @test      │  → Test results + coverage
└──────┬──────┘
       ▼  [USER MANUAL TEST OK]
┌─────────────┐
│  @review    │  → Review report
└──────┬──────┘
       ▼
┌─────────────┐
│ @pr-checker │  → PR analysis + Approve/Reject
└──────┬──────┘
       ▼
┌─────────────┐
│ @pr-merger  │  → Merge commit
└─────────────┘

Side flow: @test FAIL → @debug → @build (fix) → loop

Agents

Agent	Role	Edit	Bash	Description
@plan	Architect	✅	✅	Analyze requirements, create PRD, break into issues
@build	Developer	✅	✅	Implement features, build, deploy, create PR
@test	QA Engineer	✅	✅	Write and run tests (TDD), report coverage
@review	Reviewer	❌	❌	Code review - quality, security, performance
@pr-checker	Tech Lead	❌	✅	PR analysis, risk assessment, approve/reject
@pr-merger	Executor	✅	✅	Safe merge after approval
@debug	Debugger	❌	✅	Investigate bugs, find root cause

Gate Rules

• Task > 2h: Must go through @plan first, output .plan.md
• No .plan.md: @build rejects the task
• No test pass: @review rejects the review
• No review pass: @pr-checker rejects verification
• No pr-checker approve: @pr-merger rejects merge

Usage Example

User: "I want to add feature X"
       |
       v
User: "@plan I want to add feature X"
       |  plan agent runs → output .plan.md + issues
       v
User: "@build implement issue-123 following .plan.md"
       |  build agent runs → auto dispatch test
       v
       |  test agent runs → report
       v
User: (manual test local) → OK
       |
User: "@review review PR #456"
       |  review pass
       v
User: "@pr-checker check PR #456"
       |  approve
       v
User: "@pr-merger merge PR #456"
       |  merged
       v
       DONE

Configuration

opencode.json

Edit the following in opencode.json:

1. permission.external_directory: Set your workspace paths
2. mcp: Add your MCP server configurations (Gitea, etc.)
3. Model providers: Configure your preferred AI models

Skills

This workflow includes 16 custom skills plus the Superpowers plugin:

Skill	Purpose
karpathy-guidelines	Coding best practices
git-guardrails	Prevent destructive git operations
design-an-interface	Generate multiple API designs
frontend-design	Create frontend interfaces
ui-ux-pro-max	UI/UX design intelligence
canvas-design	Create visual art and posters
grill-me	Stress-test plans through interview
to-prd	Convert conversation to PRD
to-issues	Break PRD into issues
request-refactor-plan	Plan refactoring
improve-codebase-architecture	Find architecture improvements
ubiquitous-language	Create DDD glossary
domain-model	Stress-test against domain model
triage-issue	Investigate bugs and plan fixes
edit-article	Edit and improve articles
zoom-out	Understand broader context

Auto-Chain Behavior

1. @build completes → auto dispatch @test (no user trigger needed)
2. @test completes → STOP (user manual test locally)
3. After manual test OK → user triggers @review manually
4. @review passes → user triggers @pr-checker manually
5. @pr-checker approves → user triggers @pr-merger manually

License

MIT