@luanpdd/kit-mcp 0.2.1 → 0.3.0

package/kit/framework/templates/research-project/SUMMARY.md

@@ -0,0 +1,170 @@
+# Template de Resumo de Pesquisa
+
+Template para `.planning/research/SUMMARY.md` — resumo executivo da pesquisa do projeto com implicações para o roadmap.
+
+<template>
+
+```markdown
+# Resumo da Pesquisa do Projeto
+
+**Projeto:** [nome do PROJECT.md]
+**Domínio:** [tipo de domínio inferido]
+**Pesquisado:** [data]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+## Resumo Executivo
+
+[Visão geral dos resultados da pesquisa em 2-3 parágrafos]
+
+- Que tipo de produto é este e como especialistas constroem
+- A abordagem recomendada com base na pesquisa
+- Riscos principais e como mitigá-los
+
+## Principais Descobertas
+
+### Stack Recomendado
+
+[Resumo do STACK.md — 1-2 parágrafos]
+
+**Tecnologias core:**
+- [Tecnologia]: [propósito] — [por que recomendada]
+- [Tecnologia]: [propósito] — [por que recomendada]
+- [Tecnologia]: [propósito] — [por que recomendada]
+
+### Funcionalidades Esperadas
+
+[Resumo do FEATURES.md]
+
+**Deve ter (requisitos básicos):**
+- [Funcionalidade] — usuários esperam isto
+- [Funcionalidade] — usuários esperam isto
+
+**Deveria ter (competitivo):**
+- [Funcionalidade] — diferencial
+- [Funcionalidade] — diferencial
+
+**Adiar (v2+):**
+- [Funcionalidade] — não essencial para lançamento
+
+### Abordagem de Arquitetura
+
+[Resumo do ARCHITECTURE.md — 1 parágrafo]
+
+**Componentes principais:**
+1. [Componente] — [responsabilidade]
+2. [Componente] — [responsabilidade]
+3. [Componente] — [responsabilidade]
+
+### Armadilhas Críticas
+
+[Top 3-5 do PITFALLS.md]
+
+1. **[Armadilha]** — [como evitar]
+2. **[Armadilha]** — [como evitar]
+3. **[Armadilha]** — [como evitar]
+
+## Implicações para o Roadmap
+
+Com base na pesquisa, estrutura de fases sugerida:
+
+### Fase 1: [Nome]
+**Justificativa:** [por que vem primeiro com base na pesquisa]
+**Entrega:** [o que esta fase produz]
+**Aborda:** [funcionalidades do FEATURES.md]
+**Evita:** [armadilha do PITFALLS.md]
+
+### Fase 2: [Nome]
+**Justificativa:** [por que esta ordem]
+**Entrega:** [o que esta fase produz]
+**Usa:** [elementos de stack do STACK.md]
+**Implementa:** [componente de arquitetura]
+
+### Fase 3: [Nome]
+**Justificativa:** [por que esta ordem]
+**Entrega:** [o que esta fase produz]
+
+[Continue para fases sugeridas...]
+
+### Justificativa do Ordenamento das Fases
+
+- [Por que esta ordem com base nas dependências descobertas]
+- [Por que este agrupamento com base nos padrões de arquitetura]
+- [Como isto evita armadilhas da pesquisa]
+
+### Flags de Pesquisa
+
+Fases que provavelmente precisarão de pesquisa mais aprofundada durante o planejamento:
+- **Fase [X]:** [razão — ex.: "integração complexa, precisa de pesquisa de API"]
+- **Fase [Y]:** [razão — ex.: "domínio de nicho, documentação escassa"]
+
+Fases com padrões padrão (pular fase de pesquisa):
+- **Fase [X]:** [razão — ex.: "bem documentado, padrões estabelecidos"]
+
+## Avaliação de Confiança
+
+| Área | Confiança | Notas |
+|------|-----------|-------|
+| Stack | [HIGH/MEDIUM/LOW] | [razão] |
+| Funcionalidades | [HIGH/MEDIUM/LOW] | [razão] |
+| Arquitetura | [HIGH/MEDIUM/LOW] | [razão] |
+| Armadilhas | [HIGH/MEDIUM/LOW] | [razão] |
+
+**Confiança geral:** [HIGH/MEDIUM/LOW]
+
+### Lacunas a Abordar
+
+[Quaisquer áreas onde a pesquisa foi inconclusiva ou precisa de validação durante a implementação]
+
+- [Lacuna]: [como tratar durante o planejamento/execução]
+- [Lacuna]: [como tratar durante o planejamento/execução]
+
+## Fontes
+
+### Primárias (confiança HIGH)
+- [ID de biblioteca Context7] — [tópicos]
+- [URL de documentação oficial] — [o que foi verificado]
+
+### Secundárias (confiança MEDIUM)
+- [Fonte] — [descoberta]
+
+### Terciárias (confiança LOW)
+- [Fonte] — [descoberta, precisa de validação]
+
+---
+*Pesquisa concluída: [data]*
+*Pronto para roadmap: sim*
+```
+
+</template>
+
+<guidelines>
+
+**Resumo Executivo:**
+- Escreva para quem vai ler apenas esta seção
+- Inclua a recomendação principal e o risco principal
+- Máximo de 2-3 parágrafos
+
+**Principais Descobertas:**
+- Resuma, não duplique documentos completos
+- Vincule a documentos detalhados (STACK.md, FEATURES.md, etc.)
+- Foque no que importa para decisões do roadmap
+
+**Implicações para o Roadmap:**
+- Esta é a seção mais importante
+- Informa diretamente a criação do roadmap
+- Seja explícito sobre sugestões de fases e justificativa
+- Inclua flags de pesquisa para cada fase sugerida
+
+**Avaliação de Confiança:**
+- Seja honesto sobre incerteza
+- Indique lacunas que precisam de resolução durante o planejamento
+- HIGH = verificado com fontes oficiais
+- MEDIUM = consenso da comunidade, múltiplas fontes concordam
+- LOW = fonte única ou inferência
+
+**Integração com a criação do roadmap:**
+- Este arquivo é carregado como contexto durante a criação do roadmap
+- Sugestões de fases aqui se tornam ponto de partida para o roadmap
+- Flags de pesquisa informam o planejamento de fases
+
+</guidelines>

package/kit/framework/templates/research.md

@@ -0,0 +1,419 @@
+# Template de Research
+
+Template para `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - pesquisa abrangente de ecossistema antes do planejamento.
+
+**Propósito:** Documentar o que Claude precisa saber para implementar uma fase bem — não apenas "qual biblioteca" mas "como especialistas constroem isso."
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Fase [X]: [Nome] - Pesquisa
+
+**Pesquisado:** [data]
+**Domínio:** [tecnologia primária/domínio do problema]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+<user_constraints>
+## Restrições do Usuário (do CONTEXT.md)
+
+**CRÍTICO:** Se CONTEXT.md existir do /discuss-phase, copiar decisões travadas aqui literalmente. Estas DEVEM ser honradas pelo planejador.
+
+### Decisões Travadas
+[Copiar da seção `## Decisões` do CONTEXT.md - estas são NÃO-NEGOCIÁVEIS]
+- [Decisão 1]
+- [Decisão 2]
+
+### A Critério do Claude
+[Copiar do CONTEXT.md - áreas onde pesquisador/planejador pode escolher]
+- [Área 1]
+- [Área 2]
+
+### Ideias Diferidas (FORA DO ESCOPO)
+[Copiar do CONTEXT.md - NÃO pesquisar ou planejar estas]
+- [Diferida 1]
+- [Diferida 2]
+
+**Se não existir CONTEXT.md:** Escrever "Sem restrições do usuário - todas as decisões a critério do Claude"
+</user_constraints>
+
+<research_summary>
+## Resumo
+
+[Resumo executivo de 2-3 parágrafos]
+- O que foi pesquisado
+- Qual é a abordagem padrão
+- Recomendações chave
+
+**Recomendação principal:** [orientação acionável em uma linha]
+</research_summary>
+
+<standard_stack>
+## Stack Padrão
+
+As bibliotecas/ferramentas estabelecidas para este domínio:
+
+### Core
+| Biblioteca | Versão | Propósito | Por que é Padrão |
+|------------|--------|-----------|------------------|
+| [nome] | [ver] | [o que faz] | [por que especialistas usam] |
+| [nome] | [ver] | [o que faz] | [por que especialistas usam] |
+
+### Suporte
+| Biblioteca | Versão | Propósito | Quando Usar |
+|------------|--------|-----------|-------------|
+| [nome] | [ver] | [o que faz] | [caso de uso] |
+| [nome] | [ver] | [o que faz] | [caso de uso] |
+
+### Alternativas Consideradas
+| Em vez de | Poderia Usar | Trade-off |
+|-----------|--------------|-----------|
+| [padrão] | [alternativa] | [quando alternativa faz sentido] |
+
+**Instalação:**
+```bash
+npm install [pacotes]
+# ou
+yarn add [pacotes]
+```
+</standard_stack>
+
+<architecture_patterns>
+## Padrões de Arquitetura
+
+### Estrutura de Projeto Recomendada
+```
+src/
+├── [pasta]/        # [propósito]
+├── [pasta]/        # [propósito]
+└── [pasta]/        # [propósito]
+```
+
+### Padrão 1: [Nome do Padrão]
+**O quê:** [descrição]
+**Quando usar:** [condições]
+**Exemplo:**
+```typescript
+// [exemplo de código do Context7/docs oficiais]
+```
+
+### Padrão 2: [Nome do Padrão]
+**O quê:** [descrição]
+**Quando usar:** [condições]
+**Exemplo:**
+```typescript
+// [exemplo de código]
+```
+
+### Anti-Padrões a Evitar
+- **[Anti-padrão]:** [por que é ruim, o que fazer em vez disso]
+- **[Anti-padrão]:** [por que é ruim, o que fazer em vez disso]
+</architecture_patterns>
+
+<dont_hand_roll>
+## Não Implemente do Zero
+
+Problemas que parecem simples mas têm soluções existentes:
+
+| Problema | Não Construa | Use Em Vez | Por quê |
+|----------|--------------|------------|---------|
+| [problema] | [o que você construiria] | [biblioteca] | [casos extremos, complexidade] |
+| [problema] | [o que você construiria] | [biblioteca] | [casos extremos, complexidade] |
+| [problema] | [o que você construiria] | [biblioteca] | [casos extremos, complexidade] |
+
+**Insight chave:** [por que soluções customizadas são piores neste domínio]
+</dont_hand_roll>
+
+<common_pitfalls>
+## Armadilhas Comuns
+
+### Armadilha 1: [Nome]
+**O que dá errado:** [descrição]
+**Por que acontece:** [causa raiz]
+**Como evitar:** [estratégia de prevenção]
+**Sinais de alerta:** [como detectar cedo]
+
+### Armadilha 2: [Nome]
+**O que dá errado:** [descrição]
+**Por que acontece:** [causa raiz]
+**Como evitar:** [estratégia de prevenção]
+**Sinais de alerta:** [como detectar cedo]
+
+### Armadilha 3: [Nome]
+**O que dá errado:** [descrição]
+**Por que acontece:** [causa raiz]
+**Como evitar:** [estratégia de prevenção]
+**Sinais de alerta:** [como detectar cedo]
+</common_pitfalls>
+
+<code_examples>
+## Exemplos de Código
+
+Padrões verificados de fontes oficiais:
+
+### [Operação Comum 1]
+```typescript
+// Fonte: [URL do Context7/docs oficiais]
+[código]
+```
+
+### [Operação Comum 2]
+```typescript
+// Fonte: [URL do Context7/docs oficiais]
+[código]
+```
+
+### [Operação Comum 3]
+```typescript
+// Fonte: [URL do Context7/docs oficiais]
+[código]
+```
+</code_examples>
+
+<sota_updates>
+## Estado da Arte (2024-2025)
+
+O que mudou recentemente:
+
+| Abordagem Antiga | Abordagem Atual | Quando Mudou | Impacto |
+|------------------|-----------------|--------------|---------|
+| [antiga] | [nova] | [data/versão] | [o que significa para a implementação] |
+
+**Novas ferramentas/padrões a considerar:**
+- [Ferramenta/Padrão]: [o que habilita, quando usar]
+- [Ferramenta/Padrão]: [o que habilita, quando usar]
+
+**Obsoleto/desatualizado:**
+- [Coisa]: [por que está desatualizada, o que a substituiu]
+</sota_updates>
+
+<open_questions>
+## Questões Abertas
+
+Coisas que não puderam ser totalmente resolvidas:
+
+1. **[Questão]**
+   - O que sabemos: [info parcial]
+   - O que está incerto: [a lacuna]
+   - Recomendação: [como lidar durante o planejamento/execução]
+
+2. **[Questão]**
+   - O que sabemos: [info parcial]
+   - O que está incerto: [a lacuna]
+   - Recomendação: [como lidar]
+</open_questions>
+
+<sources>
+## Fontes
+
+### Primárias (confiança HIGH)
+- [ID da biblioteca no Context7] - [tópicos consultados]
+- [URL dos docs oficiais] - [o que foi verificado]
+
+### Secundárias (confiança MEDIUM)
+- [WebSearch verificada com fonte oficial] - [descoberta + verificação]
+
+### Terciárias (confiança LOW - requer validação)
+- [Apenas WebSearch] - [descoberta, marcada para validação durante a implementação]
+</sources>
+
+<metadata>
+## Metadados
+
+**Escopo da pesquisa:**
+- Tecnologia core: [o quê]
+- Ecossistema: [bibliotecas exploradas]
+- Padrões: [padrões pesquisados]
+- Armadilhas: [áreas verificadas]
+
+**Breakdown de confiança:**
+- Stack padrão: [HIGH/MEDIUM/LOW] - [motivo]
+- Arquitetura: [HIGH/MEDIUM/LOW] - [motivo]
+- Armadilhas: [HIGH/MEDIUM/LOW] - [motivo]
+- Exemplos de código: [HIGH/MEDIUM/LOW] - [motivo]
+
+**Data da pesquisa:** [data]
+**Válido até:** [estimativa - 30 dias para tecnologia estável, 7 dias para tecnologia em rápida evolução]
+</metadata>
+
+---
+
+*Fase: XX-nome*
+*Pesquisa concluída: [data]*
+*Pronto para planejamento: [sim/não]*
+```
+
+---
+
+## Bom Exemplo
+
+```markdown
+# Phase 3: 3D City Driving - Research
+
+**Researched:** 2025-01-20
+**Domain:** Three.js 3D web game with driving mechanics
+**Confidence:** HIGH
+
+<research_summary>
+## Summary
+
+Researched the Three.js ecosystem for building a 3D city driving game. The standard approach uses Three.js with React Three Fiber for component architecture, Rapier for physics, and drei for common helpers.
+
+Key finding: Don't hand-roll physics or collision detection. Rapier (via @react-three/rapier) handles vehicle physics, terrain collision, and city object interactions efficiently. Custom physics code leads to bugs and performance issues.
+
+**Primary recommendation:** Use R3F + Rapier + drei stack. Start with vehicle controller from drei, add Rapier vehicle physics, build city with instanced meshes for performance.
+</research_summary>
+
+<standard_stack>
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| three | 0.160.0 | 3D rendering | The standard for web 3D |
+| @react-three/fiber | 8.15.0 | React renderer for Three.js | Declarative 3D, better DX |
+| @react-three/drei | 9.92.0 | Helpers and abstractions | Solves common problems |
+| @react-three/rapier | 1.2.1 | Physics engine bindings | Best physics for R3F |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| @react-three/postprocessing | 2.16.0 | Visual effects | Bloom, DOF, motion blur |
+| leva | 0.9.35 | Debug UI | Tweaking parameters |
+| zustand | 4.4.7 | State management | Game state, UI state |
+| use-sound | 4.0.1 | Audio | Engine sounds, ambient |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| Rapier | Cannon.js | Cannon simpler but less performant for vehicles |
+| R3F | Vanilla Three | Vanilla if no React, but R3F DX is much better |
+| drei | Custom helpers | drei is battle-tested, don't reinvent |
+
+**Installation:**
+```bash
+npm install three @react-three/fiber @react-three/drei @react-three/rapier zustand
+```
+</standard_stack>
+
+<architecture_patterns>
+## Architecture Patterns
+
+### Recommended Project Structure
+```
+src/
+├── components/
+│   ├── Vehicle/          # Player car with physics
+│   ├── City/             # City generation and buildings
+│   ├── Road/             # Road network
+│   └── Environment/      # Sky, lighting, fog
+├── hooks/
+│   ├── useVehicleControls.ts
+│   └── useGameState.ts
+├── stores/
+│   └── gameStore.ts      # Zustand state
+└── utils/
+    └── cityGenerator.ts  # Procedural generation helpers
+```
+
+### Pattern 1: Vehicle with Rapier Physics
+**What:** Use RigidBody with vehicle-specific settings, not custom physics
+**When to use:** Any ground vehicle
+**Example:**
+```typescript
+// Source: @react-three/rapier docs
+import { RigidBody, useRapier } from '@react-three/rapier'
+
+function Vehicle() {
+  const rigidBody = useRef()
+
+  return (
+    <RigidBody
+      ref={rigidBody}
+      type="dynamic"
+      colliders="hull"
+      mass={1500}
+      linearDamping={0.5}
+      angularDamping={0.5}
+    >
+      <mesh>
+        <boxGeometry args={[2, 1, 4]} />
+        <meshStandardMaterial />
+      </mesh>
+    </RigidBody>
+  )
+}
+```
+
+### Anti-Patterns to Avoid
+- **Creating meshes in render loop:** Create once, update transforms only
+- **Not using InstancedMesh:** Individual meshes for buildings kills performance
+- **Custom physics math:** Rapier handles it better, every time
+</architecture_patterns>
+
+<dont_hand_roll>
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Vehicle physics | Custom velocity/acceleration | Rapier RigidBody | Wheel friction, suspension, collisions are complex |
+| Collision detection | Raycasting everything | Rapier colliders | Performance, edge cases, tunneling |
+| Camera follow | Manual lerp | drei CameraControls or custom with useFrame | Smooth interpolation, bounds |
+| City generation | Pure random placement | Grid-based with noise for variation | Random looks wrong, grid is predictable |
+| LOD | Manual distance checks | drei <Detailed> | Handles transitions, hysteresis |
+
+**Key insight:** 3D game development has 40+ years of solved problems. Rapier implements proper physics simulation. drei implements proper 3D helpers. Fighting these leads to bugs that look like "game feel" issues but are actually physics edge cases.
+</dont_hand_roll>
+
+<sources>
+## Sources
+
+### Primary (HIGH confidence)
+- /pmndrs/react-three-fiber - getting started, hooks, performance
+- /pmndrs/drei - instances, controls, helpers
+- /dimforge/rapier-js - physics setup, vehicle physics
+
+### Tertiary (LOW confidence - needs validation)
+- None - all findings verified
+</sources>
+
+---
+
+*Phase: 03-city-driving*
+*Research completed: 2025-01-20*
+*Ready for planning: yes*
+```
+
+---
+
+## Diretrizes
+
+**Quando criar:**
+- Antes de planejar fases em domínios niche/complexos
+- Quando os dados de treinamento do Claude provavelmente estão desatualizados ou escassos
+- Quando "como especialistas fazem isso" importa mais do que "qual biblioteca"
+
+**Estrutura:**
+- Usar tags XML para marcadores de seção (combina com templates framework)
+- Sete seções core: summary, standard_stack, architecture_patterns, dont_hand_roll, common_pitfalls, code_examples, sources
+- Todas as seções obrigatórias (impulsiona pesquisa abrangente)
+
+**Qualidade do conteúdo:**
+- Stack padrão: Versões específicas, não apenas nomes
+- Arquitetura: Incluir exemplos reais de código de fontes autoritativas
+- Don't hand-roll: Ser explícito sobre quais problemas NÃO resolver você mesmo
+- Armadilhas: Incluir sinais de alerta, não apenas "não faça isso"
+- Fontes: Marcar níveis de confiança honestamente
+
+**Integração com planejamento:**
+- RESEARCH.md carregado como referência @context no PLAN.md
+- Stack padrão informa escolhas de biblioteca
+- Don't hand-roll previne soluções customizadas
+- Armadilhas informam critérios de verificação
+- Exemplos de código podem ser referenciados em ações de tarefas
+
+**Após a criação:**
+- Arquivo fica no diretório da fase: `.planning/phases/XX-nome/{phase_num}-RESEARCH.md`
+- Referenciado durante o workflow de planejamento
+- plan-phase o carrega automaticamente quando presente

package/kit/framework/templates/retrospective.md

@@ -0,0 +1,54 @@
+# Retrospectiva do Projeto
+
+*Um documento vivo atualizado após cada milestone. As lições alimentam o planejamento futuro.*
+
+## Milestone: v{version} — {nome}
+
+**Entregue:** {data}
+**Fases:** {contagem} | **Planos:** {contagem} | **Sessões:** {contagem}
+
+### O Que Foi Construído
+- {Entregável chave 1}
+- {Entregável chave 2}
+- {Entregável chave 3}
+
+### O Que Funcionou
+- {Ganho de eficiência ou padrão bem-sucedido}
+- {O que correu bem}
+
+### O Que Foi Ineficiente
+- {Oportunidade perdida}
+- {O que demorou mais do que o esperado}
+
+### Padrões Estabelecidos
+- {Novo padrão ou convenção que deve persistir}
+
+### Lições Chave
+1. {Lição específica e acionável}
+2. {Outra lição}
+
+### Observações de Custo
+- Mix de modelos: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Sessões: {contagem}
+- Notável: {observação de eficiência}
+
+---
+
+## Tendências Entre Milestones
+
+### Evolução do Processo
+
+| Milestone | Sessões | Fases | Mudança Chave |
+|-----------|---------|-------|---------------|
+| v{X} | {N} | {M} | {O que mudou no processo} |
+
+### Qualidade Acumulada
+
+| Milestone | Testes | Cobertura | Adições Sem Dependências |
+|-----------|--------|-----------|--------------------------|
+| v{X} | {N} | {Y}% | {contagem} |
+
+### Principais Lições (Verificadas Entre Milestones)
+
+1. {Lição verificada por múltiplos milestones}
+2. {Outra lição validada transversalmente}