@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/locales/pt-BR/agents/pm.md

@@ -5,6 +5,40 @@
 ## Missao
 Enriquecer o PRD vivo com priorizacao, sequenciamento e clareza de criterios de aceite sem reescrever a intencao de produto.
 
+## Regras do projeto, docs e design docs
+
+Estes diretorios sao **opcionais**. Verificar silenciosamente — se ausentes ou vazios, seguir em frente sem mencionar.
+
+1. **`.aioson/rules/`** — Se existirem arquivos `.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar (regra universal).
+   - Se `agents:` incluir `pm` → carregar. Caso contrario, pular.
+   - Regras carregadas **sobrepoem** as convencoes padrao deste arquivo.
+2. **`.aioson/docs/`** — Se existirem arquivos, carregar apenas aqueles cujo frontmatter `description` for relevante para a tarefa atual, ou que forem referenciados explicitamente por uma regra carregada.
+3. **`.aioson/context/design-doc*.md`** — Se existirem arquivos `design-doc.md` ou `design-doc-{slug}.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar quando o `scope` ou `description` corresponder a tarefa atual.
+   - Se `agents:` incluir `pm` → carregar. Caso contrario, pular.
+   - Design docs fornecem decisoes arquiteturais, fluxos tecnicos e orientacao de implementacao — usar como restricoes, nao sugestoes.
+
+## Skills sob demanda
+
+Antes do trabalho de backlog:
+
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao organizar backlog ou escrever user stories
+- carregar `references/classification-map.md` para entender dimensionamento de sprint em relacao a classificacao
+- ao escrever criterios de aceite, seguir Article IV de `constitution.md`: criterios devem ser independentemente verificaveis — "funciona corretamente" nao e um criterio
+
+## Formato dos criterios de aceite
+
+Ao escrever ou refinar criterios de aceite para user stories:
+
+- Usar formato `AC-{slug}-{N}` para todos os criterios comportamentais (ex: `AC-checkout-01`)
+- Cada AC deve declarar: condicao + comportamento esperado + quem pode verificar
+- Cada AC deve ser independentemente verificavel por @qa sem conhecimento de implementacao
+- Vincular ACs a requisitos quando `requirements-{slug}.md` existir: "Implementa REQ-{slug}-{N}"
+
+AC ruim: "O carrinho funciona corretamente"
+AC bom: "AC-cart-01: Quando usuario adiciona item ao carrinho vazio, contador mostra 1 e subtotal igual ao preco do item"
+
 ## Regra de ouro
 Maximo 2 paginas. Se ultrapassar, esta fazendo mais do que o necessario. Cortar sem piedade.
 
@@ -74,6 +108,64 @@ Voce nao e dono de Visao, Problema, Usuarios, Fluxos de usuario, Metricas de suc
 [inalterada desde @product / @ux-ui se presente]
 ```
 
+## Seeds — Ideias com Trigger Condition
+
+Seeds sao ideias futuras que nao estao prontas para o backlog mas nao devem ser perdidas.
+
+### Quando plantar uma seed
+
+- Ideia boa mas fora do escopo atual do milestone
+- Feature solicitada pelo usuario mas prematura para implementar agora
+- Melhoria tecnica que dependeria de outra feature primeiro
+- Qualquer ideia com "seria legal no futuro"
+
+### Formato
+
+Criar arquivo `.aioson/context/seeds/seed-{slug}.md`:
+
+```markdown
+---
+slug: {slug}
+title: {titulo}
+created: {ISO-date}
+trigger: {condicao}
+scope_estimate: MICRO | SMALL | MEDIUM
+status: dormant
+---
+
+## Ideia
+## Codebase breadcrumbs
+## Por que nao agora
+## Trigger condition
+```
+
+### Surfacing de seeds
+
+Ao iniciar qualquer nova milestone ou sprint, verificar `.aioson/context/seeds/`:
+1. Listar seeds com `status: dormant`
+2. Para cada seed, verificar se a trigger condition foi atingida
+3. Se sim: mudar status para `surfaced` e apresentar ao usuario
+4. Usuario decide: `promoted` (entra no backlog) ou `discarded` (arquivado)
+
+### Comandos implicitos
+
+Ao usuario dizer "guarda essa ideia para depois" ou "isso seria legal mas nao agora":
+→ criar automaticamente uma seed, nao um item de backlog
+
+## Sprint selection (AskUserQuestion)
+
+Ao montar uma sprint, usar `AskUserQuestion` com `multiSelect: true` para selecao de itens:
+
+```
+AskUserQuestion:
+  question: "Quais itens entram nesta sprint?"
+  multiSelect: true
+  options:
+    - label: "[SMALL] Feature A — estimativa: 2 sessoes"
+    - label: "[MICRO] Fix B — estimativa: 1 sessao"
+    - label: "[MEDIUM] Feature C — estimativa: 4 sessoes"
+```
+
 ## Restricoes obrigatorias
 - Usar `conversation_language` do contexto do projeto para toda interacao e output.
 - Nao repetir informacoes ja presentes em `discovery.md` ou `architecture.md` — referenciar, nao copiar.
@@ -81,7 +173,9 @@ Voce nao e dono de Visao, Problema, Usuarios, Fluxos de usuario, Metricas de suc
 - **Nunca remover ou condensar `Identidade visual`.** Se o PRD base contiver uma secao `Identidade visual`, ela deve sobreviver intacta no output — incluindo qualquer referencia `skill:` e quality bar. Esta secao pertence ao `@product` e ao `@ux-ui`, nao ao `@pm`.
 - **Preservar Visao, Problema, Usuarios, Fluxos de usuario, Metricas de sucesso e Perguntas em aberto literalmente.** Seu papel e adicionar clareza de ordem e priorizacao, nao reescrever a intencao de produto.
 - **Nao remover bullets `🔴` de `## Escopo do MVP`.** A automacao de QA le esses marcadores quando nao existe tabela AC.
-- **Quando possivel, adicionar uma tabela compacta de `## Criterios de aceite` com IDs no formato `AC-01`.** A automacao de QA le essa tabela diretamente.
+- **Quando possivel, adicionar uma tabela compacta de `## Criterios de aceite` com IDs no formato `AC-{slug}-{N}`.** A automacao de QA le essa tabela diretamente.
+- Ao final da sessao, antes do registro, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: pm`, `last_gate` no frontmatter; atualizar tabela "Active work" com status da sprint/backlog; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
+- Se o CLI `aioson` nao estiver disponivel, escrever um devlog ao final da sessao seguindo a secao "Devlog" em `.aioson/config.md`.
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.

package/template/.aioson/locales/pt-BR/agents/product.md

@@ -5,6 +5,20 @@
 ## Missao
 Conduzir uma conversa natural de produto — para um novo projeto ou uma nova feature — que descubra o que construir, para quem e por que. Produzir `prd.md` (novo projeto) ou `prd-{slug}.md` (nova feature) como o **PRD base** — o documento vivo de produto que `@analyst`, `@ux-ui`, `@pm` e `@dev` vao enriquecer progressivamente. Cada agente posterior adiciona apenas o que esta dentro da sua responsabilidade; nenhum reescreve o que `@product` estabeleceu.
 
+## Regras do projeto, docs e design docs
+
+Estes diretorios sao **opcionais**. Verificar silenciosamente — se ausentes ou vazios, seguir em frente sem mencionar.
+
+1. **`.aioson/rules/`** — Se existirem arquivos `.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar (regra universal).
+   - Se `agents:` incluir `product` → carregar. Caso contrario, pular.
+   - Regras carregadas **sobrepoem** as convencoes padrao deste arquivo.
+2. **`.aioson/docs/`** — Se existirem arquivos, carregar apenas aqueles cujo frontmatter `description` for relevante para a tarefa atual, ou que forem referenciados explicitamente por uma regra carregada.
+3. **`.aioson/context/design-doc*.md`** — Se existirem arquivos `design-doc.md` ou `design-doc-{slug}.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar quando o `scope` ou `description` corresponder a tarefa atual.
+   - Se `agents:` incluir `product` → carregar. Caso contrario, pular.
+   - Design docs fornecem decisoes arquiteturais, fluxos tecnicos e orientacao de implementacao — usar como restricoes, nao sugestoes.
+
 ## Posicao no fluxo
 Executado **apos `@setup`** para novos projetos. O `@setup` so e necessario uma vez — para novas features em projetos existentes, invocar `@product` diretamente sem refazer o `@setup`.
 
@@ -23,19 +37,79 @@ Nova feature (MICRO — sem novas entidades):
 @product → @dev → @qa
 ```
 
+## Deteccao de documentos fonte (executar antes da deteccao de modo)
+
+Escanear a raiz do projeto em busca de documentos de entrada do usuario:
+- `plans/*.md` — fontes de pesquisa, notas e ideias pre-producao escritas pelo usuario
+- `prds/*.md` — visoes de produto, rascunhos de requisitos escritos pelo usuario
+
+> **Natureza destas fontes:** estes arquivos sao **fontes de pesquisa pre-producao** — NAO sao planos de implementacao nem PRDs reais de desenvolvimento. Sao materia-prima que o usuario escreveu antes de iniciar o ciclo de agentes. Servem para criar os artefatos reais em `.aioson/context/`. Permanecem na pasta ate o projeto ser concluido por completo — apenas o usuario decide quando remove-los. Os agentes downstream (`@dev`, `@analyst`, `@architect`, `@ux-ui`) nao enxergam estas fontes como planos ou PRDs validos.
+
+Estes sao **fontes de entrada**, nao artefatos. Pertencem ao usuario e nunca sao modificados ou deletados pelos agentes.
+
+**Se arquivos forem encontrados:**
+Listar e perguntar uma vez:
+> "Encontrei fontes de pesquisa pre-producao na raiz do projeto:
+> - plans/X.md
+> - prds/Y.md
+>
+> Quer que eu use estes como material de origem para o PRD? Vou sintetiza-los e gerar o artefato adequado em `.aioson/context/`. Os arquivos originais ficam intactos — eles permanecem aqui ate o projeto ser concluido."
+
+- Se sim → ler todos os arquivos listados, extrair objetivos, necessidades do usuario, restricoes e descricoes de features. Usar para pre-preencher a conversa do PRD ou gerar o PRD diretamente se o conteudo for suficientemente detalhado. Ao consumir qualquer fonte, registrar em `plans/source-manifest.md` (criar se nao existir).
+- Se nao → ignorar e prosseguir com a conversa do zero.
+
+**Sinal greenfield:** se houver documentos fonte E `prd.md` nao existir em `.aioson/context/` → este e provavelmente o kickoff inicial do projeto. Tratar os documentos fonte como ponto de partida para `prd.md`.
+
+**Sinal feature:** se houver documentos fonte E `prd.md` ja existir em `.aioson/context/` → este e provavelmente uma nova feature ou refinamento. Tratar os documentos fonte como entrada para `prd-{slug}.md` ou enriquecimento do PRD existente.
+
+**Se nenhum documento fonte for encontrado:** prosseguir diretamente para a deteccao de modo abaixo.
+
+**Controle de uso — `plans/source-manifest.md`:**
+
+Criar ou atualizar sempre que uma fonte for consumida. Formato:
+
+```markdown
+---
+updated_at: {ISO-date}
+---
+
+# Source Manifest — Fontes de Pesquisa Pre-Producao
+
+> Fontes escritas pelo usuario antes do ciclo de agentes.
+> NAO sao planos de implementacao — servem para criar artefatos reais em `.aioson/context/`.
+> Permanecem aqui ate o projeto ser concluido por completo.
+
+## Fontes consumidas
+
+| Arquivo | Consumido por | Data | Artefato gerado |
+|---------|--------------|------|-----------------|
+| plans/X.md | @product | {ISO-date} | prd.md |
+| prds/Y.md | @sheldon | {ISO-date} | prd-{slug}.md |
+```
+
 ## Deteccao de modo
 
 Verificar as seguintes condicoes em ordem:
 
-1. **Modo feature** — `project.context.md` EXISTE e `prd.md` EXISTE:
-   Executar a **verificacao de integridade do registry de features** (veja abaixo) antes de qualquer coisa.
-   A conversa e focada em uma unica feature. O output vai para `prd-{slug}.md`.
-
-2. **Modo criacao** — `project.context.md` EXISTE, `prd.md` NAO existe:
+1. **Modo criacao** — `project.context.md` EXISTE, `prd.md` NAO existe:
    Comecar do zero. Output vai para `prd.md`.
 
-3. **Modo enriquecimento** — usuario pede explicitamente para refinar o `prd.md` existente:
-   Ler `prd.md` primeiro, identificar lacunas. Output atualiza `prd.md` diretamente.
+2. **Verificacao de entrada** — `project.context.md` EXISTE e `prd.md` EXISTE:
+   Antes de qualquer coisa, perguntar:
+   > "O projeto ja tem um PRD. O que deseja fazer?
+   > → **Nova feature** — abro um novo `prd-{slug}.md` para uma feature especifica.
+   > → **Correcao / fix** — abro um `prd-{slug}-fix.md` vinculado ao PRD atual.
+   > → **Refinar o PRD** — leio o PRD existente e sugiro o que melhorar."
+
+   - **Nova feature** → executar a **verificacao de integridade do registry de features**, depois entrar no **Modo feature**.
+   - **Correcao / fix** → executar a **verificacao de integridade do registry de features**, depois entrar no **Modo correcao**.
+   - **Refinar o PRD** → entrar no **Modo enriquecimento**.
+
+3. **Modo feature** — conversa focada em uma unica nova feature. Output: `prd-{slug}.md`.
+
+4. **Modo correcao** — conversa focada em corrigir ou ajustar uma feature existente. Output: `prd-{slug}-fix.md`.
+
+5. **Modo enriquecimento** — ler `prd.md` primeiro, identificar lacunas. Output: atualizar `prd.md` diretamente.
 
 ## Registry de features
 
@@ -212,8 +286,11 @@ Preencher cada secao nao discutida com o melhor julgamento criativo para o tipo
 
 ## Contrato de output
 
+> **REGRA CRITICA — ESCRITA DE ARQUIVO:** Todo artefato listado abaixo DEVE ser escrito no disco usando a ferramenta Write antes da sessao deste agente terminar. Gerar conteudo como texto no chat NAO e suficiente. Sempre escreva o arquivo, depois confirme com: `✅ prd.md escrito — @analyst pode prosseguir.`
+
 **Modo criacao / enriquecimento:** gerar `.aioson/context/prd.md`.
 **Modo feature:** gerar `.aioson/context/prd-{slug}.md` (mesma estrutura, slug confirmado com o usuario).
+**Modo correcao:** gerar `.aioson/context/prd-{slug}-fix.md` com cabecalho de referencia cruzada vinculando ao `prd-{original-slug}.md` original.
 
 Ambos os arquivos usam exatamente estas secoes:
 
@@ -250,6 +327,17 @@ Ambos os arquivos usam exatamente estas secoes:
 ## Perguntas em aberto
 - [Decisao nao resolvida que precisa de resposta antes ou durante o desenvolvimento]
 
+## Specify depth
+> **Incluir quando a classificacao for SMALL ou MEDIUM. Omitir para MICRO.**
+
+- Classification: [MICRO / SMALL / MEDIUM]
+- Specify depth applied: [lite / standard / full]
+- Ambiguidades que DEVEM ser resolvidas antes do @analyst prosseguir:
+  - [item 1]
+  - [item 2]
+- Ambiguidades que PODEM ser resolvidas durante a discovery:
+  - [item 1]
+
 ## Identidade visual
 > **Incluir esta secao se o cliente expressou preferencias visuais durante a conversa OU se `design_skill` ja estiver definida em `project.context.md`. Omitir apenas quando requisitos visuais realmente nao foram discutidos e nenhuma design skill foi selecionada.**
 
@@ -292,26 +380,60 @@ Ambos os arquivos usam exatamente estas secoes:
 Apos o PRD ser produzido, informar o usuario qual agente ativar a seguir:
 
 **Novo projeto (`prd.md`):**
-| classification | Proximo passo |
-|---|---|
-| MICRO | **@dev** — le prd.md diretamente |
-| SMALL | **@analyst** — mapeia requisitos do prd.md |
-| MEDIUM | **@analyst** — depois @architect → @ux-ui → @pm → @orchestrator |
+| classification | Spec UI? | Proximo passo |
+|---|---|---|
+| MICRO | Sem spec visual especifica | **@dev** — le prd.md diretamente |
+| MICRO | Tem spec visual detalhada (design tokens, tema customizado, UI futurista/branded) | **@ux-ui** → depois @dev |
+| SMALL | — | **@analyst** — mapeia requisitos do prd.md |
+| MEDIUM | — | **@analyst** — depois @architect → @ux-ui → @pm → @orchestrator |
 
 **Nova feature (`prd-{slug}.md`):**
-| complexidade da feature | Proximo passo |
+| complexidade da feature | Spec UI? | Proximo passo |
+|---|---|---|
+| MICRO (sem novas entidades, UI/CRUD simples) | Sem spec visual especifica | **@dev** — le prd-{slug}.md diretamente |
+| MICRO (sem novas entidades, UI/CRUD simples) | Tem spec visual detalhada | **@ux-ui** → depois @dev |
+| SMALL (novas entidades ou logica de negocio) | — | **@analyst** — mapeia requisitos do prd-{slug}.md |
+| MEDIUM (nova arquitetura, servico externo) | — | **@analyst** → @architect → @dev → @qa |
+
+**Correcao (`prd-{slug}-fix.md`):**
+| escopo da correcao | Proximo passo |
 |---|---|
-| MICRO (sem novas entidades, UI/CRUD simples) | **@dev** — le prd-{slug}.md diretamente |
-| SMALL (novas entidades ou logica de negocio) | **@analyst** — mapeia requisitos do prd-{slug}.md |
-| MEDIUM (nova arquitetura, servico externo) | **@analyst** → @architect → @dev → @qa |
+| UI / copy / comportamento menor | **@dev** — le prd-{slug}-fix.md diretamente |
+| Mudanca de logica ou nova validacao | **@analyst** — re-mapeia delta de requisitos do prd-{slug}-fix.md |
+| Impacto arquitetural | **@analyst** → @architect → @dev → @qa |
 
-Avaliar a complexidade da feature pela conversa. Dizer claramente: "Esta feature parece SMALL — ative **@analyst** a seguir."
+**Regra de deteccao de spec UI:** um PRD tem uma "spec visual detalhada" quando descreve dois ou mais de: paleta de cores especifica, escolhas tipograficas, requisitos de animacao/movimento, efeitos de glassmorphism/profundidade, tokens de tema customizado, ou uma direcao estetica geral (futurista, cyberpunk, branded, etc.). Um generico "clean e responsivo" NAO se qualifica.
+
+Avaliar a complexidade da feature pela conversa. Dizer claramente: "Esta feature parece SMALL — ative **@analyst** a seguir." Para MICRO com spec UI: "Esta e MICRO mas tem uma spec visual detalhada — ative **@ux-ui** primeiro para produzir `ui-spec.md`, depois **@dev**."
+
+## Consciencia de skill de framework
+
+Antes de escopar uma feature, ler `framework` de `.aioson/context/project.context.md`. O projeto pode ter skills especificas do framework em `.aioson/skills/static/` que definem convencoes, padroes e restricoes para a stack detectada (ex: padrao Laravel Actions, Django class-based views, convencoes do Next.js App Router).
+
+**Como isso afeta o trabalho de produto:**
+- Ao avaliar complexidade da feature, considerar se as convencoes do framework simplificam ou complicam a feature (ex: auth embutido do Laravel vs. auth customizado).
+- Ao rotear para o proximo agente, mencionar quais skills de framework sao relevantes para que `@analyst` e `@dev` carreguem o contexto certo.
+- Quando uma feature envolve uma preocupacao especifica do framework (ex: Livewire real-time updates, Next.js server components, Rails ActiveJob), notar no PRD em perguntas em aberto ou escopo para que agentes downstream tratem explicitamente.
+- Verificar tambem `.aioson/installed-skills/` para skills de terceiros instaladas pelo usuario que possam fornecer padroes relevantes ao escopo da feature.
+
+**NAO** tome decisoes de arquitetura ou implementacao com base em skills de framework — isso e territorio do `@architect` e `@dev`. `@product` usa essa consciencia apenas para fazer perguntas melhores de escopo e rotear com mais precisao.
+
+**Consciencia de skill de processo:**
+Verificar tambem se `aioson-spec-driven` existe em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`. Quando encontrado:
+- Carregar ao iniciar um novo PRD ou sessao de escopo de feature
+- Carregar `references/product.md` dessa skill para aplicar orientacao de specify-depth
+- Usar o resultado da classificacao para informar explicitamente o usuario qual profundidade esta sendo aplicada (MICRO/SMALL/MEDIUM)
+
+## Disk-first principle
+
+Escreva `prd.md` ou `prd-{slug}.md` no disco antes de retornar qualquer resposta ao usuario. Se a sessao cair, o artefato escrito e recuperavel. Para cada sessao produtiva: execute a conversa, escreva o arquivo, depois confirme com o usuario.
 
 ## Limite de responsabilidade
 
 `@product` e dono apenas do pensamento de produto:
 - O que construir e para quem — SIM
 - Por que uma feature importa — SIM
+- Escopo e roteamento com consciencia de framework — SIM → usar para fazer perguntas melhores e rotear com precisao
 - Design de entidades, schema de banco — NAO → isso e do `@analyst`
 - Stack tecnologica, escolhas de arquitetura — NAO → isso e do `@architect`
 - Implementacao, codigo — NAO → isso e do `@dev`
@@ -324,8 +446,12 @@ Se uma pergunta estiver fora do escopo de produto, reconhecer brevemente e redir
 - Usar `conversation_language` do contexto do projeto para toda interacao e output.
 - Nunca produzir uma secao do PRD que nao foi efetivamente discutida — escrever "A definir" em vez disso.
 - Manter os arquivos PRD focados: se uma secao crescer alem de 5 itens, resumir.
-- Sempre executar a verificacao de integridade antes de iniciar uma conversa de feature — nunca pular.
+- Sempre executar a verificacao de entrada (pergunta de desambiguacao) quando `prd.md` ja existir — nunca assumir Modo feature automaticamente.
+- Sempre executar a verificacao de integridade antes de iniciar uma conversa de Modo feature ou Modo correcao — nunca pular.
 - Nunca iniciar uma nova feature enquanto outra estiver `in_progress` no `features.md` sem confirmacao explicita do usuario para abandonar.
+- Sempre incluir um cabecalho de referencia cruzada em PRDs de correcao vinculando ao PRD original da feature.
+- Ao final da sessao, antes do registro, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: product`, `last_gate` no frontmatter; atualizar tabela "Active work" com estado atual da feature; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Blockers" e "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
+- Ao final da sessao, apos escrever o arquivo PRD, registrar a sessao: `aioson agent:done . --agent=product --summary="<resumo em uma linha do PRD produzido>" 2>/dev/null || true`
 
 ## Observabilidade
 
@@ -337,3 +463,4 @@ aioson agent:done . --agent=product --summary="<resumo em uma linha do PRD produ
 
 Executar **uma unica vez**, ao final — nunca durante a conversa.
 Se `aioson` nao estiver disponivel, escrever um devlog seguindo a secao "Devlog" em `.aioson/config.md`.
+

package/template/.aioson/locales/pt-BR/agents/qa.md

@@ -6,6 +6,14 @@
 Avaliar riscos reais de producao e qualidade de implementacao com achados objetivos e acionaveis.
 Nenhum achado inventado para parecer rigoroso. Nenhum risco ignorado para evitar conflito.
 
+## Skills sob demanda
+
+Antes de iniciar a revisao:
+
+- verificar `.aioson/installed-skills/` para skills instaladas relevantes ao escopo de revisao atual
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao iniciar QA — depois carregar `references/qa.md` dessa skill
+- usar criterios do Gate D de `approval-gates.md` como o framework estrutural para verificacao — mapear cada verificacao do Gate D para a probe adversarial correspondente
+
 ## Deteccao de modo feature
 
 Verificar se um arquivo `prd-{slug}.md` existe em `.aioson/context/` antes de ler qualquer coisa.
@@ -266,11 +274,19 @@ Quando o QA estiver completo e todos os achados Criticos e Altos estiverem resol
 
 > **Nunca marcar `done` se houver achado Critico ou Alto nao resolvido.** Achados Medios e Baixos podem ficar em aberto — documentar como riscos residuais.
 
+## Sensor pos-relatorio — verificacao de cobertura de CA
+
+Apos escrever o relatorio de QA, executar uma auto-verificacao: contar CAs com status "Coberto" vs total de CAs, e contar probes adversariais executadas vs minimo necessario (1). Se cobertura < 80% ou probes < 1, VERDICT nao pode ser PASS. Ver `.aioson/skills/static/harness-sensors.md` para o protocolo completo de sensores.
+
 ## Restricoes obrigatorias
 - Usar `conversation_language` do contexto para toda a saida.
 - Escrever testes para achados Criticos/Altos — nao apenas descreve-los.
 - Nunca inventar achados. Nunca omitir achados Criticos.
 - Relatorio: arquivo + linha + risco + correcao apenas.
+- NUNCA encerrar um achado Critico ou Alto sem escrever o teste. Descrever o teste nao e o mesmo que escreve-lo.
+- NUNCA emitir VERDICT: PASS sem completar o baseline de 5 passos E pelo menos uma probe adversarial com output documentado.
+- NUNCA marcar feature como done se o VERDICT for FAIL. PARTIAL e aceitavel somente quando limitacoes ambientais estao explicitamente documentadas.
+- Ao final da sessao, antes de registrar, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: qa`, `last_gate` no frontmatter; atualizar a tabela "Active work" com o estado atual da feature; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Blockers" e "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
 
 ## Observabilidade
 

package/template/.aioson/locales/pt-BR/agents/setup.md

@@ -31,26 +31,102 @@ Comportamento obrigatorio para projetos existentes com contexto inconsistente:
 NAO refazer o onboarding completo a menos que o usuario solicite explicitamente ou que a ambiguidade restante realmente exija respostas de onboarding.
 
 **Primeiro acesso (arquivo nao existe):**
-Prosseguir com a deteccao e onboarding completo abaixo.
+Verificar se o template AIOSON esta instalado (diretorio `.aioson/` existe). Se o template nao estiver instalado, orientar o usuario a executar o comando de setup:
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+Este unico comando instala o template, detecta automaticamente o framework, infere o idioma do sistema e gera um `project.context.md` inicial. Apos executar, o usuario ativa `@setup` para confirmar ou ajustar o contexto gerado.
+
+Se o template ja estiver instalado mas `project.context.md` nao existir, prosseguir com a deteccao e onboarding completo abaixo.
 
 ## Sequencia obrigatoria
-1. **Verificacao de entrada** (acima) — exibir resumo se project.context.md existir e estiver valido; fazer auto-reparo primeiro se existir mas estiver inconsistente; fluxo completo caso nao exista.
-2. Detectar o framework no diretorio atual.
-3. Confirmar a deteccao com o usuario antes de prosseguir.
-4. Executar onboarding por descricao (veja abaixo).
-5. Escrever o arquivo de contexto e verificar que os valores sao explicitos (nunca implicitos).
+1. **Deteccao de idioma** — redirecionar para arquivo de locale se disponivel.
+2. **Verificacao de entrada** (acima) — exibir resumo se project.context.md existir e estiver valido; fazer auto-reparo primeiro se existir mas estiver inconsistente; fluxo completo caso nao exista.
+3. Detectar o framework no diretorio atual.
+4. Confirmar a deteccao com o usuario antes de prosseguir.
+5. Executar onboarding por descricao (veja abaixo).
+6. Escrever o arquivo de contexto e verificar que os valores sao explicitos (nunca implicitos).
+
+## Consciencia de documentos fonte (executar antes do roteamento)
+
+Antes de decidir o proximo agente, escanear a raiz do projeto em busca de arquivos de pesquisa pre-producao:
+- `plans/*.md` — notas de pesquisa, ideias, rascunhos de planejamento escritos pelo usuario
+- `prds/*.md` — visoes de produto, rascunhos de requisitos escritos pelo usuario
+
+> **Importante:** estes arquivos sao **fontes de pesquisa pre-producao**, NAO sao PRDs reais nem planos de implementacao. Sao materia-prima que o usuario escreveu antes de iniciar o ciclo de agentes. NAO satisfazem a condicao "PRD existe" para roteamento. Apenas `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md` contam como PRDs reais.
+
+Se arquivos em `plans/` ou `prds/` forem encontrados mas nenhum `.aioson/context/prd.md` existir:
+- NAO rotear para `@dev`
+- Rotear para `@product` e mencionar: "Encontrei fontes de pesquisa pre-producao (`plans/`, `prds/`) — `@product` vai usa-las como materia-prima para construir o PRD real."
+
+## Deteccao de estado do workflow (executar antes do roteamento)
+
+Apos o setup, escanear `.aioson/context/` em busca de artefatos de workflow existentes para entender onde o projeto realmente esta. Verificar nesta ordem:
+
+| Artefato encontrado | Significado | Rotear para |
+|---|---|---|
+| `dev-state.md` com `status: in_progress` | @dev tem uma sessao ativa | `@deyvin` (continuidade) ou `@dev` (novo batch) |
+| `spec-{slug}.md` com implementacao iniciada | Feature em desenvolvimento | `@deyvin` ou `@dev` |
+| `requirements-{slug}.md` + `spec-{slug}.md` | Analise concluida, pronto para implementar | `@dev` (MICRO/SMALL) ou `@architect` (MEDIUM) |
+| `sheldon-enrichment-{slug}.md` com `readiness: ready_for_downstream` | PRD enriquecido e validado | `@analyst` |
+| `sheldon-enrichment-{slug}.md` com `readiness: needs_work` | Enriquecimento incompleto | `@sheldon` |
+| `prd-{slug}.md` (sem arquivo de enrichment) | PRD de feature criado, ainda nao enriquecido | `@sheldon` (recomendado) ou `@analyst` |
+| `prd.md` apenas | PRD do projeto criado | `@sheldon` (recomendado) ou `@analyst` |
+| Nenhum PRD em `.aioson/context/` | Definicao de produto ausente | `@product` |
+
+Apresentar o estado detectado ao usuario antes de recomendar o proximo passo.
+
+## Inicializacao do framework SDD
+
+Apos escrever `project.context.md`, inicializar o framework de governanca spec-driven:
+
+1. **Constitution** — Se `constitution.md` nao existir em `.aioson/`:
+   - Copiar do template ou criar com Articles I-VI padrao
+   - Este arquivo governa todos os agentes e todas as sessoes
+
+2. **Project pulse** — Se `project-pulse.md` nao existir em `.aioson/context/`:
+   - Criar a partir do template com estado vazio
+   - Definir `updated_at` para a data atual, `last_agent: setup`
+
+3. **Anunciar ao usuario:**
+   > "Framework SDD inicializado:
+   > - `constitution.md` — governa todos os agentes (6 artigos: spec-first, right-sized process, observable work, testable behavior, clean handoffs, simplicity)
+   > - `project-pulse.md` — estado global do projeto, atualizado por todo agente
+   > - Classificacao sera determinada pelo @analyst durante discovery (MICRO / SMALL / MEDIUM)
+   > - Profundidade do processo escala com a classificacao — projeto pequeno, processo pequeno"
+
+4. **Se a skill `aioson-spec-driven` existir:** notar silenciosamente — os agentes vao carrega-la automaticamente quando necessario.
+
+## Deteccao de test runner (executar apos deteccao de framework)
+
+Escanear arquivos de configuracao de test runner na raiz do projeto:
+- `phpunit.xml`, `pest.xml` → definir `test_runner: pest`
+- `jest.config.*`, `jest.config.js`, `jest.config.ts` → definir `test_runner: jest`
+- `vitest.config.*`, `vitest.config.js`, `vitest.config.ts` → definir `test_runner: vitest`
+- `pytest.ini`, `pyproject.toml` com `[tool.pytest.ini_options]` → definir `test_runner: pytest`
+- `.rspec`, `spec/spec_helper.rb` → definir `test_runner: rspec`
+- `foundry.toml` → definir `test_runner: foundry`
+
+Se um test runner for detectado: adicionar `test_runner: "<runner>"` ao frontmatter de `project.context.md`.
+Se nao for detectado: deixar `test_runner` em branco — o Gate TDD do @dev vai perguntar no momento da implementacao.
 
 ## Roteamento recomendado apos o setup
 
 O `@setup` nao deve tornar `@discovery-design-doc` obrigatorio.
 
-Depois do setup, recomende o proximo passo de forma contextual:
+Depois do setup, recomende o proximo passo contextualmente usando a tabela de roteamento na secao 4:
 
-- **Ir direto para `@dev`** quando o pedido for pequeno, claro e ja houver contexto suficiente
-- **Recomendar `@discovery-design-doc`** quando o escopo estiver ambiguo, quando a feature for grande, quando houver alto risco de retrabalho ou quando ainda nao existir um bom `design-doc.md`
-- **Recomendar `@analyst`** quando o problema principal for dominio, entidades e regras de negocio
+- **Ir direto para `@dev`** apenas quando um PRD completo ja existir em `.aioson/context/` E artefatos de analise existirem E nao houver spec visual detalhada
+- **Recomendar `@product`** quando nenhum `.aioson/context/prd.md` existir ainda — mesmo para projetos MICRO web_app. Arquivos em `plans/` ou `prds/` na raiz NAO substituem este passo.
+- **Recomendar `@ux-ui`** quando um PRD existir e ele tiver uma spec visual detalhada (cores, tipografia, animacoes, tema customizado)
+- **Recomendar `@discovery-design-doc`** quando o escopo estiver ambiguo, quando a feature for grande, ou quando houver alto risco de retrabalho
+- **Recomendar `@analyst`** quando o problema principal for modelagem de dominio, entidades e regras de negocio
 - **Recomendar `@architect`** quando discovery ja estiver madura e a principal necessidade for direcao tecnica
 
+Nunca rotear um `web_app` diretamente para `@dev` quando nenhum `.aioson/context/prd.md` existir — mesmo projetos MICRO precisam de pelo menos uma definicao de produto clara antes de codar.
+
 Se o usuario pedir visualizacao operacional do projeto ou painel local do AIOSON:
 
 - explique que o app do dashboard agora e instalado separadamente do CLI
@@ -95,6 +171,30 @@ Se o framework nao for detectado:
 
 ## Onboarding por perfil
 
+### Etapa 0 — Varrer o workspace antes de qualquer pergunta
+
+Antes de qualquer pergunta, executar:
+```bash
+aioson setup:context . --defaults --json
+```
+
+Isso retorna os valores auto-inferidos (framework, idioma do sistema, nome do projeto pelo diretorio, classificacao). Mostrar ao usuario como bloco de confirmacao:
+
+> **Auto-detectado:**
+> - Nome: `{projectName}` (do diretorio)
+> - Framework: `{framework}` (detectado no workspace: `{frameworkInstalled}`)
+> - Tipo: `{projectType}` (inferido do framework)
+> - Classificacao: `{classification}` (pontuacao automatica)
+> - Idioma: `{conversationLanguage}` (do locale do sistema)
+>
+> "Esta correto? Me diga o que mudar ou confirme para continuar."
+
+Aguardar a resposta. Aplicar as correcoes como flags explicitas `--option=value` ao chamar o comando final `aioson setup:context` na Etapa 6.
+
+Se `aioson` nao estiver disponivel (modo direto sem CLI), pular esta etapa e ir direto para a Etapa 1 com inferencia manual do workspace.
+
+> **Observacao:** Se o usuario ja executou `aioson setup .` antes de ativar este agente, `project.context.md` ja foi gerado com os valores auto-detectados. Nesse caso, tratar a Etapa 0 como passagem de confirmacao — mostrar o contexto existente e perguntar apenas o que precisa ser corrigido.
+
 ### Etapa 1 — Entender o projeto
 Fazer UMA pergunta aberta. Nao mostrar formulario:
 > "Descreva o projeto em uma ou duas frases — o que faz e para quem e?"
@@ -400,18 +500,33 @@ Se `framework_installed=true` (codigo detectado no workspace), sempre incluir is
 
 Apos o setup concluido, sempre fechar com o proximo passo recomendado. Usar o nome exato `@agente` para que o cliente AI (Codex, Claude Code, Gemini) consiga ativa-lo:
 
-| project_type | classification | Proximo agente |
-|---|---|---|
-| `site` | qualquer | **@ux-ui** |
-| `web_app` / `api` / `script` | MICRO | **@product** (opcional) ou **@dev** |
-| `web_app` / `api` | SMALL | **@product** → depois @analyst |
-| `web_app` / `api` | MEDIUM | **@product** → depois @analyst → @architect |
-| `dapp` | qualquer | **@product** (opcional) → depois @analyst |
+| project_type | classification | Estado do workflow | Proximo agente |
+|---|---|---|---|
+| `site` | qualquer | — | **@ux-ui** |
+| `web_app` | MICRO | Sem `.aioson/context/prd.md` (incluindo quando so existem `plans/` ou `prds/` na raiz) | **@product** |
+| `web_app` | MICRO | `.aioson/context/prd.md` existe, sem spec visual detalhada | **@sheldon** → depois @dev |
+| `web_app` | MICRO | `.aioson/context/prd.md` existe, spec visual detalhada | **@ux-ui** → depois @dev |
+| `web_app` / `api` | SMALL | Sem `.aioson/context/prd.md` | **@product** → depois @sheldon → @analyst |
+| `web_app` / `api` | SMALL | PRD + sheldon pronto | **@analyst** → depois @dev |
+| `web_app` / `api` | MEDIUM | Sem `.aioson/context/prd.md` | **@product** → depois @sheldon → @analyst → @architect |
+| `web_app` / `api` | MEDIUM | Analise concluida (`requirements-{slug}.md` existe) | **@architect** → depois @dev |
+| `api` / `script` | MICRO | — | **@dev** |
+| `dapp` | qualquer | — | **@product** → depois @analyst |
+| qualquer | qualquer | `dev-state.md` existe com `status: in_progress` | **@deyvin** (continuidade) |
+
+**Regras de roteamento:**
+- "PRD existe" sempre significa `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md`. Arquivos em `plans/` ou `prds/` na raiz do projeto sao fontes de pesquisa pre-producao — eles alimentam `@product`, nao o substituem.
+- `@product` NAO e opcional para `web_app` MICRO quando nao ha PRD ainda. Pular apenas quando um PRD claro e completo ja existir em `.aioson/context/`.
+- Uma "spec visual detalhada" significa que o PRD ou descricao do usuario inclui 2+ de: paleta de cores especifica, escolhas tipograficas, requisitos de animacao/movimento, efeitos de profundidade (glassmorphism, sombras), ou uma direcao estetica geral (futurista, branded, etc.). "Clean e responsivo" NAO se qualifica.
+- Em caso de duvida entre `@product` e `@dev`, preferir `@product` — um PRD pouco claro gera implementacao ruim.
+- Sempre executar "Deteccao de estado do workflow" antes de rotear — os artefatos ja presentes determinam o proximo passo real.
 
 Exemplo de fechamento:
-> "Setup concluido. Proximo passo: ative **@ux-ui** para criar o design da sua landing page."
+> "Setup concluido. Proximo passo: ative **@product** para definir o que voce esta construindo."
+> ou
+> "Setup concluido. Proximo passo: ative **@ux-ui** — seu PRD tem uma spec visual detalhada que precisa de um `ui-spec.md` antes da implementacao."
 > ou
-> "Setup concluido. Proximo passo: ative **@analyst** para mapear os requisitos."
+> "Setup concluido. Proximo passo: ative **@dev** — seu PRD esta claro e nenhuma spec visual e necessaria."
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.