#Practical Examples

These examples show typical Plan → Explore → Build workflows you can replay in your project.

#Example 1: Design a New API Endpoint (Plan + Explore)

Goal: Add POST /users in an Express project.

1. Tab to Plan

2. Prompt:

   We need POST /users. Do not write code yet—list files to change, verification steps, and risks.

3. @explore:

   @explore How are routes registered today? Is there already a User model and validation middleware?

4. Review Plan output and confirm approach

5. Tab to Build, paste summary:

   Implement POST /users per the plan and add tests.

Takeaway: Plan avoids blind edits; Explore aligns with existing patterns quickly.

#Example 2: Fix a Failing Test (Build + LSP)

Goal: One test fails in CI.

1. Build mode:

   Run pnpm test -- src/auth/login.test.ts, fix failures from the output until green.

2. If TypeScript errors appear, ensure typescript-language-server is in opencode.json

3. Agent iterates using LSP diagnostics

Permission tip: If bash is ask, allow pnpm test* in config to reduce prompts.

#Example 3: Custom Code Review Subagent

1. Create .opencode/agents/review.md (see Agents & Permissions)

2. Plan mode:

   @review Review diff vs main on this branch; list issues by severity

3. Allow only git diff*, git log* so review agent does not edit code

#Example 4: Parallel Sessions in a Monorepo

Scenario: Frontend styling and backend API at once.

1. Session 1 (Build): frontend task, @apps/web/package.json
2. Session 2 (Build): API task in packages/api
3. Separate context reduces confusion

Note: git pull before merge; avoid parallel edits to the same files.

#Example 5: Headless CHANGELOG Draft

opencode run "From git log since last tag, draft a CHANGELOG in Markdown"

Polish before release. In CI, configure API keys, permissions, and token budget.

#Example 6: MCP for Internal Docs

With read-only Confluence/Notion MCP:

@explore Find our internal doc on OAuth refresh token flow and summarize for Build to implement

Explore + read-only MCP, then Build—lower risk of writing to external systems.

#Example 7: /init for New Contributors

1. Clone repo
2. opencode → /init → review AGENTS.md
3. Plan mode: “How do I run the first test in this project?”
4. Self-serve onboarding in ~30 minutes

#Anti-patterns

#Next Steps

• Resources
• Quick Start