@luanpdd/kit-mcp 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-05-06
+
+Milestone v1.7 — perf+lean part 2 + UX naming canonical: 10 REQs em 3 fases.
+
+### Performance
+
+- **Workflow files compactados** (Phase 22) — `discuss-phase.md` 49→39 KB (-22%), `plan-phase.md` 36→31 KB (-15%), `new-project.md` 40→37 KB (-7%). Cuts em prosa redundante; specs core (questionamento, fluxo de fases, retornos estruturados) preservados.
+- **`listKit({ stubsOnly: true })`** (Phase 23, PERF-S1) — sync em mode=reference (default) lê só os primeiros 4KB de cada arquivo (frontmatter), pulando body/content que stub renderers nunca usam. Cache key separado (`${kitRoot}:full` vs `${kitRoot}:stubs`). Benchmark local: 1.79× speedup em cold listKit.
+
+### Tokens (boilerplate dedup)
+
+- **Output style centralizado** (Phase 24, TOK-D1) — `kit/framework/references/output-style.md` é a única fonte; 18 agentes referenciam via `@./.claude/framework/references/output-style.md`. Economia: 19,110 bytes na árvore agents/ (-6%).
+
+### UX (naming canonical)
+
+- **`/fazer` é o entrypoint canônico** (Phase 24, UX-F1/F2/F3) — abre com tabela de decisão "intenção → comando". `/rapido`, `/expresso`, `/proximo` continuam funcionando direto, mas cada um tem nova seção "Quando usar" com trade-offs (✅/❌/🤔) e link de volta a `/fazer`. `/ajuda` (e `kit/framework/workflows/help.md`) destaca `/fazer` no topo.
+
+### Sem mudanças de API runtime
+
+Stable API v1.0+ preservada. `mode=copy` continua lendo content full. `mcp__kit__kit action=get` retorna content/absPath. Aliases de comando todos preservados.
+
+### Tests
+
+115 unit (+3 stubs-only) + 67 integration. Todos verdes.
+
+## [1.6.1] - 2026-05-05
+
+DX patch: comando `kit doctor` + upgrade-check no boot do sidecar + cache de gates.
+
+### Adicionado
+
+- **`kit doctor`** ([src/cli/index.js](src/cli/index.js), nova função `runDoctorChecks`) — comando único de diagnóstico que checa: versão local vs npm latest, sidecar reachability via lockfile + healthz, validade do `~/.claude/settings.json`, presença do hook PostToolUse `sidecar-tool-publisher`, dirs do kit bundled, integridade do `.planning/`, e lockfiles órfãos em tmpdir. Retorna checklist colorido com `fix:` específico em cada falha. Suporta `--json` (via flag global) pra consumo programático.
+- **Upgrade-check no `kit ui start`** ([src/cli/index.js](src/cli/index.js), [src/cli/upgrade-check.js](src/cli/upgrade-check.js)) — verifica npm registry em background; se versão local atrás da latest, imprime banner amarelo "v1.6 → v1.6.1 disponível, atualize com npm i -g". Cache TTL 24h em `~/.kit-mcp/version-check.json` evita hit no registry em todo boot. Falha gracefully em modo offline.
+- **Cache TTL em `listGates`** ([src/core/gates.js](src/core/gates.js)) — mesmo padrão de PERF-01 (`listKit`). Sequência `listGates → getGate → gatesForStage` num único processo agora faz 1 walk de disco em vez de 3.
+
+### Sem mudanças de API
+
+`mcp__kit__gates` action=list e action=get continuam funcionando com mesma assinatura. Doctor e upgrade-check são CLI-only.
+
+### Testes
+
++10 unit (112 total): 8 cobrindo `compareVersions`/`getLocalVersion`/constantes do upgrade-check, 2 cobrindo cache hit/miss em gates.
+
 ## [1.6.0] - 2026-05-05
 
 Milestone v1.6 — perf+lean: 16 itens de auditoria de codebase entregues em 3 fases (Phase 19 quick wins, Phase 20 hardening, Phase 21 token economy) + observability hook (Phase 19.5).

package/kit/agents/advisor-researcher.md

@@ -6,20 +6,7 @@ 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
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/assumptions-analyzer.md

@@ -6,20 +6,7 @@ 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.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/codebase-mapper.md

@@ -12,20 +12,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefatos completos e detalhados.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- 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 — docs em `.planning/codebase/` são referência durável:**
-Os arquivos que você escreve em `.planning/codebase/` (architecture.md, conventions.md, structure.md, etc.) são **referência consultada repetidamente** por agents e humanos durante todo o projeto. Devem ser **completos, navegáveis e narrativos** conforme template — ZERO compressão caveman no conteúdo. Caveman aplica-se SÓ ao raciocínio falado e progresso de exploração.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Avisos de segurança ou ações irreversíveis
-- Discussão de trade-offs entre opções (preserva nuance)
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/debugger.md

@@ -13,25 +13,7 @@ color: orange
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na fala, prosa normal em artefatos e diagnósticos críticos.**
-
-Em mensagens conversacionais e logs de progresso de debug:
-- Cortar: filler (just/really/basically/actually/simply), pleasantries (claro/com certeza/feliz em ajudar), hedging desnecessário
-- Manter artigos e estrutura de frase quando ajudam clareza diagnóstica
-- Padrão: `[hipótese] → [teste] → [resultado]. [próxima hipótese].`
-- Termos técnicos exatos. Código inalterado. Stacktraces e erros citados literais.
-
-**Auto-clarity OBRIGATÓRIO — sair completamente do caveman quando:**
-- Reportar root cause de bug crítico ou explicar por que uma correção funciona
-- Avisos de segurança ou ações destrutivas/irreversíveis
-- Sequências multi-passo de reprodução do bug onde ordem importa
-- Usuário pediu clarificação ou está confuso
-- Análise comparativa entre múltiplas causas suspeitas
-
-**Por que LITE em vez de FULL:** Debug exige nuance — fragmentar demais arrisca perder relação causal sutil entre componentes. Prefira clareza diagnóstica a economia de tokens nos pontos críticos.
-
-**Boundary crítico — artefatos mantêm formato completo:**
-Arquivos `DEBUG.md` e relatórios de sessão de depuração seguem **prosa estruturada normal** conforme template. Caveman aplica-se SÓ ao raciocínio falado e logs de progresso.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/executor.md

@@ -13,24 +13,7 @@ color: yellow
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
-
-**Mensagens de commit, code, PRs:** prosa normal (não caveman) — já é convenção do framework.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/integration-checker.md

@@ -6,22 +6,7 @@ color: blue
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/nyquist-auditor.md

@@ -12,22 +12,7 @@ color: "#8B5CF6"
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/phase-researcher.md

@@ -12,20 +12,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefatos completos e detalhados.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- 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 — RESEARCH.md é seu produto principal:**
-RESEARCH.md é **consumido pelo planner** que vai derivar tarefas a partir dele. Conteúdo ambíguo no RESEARCH.md = plano ambíguo = execução quebrada. Mantenha **completo, detalhado e narrativo** conforme template — ZERO compressão caveman no conteúdo. Caveman aplica-se SÓ ao raciocínio falado e progresso de pesquisa.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Avisos de segurança ou ações irreversíveis
-- Discussão de trade-offs entre opções (preserva nuance)
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/plan-checker.md

@@ -6,22 +6,7 @@ color: green
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/planner.md

@@ -12,22 +12,7 @@ color: green
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — PLAN.md mantém formato completo:**
-PLAN.md é o **prompt de execução** que o `executor` vai consumir. Ele DEVE seguir prosa estruturada conforme template, com tarefas inequívocas, dependências explícitas e critérios de sucesso completos. Caveman no PLAN.md = plano ambíguo = execução quebrada. **Caveman aplica-se SÓ ao raciocínio falado, logs de progresso e retorno ao orquestrador — NUNCA ao conteúdo do PLAN.md ou de qualquer artefato em `.planning/`.**
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/project-researcher.md

@@ -12,20 +12,7 @@ color: cyan
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefatos completos e detalhados.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- 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 — artefatos são seu produto principal:**
-Os arquivos `.md` que você produz em `.planning/research/` (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md, etc.) são **lidos pelo roadmapper e por humanos** muitas vezes. Devem ser **completos, detalhados e narrativos** conforme template — ZERO compressão caveman no conteúdo do artefato. Caveman aplica-se SÓ ao raciocínio falado e progresso de pesquisa.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Avisos de segurança ou ações irreversíveis
-- Discussão de trade-offs entre opções (preserva nuance)
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/research-synthesizer.md

@@ -12,15 +12,7 @@ color: purple
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, SUMMARY.md completo.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- 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. Citações dos research outputs literais.
-
-**Boundary CRÍTICO — SUMMARY.md é seu único produto:**
-SUMMARY.md sintetiza 4 research outputs (STACK, FEATURES, ARCHITECTURE, PITFALLS) em um doc coeso que será **referência principal do projeto** consultada repetidamente. Deve ser **completo, narrativo e navegável** conforme template — ZERO compressão caveman no conteúdo. Caveman aplica-se SÓ ao raciocínio falado durante a síntese.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/roadmapper.md

@@ -12,20 +12,7 @@ color: purple
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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 — ROADMAP.md mantém formato completo:**
-ROADMAP.md é doc de referência consumido por outros agentes (planner, plan-checker) e por humanos. **Mantenha prosa estruturada conforme template** — nomes de fase, descrições, critérios de sucesso e dependências completos. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/ui-auditor.md

@@ -12,22 +12,7 @@ color: "#F472B6"
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/ui-checker.md

@@ -6,22 +6,7 @@ color: "#22D3EE"
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/ui-researcher.md

@@ -12,20 +12,7 @@ color: "#E879F9"
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, artefatos completos e detalhados.**
-
-Em mensagens conversacionais, logs e retorno ao orquestrador:
-- 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, copy de UI e citações literais.
-
-**Boundary CRÍTICO — UI-SPEC.md é seu produto principal:**
-UI-SPEC.md é **consumido pelo planner e pelo executor** como contrato de design. Labels, copy, estados visuais e interações DEVEM estar completos e literais. Caveman no UI-SPEC.md = contrato ambíguo = UI quebrada. ZERO compressão no conteúdo do artefato. Caveman aplica-se SÓ ao raciocínio falado e progresso de pesquisa.
-
-**Auto-clarity — sair completamente do caveman quando:**
-- Avisos de segurança ou ações irreversíveis
-- Discussão de trade-offs de design (preserva nuance)
-- Usuário pediu clarificação ou está confuso
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/user-profiler.md

@@ -6,15 +6,7 @@ color: magenta
 ---
 
 <output_style>
-**Estilo: caveman LITE — compressão moderada na narração, JSON estruturado completo.**
-
-Em mensagens conversacionais e logs de progresso:
-- 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. Citações de mensagem do usuário literais.
-
-**Boundary CRÍTICO — análise JSON estruturada é seu produto:**
-O JSON de saída com 8 dimensões, scores, evidências e confiança é parseado diretamente. Estrutura, chaves e valores DEVEM seguir o schema da rubrica de referência exatamente. Evidências citadas devem ser literais (não parafrasear caveman a fala original do usuário). Caveman aplica-se SÓ ao raciocínio falado durante a análise.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/agents/verifier.md

@@ -12,22 +12,7 @@ color: green
 ---
 
 <output_style>
-**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
-
-Em mensagens conversacionais, logs e relatórios ao orquestrador:
-- 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.
-- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
-- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
-
-**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 — artefatos mantêm formato completo:**
-Arquivos `.md` produzidos em `.planning/` (PLAN.md, SUMMARY.md, VERIFICATION.md, UI-REVIEW.md, ROADMAP.md, etc.) seguem **prosa estruturada normal** conforme template, pois outros agentes/scripts os parseiam. Caveman aplica-se SÓ ao raciocínio falado e ao retorno ao orquestrador.
+@./.claude/framework/references/output-style.md
 </output_style>
 
 <role>

package/kit/commands/expresso.md

@@ -29,6 +29,15 @@ Modo expresso é o mesmo sistema com um caminho mais curto:
 **Flag `--research`:** Invoca um agente de pesquisa focado antes do planejamento. Investiga abordagens de implementação, opções de biblioteca e armadilhas para a tarefa. Use quando não tem certeza da melhor abordagem.
 
 Flags são combináveis: `--discuss --research --full` dá discussão + pesquisa + verificação de plano + verificação.
+
+## Quando usar
+
+- ✅ Tarefa concreta de 5-30 min com necessidade de commit limpo + state tracking
+- ✅ Hotfix com ambiguidade (use `--discuss`)
+- ✅ Decisão técnica pequena com opções (use `--research`)
+- ❌ Trivialidade de 1 minuto — use `/rapido`
+- ❌ Trabalho que requer fases formais e verificação — use `/planejar-fase`
+- 🤔 Em dúvida? → **`/fazer "descrição"`** roteia automaticamente
 </objective>
 
 <execution_context>

package/kit/commands/fazer.md

@@ -1,6 +1,6 @@
 ---
 name: fazer
-description: Roteia texto livre para o comando do framework correto automaticamente
+description: Entrypoint canônico — roteia texto livre para o comando do framework correto. Use este quando estiver na dúvida.
 argument-hint: "<descrição do que você quer fazer>"
 allowed-tools:
   - Read
@@ -8,11 +8,24 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Analisar entrada em linguagem natural e despachar para o comando do framework mais adequado.
+**Entrypoint canônico do framework.** Quando você sabe o que quer mas não sabe qual `/*` executar, use `/fazer "descrição"`.
 
-Age como um despachante inteligente — nunca faz o trabalho diretamente. Combina a intenção com o melhor comando do framework usando regras de roteamento, confirma a correspondência e então transfere.
+`/fazer` é um despachante inteligente — nunca faz o trabalho diretamente; combina a intenção com o melhor comando e transfere com confirmação.
 
-Use quando você sabe o que quer mas não sabe qual comando `/*` executar.
+## Árvore de decisão
+
+| Sua intenção | Comando recomendado | Quando usar |
+|---|---|---|
+| Tarefa **trivial** (rename, ajuste pontual) | **`/rapido`** | Sem necessidade de plano formal; commit atômico, sem subagentes |
+| Tarefa **rápida com garantias** (commit limpo, rastreamento de estado) | **`/expresso`** | Algo concreto mas pequeno; pula agentes opcionais mas mantém disciplina |
+| Trabalho **estruturado** (multi-arquivo, requer planejamento) | **`/discutir-fase` → `/planejar-fase` → `/executar-fase`** | Fase real de milestone; usa agentes completos |
+| **Próximo passo** ambíguo no fluxo atual | **`/proximo`** | Avança no roadmap automaticamente |
+| **Capturar ideia** sem agir agora | **`/nota`** ou **`/adicionar-tarefa`** | Salva pra depois sem interromper o foco |
+| **Investigar bug** com método científico | **`/depurar`** | Hipótese → teste → fix com checkpoints |
+
+## Aliases (continuam funcionando)
+
+`/rapido`, `/expresso`, `/proximo`, `/depurar`, `/discutir-fase`, `/planejar-fase`, `/executar-fase` — todos continuam executando direto, sem passar pelo `/fazer`. Use `/fazer` quando estiver em dúvida sobre qual escolher.
 </objective>
 
 <execution_context>

package/kit/commands/proximo.md

@@ -13,6 +13,13 @@ Detectar o estado atual do projeto e automaticamente invocar o próximo passo l
 Sem argumentos necessários — lê STATE.md, ROADMAP.md e diretórios de fase para determinar o que vem a seguir.
 
 Projetado para workflows multi-projeto rápidos onde lembrar em qual fase/passo você está é overhead.
+
+## Quando usar
+
+- ✅ "Não lembro onde parei" — `/proximo` lê estado e avança
+- ✅ Pulando entre vários projetos durante o dia
+- ❌ Sabe exatamente o que fazer — invoque o comando direto
+- 🤔 Tem uma intenção mas não sabe qual comando usar? → **`/fazer "descrição"`**
 </objective>
 
 <execution_context>

package/kit/commands/rapido.md

@@ -19,6 +19,12 @@ correções de typo, mudanças de configuração, pequenas refatorações, commi
 Este NÃO é um substituto para /expresso — use /expresso para qualquer coisa que
 precise de pesquisa, planejamento multi-etapas ou verificação. /rapido é para tarefas
 que você poderia descrever em uma frase e executar em menos de 2 minutos.
+
+## Quando usar
+
+- ✅ "renomear variável X pra Y", "ajustar copy do botão", "adicionar log", "fix de typo"
+- ❌ Multi-arquivo, multi-passo, requer pesquisa — use `/expresso` ou `/planejar-fase`
+- 🤔 Em dúvida sobre qual comando? → **`/fazer "descrição"`** roteia automaticamente
 </objective>
 
 <execution_context>

package/kit/framework/references/output-style.md

@@ -0,0 +1,22 @@
+# Output Style — Caveman (compartilhado por todos os agentes framework)
+
+> Referenciado por agentes via `@./.claude/framework/references/output-style.md`. Agentes herdam essas regras automaticamente — não duplique o conteúdo no agente.
+
+**Estilo: caveman — compressão alta na fala, prosa normal em artefatos.**
+
+Em mensagens conversacionais, logs e relatórios ao orquestrador:
+- 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.
+- NÃO: "Claro! O problema que você está enfrentando provavelmente é causado por..."
+- SIM: "Bug em auth middleware. Token expiry usa `<` em vez de `<=`. Fix:"
+
+**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 — artefatos em `.planning/` mantêm formato completo:**
+PLAN.md, ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, SUMMARY.md, VERIFICATION.md e qualquer outro artefato em `.planning/` é o **prompt de execução** ou registro auditável que outros agentes/humanos vão consumir. Esses DEVEM seguir prosa estruturada conforme template, com regras inequívocas, dependências explícitas e critérios completos. Caveman em artefatos = ambíguo = quebrado.
+
+**Caveman aplica-se SÓ ao raciocínio falado, logs de progresso e retorno ao orquestrador — NUNCA ao conteúdo de artefatos em `.planning/`.**