|
| 1 | +# OpenCode Agent Cheatsheet |
| 2 | + |
| 3 | +Quick reference for all custom agents. Invoke subagents with `@agent-name` in any OpenCode session. Switch primary agents with `Tab`. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## Quick Routing |
| 8 | + |
| 9 | +``` |
| 10 | +Need help choosing? → @agent-advisor what agent should I use for X? |
| 11 | +Planning/architecture? → Switch to plan mode (Tab) |
| 12 | +Writing code? → Switch to engineer (Tab) or build mode |
| 13 | +Quick question? → Use Copilot Chat instead (save Zen credits) |
| 14 | +Tab-complete? → Use Copilot inline (unlimited, always on) |
| 15 | +``` |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Primary Agents (Tab to switch) |
| 20 | + |
| 21 | +### engineer — Default Builder |
| 22 | +**Model:** GPT 5.4 | **Use for:** Day-to-day implementation, ambiguous tasks |
| 23 | + |
| 24 | +``` |
| 25 | +# Start coding directly — engineer is the default build agent |
| 26 | +Implement a REST endpoint for /api/properties that returns paginated results |
| 27 | +
|
| 28 | +# Multi-file feature |
| 29 | +Add webhook support to the payment service. Create the handler, register the route, and add validation. |
| 30 | +
|
| 31 | +# Refactor with context |
| 32 | +Refactor the HVAC controller to use the strategy pattern instead of the switch statement |
| 33 | +``` |
| 34 | + |
| 35 | +### lead_dev — Orchestrator |
| 36 | +**Model:** MiniMax M2.5 Free | **Use for:** Quick tasks, auto-delegation to QA/reviewer/commit |
| 37 | + |
| 38 | +``` |
| 39 | +# Full lifecycle — plans, codes, tests, reviews, commits |
| 40 | +Add a health check endpoint to the API server |
| 41 | +
|
| 42 | +# Delegates automatically |
| 43 | +Fix the failing test in auth_test.go and commit when green |
| 44 | +``` |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Subagents (@mention to invoke) |
| 49 | + |
| 50 | +### @agent-advisor — Task Router |
| 51 | +**Model:** Gemini 3 Flash (cheap) | **Use for:** Picking the right agent or tool |
| 52 | + |
| 53 | +``` |
| 54 | +@agent-advisor I need to redesign the database schema and then implement it. What's the workflow? |
| 55 | +
|
| 56 | +@agent-advisor Should I use Copilot or OpenCode for reviewing this PR? |
| 57 | +
|
| 58 | +@agent-advisor I have a Figma mockup to implement and tests to write. Which agents and in what order? |
| 59 | +``` |
| 60 | + |
| 61 | +### @planning-agent — Systems Architect |
| 62 | +**Model:** Gemini 3.1 Pro (1M context) | **Use for:** Architecture, migration plans, system design |
| 63 | +**Saves plans to `.opencode/plans/`** — designs blueprints, does not write implementation code |
| 64 | + |
| 65 | +``` |
| 66 | +@planning-agent Design the database schema for a multi-tenant property management system |
| 67 | +
|
| 68 | +@planning-agent Plan the migration from REST to gRPC for the internal services |
| 69 | +
|
| 70 | +@planning-agent Break down the authentication flow for OAuth2 + PKCE. Include a Mermaid diagram. |
| 71 | +
|
| 72 | +@planning-agent Review the current project structure and propose a module boundary refactor |
| 73 | +``` |
| 74 | + |
| 75 | +### @plan-reviewer — Plan Critic |
| 76 | +**Model:** GPT 5.4 (cross-model from planner's Gemini) | **Use for:** Reviewing architecture plans before implementation |
| 77 | +**Requires a file path or pasted plan as input. Saves review to `.opencode/plans/`** |
| 78 | + |
| 79 | +``` |
| 80 | +@plan-reviewer Review the plan in docs/migration-plan.md for gaps and risks |
| 81 | +
|
| 82 | +@plan-reviewer Critique this API design: |
| 83 | + POST /api/orders → creates order + sends email + updates inventory |
| 84 | +
|
| 85 | +@plan-reviewer Is this DynamoDB single-table design going to scale? See docs/schema.md |
| 86 | +``` |
| 87 | + |
| 88 | +### @coder — Autonomous Test-Fix Loop |
| 89 | +**Model:** GPT 5.3 Codex | **Use for:** Clear specs with existing tests — implement until green |
| 90 | + |
| 91 | +``` |
| 92 | +@coder Implement the OrderService interface in internal/service/order.go. Run tests until all pass. |
| 93 | +
|
| 94 | +@coder The spec is in docs/webhook-spec.md. Implement it and make all tests in webhook_test.go pass. |
| 95 | +
|
| 96 | +@coder Refactor calculateDiscount to handle the new tier system. Existing tests must stay green. |
| 97 | +``` |
| 98 | + |
| 99 | +### @frontend — UI Specialist |
| 100 | +**Model:** Kimi K2.5 (vision) | **Use for:** Screenshots to code, responsive UI, component implementation |
| 101 | + |
| 102 | +``` |
| 103 | +@frontend Build a pricing page with 3 tiers: Free, Pro, Enterprise. Use Tailwind, make it responsive. |
| 104 | +
|
| 105 | +@frontend Implement this design [paste screenshot]. Use React + Tailwind. Match the spacing exactly. |
| 106 | +
|
| 107 | +@frontend Create a dashboard sidebar with collapsible navigation groups and active state indicators |
| 108 | +
|
| 109 | +@frontend Add a dark mode toggle to the header. Persist preference in localStorage. |
| 110 | +``` |
| 111 | + |
| 112 | +### @reviewer — Code Review |
| 113 | +**Model:** Gemini 3.1 Pro | **Use for:** SRP, complexity, performance, readability review |
| 114 | +**Read-only** — critiques, does not fix |
| 115 | + |
| 116 | +``` |
| 117 | +@reviewer Review internal/handler/payment.go for clean code and performance issues |
| 118 | +
|
| 119 | +@reviewer Check the new auth middleware for SRP violations and unnecessary complexity |
| 120 | +
|
| 121 | +@reviewer Review the last 3 commits for code quality. Focus on the service layer changes. |
| 122 | +``` |
| 123 | + |
| 124 | +### @security — Security Audit |
| 125 | +**Model:** Gemini 3.1 Pro | **Use for:** OWASP top 10, injection, auth flaws, input validation |
| 126 | +**Read-only** — reports vulnerabilities, does not patch |
| 127 | + |
| 128 | +``` |
| 129 | +@security Audit the authentication flow in internal/auth/ for common vulnerabilities |
| 130 | +
|
| 131 | +@security Check api/handlers/ for injection risks, especially the search endpoint |
| 132 | +
|
| 133 | +@security Review the file upload handler for path traversal and size limit issues |
| 134 | +
|
| 135 | +@security Full security scan of the payment processing module. Check for IDOR and SSRF. |
| 136 | +``` |
| 137 | + |
| 138 | +### @qa — QA Automation |
| 139 | +**Model:** GPT 5.3 Codex | **Use for:** Writing comprehensive test suites with mocking |
| 140 | + |
| 141 | +``` |
| 142 | +@qa Write unit tests for internal/service/order.go. Cover happy path, sad path, and edge cases. |
| 143 | +
|
| 144 | +@qa Create integration tests for the webhook handler. Mock the external payment API. |
| 145 | +
|
| 146 | +@qa The calculateShipping function has no tests. Write comprehensive coverage including boundary values. |
| 147 | +
|
| 148 | +@qa Add property-based tests for the JSON serialization round-trip in the config package. |
| 149 | +``` |
| 150 | + |
| 151 | +### @test_generator — Requirements-Driven Tests |
| 152 | +**Model:** GPT 5.3 Codex | **Use for:** Translating user requirements into BDD-style tests |
| 153 | + |
| 154 | +``` |
| 155 | +@test_generator The user should not be able to place an order if their cart is empty or payment is declined |
| 156 | +
|
| 157 | +@test_generator Requirements: |
| 158 | + - Users can only edit their own profiles |
| 159 | + - Admins can edit any profile |
| 160 | + - Email changes require re-verification |
| 161 | +
|
| 162 | +@test_generator Generate tests for the discount engine based on this spec: docs/discount-rules.md |
| 163 | +``` |
| 164 | + |
| 165 | +### @docs_generator — Documentation |
| 166 | +**Model:** Gemini 3 Flash (cheap) | **Use for:** Inline comments, JSDoc, GoDoc, external docs |
| 167 | + |
| 168 | +``` |
| 169 | +@docs_generator Add inline documentation to internal/service/. Focus on domain logic, skip obvious code. |
| 170 | +
|
| 171 | +@docs_generator Generate GoDoc for all exported functions in the auth package |
| 172 | +
|
| 173 | +@docs_generator mode=external source=internal/ target=docs/ — generate module-level documentation |
| 174 | +
|
| 175 | +@docs_generator Add JSDoc to the React components in src/components/dashboard/ |
| 176 | +``` |
| 177 | + |
| 178 | +### @commit — Git Automation |
| 179 | +**Model:** MiniMax M2.5 Free (free) | **Use for:** Semantic commits, branch protection |
| 180 | + |
| 181 | +``` |
| 182 | +@commit Stage and commit the changes to the auth handler with a descriptive message |
| 183 | +
|
| 184 | +@commit Review the staged changes and create a conventional commit |
| 185 | +
|
| 186 | +@commit Stage only the test files and commit separately from the implementation |
| 187 | +``` |
| 188 | + |
| 189 | +### @linear — Project Management |
| 190 | +**Model:** Gemini 3 Flash | **Use for:** Creating/managing Linear issues and projects |
| 191 | + |
| 192 | +``` |
| 193 | +@linear Create an issue: "Add rate limiting to public API endpoints" with priority High |
| 194 | +
|
| 195 | +@linear Create a project "Q2 Auth Rewrite" with 5 issues broken down from docs/auth-plan.md |
| 196 | +
|
| 197 | +@linear What are the open issues in the current sprint? |
| 198 | +``` |
| 199 | + |
| 200 | +--- |
| 201 | + |
| 202 | +## Common Workflows |
| 203 | + |
| 204 | +### New Feature (full pipeline) |
| 205 | +``` |
| 206 | +1. @agent-advisor → picks the right workflow |
| 207 | +2. @planning-agent → designs architecture |
| 208 | +3. @plan-reviewer → critiques the plan |
| 209 | +4. engineer (Tab) → implements the feature |
| 210 | +5. @qa → writes and runs tests |
| 211 | +6. @reviewer → code review (different model than builder) |
| 212 | +7. @security → security audit |
| 213 | +8. @commit → semantic commit |
| 214 | +``` |
| 215 | + |
| 216 | +### Bug Fix (fast track) |
| 217 | +``` |
| 218 | +1. engineer (Tab) → investigate and fix |
| 219 | +2. @qa → verify with tests |
| 220 | +3. @commit → commit the fix |
| 221 | +``` |
| 222 | + |
| 223 | +### Spec-Driven Implementation |
| 224 | +``` |
| 225 | +1. @planning-agent → write the spec |
| 226 | +2. @test_generator → generate tests from spec |
| 227 | +3. @coder → implement until tests pass (autonomous) |
| 228 | +4. @reviewer → review the implementation |
| 229 | +``` |
| 230 | + |
| 231 | +### Frontend Feature |
| 232 | +``` |
| 233 | +1. @frontend → implement from design/screenshot |
| 234 | +2. @qa → component tests |
| 235 | +3. @security → XSS/input validation check |
| 236 | +4. @commit → commit |
| 237 | +``` |
| 238 | + |
| 239 | +### Pre-Merge Review |
| 240 | +``` |
| 241 | +1. @reviewer → code quality |
| 242 | +2. @security → vulnerability scan |
| 243 | +3. @commit → squash and commit |
| 244 | + (or use Copilot PR review — free) |
| 245 | +``` |
| 246 | + |
| 247 | +--- |
| 248 | + |
| 249 | +## Cost Awareness |
| 250 | + |
| 251 | +| Tier | Agents | Cost | |
| 252 | +|------|--------|------| |
| 253 | +| **Free** | commit, lead_dev | $0 | |
| 254 | +| **Cheap** | agent-advisor, docs_generator, linear | ~$0.50-3/1M tokens | |
| 255 | +| **Standard** | engineer, coder, frontend, qa, test_generator | ~$1.75-15/1M tokens | |
| 256 | +| **Premium** | planning-agent, reviewer, security (Gemini 3.1 Pro), plan-reviewer (GPT 5.4) | ~$2-15/1M tokens | |
| 257 | + |
| 258 | +**Rule:** Free for grunt work. Cheap for docs/routing. Standard for building. Premium for thinking. |
0 commit comments