Opencode multi agent guide.md

OpenCode Multi-Agent — Guía de uso diario

Mi configuración personal de OpenCode con 11 agentes especializados que trabajan como un equipo coordinado. Build orquesta, los workers ejecutan.

---

Agentes disponibles

Agente	Tipo	Modelo	Función
build	Primary	DeepSeek Chat	Orquestador principal. Implementa código y delega a workers.
plan	Primary	DeepSeek Reasoner	Analiza y planifica sin modificar código. Solo delega a workers de lectura.
@explore	Subagent	Kimi K2 (Groq)	Navega el repo. Solo lectura.
@general	Subagent	DeepSeek Reasoner	Razonamiento profundo, debugging complejo.
@quick-thinker	Subagent	GPT-OSS-20B (Groq)	Respuestas rápidas (~1000 t/s).
@review	Subagent	DeepSeek Chat	Revisión de calidad de código. Solo lectura.
@audit	Subagent	GPT-OSS Safeguard (Groq)	Auditoría de seguridad. Solo lectura.
@docs-writer	Subagent	DeepSeek Chat	Genera y actualiza documentación.
@committer	Subagent	Qwen3-32B (Groq)	Commits con Conventional Commits.
@task-runner	Subagent	DeepSeek Chat	Tarea completa en worktree aislado → PR.
compaction	Sistema	DeepSeek Chat	Resume contexto largo automáticamente. Oculto.

---

Resumen rápido — cuándo usar qué

Solo escribes en el chat, los agentes hacen el resto:

Situación	Qué hacer
Llegas al proyecto y no recuerdas la estructura	@explore muéstrame la estructura del proyecto
Duda rápida de sintaxis o concepto	@quick-thinker ¿diferencia entre map y flatMap?
Bug complejo	build delega a @explore + @general, luego implementa
Feature nueva con PR	build pregunta si quieres worktree → @task-runner
Feature rápida sin PR	build implementa → @review → @committer
Terminaste de trabajar	/ship (review + audit + docs + commit automático)
Analizar antes de implementar	Tab → plan, luego Tab → build
Varias tareas a la vez	@task-runner múltiples veces (cada una en su worktree)
Documentar el proyecto	@docs-writer actualiza la documentación
Auditoría de seguridad	@review + @audit

La mayoría del tiempo solo hablas con build y él decide a quién delegar. Los @ directos son para cuando tú quieres forzar un worker específico.

---

10 escenarios del día a día

1. Llego al proyecto y no recuerdo la estructura

@explore muéstrame la estructura del proyecto y dónde están los controllers

2. Feature con PR (la forma segura)

agrega un endpoint para listar partidas activas

→ build pregunta: "¿Quieres worktree aislado?" → dices sí → @task-runner se encarga de todo: worktree → branch → código → tests → commit → push → PR → cleanup

3. Feature rápida sin PR

agrega validación de email en el registro, sin worktree

→ build explora → implementa → @review valida → @committer hace commit

4. Bug raro que no entiendo

el endpoint /api/games devuelve 500 intermitentemente

→ build delega a @explore (localizar) → @general (analizar causa raíz con razonamiento profundo) → build implementa el fix

5. Duda rápida mientras trabajo

@quick-thinker ¿cuál es la diferencia entre @Transactional(readOnly=true) y sin readOnly?

→ Respuesta en ~1 segundo

6. Terminé de trabajar, quiero validar y commitear todo

/ship

→ Ejecuta automáticamente: @review → @audit → @docs-writer → @committer

7. Review de seguridad antes de un merge

@review revisa los cambios del último commit
@audit revísalo también

8. Documentar el proyecto

@docs-writer actualiza toda la documentación del proyecto

9. Trabajar en 2 cosas a la vez

@task-runner implementa paginación en el listado de partidas
@task-runner también agrega filtro por estado de partida

→ Cada tarea en su propio worktree dentro de .ai-worktrees/

10. Analizar antes de implementar

[Tab] → plan
analiza cómo podría agregar websockets para partidas en tiempo real
[Tab] → build
implementa lo que propuso plan, con PR

---

Worktrees (.ai-worktrees/)

Los worktrees creados por @task-runner viven dentro del repo:

mi-proyecto/
├── .ai-worktrees/          ← ignorado por git automáticamente
│   ├── task-2026-03-21-add-jwt-auth/
│   ├── task-2026-03-21-fix-null-response/
│   └── task-2026-03-21-docs-readme/
├── .gitignore              ← contiene .ai-worktrees/
├── src/
└── ...

Comandos útiles:

• @task-runner qué worktrees tengo activos? — listar tareas en progreso
• @task-runner retoma la tarea de jwt-refresh — continuar una tarea
• git worktree list — ver worktrees desde la terminal

---

Comando /ship

Ejecuta el flujo completo de validación después de implementar cambios:

1. @review → revisa calidad
2. @audit → revisa seguridad
3. Evaluación → si hay problemas, pregunta antes de continuar
4. @docs-writer → actualiza documentación
5. @committer → hace commit(s) con Conventional Commits

---

Archivos de configuración

~/.config/opencode/
├── opencode.json                  ← config principal (agentes, modelos, permisos)
├── AGENTS.md                      ← instrucciones globales + orquestación
├── prompts/
│   ├── build.md                   ← prompt del orquestador
│   ├── plan.md
│   ├── explore.md
│   ├── general.md
│   ├── quick-thinker.md
│   ├── review.md
│   ├── audit.md
│   ├── docs-writer.md
│   ├── committer.md
│   └── task-runner.md
└── commands/
    └── ship.md                    ← comando /ship

---

Tips

• Tab alterna entre agentes primarios (build ↔ plan)
• @nombre invoca un subagente directamente
• /ship es tu "ya terminé, valida todo"
• @task-runner es tu "hazlo todo seguro con PR"
• Si algo sale mal → /undo (OpenCode guarda snapshots)
• build nunca hace git push ni git commit directamente — siempre delega

---

Configuración creada con Claude + OpenCode. Usa DeepSeek y Groq como proveedores.