# Pipeline multi-agent — Genesis

Plano de orquestração de agentes Claude Code para o ciclo de desenvolvimento do Genesis: do PRD à PR revisada.

> **Status**: planejamento — nada implementado ainda. Aguardando aprovação para criar os arquivos em `.claude/agents/` e `.claude/commands/`.

## Princípios de desenho

1. **Pipeline sequencial com gates humanos.** Determinístico, auditável. Cada etapa termina com um artefato versionado em `/PRD/<feature>/` e exige seu OK antes da próxima.
2. **Agentes = persona + escopo.** Skills (já criadas) = conhecimento estático compartilhado. Cada agente carrega as skills do seu papel.
3. **Mesmos arquivos rodam local e remoto.** `.claude/agents/<role>.md` é invocável tanto em sessão CLI (via tool Agent) quanto via `/schedule`/cloud.
4. **Devs escrevem código direto** (sua escolha). PO/TL produzem só artefatos; Dev/Tester/Reviewer mexem em arquivos.
5. **Gatilho = PRD.** Você cria `PRD/<feature>/00-prd.md` (linguagem livre, brainstorm) e dispara o pipeline.

## Os papéis (6 agentes)

### 1. `genesis-po` — Product Owner

- **Lê**: `PRD/<feature>/00-prd.md` + perguntas iniciais.
- **Faz**: identifica gaps, escopo, fora-do-escopo, ACs por user story, prioridade, métricas de sucesso. Pode usar `AskUserQuestion` para esclarecer.
- **Entrega**: `PRD/<feature>/01-spec.md` (user stories + ACs + escopo + dependências).
- **Tools**: Read, Write, Glob, AskUserQuestion, WebFetch.
- **Skills**: nenhuma específica do Genesis (PO trabalha em domínio, não em código).

### 2. `genesis-techlead` — Tech Lead

- **Lê**: `01-spec.md` + repo (varredura de código existente).
- **Faz**: decide arquitetura — sinal novo ou estender existente? Que padrões V2 aplicam (Adapter? Registry? só CRUD)? Lista Sondas/migrations/rotas/views a criar. Identifica riscos e ordem de execução. Detecta sinais existentes que servem de molde.
- **Entrega**: `PRD/<feature>/02-techplan.md` (arquivos a criar/alterar com paths, ordem, decisões arquiteturais com justificativa, breaking changes, plano de teste).
- **Tools**: Read, Grep, Glob, Bash (read-only — git, ls, php -l).
- **Skills**: `genesis-arquitetura`, `genesis-callbacks-adapters` (decisão de extensibilidade).

### 3. `genesis-dev-backend` — Dev Backend

- **Lê**: `02-techplan.md`.
- **Faz**: implementa Sondas, Migrations versionadas, Laboratórios, Validators, Handlers de API, Callbacks/Adapters quando indicado. Roda `php -l` nos arquivos novos.
- **Entrega**: código + `PRD/<feature>/03-backend.md` (lista de arquivos tocados + desvios do techplan com motivo).
- **Tools**: Read, Write, Edit, Bash, Glob, Grep.
- **Skills**: `genesis-arquitetura`, `genesis-novo-sinal`, `genesis-sondas-db`, `genesis-api-handler`, `genesis-canais-otp`, `genesis-callbacks-adapters`.

### 4. `genesis-dev-frontend` — Dev Frontend

- **Lê**: `02-techplan.md` + `03-backend.md` (precisa saber endpoints/dados disponíveis).
- **Faz**: views Metronic, JS pareado, forms, i18n nas 3 línguas (`pt-br`, `en`, `es`). Não toca PHP de domínio.
- **Entrega**: código + `PRD/<feature>/04-frontend.md`.
- **Tools**: Read, Write, Edit, Bash, Glob.
- **Skills**: `genesis-arquitetura`, `genesis-views-i18n`.

### 5. `genesis-tester` — QA

- **Lê**: `02-techplan.md` + diff (`git diff base...HEAD`).
- **Faz**: escreve testes em `Testes/<espelho>/` seguindo padrão V2 (`*TddTest.php`). Unit + integration onde fizer sentido. Roda os testes (`php tests/...`) e coleta resultados.
- **Entrega**: testes + `PRD/<feature>/05-testes.md` (cobertura por Laboratório, gaps com justificativa, output da execução).
- **Tools**: Read, Write, Edit, Bash, Grep.
- **Skills**: `genesis-tests`, `genesis-arquitetura`.

### 6. `genesis-reviewer` — Reviewer

- **Lê**: diff completo (`git diff main...HEAD`) + `02-techplan.md` + memórias de feedback.
- **Faz**: review contra padrões V2 — checklist hard:
  - Raw SQL via Connect? (block)
  - Sondas V2 (não Inteligencias)?
  - `block_*` na migration sem DEFAULT?
  - `customerControl` correto pro fluxo (interno × público)?
  - Controller fino (sem regra de negócio)?
  - Validators dedicados?
  - Adapter quando há domínio externo?
  - i18n nas 3 línguas?
  - Naming: `<S>.php`, view lowercase, sufixos `*Sonda/*Laboratorio/*Validator`?
  - Tests existem para Laboratórios?
  - Imita Otp/Edicaorota, não Designacoes?
- **Entrega**: `PRD/<feature>/06-review.md` (issues priorizadas: 🔴 blocker / 🟡 major / 🟢 minor / ⚪ nit), com path:linha e sugestão concreta.
- **Tools**: Read, Bash (git/grep), Grep, Glob.
- **Skills**: todas as `genesis-*`.

## Orquestrador — `/genesis-feature`

Slash command em `.claude/commands/genesis-feature.md` que:

1. Recebe `<feature-name>` (= subdir em `PRD/`).
2. Verifica `PRD/<feature>/00-prd.md` existe.
3. Roda o pipeline com gates:

```
00-prd.md (você)
   ↓
[genesis-po] → 01-spec.md → 🛑 GATE você revisa
   ↓
[genesis-techlead] → 02-techplan.md → 🛑 GATE você revisa
   ↓
[genesis-dev-backend] → código + 03-backend.md
   ↓ (paralelizável com tester se code base estável)
[genesis-dev-frontend] → código + 04-frontend.md
   ↓
[genesis-tester] → testes + 05-testes.md → roda php tests/...
   ↓
[genesis-reviewer] → 06-review.md → 🛑 GATE você decide o que corrigir
   ↓
loop de correção (Devs reabertos com 06-review.md como input) até 0 blocker
   ↓
você abre PR
```

**Gates obrigatórios** (3): pós-PO, pós-TL, pós-review. Devs e Tester correm sem gate intermediário (você vê o diff no fim).

**Modo passos individuais**: cada agente também é invocável solto:
- `/po refine <feature>` (só roda PO)
- `/tl plan <feature>`
- `/review` (só roda reviewer no diff atual)

Útil quando você só quer uma etapa, ou quer iterar uma específica.

## Estrutura de pastas

```
.claude/
├── skills/   # já existe (8 genesis-*)
├── agents/   # NOVO
│   ├── genesis-po.md
│   ├── genesis-techlead.md
│   ├── genesis-dev-backend.md
│   ├── genesis-dev-frontend.md
│   ├── genesis-tester.md
│   └── genesis-reviewer.md
└── commands/ # NOVO
    ├── genesis-feature.md   # orquestrador full
    ├── po.md
    ├── tl.md
    └── review.md
```

```
PRD/<feature>/
├── 00-prd.md         # você (entrada)
├── 01-spec.md        # PO
├── 02-techplan.md    # TL
├── 03-backend.md     # Dev backend
├── 04-frontend.md    # Dev frontend
├── 05-testes.md      # Tester
└── 06-review.md      # Reviewer
```

## Local × Remoto — mesmo arquivo

- **Local** (sessão CLI): orquestrador chama tool `Agent({ subagent_type: 'genesis-po', prompt: '...' })`. Agente roda na sua máquina, você vê tool calls.
- **Remoto**: `/schedule` aponta pra `.claude/agents/<role>.md`. Útil pra:
  - Rodar `genesis-reviewer` em todas as PRs abertas todo dia 8h (cron).
  - Disparar `genesis-tester` à noite contra `dev_team` e mandar relatório.
- **Definição igual** — frontmatter `name`/`description`/`tools`/`model` + system prompt em markdown. O harness escolhe runtime.

## Decisões a confirmar antes de implementar

1. **Modelo por agente.** Padrão sugerido:
   - PO/TL/Reviewer: `sonnet` (raciocínio caro, contexto cabe)
   - Devs/Tester: `sonnet` também (escrevem código)
   - Para economizar: PO/Reviewer em `haiku-4-5` se o volume cresce
2. **Tool restriction**: limito tools por papel (PO sem Edit/Write em código; TL sem Write em código de produção)? Recomendo **sim** — força o pipeline. Senão um agente "Dev" pode acabar refinando spec.
3. **Gates como AskUserQuestion ou pause manual?** AskUserQuestion bloqueia esperando você; pause manual o orquestrador para e você roda o próximo `/<step> <feature>`. Recomendo **AskUserQuestion** com opções "aprovar", "pedir ajuste", "abortar".
4. **Onde mora o template do PRD inicial (`00-prd.md`)?** Crio um `templates/PRD-template.md` que o `/genesis-feature` copia se não existir? Recomendo **sim**.
5. **Gestão de branch**: orquestrador cria branch `feature/<nome>` no início, ou trabalha na branch atual? Recomendo **branch dedicada** com checkpoint commits entre etapas (audit trail).

## Riscos e mitigações

| Risco | Mitigação |
|---|---|
| Devs paralelos editam mesmo arquivo | Pipeline sequencial — backend antes de frontend; tester depois dos devs. |
| TL escolhe arquitetura errada e devs gastam contexto refazendo | Gate humano pós-TL é obrigatório. |
| Reviewer reclama de coisas que TL aprovou (ruído) | Reviewer recebe `02-techplan.md` como contexto e prioriza issues que **divergem** do plano. |
| Agente perde contexto entre passos | Cada artefato `0N-*.md` é a "memória externa" do pipeline. Próximo agente lê os anteriores. |
| Custo de inferência alto | Modelos diferenciados por papel; gates evitam re-rodadas tardias. |

## Próximos passos (após sua aprovação)

1. Criar 6 arquivos `.claude/agents/genesis-<role>.md` com system prompts detalhados.
2. Criar `.claude/commands/genesis-feature.md` (orquestrador) + 3 atalhos (`/po`, `/tl`, `/review`).
3. Criar `templates/PRD-template.md`.
4. Smoke test: rodar pipeline contra um PRD pequeno existente (sugestão: pegar um item simples de `PRD/painel-universal/` ou criar um PRD-piloto).
5. Iterar prompts dos agentes baseado no smoke test.

## Pergunta antes de implementar

Confirma os 5 itens de "Decisões a confirmar"? Ou prefere ajustar alguma coisa do desenho geral antes?