OpenCode Playbook

Provision your OpenCode workspace

1. Clone or open the repository and ensure AI-toolkit/ lives in the workspace root so agents and prompts resolve with relative paths.
2. Copy required agents, prompts, and session commands into .claude/ folders so Claude, Gemini, Codex, and Cursor stay aligned.
3. Pin AI-toolkit/agents/INDEX.md, the prompts bundle, the session command set, and your session summary log in the resource sidebar for instant access.
4. Mirror environment variables (API keys, DB URLs) to match your local shell so recommendations that reference CLI commands succeed on the first try.
5. Install workspace extensions for Git, testing, and formatters—OpenCode can execute them directly from Claude or Gemini instructions.

Use OpenCode’s “Quick Actions” search (Ctrl/Cmd+K) to run shell snippets that Claude or Gemini propose without leaving the IDE.

Organise shared context

• Context templates: Keep claude.md, gemini.md, and session-summary.md open in split panes so every assistant references identical notes.
• Scratch buffers: Maintain notes/opencode-scratch.md for staging prompts, logs, or command output before pasting into Claude.
• Assets: Store diagrams, API schemas, or design exports in a dedicated assets folder next to your project notes and drag them into OpenCode chat when you need visual context.
• Command library: Save frequently used commands (linting, migrations, seeding) as OpenCode command palette entries for one-click execution.

Working with agents

Prompts that anchor each iteration

Multi-agent collaboration inside OpenCode

1. Generate the orchestration: Run @plan_feature.md followed by tech-lead-orchestrator.md to document the agent order, expected outputs, and review gates.
2. Build the roster: Invoke team-configurator.md to map which agent owns each phase, communication channels, and escalation rules; pin this file in the workspace.
3. Execute sequentially: In chat threads, paste the previous agent’s summary, then call the next specialist (e.g. @django-api-developer.md → @testing-expert.md).
4. Agent-controlled handoffs: Ask each agent to produce a short “handoff” paragraph (or run @session-closer.md) before triggering the next one to keep every transition explicit.
5. Parallel lanes: When multiple agents can work in parallel, open separate chat threads (e.g. #backend, #frontend) and merge their outputs with a final @reliability-commander.md pass.

Track the active agent stack in your session summary log. If someone joins mid-stream, they can replay the chain from the stored handoffs.

Sample scenario: building a dashboard feature

1. Prompt kickoff: Open a new chat thread, run @create_brief.md to capture requirements, then @plan_feature.md to outline backend + frontend tasks. Paste both into the Claude session.
2. Agent orchestration: Ask tech-lead-orchestrator.md for the execution order (backend-developer → react-component-architect → testing-expert) and confirm roles with @team-configurator.md.
3. Implementation in OpenCode: Call @backend-developer.md to scaffold APIs, run tests in the built-in terminal, then use @react-component-architect.md for UI composition. Each agent drops a handoff note via @session-closer.md.
4. Session updates: Throughout the loop, paste terminal output and key agent results into /project:session-update. Drag .claude/sessions/current.log into chat when you need a recap.
5. Wrap-up & docs: Execute @code_review.md, @testing-expert.md, and @write_docs.md; archive the produced markdown and export the chat transcript to your session insights archive.

Use OpenCode comments to assign follow-ups (“@Sam run testing-expert output”) and reference the stored handoff notes for quick onboarding.

New project playbook

1. Kick off with @create_brief.md to align goals and risks.
2. Generate the first plan via @plan_feature.md, then run specialist agents (backend/frontend) from the output.
3. Pair with teammates inside chat: assign TODOs, capture decisions, and tag owners.
4. Execute commands in the integrated terminal, paste results back for analysis, and log outcomes in /project:session-update.
5. Close the block with session-closer.md so the summary flows to Claude, Gemini, Codex, and Cursor.

Legacy or handoff workflow

1. Drag the latest Claude session log into chat for instant context transfer.
2. Run session-restorer.md to rebuild unresolved tasks and knowledge gaps.
3. Use project-analyst.md on a tree or ls snapshot to surface stacks, build steps, and ownership questions.
4. Draft a refactor checklist with code-refactorer.md and validate with testing-expert.md.
5. Mirror takeaways back into Claude via /project:session-update and archive the OpenCode transcript in your session insights folder.

Apply OpenCode across disciplines

• Backend: Combine django-backend-expert.md or fastapi-expert.md with the terminal to run migrations/tests instantly.
• Frontend: Pair react-component-architect.md plus tailwind-css-expert.md while previewing Storybook or Vite dev servers.
• Design/UX: Use frontend-designer.md to translate Figma tokens. Keep Markdown preview open to iterate on copy and UX notes.
• Documentation: Let documentation-specialist.md rewrite READMEs while you live-preview the rendered Markdown.
• Ops: Stream logs into chat, run reliability-commander.md, and generate runbooks or incident timelines on the spot.

Keep session logs synchronised

Integrations & supporting tools

• GitHub/GitLab: Use the integrated Git UI to stage, commit, and push patches produced with the toolkit.
• CI status: Enable pipeline/test watcher plugins so assistant advice stays aligned with build health.
• Testing frameworks: Configure tasks for pytest, jest, vitest, rspec, or go test; run them from the sidebar.
• Design systems: Link to Figma, Storybook, or Zeroheight and include URLs in prompts for richer feedback.
• Issue trackers: Use OpenCode’s Jira/Azure DevOps/GitHub Issues integrations to attach generated plans and docs directly to tickets.

Best practices

• Keep Claude as the authoritative log—after significant OpenCode discussions, summarise and paste into /project:session-update.
• Create focused chat threads per feature or bug so history stays searchable.
• Toggle read-only on foundational agent files to prevent accidental edits during pair programming.
• Tag messages with #frontend, #backend, #ops, etc., so you can filter insights later.
• Alternate between terminal commands and assistant reasoning: you execute, OpenCode analyses. This keeps reality and recommendations in lockstep.