opencode-go-agents/README.md

# Arquitetura de Agentes — OpenCode

Implementação do padrão **Planner-Executor em 3 níveis** (low/mid/high) para qualquer linguagem de programação.

## Estrutura de arquivos

```
seu-projeto/
├── opencode.json                        ← configuração principal
└── .opencode/
    └── agents/
        ├── router.md                    ← classifica complexidade
        ├── low-planner.md               ← analisa AST imediata
        ├── low-executor.md              ← emite micro-diff
        ├── mid-planner.md               ← decompõe em task list
        ├── mid-executor.md              ← código idiomático
        ├── high-planner.md              ← ADR + portão de aprovação
        └── high-executor.md             ← Clean Arch + perf
```

## Instalação

1. Copie `opencode.json` para a raiz do seu projeto
2. Copie a pasta `.opencode/` para o mesmo nível

```bash
cp opencode.json /caminho/do/seu-projeto/
cp -r .opencode /caminho/do/seu-projeto/
```

## Agentes

### Agentes primários (built-in + customizados)

| Agente | Modo | Modelo | Descrição |
|--------|------|--------|-----------|
| **build** | primary | opencode-go/qwen3.6-plus | Orquestrador principal. Invoca @router e delega para planners/executors |
| **plan** | primary | opencode-go/qwen3.6-plus | Análise somente-leitura. Usa @explore e @scout para navegar código |

### Subagentes customizados (deste repositório)

> **Todos os subagentes abaixo possuem `"hidden": true`** no `opencode.json`. Isso significa que eles **não aparecem na lista de agentes disponíveis** (menu Tab) e só podem ser invocados explicitamente via `@nome-do-agente` pelo agente `build` durante o fluxo de orquestração. O usuário final interage apenas com `@build` ou `@plan`.

| Agente | Modelo | Hidden | Função |
|--------|--------|--------|--------|
| **router** | opencode-go/deepseek-v4-flash | ✅ | Classifica complexidade (low/mid/high) e detecta linguagem |
| **low-planner** | opencode-go/deepseek-v4-flash | ✅ | Análise de AST pontual, plano micro-cirúrgico |
| **low-executor** | opencode-go/deepseek-v4-flash | ✅ | Geração de micro-diff, custo mínimo |
| **mid-planner** | opencode-go/deepseek-v4-pro | ✅ | Raciocínio estruturado para task list |
| **mid-executor** | opencode-go/qwen3.6-plus | ✅ | Código idiomático para qualquer linguagem |
| **high-planner** | opencode-go/qwen3.7-max | ✅ | Análise arquitetural profunda, ADR, cross-file |
| **high-executor** | opencode-go/qwen3.7-max | ✅ | Clean Arch, DDD, performance, migrações críticas |

### Subagentes built-in do OpenCode

O OpenCode inclui estes agentes — não é necessário configurá-los:

| Agente | Modo | Visível no `@` | Descrição |
|--------|------|----------------|-----------|
| **general** | subagent | ✅ | Propósito geral, executa tarefas multi-etapa em paralelo |
| **explore** | subagent | ✅ | Navegação rápida pelo codebase, somente-leitura |
| **scout** | subagent | ❌ | Pesquisa em documentação externa e dependências (pode não aparecer no autocomplete dependendo da versão) |
| **compaction** | primary | ❌ | Sistema interno — compacta contexto longo. Não selecionável. |
| **title** | primary | ❌ | Sistema interno — gera títulos de sessão. Não selecionável. |
| **summary** | primary | ❌ | Sistema interno — cria resumos de sessão. Não selecionável. |

> **Alternativas para High:** `opencode-go/kimi-k2.6` e `opencode-go/minimax-m3` são substitutos válidos para o `opencode-go/qwen3.7-max` caso você queira rotacionar ou comparar outputs arquiteturais.

## Fluxo de uso

O usuário interage **apenas** com `@build` ou `@plan`. Todos os demais agentes são `hidden` e trabalham nos bastidores:

```
Você → @build → @router → classifica
                → @low-planner  → @low-executor   (correções, lints)
                → @mid-planner  → @mid-executor   (features, testes)
                → @high-planner → APROVAÇÃO → @high-executor  (arquitetura)

Ou apenas análise:
Você → @plan → @explore / @scout (somente leitura)
```

### Comandos úteis

| Ação | Como usar |
|------|-----------|
| Alternar agente primário | `Tab` ou atalho configurado (`build` ↔ `plan`) |
| Invocar subagente hidden | Não aparece no menu — é invocado automaticamente pelo `@build` |
| Invocar subagente built-in visível | `@explore`, `@general` (visíveis no `@` autocomplete) |
| Navegar sessões pai/filho | `<Leader>+Right` / `<Leader>+Left` |

### Exemplos de uso

**Correção rápida (LOW):**
```
@build corrija o erro de sintaxe na linha 42 do arquivo auth.py
```

**Implementação de feature (MID):**
```
@build implemente um endpoint de login com validação de JWT
```

**Refatoração arquitetural (HIGH):**
```
@build refatore o módulo de pagamentos para usar Clean Architecture
```

**Análise sem alterações:**
```
@plan analise a complexidade ciclomática do módulo de relatórios
```

**Explorar código:**
```
@explore encontre todos os handlers de eventos assíncronos
```

**Consultar documentação externa (se disponível):**
```
@scout como o Redis implementa pub/sub internamente?
```

## Níveis de complexidade

### LOW — Escopo ultra-focado
- Correção de sintaxe explícita
- Geração de docstring
- Renomeação de variável
- Lint fix pontual
- Regex simples

**Output:** Micro-diff (apenas caracteres alterados)

### MID — Desenvolvimento diário
- Implementação de método/função nova
- Criação de rotas de API
- Escrita de testes
- Correção de bugs de lógica
- Refatoração com padrões (Factory, Strategy, Repository)

**Output:** Unified diff + testes nativos da stack

### HIGH — Arquitetura e infraestrutura
- Diagnóstico de falhas distribuídas
- Refatoração cross-service
- Otimização de queries SQL
- Investigação de memory leaks
- Design de contratos entre serviços
- Migrações críticas sem table lock
- Configuração de observabilidade (OpenTelemetry)

**Output:** ADR + plano aprovado antes de gerar código

## Economia de tokens

- **Low:** Apenas os caracteres alterados (micro-diff)
- **Mid:** Unified diff — nunca repete código inalterado
- **High:** Plano textual aprovado antes de gerar código massivo

## Permissões configuradas

| Agente | Write | Edit | Bash | Hidden |
|--------|-------|------|------|--------|
| build | ✅ | ✅ | ✅ | ❌ |
| plan | ❌ | ❌ | ❌ | ❌ |
| router | ❌ | ❌ | ❌ | ✅ |
| low-planner | ❌ | ❌ | ❌ | ✅ |
| low-executor | ✅ | ✅ | ❌ | ✅ |
| mid-planner | ❌ | ❌ | ❌ | ✅ |
| mid-executor | ✅ | ✅ | ✅ | ✅ |
| high-planner | ❌ | ❌ | 🔒 (apenas leitura) | ✅ |
| high-executor | ✅ | ✅ | ✅ | ✅ |

> **plan** tem `permission.edit: deny` e `permission.bash: deny` explícitos no `opencode.json`.
>
> O **high-planner** tem bash restrito a comandos de leitura (`grep`, `find`, `ls`, `cat`, `wc`, `head`, `tail`, `git log`, `git diff`, `git blame`) para análise sem risco de alterações acidentais.

## Suporte a linguagens

Este framework é **agnóstico de linguagem**. Os agentes detectam automaticamente a linguagem do código e aplicam:

- Convenções de nomenclatura nativas (camelCase, snake_case, PascalCase, etc.)
- Padrões idiomáticos da linguagem
- Ferramentas de teste nativas da stack
- Logging e observabilidade seguindo o padrão do ecossistema

**Exemplos de linguagens suportadas:** Java, Python, TypeScript, JavaScript, Go, Rust, C#, Ruby, Kotlin, Swift, PHP, Scala, Elixir, e qualquer outra linguagem suportada pelo modelo.

## Customização

### Alterar modelos

Edite `opencode.json` e substitua o campo `model` de cada agente:

```json
{
  "agent": {
    "build": {
      "model": "opencode-go/qwen3.7-max"
    }
  }
}
```

### Adicionar novos agentes

Crie um arquivo `.md` em `.opencode/agents/` e adicione a configuração em `opencode.json`:

```json
{
  "agent": {
    "security-reviewer": {
      "description": "Revisa código para vulnerabilidades de segurança",
      "mode": "subagent",
      "model": "opencode-go/qwen3.6-plus",
      "prompt": "{file:.opencode/agents/security-reviewer.md}",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}
```

## Licença

MIT
=======
# opencode-go-agents