<p align="center">
  <img src="docs/assets/nexus-banner.png" alt="NEXUS" width="720">
</p>

# NEXUS Core v3

> **Um comando. Um time inteiro de agentes. Software de verdade.**

Orquestrador de agentes de IA **CLI-first**: um time de 12 agentes core especializados (dev, qa, architect, pm, devops, …) — mais squad packs instaláveis (security, negócios, marketing) — com DNA próprio, conhecimento real e autoridade governada por constituição, coordenados a partir de um único comando no seu terminal.

Construído sobre o princípio **"menos código, mais verdade"**: tudo que o sistema declara é validado mecanicamente contra o que existe de fato (validators de integridade, gates fail-closed, manifesto assinado). Sem teatro.

## Requisitos

- **Node.js ≥ 22**
- **[Claude Code](https://claude.com/claude-code)** instalado no terminal (`npm install -g @anthropic-ai/claude-code`) e logado com a **sua assinatura Claude** — o NEXUS usa o Claude Code como motor de execução; **nenhuma API key é necessária**.

## Instalação

```bash
git clone https://github.com/emersoniabrasil/nexus-core-v3.git
cd nexus-core-v3
npm install
npm link        # deixa o comando `nexus` disponível no PATH
```

Depois, dentro do **seu projeto** (novo ou existente):

```bash
cd meu-projeto
nexus install   # instala o framework (assinatura Ed25519 verificada, fail-closed)
nexus doctor    # diagnóstico do ambiente
nexus team      # conheça seus agentes
```

O `nexus install` verifica o manifesto assinado antes de tocar qualquer arquivo, copia agents/tasks/templates/checklists/knowledge/squads para o projeto e **nunca sobrescreve** customizações suas (agents/, squads/ e knowledge/ são preservados em reinstalações).

## Primeiros passos

```bash
nexus run "crie uma landing page com formulário de contato"   # o coordenador delega ao time
nexus run --squad exemplo-conteudo "escreva um artigo sobre X" # squad especializado executa
nexus party "monolito ou microserviços para o MVP?"            # deliberação multi-persona
nexus squad create "squad de marketing de conteúdo"            # o Forge cria um squad novo
```

## O time

Doze agentes core, cada um com DNA próprio (persona, princípios, método, "como eu falo", knowledge e
autoridade). A tabela abaixo é **gerada dos frontmatters** — `nexus team --md` imprime exatamente isto,
e um teste anti-rot garante que a vitrine nunca se descola do time real.

<!-- nexus:team:start -->
| Agente | Especialidade | Quando usar |
| --- | --- | --- |
| 🔍 Alex (`analyst`) | Analista Estratégico & Parceiro de Ideação | pesquisa de mercado, análise competitiva, pesquisa de usuário, facilitação de brainstorming, ideação estruturada, estudos de viabilidade, tendências de indústria, descoberta de projeto (documentação brownfield), pesquisa de dependências técnicas para spec |
| 🏛️ Aria (`architect`) | Arquiteta de Sistemas Holística & Líder Técnica Full-Stack | arquitetura de sistema (fullstack, backend, frontend, infra), seleção de stack, design de API (REST/GraphQL/tRPC/WebSocket), arquitetura de segurança, performance cross-stack, estratégia de deploy, avaliação de complexidade e planos de implementação |
| 📊 Dara (`data-engineer`) | Arquiteta de Banco de Dados & Engenheira de Confiabilidade | design de schema, modelagem de domínio, migrations, políticas RLS, otimização de query, configuração Supabase/PostgreSQL, operações de banco e observabilidade |
| 💻 Dex (`dev`) | Expert Senior Software Engineer | implementar story, escrever/refatorar código, debugar, aplicar correções de QA, rodar testes |
| 🚀 Gage (`devops`) | Guardião do Repositório & Release Manager | git push, criação e merge de PR, versionamento semântico e release, CI/CD (GitHub Actions), limpeza de repositório, gestão de MCP. ÚNICO agente autorizado a operar o remoto. |
| 👑 Sofia (`nexus-master`) | HEAD Orchestrator do NEXUS | coordenar múltiplos agentes, decompor um objetivo em entregas, decidir entre executar (run) e deliberar (party), rotear trabalho especializado |
| 📋 Morgan (`pm`) | Product Manager | criar PRD (greenfield e brownfield), criar e estruturar epics, definir produto e direção, priorizar features (MoSCoW, RICE), recortar escopo, definir métricas de sucesso, decisão go/no-go, gather de requisitos e spec |
| ✅ Pax (`po`) | Product Owner — Guardião da Prontidão da Story | validar draft de story, refinar backlog, priorizar e agendar itens, fechar story concluída, garantir coesão e rastreabilidade dos artefatos |
| 🛡️ Quinn (`qa`) | Test Architect & Quality Advisor | review de story, decisão de quality gate, design de testes, avaliação de risco e NFRs, scan de segurança, rastreabilidade requisito→teste |
| 🌊 River (`sm`) | Scrum Master — especialista em preparação de stories | criar story a partir de PRD/épico, expandir e refinar story, definir critérios de aceite, rodar o checklist de draft, planejar branch local de desenvolvimento |
| 🔨 Forge (`squad-creator`) | Forjador de Squads — de uma missão a um time coeso de especialistas | criar um squad de especialistas a partir de uma missão, validar a integridade de um squad, estender um squad com novos membros/tasks, arquivar um squad que cumpriu a missão |
| 🎨 Uma (`ux-design-expert`) | UX/UI Designer & Design System Architect | pesquisa de usuário, wireframes, design system, extração de tokens, construção de componentes atômicos, auditoria de acessibilidade |
<!-- nexus:team:end -->

Além do core, **squad packs** especializados (instaláveis): `security`, `negocios`, `marketing`,
`exemplo-conteudo`. `nexus team --matrix` mostra quem delega para quem (gerado dos `delegatesTo` reais).

## Comandos

| Comando | O que faz |
|---|---|
| `nexus run <tarefa>` | Executa uma missão: o coordenador decompõe e delega a sub-agentes reais (paralelismo por ondas, budget e guardrails) |
| `nexus party <tópico>` | Sala de reunião: personas deliberam e o master sintetiza uma decisão |
| `nexus team` | Roster do time core + validação de integridade dos DNAs (`--matrix` matriz de delegação, `--md` tabela markdown) |
| `nexus metrics` | Métricas reais do pipeline (first-pass QA, tentativas, escalações) — sem dado = "sem dados" |
| `nexus runbook` | Runbooks por cenário: sequências de comandos + gates + handoffs |
| `nexus squad …` | `list · validate · create · archive · restore · sync · sweep` — squads dinâmicos criados por IA e validados pelo motor |
| `nexus memory …` | Memória semântica (FTS5 + BM25 + PageRank) com aprendizado por feedback real |
| `nexus learn …` | Padrões aprendidos → propostas de novas tasks (gate humano para aprovar) |
| `nexus validate` | Suíte de validators declarado=real (`--strict` para gate de release) |
| `nexus doctor` | Diagnóstico do ambiente e do projeto |
| `nexus install [dir]` | Instala o framework num projeto (manifesto assinado, fail-closed) |
| `nexus hook` | Entrypoint dos hooks nativos do Claude Code (memória/synapse/autoridade) |
| `nexus mcp start` | Servidor MCP fino expondo os comandos como tools nativas |

`nexus help` lista tudo.

## Arquitetura (resumo honesto)

- **17 pacotes** TypeScript ESM (workspaces), dependências de produção mínimas: `js-yaml`, `zod`, `tsx`.
- **Agentes com DNA real**: persona, princípios, método, knowledge packs e autoridade — injetados de verdade no spawn de cada sub-agente.
- **Governança fail-closed**: a Constitution define autoridades exclusivas (ex.: `git push` só via @devops); o AuthorityGate resiste a quoting/wrappers/bypass.
- **Memória que aprende**: recall no prompt (hot-path) + feedback por verdict no fim da sessão ajustando confiança das memórias.
- **Squads dinâmicos**: "LLM propõe, motor valida" — o Forge gera, o motor re-parseia, valida e materializa atomicamente.
- **Distribuição íntegra**: manifesto com SHA-256 por arquivo, assinado com Ed25519; o install verifica assinatura e cada hash antes de copiar.
- **796 testes**, cobertura ~97%, **13 validators** declarado=real, `npm run check` (typecheck + testes + cobertura + validate + ratchet) como gate único — a fonte de verdade destes números (não confie no badge, rode o gate).

## Doutrina

O NEXUS não é um chat com prompts — é um método. As sequências reais de comando + gates + handoffs
por cenário vivem em [`runbooks/`](runbooks/):

- [MVP do zero](runbooks/mvp-startup.md) — da ideia ao primeiro deploy
- [Feature em projeto existente](runbooks/feature-em-projeto-existente.md) — brownfield com QA
- [Resposta a incidente](runbooks/resposta-a-incidente.md) — do alerta ao post-mortem
- [Campanha de conteúdo](runbooks/campanha-de-conteudo.md) — squad de conteúdo do brief à publicação

O ciclo de vida completo (7 fases, com gates que cruzam checklist↔roster) está em
[`knowledge/pipeline/`](knowledge/pipeline/); a matriz de risco governada em
[`knowledge/governance/risk-matrix.md`](knowledge/governance/risk-matrix.md).

## Prova

Sem teatro: a prova é o run real, com transcript, veredito estruturado, evidência e **custo em US$**.
As missões de exemplo e como reproduzi-las estão em [`examples/`](examples/) — cada uma traz o comando
exato; rodá-lo (com a sua assinatura Claude) gera os artefatos reais daquela missão.

## Para mantenedores (release)

```bash
npm run check          # gate completo — precisa estar verde
npm run release:sign   # re-gera e assina o artifact-manifest.json (commite-o)
```

A chave **privada** de assinatura fica em `.nexus-keys/` (gitignored — guarde-a). A **pública** é embutida em `packages/dist/src/nexus-public-key.ts` e commitada.

## Licença

[MIT](./LICENSE)