# NEXUS Team — o DNA dos agentes (v3)

Este diretório é o **conteúdo de qualidade** do NEXUS: o DNA de cada agente da equipe. Cada arquivo
`{id}.md` descreve UM agente. O motor (`@nexus/orchestration`, `@nexus/deliberation`) **executa**
esses agentes; este diretório é **quem eles são**.

> **Regra de ouro (earn-its-place):** cada linha de DNA tem que passar num teste — *um modelo capaz
> faria isso certo sem ser instruído?* Se sim, a linha é atrito e fica de fora. DNA não é manual de
> LLM; é o que torna ESTE agente distinto, confiável e repetível.

## Por que o formato é enxuto

Cada agente NÃO repete o boilerplate de ativação (no design anterior eram ~40 linhas idênticas por
arquivo). No NEXUS isso é **protocolo compartilhado** (`_protocol.md`, escrito uma vez). O arquivo do
agente carrega só o que é **único**: identidade, princípios, método, comandos e voz. Resultado: ~3×
menos ruído, 100% sinal. E os comandos apontam para o **motor real**, não para narrativa.

E os comandos apontam para o **motor real**, não para narrativa:

| Comando | v2 (teatro) | v3 (motor real) |
|---|---|---|
| orquestrar | a persona *contava* que delegava | `nexus run` → spawn-subagent de verdade |
| deliberar | — | `nexus party` → sala de deliberação de verdade |

## Estrutura canônica de um agente

Frontmatter YAML (metadados que o loader valida contra o contrato `Agent`) + corpo Markdown (o DNA
que vira prompt do subagente quando ele é spawnado).

```markdown
---
id: dev                      # kebab-case, único. Casa com o agent da AuthorityGate.
name: Dex                    # nome próprio da persona
title: Expert Senior Software Engineer
icon: 💻
archetype: Builder           # Orchestrator | Builder | Sage | Guardian | Explorer | Maker
lens: construtibilidade      # a "lente"/viés que esta persona traz pra uma deliberação (party-mode)
whenToUse: code implementation, debugging, refactoring
authority: dev               # papel na matriz de autoridade (governance)
model: opus                  # tier de qualidade sugerido p/ spawn (opus|sonnet|haiku)
owns:                        # tasks/artefatos dos quais este agente é dono
  - dev-develop-story
  - execute-subtask
delegatesTo:                 # quando sai da sua lane, pra quem manda
  - { agent: devops, when: "git push / PR / release" }
---

# {name} — {title}

## Identidade
Um parágrafo. Quem é, como pensa, o que a torna distinta. (vira a 1ª pessoa do prompt)

## Princípios inegociáveis
- 3 a 8 princípios que governam TODA decisão deste agente. Concretos, não genéricos.

## Como eu trabalho (método)
- O passo-a-passo que produz output bom **de forma repetível**. É aqui que mora a qualidade.

## Anti-padrões (o que eu não faço)
- Os erros TÍPICOS do papel, nomeados um a um (ex.: qa: aprovar sem executar; pm: inventar
  requisito). Diferente das Guardas: guarda é fronteira de autoridade; anti-padrão é vício de craft.

## Comandos
| Comando | O que faz | Motor |
|---|---|---|
| `*develop {story}` | implementa a story | dev-develop-story |

## Guardas
- O que este agente NUNCA faz (liga à AuthorityGate). Defesa em profundidade.

## Voz
- **greeting:** {icon} {name} the {archetype} ready to {verbo}!
- **closing:** — {name}, {assinatura} {emoji}
```

> **O que NÃO entra no DNA individual:** as regras universais de execução (agência calibrada,
> ler-antes-de-agir, auto-verificação, casos-limite, diffs mínimos, honestidade estrutural) vivem
> nas **6 leis de execução** do [`_protocol.md`](./_protocol.md) — escritas uma vez, valem para
> todos. O DNA individual carrega só o que é específico do papel.

## Model tier (frontmatter `model:`)

O `model:` do frontmatter é **real**: o motor usa esse tier ao spawnar o agente (`Agent.model` →
spawn). A régua: raciocínio profundo sobre código/estrutura ou erro caro em cascata → `opus`;
trabalho guiado por task/checklist/template com julgamento moderado → `sonnet`; `haiku` fica para
sub-tarefas mecânicas roteadas pelo motor, não para agentes do roster.

| tier | agentes | por quê |
|---|---|---|
| `opus` | nexus-master, architect, dev, qa, data-engineer, squad-creator | decomposição/síntese, design estrutural, implementação+debug, review adversarial, migrations irreversíveis, composição de squads (erro caro em cascata) |
| `sonnet` | pm, po, sm, analyst, devops, ux-design-expert | trabalho documental/procedural forte em template e checklist; segurança vem do processo (gates, confirmação humana), não do tier |

## Convenção de nomes (comando ↔ motor)

Um **comando** é um verbo curto que o humano digita (`*snapshot`, `*develop`, `*gate`) — é um
*alias* ergonômico. Um **motor** é o slug canônico da task que aquele comando dispara
(`db-snapshot`, `dev-develop-story`, `qa-gate`) — é o que aparece em `owns:` e na coluna **Motor**
da tabela de Comandos. Os dois nomes **não precisam** ser idênticos.

> **A coluna `Motor` é a fonte de verdade** do mapeamento comando→task. Tooling e validação devem
> casar por ela, nunca pelo nome do comando. Isso é intencional: o comando otimiza pra digitação, o
> motor otimiza pra rastreabilidade. Todo motor em `owns:` tem exatamente uma linha na tabela.

`*help`, `*guide` e `*exit` têm Motor `—` porque são servidos pelo [protocolo de ativação](./_protocol.md)
compartilhado, não por uma task do agente.

## As duas camadas do DNA

1. **Identidade** (persona + princípios + voz) — o "código genético". É o que distingue Dex de Aria.
2. **Procedural** (`owns:` → tasks/templates/checklists) — as "habilidades aprendidas". É o que faz o
   agente *executar bem*. Um agente com identidade ótima e tasks vagas ainda entrega mal.

## Ativação

O protocolo de ativação (greeting → HALT, greenfield guard, handoff suggestion) é **compartilhado**
em [`_protocol.md`](./_protocol.md). Os arquivos de agente NÃO o repetem.

## Roster

| id | persona | arquétipo | dono de |
|---|---|---|---|
| `nexus-master` | Sofia 👑 | Orchestrator | orquestração, delegação, deliberação |
| `architect` | Aria 🏛️ | Sage | arquitetura, design técnico, complexidade |
| `dev` | Dex 💻 | Builder | implementação, refactor, debug |
| `qa` | Quinn 🛡️ | Guardian | testes, quality gates, segurança |
| `pm` | Morgan 📋 | Maker | PRD, epics, direção de produto |
| `po` | Pax ✅ | Guardian | validação de stories, backlog |
| `sm` | River 🌊 | Maker | criação/expansão de stories |
| `analyst` | Alex 🔍 | Explorer | pesquisa, análise, brainstorming |
| `data-engineer` | Dara 📊 | Sage | schema, migrations, RLS, performance |
| `ux-design-expert` | Uma 🎨 | Maker | UX/UI, design system, acessibilidade |
| `devops` | Gage 🚀 | Guardian | git push, CI/CD, PR, release, MCP (EXCLUSIVO) |
| `squad-creator` | Forge 🔨 | Maker | ciclo de vida de squads (criar, validar, estender, arquivar) |