# Guia de Agentes > **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md). > ⚠️ **A ordem de agentes mostrada nesta página está desatualizada.** A esteira atual é `@briefing → @refiner → @product → @sheldon → @planner → @dev → @qa → @tester → @pentester`. Use [4-agentes/README.md](./4-agentes/README.md) e o [Mapa do ecossistema](./1-entender/mapa-do-ecossistema.md#a-esteira-principal) como referência. > **Agentes aposentados:** `@deyvin` (e o alias `@pair`) viraram parte do `@dev`; `@architect`, `@discovery-design-doc` e `@pm` viraram parte do `@planner`; `@analyst` virou parte do `@product`; `@ux-ui` foi dividido entre `@refiner`/protótipo (direção visual), `@product` (decisões de interação), `@qa` (auditoria de acessibilidade) e `@dev` (entrega de sites); `@scope-check` virou parte do `@qa` e do gate de scope drift do `workflow:next`. Os ids antigos ainda resolvem na CLI. > Quando usar cada agente, o que ele entrega e como ativá-lo. --- ## Visão geral O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad. Você não precisa usar todos — use apenas os que o contexto pede. ``` @setup ← sempre o primeiro @product ← gera o PRD base vivo, regras de domínio e decisões de interação @orchestrator ← coordenação sob pedido @pentester ← revisão adversarial opt-in @planner ← descobre o repositório, decide arquitetura e cria o único plano @dev ← implementa; também Simple Plan, correções pequenas e continuidade @qa ← revisão final proporcional, scope drift e acessibilidade @tester ← engenharia de testes opt-in @squad ← cria squads especializados no projeto @genome ← cria genomes de domínio reutilizáveis # Agentes especializados (uso sob demanda) @committer ← gera mensagens de commit semanticas @copywriter ← copy para paginas e estrategia de conversao @briefing ← transforma plans em briefings estruturados @design-hybrid-forge ← cria skills hibridas de design @discover ← descobre o sistema e mapeia conhecimento @neo ← guia de inicio, status e proximos passos @orache ← pesquisa de mercado e competidores @profiler-researcher ← pesquisa perfil/DNA mental @profiler-enricher ← enriquece perfil cognitivo @profiler-forge ← gera advisor da persona (genome 3.0) @site-forge ← clona/rebuild de sites com skill @validator ← valida entregaveis e contratos ``` > **Nota sobre estrutura de arquivos (v1.7.3+):** Os manifests dos agentes (arquivos `.manifest.json`) foram movidos para `.aioson/agents/manifests/` para reduzir clutter no diretório de agentes. Os arquivos `.md` de instrução continuam em `.aioson/agents/`. Isso facilita a navegação e separa metadados de prompts. > Para o fluxo completo de `@squad` e `@genome`, veja também [Squad e Genome](./4-agentes/squad.md). > Para criar agentes customizados (my-agents e squad agents), veja [Agentes Customizados](./4-agentes/squad.md). > Para continuidade de sessão, correções pequenas e o sub-task scout, veja [@dev](./4-agentes/dev.md). ## Fluxo brownfield apos scan Quando o projeto ja existe e voce roda `scan:project`, o handoff correto agora e: ```text scan:project -> @product -> @sheldon -> @planner -> @dev -> @qa ``` > Fluxo atual: `[fontes em plans/{slug} -> @briefing -> @refiner -> aprovação] -> @product -> @sheldon -> @planner -> @dev -> @qa`. MICRO, SMALL e MEDIUM mudam profundidade, não a cadeia. `@orchestrator` e outros especialistas entram somente sob pedido explícito. Regras do fluxo: - os artefatos locais do scan (`scan-index.md`, `scan-folders.md`, `scan-.md`, `scan-aioson.md`) servem como mapas brutos do codigo - `discovery.md` continua sendo a memoria comprimida que os agentes usam para entender o sistema sem reler tudo - esse `discovery.md` pode ser gerado por `scan:project --with-llm` ou pelo `@discover` usando os artefatos locais do scan - `@planner` inspeciona o repositório real antes de planejar; `@qa` e o fluxo de `@dev` nao devem pular direto dos mapas brutos para a execucao quando a tarefa depende do comportamento atual do sistema - para continuidade de sessao, pequenas correcoes e implementacoes guiadas, `@dev` pode entrar direto depois que a memoria minima estiver pronta --- ## @setup **Quando usar:** Sempre. É o primeiro agente de qualquer projeto. **O que faz:** - Lê `.aioson/context/project.context.md` - Confirma stack, classificação e idioma - Define o plano de execução (quais agentes serão usados) - Orienta o desenvolvedor sobre os próximos passos - Recomenda `@briefing` quando houver ambiguidade, feature grande ou risco alto, mas sem tornar isso obrigatório **Como ativar:** ``` /aioson:agent:setup ``` **O que ele pergunta:** - O que o projeto precisa fazer e quem vai usar (sem pressuposições) - Detecta a stack automaticamente — se não reconhecer, pergunta e registra o que o usuário descrever - Confirma framework, classificação e idioma antes de finalizar > **Qualquer stack funciona.** @setup não força um framework da lista. Se você usa Django, Go, Rust, > FastAPI, SvelteKit ou qualquer outra tecnologia, ele registra o que você descrever. **Entrega:** - Confirmação do plano de agentes - Resumo do contexto do projeto - Geração opcional do `spec.md` (documento vivo para acompanhar o projeto entre sessões) **Regra importante:** - `@setup` continua sendo o primeiro agente - `@briefing` entra como recomendação contextual, não como etapa obrigatória - se o pedido já estiver claro e pequeno, o fluxo pode seguir direto para `@dev` (Simple Plan ou correção direta) - se o usuário pedir o painel local do AIOSON, o fluxo correto agora é: - abrir o app do dashboard já instalado no computador - clicar em criar/adicionar projeto - selecionar a pasta do projeto que já contém `.aioson/` --- ## @product **Quando usar:** Depois do `@setup` em projetos novos. Em features novas de projeto existente, pode entrar direto sem repetir `@setup`. **O que faz:** - varre a raiz do projeto em busca de documentos de entrada (`plans/*.md`, `prds/*.md`) antes de iniciar a conversa - conduz a conversa de produto e gera o `PRD base` - registra visão, problema, usuários, escopo inicial e perguntas em aberto - detecta sinais visuais cedo e preserva a intenção no PRD - faz classificação preliminar do escopo - aponta o próximo agente do fluxo - em brownfield, usa `discovery.md` quando já existir e trata os artefatos locais do scan apenas como orientação estrutural, nunca como substituto da leitura do sistema atual - registra as regras de domínio (antes trabalho do `@analyst`) e as decisões de interação da UI **Documentos de kickoff (plans/ e prds/ na raiz):** Você pode criar arquivos de entrada na raiz do projeto antes de ativar o `@product`: ``` plans/minha-ideia.md ← notas, esboços, planos escritos por você prds/visao-produto.md ← rascunhos de requisitos, referências ``` O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los como fonte. Se sim, ele sintetiza o conteúdo e gera o PRD formal em `.aioson/context/`. Os arquivos originais nunca são modificados — você pode deletá-los depois que o PRD estiver gerado. **Sinal de greenfield vs feature:** - `plans/*.md` ou `prds/*.md` existem + `prd.md` ainda não existe → kickoff de projeto novo - `plans/*.md` ou `prds/*.md` existem + `prd.md` já existe → nova feature ou refinamento **Como ativar:** ``` /aioson:agent:product ``` **Entrega:** Arquivo `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md` com: - visão e problema do produto - usuários e escopo inicial do MVP - fluxos principais - métricas de sucesso - perguntas em aberto - identidade visual inicial, quando houver sinal suficiente - `## Specify depth` (projetos SMALL e MEDIUM) — classificação aplicada, profundidade de spec escolhida e lista de ambiguidades que devem ser resolvidas antes que `@sheldon` e `@planner` avancem > Se o pedido mencionar explicitamente um command center premium, control tower ou painel operacional denso, o `@product` deve registrar essa intenção na seção de identidade visual do PRD — a `interface-design` resolve pela direção **Premium Dark Platform** (ou por `identity.md`, quando houver imagens de referência); nunca aponte uma skill fixa de catálogo. --- ## @planner **Quando usar:** Depois do `@sheldon`, quando o PRD está aprovado e revisado. Em qualquer classificação. **O que faz:** - inspeciona o repositório (descoberta e mapa de código: entry point de produção, módulos reutilizáveis, convenções, test runner) - classifica cada path de entrega como `reuse`, `modify`, `create` ou `retire` - registra as decisões de arquitetura necessárias (linhas de Architecture Decisions no próprio plano, com rationale) - define sequenciamento, fases verticais e rollout/recuperação quando a mudança deixa estado persistente - absorveu o trabalho dos antigos `@architect`, `@discovery-design-doc` e `@pm` **Como ativar:** ``` /aioson:agent:planner ``` **Entrega:** um único artefato `.aioson/context/implementation-plan-{slug}.md` com evidência do repositório, delta de implementação, controles de engenharia, fases verticais e sequência de execução. Não cria `architecture.md`, `design-doc.md`, `readiness.md` nem backlog separado. --- ## @orchestrator **Quando usar:** sob pedido explícito para coordenar sessões ou múltiplos especialistas; não é obrigatório em MEDIUM. **O que faz:** - Gerencia o **protocolo de sessão** (início, durante, fim) — define objetivo, acompanha progresso, atualiza spec.md - Em MEDIUM: lê o `prd.md` e `architecture.md`, cria grafo de dependências e divide em lanes paralelas - Gerencia progresso via arquivos de status e `shared-decisions.md` **Comando `*update-spec`:** atualiza `.aioson/context/spec.md` com features concluídas, novas decisões e blockers da sessão atual. **Como ativar:** ``` /aioson:agent:orchestrator ``` **Ou via CLI para preparar os arquivos:** ```bash npx @jaimevalasek/aioson parallel:init npx @jaimevalasek/aioson parallel:assign --source=prd --workers=3 npx @jaimevalasek/aioson parallel:status ``` **Entrega:** - `.aioson/context/parallel/shared-decisions.md` - `.aioson/context/parallel/agent-1.status.md` (e 2, 3...) - Cada lane tem seu escopo definido --- ## @squad **Quando usar:** Quando você quer criar um time de agentes especializados para um domínio específico dentro do projeto. **O que faz:** - Pergunta o objetivo e o tipo de trabalho - Consolida um mini pacote de `discovery/design-doc/readiness` antes de compor a squad - Gera uma squad modular, não apenas uma pasta de agentes - Cria `.aioson/squads/{squad-slug}/agents/agents.md` - Cria `.aioson/squads/{squad-slug}/squad.manifest.json` - Cria `.aioson/squads/{squad-slug}/docs/design-doc.md` - Cria `.aioson/squads/{squad-slug}/docs/readiness.md` - Cria executores reais em `.aioson/squads/{squad-slug}/agents/` - Cria um `@orquestrador` próprio para esse squad - Registra metadata em `.aioson/squads/{slug}/squad.md` - Declara `skills`, `MCPs`, política de `subagentes` e diretório `media/` - Declara `contentBlueprints` quando a squad for orientada a conteúdo - Trabalha com autonomia alta por padrão e evita perguntas extras quando a inferência já é suficiente - Detecta se o pedido parece mais `modo projeto` ou `modo feature` - Recomenda skills e documentos sob demanda em vez de inflar o contexto inteiro - Reaproveita skills instaladas em `.aioson/squads/{slug}/skills/` antes de criar especializações novas - Materializa o pacote minimo de contexto da squad para o runtime, dashboard e cloud - Pode organizar entregáveis estruturados como `content.json + index.html` por `content_key` - Usa `contentBlueprints` como contrato dinâmico do domínio; o framework fixa a casca do conteúdo, não os campos internos - Quando o usuário pedir painel local da squad, deve apontar para o app do dashboard instalado separadamente e para a seleção da pasta que já contém `.aioson/`, sem mandar usar `dashboard:*` **Como ativar:** ``` /aioson:agent:squad ``` **Entrega:** - Manifesto textual da squad - Manifesto JSON da squad - Executores reais do squad - Metadata do squad - Estrutura de output, logs, mídia e sessão > Guia completo: [Squad e Genome](./4-agentes/squad.md) --- ## @genome **Quando usar:** Quando você quer criar uma base de conhecimento de domínio reutilizável e aplicá-la a squads ou agentes específicos. **O que faz:** - Gera `O que saber`, `Mentes` e `Skills` - Pode salvar em `.aioson/genomes/` - Pode ser aplicado depois a um squad já existente - Atua como camada cognitiva do sistema, não como executor **Como ativar:** ``` /aioson:agent:genome ``` **Entrega:** - Genome estruturado - Opcionalmente, vínculo persistente com um squad **Não confundir:** - `skill` = capacidade operacional - `genome` = forma de pensar, lentes e repertório - `executor` = quem faz o trabalho - `subagente` = investigação temporária Quando uma skill vier do catálogo online ou de outro pacote, ela deve ser salva em: - `.aioson/squads/{slug}/skills/{dominio}/{skill-slug}.md` Depois disso, ela passa a ser parte real do pacote local da squad e deve ser considerada pelos agentes sob demanda. > Guia completo: [Squad e Genome](./4-agentes/squad.md) --- ## @dev **Quando usar:** Sempre — é o agente que escreve o código. **O que faz:** - Lê o contexto, o PRD revisado pelo `@sheldon` e o `implementation-plan-{slug}.md` - Implementa as fases verticais na ordem do plano - Segue as convenções e decisões de arquitetura registradas pelo `@planner` - Carrega skills e docs detalhados sob demanda, em vez de inflar contexto inteiro - Executa Simple Plan (trabalho técnico delimitado fora do fluxo de feature) e correções diretas abaixo da lane (até 2 arquivos de comportamento, sem decisão pendente e com verificação conhecida — sem arquivo de plano) - Retoma sessões (`dev-state --context=simple-plan`, recuperação de continuidade) — papel que antes era do `@deyvin`/`@pair` - Dispara o sub-task scout somente leitura (`aioson scout:prep --parent-agent=dev`; até 3 scouts por sessão e 20 arquivos por escopo) quando o diagnóstico exige varrer muitos arquivos **Como ativar:** ``` /aioson:agent:dev ``` **Princípios que ele aplica em qualquer stack:** - Isolar lógica de negócio dos handlers de requisição - Validar input na fronteira do sistema (nunca depois) - Seguir as convenções nativas do framework do projeto - Verificar skills disponíveis em `.aioson/skills/static/` antes de implementar **TDD Gate** — Antes de qualquer implementação de lógica de negócio, o `@dev` verifica o test runner configurado em `project.context.md`. Se não houver nenhum configurado, escaneia a raiz em busca de arquivos de configuração conhecidos (`pest.xml`, `vitest.config.*`, `pytest.ini`, `.rspec`, `foundry.toml`) e pergunta ao usuário se deseja configurar um antes de começar. | Classificação | Mandato | |---|---| | MICRO | Escrever o teste junto com a implementação — obrigatório antes do commit | | SMALL | Escrever o teste com falha (RED) **antes** de qualquer código de implementação | | MEDIUM | Igual ao SMALL. Anotar o teste no checkpoint do plano de implementação | **Exceções ao TDD** (nenhum teste exigido): arquivos de configuração, migrations sem regras de negócio, conteúdo estático, scaffolding de UI sem lógica de estado. Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede após insistência — nunca implementa lógica de negócio sem teste existindo primeiro. **Execução atômica** — O @dev trabalha em passos pequenos e validados, nunca implementa uma feature inteira de uma vez: 1. Declara o próximo passo antes de escrever código 2. Escreve o teste com falha (RED) — o teste deve falhar antes de qualquer implementação 3. Implementa apenas o suficiente para o teste passar (GREEN) 4. Verifica que o teste passa — lê o output completo, não um resumo 5. Faz commit com mensagem semântica 6. Repete para o próximo passo **Em projetos com Laravel especificamente:** - Form Requests para validação (nunca inline no controller) - Actions para lógica de negócio - Policies para autorização - N+1 prevenido com eager loading - Events + Listeners para side effects **Entrega:** Código implementado seguindo o plano do `@planner`, para qualquer stack. --- ## @qa **Quando usar:** Projetos SMALL e MEDIUM, após @dev. **O que faz:** - Revisa o código implementado - Escreve testes para achados Critical e High - Identifica casos de borda não cobertos - Valida se os critérios de aceite foram atendidos - usa o PRD e o plano como fonte de regras e relacionamentos - verifica scope drift entre o prometido e o entregue (antes papel do `@scope-check`) - faz auditoria de acessibilidade quando há UI (antes submodo `a11y` do `@ux-ui`) **Como ativar:** ``` /aioson:agent:qa ``` **Entrega:** - Lista de problemas encontrados por severidade - Testes para achados críticos - Relatório de cobertura **Fechamento de feature (gate humano):** Quando o QA registra PASS, ele para e recomenda que o usuário autorize: ```bash aioson feature:close . --feature={slug} --verdict=PASS --residual="..." ``` Depois da autorização explícita, o comando: 1. Adiciona QA sign-off em `spec-{slug}.md` 2. Marca a feature como `done` em `features.md` 3. Limpa `project-pulse.md` 4. Move todos os artefatos da feature (`prd-`, `spec-`, `requirements-`, etc.) para `.aioson/context/done/{slug}/` 5. Atualiza `.aioson/context/done/MANIFEST.md` O root de `.aioson/context/` fica limpo no mesmo comando, mas QA e Autopilot nunca o executam automaticamente. > **@qa vs @tester** — O `@qa` é o revisor independente e único dono do PASS/Gate D. O `@tester` é um engenheiro de testes opt-in: amplia cobertura e pode corrigir apenas um defeito determinístico dentro de paths persistidos, sempre voltando ao QA. --- ## @tester **Quando usar:** Após `@dev`, quando a aplicação foi implementada sem testes adequados. Também em projetos legados ou quando `@qa` identificar cobertura insuficiente em múltiplos módulos. **O que faz:** - Produz um relatório canônico de cobertura (`test-report-{slug}.md`) - Mapeia regras de negócio descobertas vs testes existentes, priorizando por risco - Escolhe a menor estratégia que prova os riscos concretos da feature - Escreve testes stack-native por ordem de risco - Gera relatório de cobertura antes vs depois **Estratégias disponíveis:** | Cenário | Estratégia | |---|---| | Código legado sem testes, precisa refatorar | Characterization Testing | | App implementada, cobertura zero | Test Pyramid Bottom-up | | Cobertura razoável, regras descobertas | Risk-first Gap Filling | | Código crítico com edge cases complexos | Property-based Testing | | APIs entre times | Contract Testing | | Suspeita de testes fracos que sempre passam | Mutation Testing | **Frameworks detectados automaticamente por stack:** | Stack | Test Runner | Unit | Integration | E2E | |---|---|---|---|---| | Laravel | Pest PHP | Pest unit | Pest feature (HTTP) | Dusk/Playwright | | Next.js | Vitest | Vitest + RTL | MSW + Vitest | Playwright | | Django | pytest-django | pytest | pytest + client | Playwright | | FastAPI | pytest + httpx | pytest | AsyncClient | — | | Rails | RSpec | RSpec unit | Request specs | Capybara | | Solidity | Foundry | forge unit | forge integration | — | **Como ativar:** ``` /aioson:agent:tester ``` **Entrega:** - `.aioson/context/test-report-{slug}.md` — escopo, testes, comandos/resultados e riscos restantes - Testes stack-native implementados nos paths aprovados **Restrições:** - Só modifica produção quando o defeito já é determinado pelo PRD/código e o relatório persiste `allowed_fix_paths` - O ciclo aceita no máximo 3 paths de comportamento/5 totais, exige baseline Git e volta ao QA; correção transversal vai ao DEV - Testes sem assertions são proibidos --- ## @sheldon **Quando usar:** Após `@product`, antes de iniciar a cadeia de execução — para garantir que o PRD está completo, sem lacunas e pronto para gerar código correto. **O que faz:** - Detecta documentos de entrada na raiz (`plans/*.md`, `prds/*.md`) e oferece incorporá-los ao enriquecimento do PRD - Analisa o PRD por prioridade de melhorias - Decide entre enriquecimento in-place ou plano de fases externo - Valida se o PRD está legível e implementável antes de ativar `@dev` **Modos de operação:** | Modo | Como ativar | O que faz | |---|---|---| | A — Enriquecimento (padrão) | `/aioson:agent:sheldon` | Analisa o PRD alvo e sugere melhorias prioritárias | | B — Revisão Global | `/aioson:agent:sheldon` + "revisão geral" | Escaneia todos os PRDs e planos ativos | | C — Validação Completa | `/aioson:agent:sheldon` + "validar" ou "preparar para dev" | Auditoria completa + checklist final antes de codar | **Como ativar:** ``` /aioson:agent:sheldon ``` **Entrega:** - PRD enriquecido in-place com sinal de **spec-hardened** ao final — o campo `readiness` em `sheldon-enrichment-{slug}.md` indica se o PRD está pronto para downstream (`ready_for_downstream`) ou ainda tem itens bloqueantes (`needs_work`) (Modo A) - Relatório de status de todos os PRDs (Modo B) - Checklist de validação + decisão go/no-go para implementação (Modo C) --- --- ## Agentes especializados e auxiliares Agentes que nao fazem parte do fluxo principal de entrega, mas entram sob demanda para tarefas especificas. --- ## @committer **Quando usar:** Quando voce quer gerar mensagens de commit semanticas ou preparar um conjunto de mudancas para o Git. **O que faz:** - Le o diff staged (ou working tree) e gera mensagem de commit no formato convencional - Pode gerar `commit-prep.json` com lista de arquivos, tipo de mudanca e descricao - Respeita o escopo do projeto e o formato definido no `spec.md` **Como ativar:** ``` /aioson:agent:committer ``` **Entrega:** - Mensagem de commit pronta para copiar ou mensagem semantica no formato `tipo(escopo): descricao` - Opcionalmente `.aioson/context/commit-prep.json` --- ## @copywriter **Quando usar:** Quando voce precisa de copy para landing pages, emails, CTAs ou qualquer texto voltado a conversao. **O que faz:** - Escreve copy com foco em conversao e clareza - Pode seguir uma voz de marca definida no PRD ou no `design-doc.md` - Gera variantes de headline, descricao e CTA - Nao substitui um redator humano, mas acelera a primeira versao **Como ativar:** ``` /aioson:agent:copywriter ``` **Entrega:** - Textos prontos para uso em interfaces, landing pages ou campanhas --- ## @briefing **Quando usar:** Quando voce tem notas, rascunhos ou plans brutos em `plans/` e quer transforma-los em um briefing estruturado antes de iniciar o fluxo de produto. Tambem util quando voce tem uma ideia mas ainda nao sabe se vira feature — o agente conduz uma conversa estruturada e entrega o briefing pronto pro @product decidir. **O que faz:** - Le arquivos de `plans/` e sintetiza um briefing enriquecido - Identifica gaps, riscos e perguntas em aberto (com taxonomia: research-able / testable / decision-required / out-of-scope) - Faz web research para validar suposicoes tecnicas ou de mercado - Aplica frameworks de discovery (Opportunity Solution Tree, Jobs-to-be-Done, Cagan's 4 risks) quando relevantes - Produz `.aioson/briefings/{slug}/briefings.md` - Nao cria PRD — isso e responsabilidade do @product **Como ativar:** ``` /aioson:agent:briefing ``` **Entrega:** - `.aioson/briefings/{slug}/briefings.md` com contexto, problema, solucao proposta, riscos, gaps e open questions - `.aioson/briefings/config.md` — registro de todos os briefings --- ## @design-hybrid-forge **Quando usar:** Quando voce quer criar uma skill de design hibrida combinando duas skills primarias ja existentes. **O que faz:** - Recebe duas skills de design (ex: `frontend-design` + `interface-design`) - Analisa os principios, tokens e decisoes de cada uma - Gera uma skill hibrida com contrato unico, nome, descricao e referencias - Salva em `.aioson/installed-skills/{hybrid-name}/` **Como ativar:** ``` /aioson:agent:design-hybrid-forge ``` **Entrega:** - Skill hibrida completa em `.aioson/installed-skills/{slug}/SKILL.md` --- ## @discover **Quando usar:** Quando voce quer mapear um projeto existente (brownfield) antes de comecar a trabalhar nele, ou quando quer atualizar a memoria do sistema. **O que faz:** - Escaneia a estrutura de pastas e arquivos do projeto - Gera indices e mapas semanticos (`scan-index.md`, `scan-folders.md`) - Pode gerar ou atualizar `discovery.md` e `skeleton-system.md` - Constroi um cache de conhecimento que outros agentes consomem **Como ativar:** ``` /aioson:agent:discover ``` **Ou via CLI:** ```bash npx @jaimevalasek/aioson scan:project . --folder=src ``` **Entrega:** - `scan-index.md`, `scan-folders.md`, `scan-.md`, `scan-aioson.md` - `memory-index.md`, `module-.md` - Com `--with-llm`: `discovery.md` e `skeleton-system.md` --- ## @neo **Quando usar:** Quando voce esta perdido, quer entender o status atual do projeto ou nao sabe qual agente ativar em seguida. **O que faz:** - Le `project-pulse.md`, `features.md`, `spec.md` e `workflow.state.json` - Resume o estado atual do projeto em poucas linhas - Sugere o proximo agente ou acao com base no estado do workflow - Responde perguntas do tipo "por onde comeco?" e "o que falta fazer?" **Como ativar:** ``` /aioson:agent:neo ``` **Entrega:** - Resumo do status do projeto - Recomendacao do proximo passo --- ## @orache **Quando usar:** Quando voce precisa de pesquisa de mercado, analise competitiva ou investigacao de dominio antes de definir o escopo do produto. **O que faz:** - Pesquisa na web sobre mercado, concorrentes e tendencias - Valida suposicoes de produto com dados externos - Gera resumos estruturados salvos em `researchs/{slug}/summary.md` - Segue o protocolo de cache de pesquisa: verifica `researchs/` antes de buscar novamente **Como ativar:** ``` /aioson:agent:orache ``` **Entrega:** - `researchs/{slug}/summary.md` com frontmatter (searched_at, agent, query, verdict) + findings - `researchs/{slug}/files/` com conteudo raw das fontes consultadas --- ## @pentester **Quando usar:** Antes do fechamento de uma feature (especialmente MEDIUM), quando voce quer uma revisao adversarial focada em seguranca. **O que faz:** - Atua com mentalidade de atacante, nao de validador - Revisa superficies de ataque: memory context, tool invocation, auth, handoff, protocol contracts, secrets, runtime permissions - Gera findings estruturados em `.aioson/context/security-findings-{slug}.json` - So opera em ambiente local/controlado — nunca em producao ou internet publica - Findings `high`/`critical` podem bloquear o Gate D no @qa **Como ativar:** ``` /aioson:agent:pentester ``` **Entrega:** - `.aioson/context/security-findings-{slug}.json` com review_contract, threat_surfaces e findings priorizados > **Importante:** O `@pentester` nao corrige vulnerabilidades — ele apenas encontra e documenta. A correcao e feita pelo `@dev` e a aprovacao pelo `@qa`. --- ## @profiler-researcher **Quando usar:** Quando voce quer pesquisar o "DNA mental" de uma pessoa — perfil cognitivo, comportamental e de comunicacao. **O que faz:** - Pesquisa na web e em fontes disponiveis sobre a pessoa-alvo - Gera um perfil inicial com dimensoes cognitivas e comportamentais - Salva o resultado para enriquecimento posterior **Como ativar:** ``` /aioson:agent:profiler-researcher ``` **Entrega:** - Perfil inicial da persona em formato estruturado --- ## @profiler-enricher **Quando usar:** Quando voce ja tem um perfil inicial e quer aprofundar a analise cognitiva. **O que faz:** - Le o perfil gerado pelo `@profiler-researcher` - Analisa padroes de cognicao, comunicacao e decisao - Enriquece o perfil com insights mais profundos **Como ativar:** ``` /aioson:agent:profiler-enricher ``` **Entrega:** - Perfil cognitivo enriquecido --- ## @profiler-forge **Quando usar:** Quando voce quer transformar um perfil enriquecido em um advisor funcional (genome 3.0) que pode ser usado por squads ou agentes. **O que faz:** - Le o perfil enriquecido - Gera um advisor com voice DNA, principios de decisao e framework operacional - Materializa o genome em um artefato reutilizavel **Como ativar:** ``` /aioson:agent:profiler-forge ``` **Entrega:** - Advisor/Gerome 3.0 da persona --- ## @site-forge **Quando usar:** Quando voce quer clonar o design de um site existente ou reconstruir uma URL usando uma skill de design especifica. **O que faz:** - Recebe uma URL e uma skill de design (ou extrai a skill do proprio site) - Gera a estrutura, componentes e estilos necessarios - Pode produzir entregaveis HTML/CSS/JS ou integrar com o framework do projeto **Como ativar:** ``` /aioson:agent:site-forge ``` **Exemplos de uso:** ``` Clone este site com a skill dark-console-ui Reconstrua https://exemplo.com usando a skill minha-marca-ui Extraia o design de https://exemplo.com como uma skill ``` **Entrega:** - Codigo e/ou skill extraida do site alvo --- ## @validator **Quando usar:** Quando voce quer validar entregaveis, contratos ou checklists antes de aprovar uma etapa. **O que faz:** - Valida se artefatos cumprem criterios definidos - Pode verificar conformidade com schemas, contratos ou regras de negocio - Funciona como uma camada adicional de verificacao antes de gates **Como ativar:** ``` /aioson:agent:validator ``` **Entrega:** - Relatorio de validacao com pass/fail por criterio --- ## Resumo: fluxo por tamanho ### MICRO ``` @setup → @dev ``` Duração típica: minutos a horas. Sem análise, sem arquitetura formal. ### MICRO, SMALL e MEDIUM — mesma rota ``` @setup → [fontes → @briefing → @refiner → aprovação] → @product → @sheldon → @planner → @dev → @qa ``` A classificação muda detalhe, orçamento e cobertura de risco. Sheldon é a revisão independente obrigatória do mesmo PRD antes do Planner. Tester, Pentester e Validator são opt-in e nunca entram apenas pela classificação. > `[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`. --- ## Veja também - [Fluxo de artefatos entre agentes](./5-referencia/fluxo-artefatos.md) — o que cada agente produz, o que @dev lê de fato e como o plano do Sheldon chega à implementação - [Cenários completos com exemplos práticos](./3-receitas/README.md) - [Início rápido](./2-comecar/primeiro-projeto.md) - [@dev: implementação, continuidade e sub-task scout](./4-agentes/dev.md)