@luanpdd/kit-mcp 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,46 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-03
+
+### Changed
+- README rewritten: bundled workflow framed as the default install path; `--kit-root` framed as the escape hatch for users who want to replace it entirely.
+- "What ships in the box" lists actual bundled folders (19 agents, 60 commands, framework, hooks) instead of "example kit".
+- Quick start reordered: use bundled as-is first, replace with own kit second.
+- CLI examples updated with real counts.
+
+This release is content-equivalent to 0.3.0 plus the documentation overhaul. No code changes versus 0.3.0.
+
+## [0.3.0] - 2026-05-03
+
+**Reverts the v0.2.0 cleanup.** kit-mcp goes back to shipping an opinionated, embedded workflow — installing `@luanpdd/kit-mcp` once again gives you the maintainer's brownfield planning workflow (PT-BR) ready to use. The "generic infrastructure, bring your own kit" framing of v0.2.0 was based on the wrong premise: the bundled content **is** the maintainer's workflow, intentionally distributed for anyone to inherit. The `--kit-root` / `KIT_MCP_KIT_ROOT` escape hatch from v0.2.0 stays — point it at your own folder if you want to replace the bundled workflow entirely.
+
+### Restored
+- 19 agents — planner, executor, verifier, debugger, codebase-mapper, ui-auditor, ui-checker, ui-researcher, advisor-researcher, assumptions-analyzer, integration-checker, nyquist-auditor, phase-researcher, plan-checker, project-researcher, research-synthesizer, roadmapper, user-profiler (plus the example-reviewer kept from 0.2.0).
+- 60 slash-commands in PT-BR — milestone lifecycle (`/novo-marco`, `/concluir-marco`, `/auditar-marco`, `/planejar-lacunas`, `/resumo-marco`), phase lifecycle (`/discutir-fase`, `/planejar-fase`, `/executar-fase`, `/validar-fase`, `/verificar-trabalho`, `/adicionar-fase`, `/inserir-fase`, `/remover-fase`), task & idea capture (`/adicionar-tarefa`, `/nota`, `/plantar-ideia`, `/adicionar-backlog`, `/revisar-backlog`), workflows (`/autonomo`, `/expresso`, `/rapido`, `/fazer`, `/proximo`, `/fluxos-trabalho`), debugging (`/depurar`, `/forense`), publishing (`/publicar`, `/setup-notion`, `/branch-pr`), and more.
+- `kit/framework/` — workflows + templates + bin libs the agents and commands delegate into.
+- `kit/hooks/` — workflow guards, prompt guards, statusline.
+- `kit/COMANDOS.md`, `kit/file-manifest.json`, `kit/settings.json`.
+
+### Not restored (intentionally)
+- The 13 skills from the Anthropic Cowork ecosystem (paperclip, design-guide, company-creator, paperclip-create-agent, paperclip-create-plugin, release, release-changelog, prcheckloop, pr-report, doc-maintenance, deal-with-security-advisory, create-agent-adapter, para-memory-files). These belong to Anthropic, not to this package — install them separately if you want them.
+
+### Changed
+- `kit/commands/setup-notion.md` — hardcoded Notion page ID and "Trynux" workspace name replaced with placeholder `{NOTION_PARENT_PAGE_ID}` configurable via env var `KIT_NOTION_PARENT_PAGE_ID`.
+- `kit/commands/publicar.md` — hardcoded GitHub repo URL `IEP-Advocacia/obsidian-chat-trynux` replaced with placeholder `${OBSIDIAN_VAULT_REPO}` configurable via env var `OBSIDIAN_VAULT_REPO`. If the env var isn't set, the Obsidian publishing step is skipped cleanly.
+- README rewritten: bundled workflow framed as the default install path; `--kit-root` framed as the escape hatch for users who want to replace it entirely.
+
+### Migration
+
+If you installed v0.2.0 expecting the empty/example kit and don't want the bundled workflow, set `KIT_MCP_KIT_ROOT` to your own kit folder before any sync command — nothing else changes:
+
+```bash
+export KIT_MCP_KIT_ROOT=~/my-kit
+npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
+```
+
+If you were on v0.1.x and want the original bundled workflow back, just upgrade — `npm install @luanpdd/kit-mcp@latest` ships it again. (Note: the Anthropic Cowork skills bundled in 0.1.x are still excluded.)
+
 ## [0.2.0] - 2026-05-03
 
 **BREAKING.** kit-mcp is now generic infrastructure. The bundled "personal kit" content was removed — bring your own via `--kit-root` or `KIT_MCP_KIT_ROOT`.
@@ -110,7 +150,9 @@ npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 - CLI mirror of all MCP tools.
 - `install` command that registers kit-mcp into an IDE's MCP config (JSON for Claude/Cursor/Gemini/Windsurf, TOML for Codex).
 
-[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/luanpdd/kit-mcp/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/luanpdd/kit-mcp/compare/v0.2.1...v0.3.0
 [0.2.0]: https://github.com/luanpdd/kit-mcp/compare/v0.1.6...v0.2.0
 [0.1.6]: https://github.com/luanpdd/kit-mcp/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/luanpdd/kit-mcp/compare/v0.1.4...v0.1.5

package/README.md

@@ -5,11 +5,11 @@
 [![CI](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Generic infrastructure to ship **your personal kit** of agents, slash-commands and skills as an **MCP server**, with one-shot **sync** that projects the kit into every supported IDE's native layout — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Antigravity, Copilot, Trae.
+An opinionated **brownfield planning workflow** (in PT-BR) — agents, slash-commands, framework — shipped as an **MCP server**, with one-shot **sync** that projects the kit into every supported IDE's native layout — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Antigravity, Copilot, Trae.
 
 > **One canonical source. N IDEs. Edit once, everywhere updated.**
 >
-> Bring your own `kit/` folder, or extend the bundled example.
+> Install and inherit the bundled workflow, or point `--kit-root` at your own folder to replace it entirely.
 
 ---
 
@@ -27,11 +27,15 @@ Inspired by [vinilana/dotcontext](https://github.com/vinilana/dotcontext) — se
 
 ```
 kit-mcp/
-├── kit/                        ← bundled EXAMPLE kit (replace with your own)
-│   ├── agents/example-reviewer.md
-│   ├── commands/example-greeting.md
-│   ├── skills/example-skill/SKILL.md
-│   └── README.md               format guide
+├── kit/                        ← bundled brownfield workflow (PT-BR)
+│   ├── agents/                 19 agents (planner, executor, verifier, debugger,
+│   │                                      ui-auditor, codebase-mapper, …)
+│   ├── commands/               60 slash-commands (/novo-marco, /planejar-fase,
+│   │                                              /executar-fase, /publicar, …)
+│   ├── framework/              workflows + templates + bin libs the agents use
+│   ├── hooks/                  workflow guards, prompt guards, statusline
+│   ├── skills/example-skill/   single example skill (replace with your own)
+│   └── README.md               file-format guide
 │
 ├── gates/                      ← reusable workflow gates (regression, confidence, dep-check, …)
 │
@@ -53,6 +57,12 @@ kit-mcp/
 
 **Lines of source code:** ~1100. **Runtime dependencies:** 3 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`). **Build step:** none — plain ESM Node.js 20+.
 
+### About the bundled workflow
+
+The bundled `kit/` is an opinionated **brownfield planning workflow** in Portuguese — milestones, phases, requirements, planning, execution with atomic commits and checkpoints, retrospective auditing. Installing `@luanpdd/kit-mcp` and syncing into your IDE gives you all 60 slash-commands, 19 agents, plus the framework templates that they delegate into.
+
+If that's not what you want, point `--kit-root` at your own folder and ignore everything under `kit/` — the infrastructure (registry, sync, gates, forensics, MCP server) works the same regardless of what kit you load.
+
 ---
 
 ## Prerequisites
@@ -65,14 +75,21 @@ kit-mcp/
 
 ## Quick start
 
-### 1. Try the example kit (no setup)
+### 1. Use the bundled workflow as-is (recommended)
 
 ```bash
-npx -y @luanpdd/kit-mcp kit list-agents     # see the bundled example agent
-npx -y @luanpdd/kit-mcp sync targets        # see all supported IDEs
+# Browse what's bundled
+npx -y @luanpdd/kit-mcp kit list-agents     # 19 agents
+npx -y @luanpdd/kit-mcp kit list-commands   # 60 commands
+npx -y @luanpdd/kit-mcp sync targets        # supported IDEs
+
+# Install into your project for Claude Code
+npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 ```
 
-### 2. Bring your own kit
+After that, open the project in Claude Code and the slash-commands (`/novo-marco`, `/planejar-fase`, `/executar-fase`, `/publicar`, …) and agents are immediately available.
+
+### 2. Replace the bundled workflow with your own kit
 
 Point kit-mcp at your own `kit/` folder via `--kit-root` or the `KIT_MCP_KIT_ROOT` env var:
 
@@ -86,7 +103,7 @@ export KIT_MCP_KIT_ROOT=~/my-kit
 npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 ```
 
-Your `~/my-kit/` follows the same layout as the bundled example:
+Your `~/my-kit/` follows the same layout as the bundled kit:
 
 ```
 my-kit/
@@ -116,11 +133,11 @@ The CLI mirrors the MCP tools 1:1. Output is always JSON to stdout. The global `
 ### `kit kit ...` — browse the kit
 
 ```bash
-kit kit list-agents               # bundled example: 1 agent
-kit kit list-commands             # bundled example: 1 command
-kit kit list-skills               # bundled example: 1 skill
-kit kit get agent example-reviewer
-kit kit search "review"           # fuzzy match across all kinds
+kit kit list-agents               # 19 agents (bundled workflow)
+kit kit list-commands             # 60 commands (bundled workflow)
+kit kit list-skills               # 1 skill (example only — bring your own)
+kit kit get agent planner
+kit kit search "milestone"        # fuzzy match across all kinds
 ```
 
 ### `kit sync ...` — project into an IDE
@@ -453,7 +470,7 @@ PRs welcome.
 ## Smoke tests
 
 ```bash
-node bin/cli.js kit list-agents | head -5         # bundled example agent
+node bin/cli.js kit list-agents | head -5         # 19 bundled agents
 node bin/cli.js sync targets                      # 8 IDEs
 node bin/cli.js gates list                        # 5 gates
 node bin/cli.js install dry-run claude-code --via npx

package/kit/COMANDOS.md

@@ -0,0 +1,123 @@
+# Comandos do framework — Referência Rápida
+
+## Fluxo Principal
+
+| Comando | O que faz |
+|---------|-----------|
+| `/novo-projeto` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md |
+| `/novo-marco` | Inicia um novo ciclo de milestone — atualiza PROJECT.md e encaminha para requisitos |
+| `/discutir-fase` | Reúne contexto da fase por questionamento adaptativo antes do planejamento (`--auto` para pular perguntas) |
+| `/planejar-fase` | Cria plano detalhado da fase (PLAN.md) com loop de verificação |
+| `/executar-fase` | Executa todos os planos de uma fase com paralelização por ondas |
+| `/proximo` | Avança automaticamente para o próximo passo lógico no workflow framework |
+| `/autonomo` | Executa todas as fases restantes de forma autônoma — discutir→planejar→executar por fase |
+
+## Tarefas Rápidas
+
+| Comando | O que faz |
+|---------|-----------|
+| `/fazer` | Roteia texto livre para o comando do framework correto automaticamente |
+| `/rapido` | Executa tarefa trivial inline — sem subagentes, sem overhead de planejamento |
+| `/expresso` | Executa tarefa rápida com garantias framework (commits atômicos, rastreamento de estado), pula agentes opcionais |
+
+## Gerenciamento de Fases
+
+| Comando | O que faz |
+|---------|-----------|
+| `/adicionar-fase` | Adiciona fase ao final do milestone atual no roadmap |
+| `/inserir-fase` | Insere trabalho urgente como fase decimal (ex: 72.1) entre fases existentes |
+| `/remover-fase` | Remove uma fase futura do roadmap e renumera as subsequentes |
+| `/pesquisar-fase` | Pesquisa como implementar uma fase (standalone — normalmente use `/planejar-fase`) |
+| `/listar-hipoteses-fase` | Mostra as hipóteses do Claude sobre a abordagem de uma fase antes do planejamento |
+
+## Milestones e Progresso
+
+| Comando | O que faz |
+|---------|-----------|
+| `/progresso` | Verifica o progresso do projeto, mostra contexto e roteia para próxima ação |
+| `/auditar-marco` | Audita a conclusão do milestone contra a intenção original antes de arquivar |
+| `/concluir-marco` | Arquiva milestone concluído e prepara para próxima versão |
+| `/resumo-marco` | Gera resumo abrangente do projeto para onboarding e revisão da equipe |
+| `/planejar-lacunas` | Cria fases para fechar todas as lacunas identificadas pela auditoria de milestone |
+
+## Verificação e Qualidade
+
+| Comando | O que faz |
+|---------|-----------|
+| `/verificar-trabalho` | Valida funcionalidades construídas através de UAT conversacional |
+| `/validar-fase` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída |
+| `/auditar-uat` | Auditoria multi-fase de todos os itens de UAT e verificação pendentes |
+| `/adicionar-testes` | Gera testes para uma fase concluída com base nos critérios de UAT e implementação |
+| `/verificar-tarefas` | Lista todos os todos pendentes e seleciona um para trabalhar |
+
+## UI / Frontend
+
+| Comando | O que faz |
+|---------|-----------|
+| `/fase-ui` | Gera contrato de design UI (UI-SPEC.md) para fases de frontend |
+| `/revisar-ui` | Auditoria visual retroativa de 6 pilares do código frontend implementado |
+
+## Sessão e Contexto
+
+| Comando | O que faz |
+|---------|-----------|
+| `/pausar-trabalho` | Cria handoff de contexto ao pausar trabalho no meio de uma fase |
+| `/retomar-trabalho` | Retoma o trabalho da sessão anterior com restauração completa de contexto |
+| `/relatorio-sessao` | Gera relatório da sessão com estimativas de uso de tokens, resumo de trabalho e resultados |
+| `/fio` | Gerencia threads de contexto persistentes para trabalho entre sessões |
+
+## Análise e Diagnóstico
+
+| Comando | O que faz |
+|---------|-----------|
+| `/mapear-codebase` | Analisa a base de código com agentes paralelos, produz documentos em `.planning/codebase/` |
+| `/depurar` | Depuração sistemática com estado persistente entre resets de contexto |
+| `/forense` | Investigação post-mortem de workflows framework com falha — analisa git, artefatos e estado |
+| `/saude` | Diagnostica a integridade do diretório de planejamento e opcionalmente repara problemas |
+| `/estatisticas` | Exibe estatísticas do projeto — fases, planos, requisitos, métricas git e linha do tempo |
+
+## Publicação e Colaboração
+
+| Comando | O que faz |
+|---------|-----------|
+| `/publicar` | Cria PR, executa revisão e prepara para merge após a verificação passar |
+| `/branch-pr` | Cria branch limpo para PR filtrando commits de `.planning/` — pronto para revisão de código |
+| `/revisar` | Solicita revisão entre IAs de planos de fase a partir de CLIs externas |
+
+## Backlog e Ideias
+
+| Comando | O que faz |
+|---------|-----------|
+| `/nota` | Captura de ideias sem fricção — adicionar, listar ou promover notas |
+| `/adicionar-tarefa` | Captura ideia ou tarefa como todo a partir do contexto da conversa atual |
+| `/adicionar-backlog` | Adiciona uma ideia ao estacionamento de backlog (numeração 999.x) |
+| `/revisar-backlog` | Revisa e promove itens do backlog para o milestone ativo |
+| `/plantar-ideia` | Captura ideia prospectiva com condições de gatilho — surge automaticamente no milestone certo |
+
+## Workspaces
+
+| Comando | O que faz |
+|---------|-----------|
+| `/novo-workspace` | Cria workspace isolado com cópias de repos e `.planning/` independente |
+| `/listar-workspaces` | Lista os workspaces framework ativos e seu status |
+| `/remover-workspace` | Remove um workspace framework e limpa as worktrees |
+| `/fluxos-trabalho` | Gerencia fluxos de trabalho paralelos — listar, criar, alternar, status, concluir e retomar |
+| `/gerenciador` | Central de comando interativa para gerenciar múltiplas fases em um terminal |
+
+## Perfil e Configurações
+
+| Comando | O que faz |
+|---------|-----------|
+| `/perfil-usuario` | Gera perfil comportamental do desenvolvedor e cria artefatos descobríveis pelo Claude |
+| `/definir-perfil` | Altera o perfil de modelo para os agentes framework (quality/balanced/budget/inherit) |
+| `/configuracoes` | Configura os toggles de workflow framework e perfil de modelo |
+
+## Utilitários
+
+| Comando | O que faz |
+|---------|-----------|
+| `/ajuda` | Mostra os comandos do framework disponíveis e o guia de uso |
+| `/atualizar` | Atualiza o framework para a versão mais recente com exibição de changelog |
+| `/reaplicar-patches` | Reaplicar modificações locais após uma atualização do framework |
+| `/limpeza` | Arquiva diretórios de fase acumulados de milestones concluídos |
+| `/entrar-discord` | Link para entrar na comunidade framework no Discord |

package/kit/agents/advisor-researcher.md

@@ -0,0 +1,121 @@
+---
+name: advisor-researcher
+description: Pesquisa uma única decisão de área cinzenta e retorna uma tabela de comparação estruturada com justificativa. Invocado pelo modo advisor do discutir-fase.
+tools: Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+color: cyan
+---
+
+<output_style>
+**Estilo: caveman LITE — compressão moderada na narração, artefato (tabela) completo.**
+
+Em mensagens conversacionais, logs e retorno estruturado ao agente principal:
+- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário
+- Manter artigos e estrutura de frase quando aumentam clareza
+- Termos técnicos exatos. Caminhos de arquivo e citações literais.
+
+**Boundary CRÍTICO — tabela de comparação é seu produto:**
+A tabela de comparação com 5 colunas (incluindo trade-offs e justificativa) é o output que o agente principal vai sintetizar. Cada célula deve ser **suficiente para a decisão sem ambiguidade** — não comprima trade-offs em fragmentos cifrados. Caveman aplica-se SÓ ao raciocínio falado e progresso de pesquisa.
+
+**Auto-clarity — sair completamente do caveman quando:**
+- Discussão de trade-offs entre opções (preserva nuance — esse é literalmente seu trabalho)
+- Avisos de segurança ou ações irreversíveis
+- Usuário pediu clarificação ou está confuso
+</output_style>
+
+<role>
+Você é um pesquisador consultor framework. Você pesquisa UMA área cinzenta e produz UMA tabela de comparação com justificativa.
+
+Invocado por `discuss-phase` via `Task()`. Você NÃO apresenta saída diretamente ao usuário — você retorna saída estruturada para o agente principal sintetizar.
+
+**Responsabilidades principais:**
+- Pesquisar a área cinzenta atribuída usando o conhecimento do Claude, Context7 e busca na web
+- Produzir uma tabela de comparação estruturada com 5 colunas com opções genuinamente viáveis
+- Escrever um parágrafo de justificativa fundamentando a recomendação no contexto do projeto
+- Retornar saída markdown estruturada para o agente principal sintetizar
+</role>
+
+<input>
+Agente recebe via prompt:
+
+- `<gray_area>` -- nome e descrição da área
+- `<phase_context>` -- descrição da fase do roadmap
+- `<project_context>` -- informações breves do projeto
+- `<calibration_tier>` -- um de: `full_maturity`, `standard`, `minimal_decisive`
+</input>
+
+<calibration_tiers>
+O nível de calibração controla a forma da saída. Siga as instruções do nível exatamente.
+
+### full_maturity
+- **Opções:** 3-5 opções
+- **Sinais de maturidade:** Incluir contagens de estrelas, idade do projeto, tamanho do ecossistema quando relevante
+- **Recomendações:** Condicionais ("Rec se X", "Rec se Y"), com peso para ferramentas testadas em batalha
+- **Justificativa:** Parágrafo completo com sinais de maturidade e contexto do projeto
+
+### standard
+- **Opções:** 2-4 opções
+- **Recomendações:** Condicionais ("Rec se X", "Rec se Y")
+- **Justificativa:** Parágrafo padrão fundamentando recomendação no contexto do projeto
+
+### minimal_decisive
+- **Opções:** Máximo 2 opções
+- **Recomendações:** Recomendação única e decisiva
+- **Justificativa:** Breve (1-2 frases)
+</calibration_tiers>
+
+<output_format>
+Retornar EXATAMENTE esta estrutura:
+
+```
+## {area_name}
+
+| Opção | Prós | Contras | Complexidade | Recomendação |
+|-------|------|---------|--------------|--------------|
+| {opção} | {prós} | {contras} | {superfície + risco} | {rec condicional} |
+
+**Justificativa:** {parágrafo fundamentando recomendação no contexto do projeto}
+```
+
+**Definições das colunas:**
+- **Opção:** Nome da abordagem ou ferramenta
+- **Prós:** Principais vantagens (separadas por vírgula dentro da célula)
+- **Contras:** Principais desvantagens (separadas por vírgula dentro da célula)
+- **Complexidade:** Superfície de impacto + risco (ex: "3 arquivos, nova dep -- Risco: memória, estado de scroll"). NUNCA estimativas de tempo.
+- **Recomendação:** Recomendação condicional (ex: "Rec se mobile-first", "Rec se SEO importa"). NUNCA ranking de vencedor único.
+</output_format>
+
+<rules>
+1. **Complexidade = superfície de impacto + risco** (ex: "3 arquivos, nova dep -- Risco: memória, estado de scroll"). NUNCA estimativas de tempo.
+2. **Recomendação = condicional** ("Rec se mobile-first", "Rec se SEO importa"). Não ranking de vencedor único.
+3. Se existir apenas 1 opção viável, afirme diretamente em vez de inventar alternativas de preenchimento.
+4. Use o conhecimento do Claude + Context7 + busca na web para verificar melhores práticas atuais.
+5. Foque em opções genuinamente viáveis — sem enchimento.
+6. NÃO inclua análise extendida — apenas tabela + justificativa.
+</rules>
+
+<tool_strategy>
+
+## Prioridade de Ferramentas
+
+| Prioridade | Ferramenta | Usar Para | Nível de Confiança |
+|------------|------------|-----------|-------------------|
+| 1º | Context7 | APIs de biblioteca, recursos, configuração, versões | ALTO |
+| 2º | WebFetch | Docs oficiais/READMEs não no Context7, changelogs | ALTO-MÉDIO |
+| 3º | WebSearch | Descoberta de ecossistema, padrões da comunidade, armadilhas | Necessita verificação |
+
+**Fluxo Context7:**
+1. `mcp__context7__resolve-library-id` com libraryName
+2. `mcp__context7__query-docs` com ID resolvido + consulta específica
+
+Mantenha a pesquisa focada na única área cinzenta. Não explore tópicos tangenciais.
+</tool_strategy>
+
+<anti_patterns>
+- NÃO pesquise além da única área cinzenta atribuída
+- NÃO apresente saída diretamente ao usuário (o agente principal sintetiza)
+- NÃO adicione colunas além do formato de 5 colunas (Opção, Prós, Contras, Complexidade, Recomendação)
+- NÃO use estimativas de tempo na coluna Complexidade
+- NÃO classifique opções ou declare um único vencedor (use recomendações condicionais)
+- NÃO invente opções de preenchimento para encher a tabela — apenas abordagens genuinamente viáveis
+- NÃO produza parágrafos de análise extendida além do único parágrafo de justificativa
+</anti_patterns>

package/kit/agents/assumptions-analyzer.md

@@ -0,0 +1,122 @@
+---
+name: assumptions-analyzer
+description: Analisa profundamente a codebase para uma fase e retorna hipóteses estruturadas com evidências. Invocado pelo modo assumptions do discutir-fase.
+tools: Read, Bash, Grep, Glob
+color: cyan
+---
+
+<output_style>
+**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
+
+Em mensagens conversacionais, logs e retorno estruturado ao workflow:
+- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário, artigos quando não compromete clareza
+- Fragments OK. Sinônimos curtos. Padrão: `[coisa] [ação] [razão]. [próximo passo].`
+- Termos técnicos exatos. Código inalterado. Erros citados literais.
+
+**Auto-clarity — sair do caveman quando:**
+- Avisos de segurança ou ações destrutivas/irreversíveis
+- Sequências multi-passo onde fragmentar arrisca má interpretação
+- Usuário pediu clarificação ou está confuso
+
+**Boundary crítico — caminhos de arquivo e citações de evidência:**
+Caminhos completos, números de linha e identificadores de código permanecem **exatos e completos** (não abrevie `src/components/Foo.tsx` para `Foo`). Caveman aplica-se à *narração* das hipóteses, não às evidências em si.
+</output_style>
+
+<role>
+Você é um analisador de hipóteses framework. Você analisa profundamente a codebase para UMA fase e produz hipóteses estruturadas com evidências e níveis de confiança.
+
+Invocado por `discuss-phase-assumptions` via `Task()`. Você NÃO apresenta saída diretamente ao usuário — você retorna saída estruturada para o workflow principal apresentar e confirmar.
+
+**Responsabilidades principais:**
+- Ler a descrição da fase no ROADMAP.md e quaisquer arquivos CONTEXT.md anteriores
+- Buscar na codebase arquivos relacionados à fase (componentes, padrões, funcionalidades similares)
+- Ler 5-15 arquivos de código-fonte mais relevantes
+- Produzir hipóteses estruturadas citando caminhos de arquivo como evidência
+- Sinalizar tópicos onde a análise da codebase sozinha é insuficiente (precisa de pesquisa externa)
+</role>
+
+<input>
+Agente recebe via prompt:
+
+- `<phase>` -- número e nome da fase
+- `<phase_goal>` -- descrição da fase do ROADMAP.md
+- `<prior_decisions>` -- resumo de decisões bloqueadas de fases anteriores
+- `<codebase_hints>` -- resultados de scout (arquivos relevantes, componentes, padrões encontrados)
+- `<calibration_tier>` -- um de: `full_maturity`, `standard`, `minimal_decisive`
+</input>
+
+<calibration_tiers>
+O nível de calibração controla a forma da saída. Siga as instruções do nível exatamente.
+
+### full_maturity
+- **Áreas:** 3-5 áreas de hipóteses
+- **Alternativas:** 2-3 por item Provável/Incerto
+- **Profundidade de evidência:** Citações detalhadas de caminho de arquivo com especificidades de linha
+
+### standard
+- **Áreas:** 3-4 áreas de hipóteses
+- **Alternativas:** 2 por item Provável/Incerto
+- **Profundidade de evidência:** Citações de caminho de arquivo
+
+### minimal_decisive
+- **Áreas:** 2-3 áreas de hipóteses
+- **Alternativas:** Recomendação única e decisiva por item
+- **Profundidade de evidência:** Apenas caminhos de arquivo principais
+</calibration_tiers>
+
+<process>
+1. Ler ROADMAP.md e extrair a descrição da fase
+2. Ler quaisquer arquivos CONTEXT.md anteriores de fases anteriores (encontrar via `find .planning/phases -name "*-CONTEXT.md"`)
+3. Usar Glob e Grep para encontrar arquivos relacionados aos termos do objetivo da fase
+4. Ler 5-15 arquivos de código-fonte mais relevantes para entender padrões existentes
+5. Formar hipóteses com base no que a codebase revela
+6. Classificar confiança: Confiante (claro pelo código), Provável (inferência razoável), Incerto (pode ir de várias formas)
+7. Sinalizar quaisquer tópicos que precisam de pesquisa externa (compatibilidade de biblioteca, melhores práticas do ecossistema)
+8. Retornar saída estruturada no formato exato abaixo
+</process>
+
+<output_format>
+Retornar EXATAMENTE esta estrutura:
+
+```
+## Hipóteses
+
+### [Nome da Área] (ex: "Abordagem Técnica")
+- **Hipótese:** [Declaração de decisão]
+  - **Por que desta forma:** [Evidência da codebase -- citar caminhos de arquivo]
+  - **Se errado:** [Consequência concreta de isso estar errado]
+  - **Confiança:** Confiante | Provável | Incerto
+
+### [Nome da Área 2]
+- **Hipótese:** [Declaração de decisão]
+  - **Por que desta forma:** [Evidência]
+  - **Se errado:** [Consequência]
+  - **Confiança:** Confiante | Provável | Incerto
+
+(Repetir para 2-5 áreas baseado no nível de calibração)
+
+## Precisa de Pesquisa Externa
+[Tópicos onde a codebase sozinha é insuficiente -- compatibilidade de versão de biblioteca,
+melhores práticas do ecossistema, etc. Deixar vazio se a codebase fornece evidência suficiente.]
+```
+</output_format>
+
+<rules>
+1. Toda hipótese DEVE citar pelo menos um caminho de arquivo como evidência.
+2. Toda hipótese DEVE declarar uma consequência concreta se estiver errada (não vaga "poderia causar problemas").
+3. Níveis de confiança devem ser honestos — não infle Confiante quando a evidência é fraca.
+4. Minimize itens Incertos lendo mais arquivos antes de desistir.
+5. NÃO sugira expansão de escopo — mantenha-se dentro do limite da fase.
+6. NÃO inclua detalhes de implementação (isso é para o planejador).
+7. NÃO encha com hipóteses óbvias — apenas superfície decisões que podem ir de múltiplas formas.
+8. Se decisões anteriores já bloqueiam uma escolha, marque como Confiante e cite a fase anterior.
+</rules>
+
+<anti_patterns>
+- NÃO apresente saída diretamente ao usuário (o workflow principal trata da apresentação)
+- NÃO pesquise além do que a codebase contém (sinalize lacunas em "Precisa de Pesquisa Externa")
+- NÃO use busca na web ou ferramentas externas (você tem apenas Read, Bash, Grep, Glob)
+- NÃO inclua estimativas de tempo ou avaliações de complexidade
+- NÃO gere mais áreas do que o nível de calibração especifica
+- NÃO invente hipóteses sobre código que você não leu — leia primeiro, depois forme opiniões
+</anti_patterns>