@jaimevalasek/aioson 1.4.0 → 1.6.0

package/docs/openclaw-bridge.md

@@ -0,0 +1,308 @@
+# OpenClaw + AIOSON Bridge
+
+> AIOSON receives external triggers. OpenClaw delivers them. Neither system changes — the bridge is pure configuration.
+
+## Overview
+
+```
+[External channel]          [OpenClaw]            [AIOSON squad-webhook]
+ WhatsApp, Telegram,   →   gateway de canal   →   POST /trigger
+ Slack, webhook ERP         identifica sessão       executa squad
+                                                    ↓
+                            ←   callback HTTP   ←   POST callback_url
+                            envia resposta
+                            ao canal
+```
+
+## Quick start
+
+### 1. Start the webhook server
+
+```bash
+export AIOSON_WEBHOOK_TOKEN=your-secret-token
+aioson squad:webhook start --port 3210
+```
+
+The server auto-discovers all squads in `.aioson/squads/`. Output:
+
+```
+AIOSON squad webhook server started on port 3210
+Available squads: atendimento, vendas, logistica
+Endpoints: POST /trigger  GET /status/:run_id  GET /health
+```
+
+### 2. Generate the OpenClaw configuration
+
+```bash
+aioson squad:webhook config --channel whatsapp --squad atendimento
+```
+
+Copy the output into your `openclaw.json`.
+
+### 3. Verify
+
+```bash
+curl http://localhost:3210/health
+# {"ok":true,"version":"x.x.x","squads":["atendimento","vendas","logistica"]}
+```
+
+---
+
+## Endpoints
+
+### `GET /health`
+
+No authentication required.
+
+```json
+{ "ok": true, "version": "1.4.0", "squads": ["atendimento", "vendas"] }
+```
+
+---
+
+### `POST /trigger`
+
+Async squad execution. Returns immediately with a `run_id`.
+
+**Headers:**
+```
+Authorization: Bearer <AIOSON_WEBHOOK_TOKEN>
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "squad": "atendimento",
+  "input": "quero dipirona 500mg",
+  "session_id": "wa:5511999000",
+  "callback_url": "https://your-server/callback",
+  "metadata": {
+    "channel": "whatsapp",
+    "phone": "+5511999000",
+    "user_name": "João"
+  }
+}
+```
+
+| Field          | Required | Description |
+|----------------|----------|-------------|
+| `squad`        | yes      | Squad slug to execute |
+| `input`        | yes      | User message |
+| `session_id`   | no       | Opaque string — enables conversation continuity |
+| `callback_url` | no       | Where to POST the response when done |
+| `metadata`     | no       | Arbitrary key/value, echoed back in the callback |
+
+**Response (202):**
+```json
+{ "run_id": "a1b2c3d4e5f6a7b8", "status": "queued" }
+```
+
+**Callback payload (async POST to `callback_url`):**
+```json
+{
+  "run_id": "a1b2c3d4e5f6a7b8",
+  "session_id": "wa:5511999000",
+  "response": "Temos dipirona 500mg por R$8,90. Deseja adicionar ao carrinho?",
+  "status": "completed",
+  "metadata": { "channel": "whatsapp", "phone": "+5511999000", "user_name": "João" }
+}
+```
+
+Callback delivery: 3 retries with exponential backoff (30s → 60s → 120s).
+
+---
+
+### `GET /status/:run_id`
+
+Poll execution state when no `callback_url` was provided.
+
+```
+GET /status/a1b2c3d4e5f6a7b8
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "run_id": "a1b2c3d4e5f6a7b8",
+  "status": "running",
+  "response": null,
+  "error": null
+}
+```
+
+`status` values: `queued` → `running` → `completed` | `failed`
+
+---
+
+### `POST /query`
+
+Synchronous query — for fast lookups that don't need a full squad session (e.g., product search from a website). Timeout: 10 seconds.
+
+```json
+{
+  "squad": "catalogo",
+  "query": "dipirona 500mg",
+  "max_results": 10
+}
+```
+
+```json
+{
+  "results": [{ "id": 42, "name": "Dipirona 500mg", "price": 8.90 }],
+  "squad": "catalogo",
+  "latency_ms": 340
+}
+```
+
+---
+
+## Session continuity
+
+When `session_id` is provided, AIOSON maintains conversation history across multiple calls.
+
+**First call:**
+```json
+{ "squad": "atendimento", "input": "quero dipirona", "session_id": "wa:5511999000" }
+```
+→ Squad receives: `quero dipirona`
+
+**Second call (same session):**
+```json
+{ "squad": "atendimento", "input": "qual o preço?", "session_id": "wa:5511999000" }
+```
+→ Squad receives:
+```
+[Conversation history]
+user: quero dipirona
+assistant: Temos dipirona 500mg por R$8,90. Deseja adicionar ao carrinho?
+
+[Current message]
+qual o preço?
+```
+
+Session files are stored in `.aioson/sessions/` and expire after 24 hours of inactivity (configurable via `AIOSON_SESSION_TTL_HOURS`).
+
+---
+
+## OpenClaw configuration
+
+### WhatsApp (full example)
+
+```yaml
+# openclaw.json
+hooks:
+  whatsapp:
+    auto_reply:
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          {
+            "squad": "atendimento",
+            "input": "{{message.text}}",
+            "session_id": "wa:{{message.from}}",
+            "callback_url": "{{openclaw.callback_url}}",
+            "metadata": {
+              "channel": "whatsapp",
+              "phone": "{{message.from}}",
+              "user_name": "{{message.contact_name}}"
+            }
+          }
+```
+
+### Telegram
+
+```yaml
+hooks:
+  telegram:
+    auto_reply:
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          {
+            "squad": "suporte",
+            "input": "{{message.text}}",
+            "session_id": "tg:{{message.chat_id}}",
+            "callback_url": "{{openclaw.callback_url}}",
+            "metadata": { "channel": "telegram" }
+          }
+```
+
+### Multiple squads by intent
+
+Route different message patterns to different squads:
+
+```yaml
+hooks:
+  whatsapp:
+    auto_reply:
+      - pattern: "^(pedido|comprar|quero|carrinho)"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "vendas", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+
+      - pattern: "^(onde|entrega|rastreio|pedido)"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "logistica", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "atendimento", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+```
+
+---
+
+## Security
+
+| Concern | Mechanism |
+|---------|-----------|
+| Authentication | Bearer token (`AIOSON_WEBHOOK_TOKEN`) on all endpoints except `/health` |
+| Rate limiting | 60 req/min per IP by default |
+| Squad allowlist | Only squads in `.aioson/squads/` are accessible |
+| Callback security | Callbacks only POST to URLs provided by the caller |
+| Session isolation | Each `session_id` maps to a separate file; no cross-session access |
+
+Set `AIOSON_WEBHOOK_TOKEN` to a random secret (minimum 32 chars):
+
+```bash
+openssl rand -hex 32
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AIOSON_WEBHOOK_TOKEN` | — | Bearer token (required for security) |
+| `AIOSON_WEBHOOK_PORT` | `3210` | Server port |
+| `AIOSON_SESSION_TTL_HOURS` | `24` | Session expiry in hours |
+
+---
+
+## CLI reference
+
+```bash
+# Start webhook server
+aioson squad:webhook start [path] [--port 3210] [--token TOKEN]
+
+# Generate OpenClaw config snippet
+aioson squad:webhook config [--channel whatsapp] [--squad atendimento] [--port 3210]
+```

package/docs/pt/README.md

@@ -15,9 +15,16 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 | [Squad e Genome](./squad-genome.md) | Como criar squads modulares, diferenciar skill de genome, aplicar genomes e publicar entregáveis HTML |
 | [Agentes Customizados](./agentes-customizados.md) | Criar agentes personalizados com `squad:agent-create` — tipos, Voice DNA, infra operacional, maturity scoring |
 | [Skills](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework e compatibilidade cross-tool |
+| [design-hybrid-forge](./design-hybrid-forge.md) | Fluxo canônico para criar skills híbridas de design com preset visual, locale automático e histórico |
 | [Automação de Squads](./automacao-squads.md) | Transformar processos de squad em scripts executáveis (Python/Node.js) que rodam sem LLM |
 | [Output Strategy e Delivery](./output-strategy-delivery.md) | Configurar webhooks, automatizar entrega de conteúdo, monitorar delivery e troubleshoot |
 | [Suporte Web3](./web3.md) | Guia para projetos dApp (Ethereum, Solana, Cardano) |
+| [Recuperação de Sessão](./recuperacao-de-sessao.md) | Gerar e restaurar contexto entre sessões do Claude Code após compactação |
+| [Monitor de Contexto](./monitor-de-contexto.md) | Visualizar uso de janela de contexto por agente com alertas de warning e critical |
+| [Busca de Contexto](./busca-de-contexto.md) | Indexar e buscar documentos do projeto via FTS5 com ranking por relevância e recência |
+| [Cache de Contexto](./cache-de-contexto.md) | Salvar snapshots de contexto e restaurar entre sessões |
+| [Sandbox de Execução](./sandbox.md) | Executar comandos com timeout, redação de secrets e summarização de output |
+| [Agent Sharding](./agent-sharding.md) | Carregar apenas as seções relevantes de instruções de agente para uma tarefa específica |
 
 ## Documentação em inglês
 

package/docs/pt/agent-sharding.md

@@ -0,0 +1,132 @@
+# Agent Sharding
+
+> Carrega apenas as seções relevantes de um arquivo de instruções de agente para uma tarefa específica, reduzindo consumo de tokens.
+
+Arquivos de instrução de agente podem conter muitas seções — role, guidelines, error handling, output format, checklist de revisão — mas para uma tarefa específica, apenas algumas são necessárias. O `agent:load` divide o arquivo em shards semânticos por heading, indexa via FTS5 e carrega apenas os shards mais relevantes para o objetivo informado.
+
+---
+
+## Comandos
+
+### `agent:shard:index`
+
+Indexa os arquivos de instruções de agentes para permitir carregamento inteligente.
+
+```bash
+aioson agent:shard:index [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--force` | Reindexar mesmo se já indexado |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Indexar todos os agentes do projeto
+aioson agent:shard:index .
+
+# Forçar reindexação após atualizar arquivos de agente
+aioson agent:shard:index . --force
+
+# Diretório customizado de agentes
+aioson agent:shard:index . --agents-dir=.aioson/my-agents
+```
+
+---
+
+### `agent:load`
+
+Carrega os shards mais relevantes de um agente para um objetivo dado.
+
+```bash
+aioson agent:load <agent-id> [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--goal="..."` | Objetivo da tarefa (direciona a seleção de shards) |
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--max-shards=<n>` | Máximo de shards a carregar (padrão: 3) |
+| `--max-tokens=<n>` | Orçamento de tokens (padrão: 2000) |
+| `--print` | Exibe o conteúdo completo dos shards selecionados |
+| `--json` | Retorna shards e tokens em JSON |
+
+**Exemplos:**
+
+```bash
+# Ver quais seções do agente dev são relevantes para a tarefa
+aioson agent:load dev --goal="implementar endpoint de pagamento com TDD"
+
+# Exibir o conteúdo para usar diretamente no prompt
+aioson agent:load dev --goal="refatorar autenticação" --print
+
+# Carregar mais shards se necessário
+aioson agent:load dev --goal="..." --max-shards=5 --max-tokens=3000
+
+# JSON para integração em scripts
+aioson agent:load dev --goal="..." --json
+```
+
+**Saída:**
+
+```
+  Agent: dev  (3/8 shards, 420 tokens)
+
+  ## Role  (85 tokens)
+  ## Implementation Guidelines  (180 tokens)
+  ## Error Handling  (155 tokens)
+```
+
+---
+
+## Como funciona
+
+**Divisão em shards:**
+O arquivo de instruções é dividido por headings H2 (`##`) e H3 (`###`). Cada shard é uma seção com seu conteúdo. O bloco antes do primeiro heading vira o shard `(preamble)`.
+
+**Indexação:**
+Os shards são salvos como arquivos individuais em `~/.aioson/shards/` e indexados via FTS5 (o mesmo motor do `context:search`).
+
+**Seleção:**
+1. O shard `(preamble)` e os shards de `Role` são sempre incluídos
+2. O FTS5 busca os shards mais relevantes para o `--goal`
+3. Shards são adicionados até preencher o orçamento de tokens
+4. Se ainda há espaço, shards restantes são adicionados em ordem
+
+**Orçamento:**
+O total de tokens dos shards selecionados fica dentro de `--max-tokens` (padrão 2000, estimado como chars/4).
+
+---
+
+## Exemplo de redução de contexto
+
+Para um agente com 9 seções e 228 tokens totais:
+
+```
+Carregando para "implementar com TDD e error handling":
+  Shards selecionados: 3 de 9
+  Tokens usados: 73 de 228
+
+  → Redução de 68% no consumo de tokens
+```
+
+---
+
+## Onde ficam os índices
+
+Os shards são indexados em `~/.aioson/shards/` — fora do repositório, não commitado. Use `--force` para atualizar após editar os arquivos de agente.
+
+---
+
+## Quando usar
+
+- Quando um arquivo de instrução de agente tem muitas seções e você quer enviar ao LLM apenas o que é necessário para a tarefa atual
+- Para reduzir tokens consumidos por instruções fixas do agente
+- Para agentes que têm seções muito diferentes (implementação, revisão, documentação, deploy) e você quer carregar apenas o contexto certo para cada tarefa

package/docs/pt/agentes.md

@@ -90,6 +90,7 @@ Regras do fluxo:
 **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
@@ -97,6 +98,21 @@ Regras do fluxo:
 - 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 do `@analyst`
 
+**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:**
 ```
 /product
@@ -109,6 +125,7 @@ Regras do fluxo:
 - 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 `@analyst` avance
 
 > Se o pedido mencionar explicitamente um command center premium, control tower, tri-rail shell ou estilo AIOS Dashboard, o `@product` deve registrar a skill `premium-command-center-ui` na seção de identidade visual do PRD.
 
@@ -207,6 +224,10 @@ Alias compativel:
 - Riscos identificados
 - Referências visuais (wireframes, links)
 
+Em **modo feature**, entrega adicionalmente:
+- `requirements-{slug}.md` — regras de negócio com IDs rastreáveis (`REQ-{slug}-N`) e acceptance criteria verificáveis por QA (`AC-{slug}-N`)
+- `spec-{slug}.md` — esqueleto de memória da feature, com `phase_gates` no frontmatter para que `@dev` e `@deyvin` saibam quais fases já foram aprovadas
+
 ---
 
 ## @discovery-design-doc
@@ -274,8 +295,9 @@ tests/
 **Entrega:** Arquivo `.aioson/context/architecture.md` com:
 - Estrutura de pastas (proporcional ao tamanho)
 - Stack definitiva
-- Decisões técnicas documentadas
+- Decisões técnicas documentadas com **rationale** — não só o que foi decidido, mas por que aquela escolha reduz risco de debug e manutenção futura
 - Padrões de código
+- **Gate B** — sinal explícito de aprovação ao final do arquivo (`@dev` só pode iniciar implementação após este gate)
 
 ---
 
@@ -481,12 +503,25 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 - 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. Implementa apenas aquele passo
-3. Valida antes de avançar — se houver dúvida, pergunta
-4. Faz commit do passo funcional antes de seguir
-5. Para e reporta se algo der errado — não continua em estado quebrado
+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)
@@ -505,7 +540,7 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 
 **O que faz:**
 - Revisa o código implementado
-- Escreve testes unitários e de integração
+- Escreve testes para achados Critical e High
 - Identifica casos de borda não cobertos
 - Valida se os critérios de aceite foram atendidos
 - usa `discovery.md` como fonte de regras e relacionamentos; se só existirem artefatos de scan, o fluxo correto ainda passa por `@analyst`
@@ -516,10 +551,92 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 ```
 
 **Entrega:**
-- Suite de testes
-- Lista de problemas encontrados
+- Lista de problemas encontrados por severidade
+- Testes para achados críticos
 - Relatório de cobertura
 
+> **@qa vs @tester** — O `@qa` é um revisor: lê o que foi implementado, aponta riscos e escreve testes pontuais para achados críticos. O `@tester` é um engenheiro de testes: parte de cobertura zero e constrói uma estratégia sistemática (inventário, mapa de risco, estratégia por camada). Use `@tester` quando a aplicação foi implementada sem testes adequados ou quando `@qa` identificar lacunas em 3+ módulos.
+
+---
+
+## @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 inventário completo de cobertura (`test-inventory.md`)
+- Mapeia regras de negócio descobertas vs testes existentes, priorizando por risco
+- Escolhe e documenta a estratégia de teste antes de escrever qualquer linha
+- Escreve testes por módulo em ordem de prioridade, com commit atômico por módulo
+- 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:**
+```
+/tester
+```
+
+**Entrega:**
+- `.aioson/context/test-inventory.md` — mapa de cobertura por arquivo
+- `.aioson/context/test-plan.md` — estratégia escolhida + cobertura antes/depois
+- Testes escritos por módulo, commitados incrementalmente
+
+**Restrições:**
+- Nunca modifica código de produção
+- Se encontrar um bug real: documenta em `test-plan.md` e para — não corrige silenciosamente
+- 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) | `/sheldon` | Analisa o PRD alvo e sugere melhorias prioritárias |
+| B — Revisão Global | `/sheldon` + "revisão geral" | Escaneia todos os PRDs e planos ativos |
+| C — Validação Completa | `/sheldon` + "validar" ou "preparar para dev" | Auditoria completa + checklist final antes de codar |
+
+**Como ativar:**
+```
+/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)
+
 ---
 
 ## Resumo: fluxo por tamanho
@@ -532,15 +649,18 @@ Duração típica: minutos a horas. Sem análise, sem arquitetura formal.
 
 ### SMALL
 ```
-@setup → @product → @analyst → @architect → @ux-ui → @dev → @qa
+@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]
 ```
 Duração típica: horas a dias. Análise leve, estrutura clara.
 
 ### MEDIUM
 ```
-@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa
+@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa → [@tester]
 ```
-Duração típica: dias a semanas. Análise completa, parallelismo, backlog formal.
+Duração típica: dias a semanas. Análise completa, paralelismo, backlog formal.
+
+`[@sheldon]` — opcional, recomendado antes de iniciar a cadeia de execução para validar o PRD.
+`[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
 
 ---