@luanpdd/kit-mcp 0.2.1 → 0.4.0

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

@@ -0,0 +1,204 @@
+# Template de Pesquisa de Arquitetura
+
+Template para `.planning/research/ARCHITECTURE.md` — padrões de estrutura de sistema para o domínio do projeto.
+
+<template>
+
+```markdown
+# Pesquisa de Arquitetura
+
+**Domínio:** [tipo de domínio]
+**Pesquisado:** [data]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+## Arquitetura Padrão
+
+### Visão Geral do Sistema
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        [Nome da Camada]                      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+├───────┴────────────┴────────────┴────────────┴──────────────┤
+│                        [Nome da Camada]                      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    [Componente]                      │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│                        [Nome da Camada]                      │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Responsabilidades dos Componentes
+
+| Componente | Responsabilidade | Implementação Típica |
+|------------|------------------|----------------------|
+| [nome] | [o que controla] | [como é geralmente construído] |
+| [nome] | [o que controla] | [como é geralmente construído] |
+| [nome] | [o que controla] | [como é geralmente construído] |
+
+## Estrutura de Projeto Recomendada
+
+```
+src/
+├── [pasta]/           # [propósito]
+│   ├── [subpasta]/    # [propósito]
+│   └── [arquivo].ts   # [propósito]
+├── [pasta]/           # [propósito]
+│   ├── [subpasta]/    # [propósito]
+│   └── [arquivo].ts   # [propósito]
+├── [pasta]/           # [propósito]
+└── [pasta]/           # [propósito]
+```
+
+### Justificativa da Estrutura
+
+- **[pasta]/:** [por que organizado desta forma]
+- **[pasta]/:** [por que organizado desta forma]
+
+## Padrões Arquiteturais
+
+### Padrão 1: [Nome do Padrão]
+
+**O que é:** [descrição]
+**Quando usar:** [condições]
+**Trade-offs:** [prós e contras]
+
+**Exemplo:**
+```typescript
+// [Breve exemplo de código mostrando o padrão]
+```
+
+### Padrão 2: [Nome do Padrão]
+
+**O que é:** [descrição]
+**Quando usar:** [condições]
+**Trade-offs:** [prós e contras]
+
+**Exemplo:**
+```typescript
+// [Breve exemplo de código mostrando o padrão]
+```
+
+### Padrão 3: [Nome do Padrão]
+
+**O que é:** [descrição]
+**Quando usar:** [condições]
+**Trade-offs:** [prós e contras]
+
+## Fluxo de Dados
+
+### Fluxo de Requisição
+
+```
+[Ação do Usuário]
+    ↓
+[Componente] → [Handler] → [Serviço] → [Armazenamento]
+    ↓              ↓           ↓            ↓
+[Resposta] ← [Transform] ← [Query] ← [Banco de Dados]
+```
+
+### Gerenciamento de Estado
+
+```
+[Store de Estado]
+    ↓ (subscribe)
+[Componentes] ←→ [Actions] → [Reducers/Mutations] → [Store de Estado]
+```
+
+### Fluxos de Dados Principais
+
+1. **[Nome do fluxo]:** [descrição de como os dados se movem]
+2. **[Nome do fluxo]:** [descrição de como os dados se movem]
+
+## Considerações de Escala
+
+| Escala | Ajustes de Arquitetura |
+|--------|------------------------|
+| 0-1k usuários | [abordagem — geralmente monolito está bem] |
+| 1k-100k usuários | [abordagem — o que otimizar primeiro] |
+| 100k+ usuários | [abordagem — quando considerar separação] |
+
+### Prioridades de Escala
+
+1. **Primeiro gargalo:** [o que quebra primeiro, como corrigir]
+2. **Segundo gargalo:** [o que quebra depois, como corrigir]
+
+## Anti-Padrões
+
+### Anti-Padrão 1: [Nome]
+
+**O que as pessoas fazem:** [o erro]
+**Por que está errado:** [o problema que causa]
+**Faça isto em vez disso:** [a abordagem correta]
+
+### Anti-Padrão 2: [Nome]
+
+**O que as pessoas fazem:** [o erro]
+**Por que está errado:** [o problema que causa]
+**Faça isto em vez disso:** [a abordagem correta]
+
+## Pontos de Integração
+
+### Serviços Externos
+
+| Serviço | Padrão de Integração | Notas |
+|---------|----------------------|-------|
+| [serviço] | [como conectar] | [armadilhas] |
+| [serviço] | [como conectar] | [armadilhas] |
+
+### Limites Internos
+
+| Limite | Comunicação | Notas |
+|--------|-------------|-------|
+| [módulo A ↔ módulo B] | [API/eventos/direto] | [considerações] |
+
+## Fontes
+
+- [Referências de arquitetura]
+- [Documentação oficial]
+- [Estudos de caso]
+
+---
+*Pesquisa de arquitetura para: [domínio]*
+*Pesquisado: [data]*
+```
+
+</template>
+
+<guidelines>
+
+**Visão Geral do Sistema:**
+- Use diagramas ASCII box-drawing para clareza (├── └── │ ─ apenas para visualização de estrutura)
+- Mostre componentes principais e seus relacionamentos
+- Não detalhe demais — isso é conceitual, não implementação
+
+**Estrutura do Projeto:**
+- Seja específico sobre organização de pastas
+- Explique a justificativa para agrupamento
+- Corresponda às convenções do stack escolhido
+
+**Padrões:**
+- Inclua exemplos de código quando útil
+- Explique trade-offs honestamente
+- Indique quando padrões são excessivos para projetos pequenos
+
+**Considerações de Escala:**
+- Seja realista — a maioria dos projetos não precisa escalar para milhões
+- Foque em "o que quebra primeiro", não em limites teóricos
+- Evite recomendações de otimização prematura
+
+**Anti-Padrões:**
+- Específicos para este domínio
+- Inclua o que fazer em vez disso
+- Ajuda a prevenir erros comuns durante a implementação
+
+</guidelines>

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

@@ -0,0 +1,147 @@
+# Template de Pesquisa de Funcionalidades
+
+Template para `.planning/research/FEATURES.md` — panorama de funcionalidades para o domínio do projeto.
+
+<template>
+
+```markdown
+# Pesquisa de Funcionalidades
+
+**Domínio:** [tipo de domínio]
+**Pesquisado:** [data]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+## Panorama de Funcionalidades
+
+### Requisitos Básicos (Usuários Esperam Estes)
+
+Funcionalidades que os usuários presumem existir. Faltar estas = produto parece incompleto.
+
+| Funcionalidade | Por Que É Esperada | Complexidade | Notas |
+|----------------|--------------------|--------------|-------|
+| [funcionalidade] | [expectativa do usuário] | LOW/MEDIUM/HIGH | [notas de implementação] |
+| [funcionalidade] | [expectativa do usuário] | LOW/MEDIUM/HIGH | [notas de implementação] |
+| [funcionalidade] | [expectativa do usuário] | LOW/MEDIUM/HIGH | [notas de implementação] |
+
+### Diferenciais (Vantagem Competitiva)
+
+Funcionalidades que destacam o produto. Não obrigatórias, mas valiosas.
+
+| Funcionalidade | Proposta de Valor | Complexidade | Notas |
+|----------------|-------------------|--------------|-------|
+| [funcionalidade] | [por que importa] | LOW/MEDIUM/HIGH | [notas de implementação] |
+| [funcionalidade] | [por que importa] | LOW/MEDIUM/HIGH | [notas de implementação] |
+| [funcionalidade] | [por que importa] | LOW/MEDIUM/HIGH | [notas de implementação] |
+
+### Anti-Funcionalidades (Comumente Pedidas, Frequentemente Problemáticas)
+
+Funcionalidades que parecem boas mas criam problemas.
+
+| Funcionalidade | Por Que É Pedida | Por Que É Problemática | Alternativa |
+|----------------|------------------|------------------------|-------------|
+| [funcionalidade] | [apelo superficial] | [problemas reais] | [melhor abordagem] |
+| [funcionalidade] | [apelo superficial] | [problemas reais] | [melhor abordagem] |
+
+## Dependências de Funcionalidades
+
+```
+[Funcionalidade A]
+    └──requer──> [Funcionalidade B]
+                     └──requer──> [Funcionalidade C]
+
+[Funcionalidade D] ──melhora──> [Funcionalidade A]
+
+[Funcionalidade E] ──conflita──> [Funcionalidade F]
+```
+
+### Notas de Dependência
+
+- **[Funcionalidade A] requer [Funcionalidade B]:** [por que a dependência existe]
+- **[Funcionalidade D] melhora [Funcionalidade A]:** [como funcionam juntas]
+- **[Funcionalidade E] conflita com [Funcionalidade F]:** [por que são incompatíveis]
+
+## Definição de MVP
+
+### Lançar Com (v1)
+
+Produto mínimo viável — o que é necessário para validar o conceito.
+
+- [ ] [Funcionalidade] — [por que é essencial]
+- [ ] [Funcionalidade] — [por que é essencial]
+- [ ] [Funcionalidade] — [por que é essencial]
+
+### Adicionar Após Validação (v1.x)
+
+Funcionalidades a adicionar depois que o core estiver funcionando.
+
+- [ ] [Funcionalidade] — [gatilho para adicionar]
+- [ ] [Funcionalidade] — [gatilho para adicionar]
+
+### Consideração Futura (v2+)
+
+Funcionalidades a adiar até que o product-market fit seja estabelecido.
+
+- [ ] [Funcionalidade] — [por que adiar]
+- [ ] [Funcionalidade] — [por que adiar]
+
+## Matriz de Priorização de Funcionalidades
+
+| Funcionalidade | Valor para o Usuário | Custo de Implementação | Prioridade |
+|----------------|----------------------|------------------------|------------|
+| [funcionalidade] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [funcionalidade] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [funcionalidade] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+
+**Chave de prioridade:**
+- P1: Obrigatório para lançamento
+- P2: Deve ter, adicionar quando possível
+- P3: Seria bom ter, consideração futura
+
+## Análise de Funcionalidades dos Concorrentes
+
+| Funcionalidade | Concorrente A | Concorrente B | Nossa Abordagem |
+|----------------|---------------|---------------|-----------------|
+| [funcionalidade] | [como fazem] | [como fazem] | [nosso plano] |
+| [funcionalidade] | [como fazem] | [como fazem] | [nosso plano] |
+
+## Fontes
+
+- [Produtos concorrentes analisados]
+- [Pesquisa de usuário ou fontes de feedback]
+- [Padrões do setor referenciados]
+
+---
+*Pesquisa de funcionalidades para: [domínio]*
+*Pesquisado: [data]*
+```
+
+</template>
+
+<guidelines>
+
+**Requisitos Básicos:**
+- Estes são inegociáveis para o lançamento
+- Usuários não dão crédito por tê-los, mas penalizam por faltarem
+- Exemplo: Uma plataforma comunitária sem perfis de usuário está quebrada
+
+**Diferenciais:**
+- Aqui é onde você compete
+- Deve se alinhar com o Valor Central do PROJECT.md
+- Não tente se diferenciar em tudo
+
+**Anti-Funcionalidades:**
+- Previne scope creep documentando o que parece bom mas não é
+- Inclua a abordagem alternativa
+- Exemplo: "Tudo em tempo real" frequentemente cria complexidade sem valor
+
+**Dependências de Funcionalidades:**
+- Crítico para ordenamento de fases do roadmap
+- Se A requer B, B deve estar em uma fase anterior
+- Conflitos informam o que NÃO combinar na mesma fase
+
+**Definição de MVP:**
+- Seja implacável sobre o que é verdadeiramente mínimo
+- "Seria bom ter" não é MVP
+- Lance com menos, valide, depois expanda
+
+</guidelines>

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

@@ -0,0 +1,200 @@
+# Template de Pesquisa de Armadilhas
+
+Template para `.planning/research/PITFALLS.md` — erros comuns a evitar no domínio do projeto.
+
+<template>
+
+```markdown
+# Pesquisa de Armadilhas
+
+**Domínio:** [tipo de domínio]
+**Pesquisado:** [data]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+## Armadilhas Críticas
+
+### Armadilha 1: [Nome]
+
+**O que dá errado:**
+[Descrição do modo de falha]
+
+**Por que acontece:**
+[Causa raiz — por que desenvolvedores cometem este erro]
+
+**Como evitar:**
+[Estratégia específica de prevenção]
+
+**Sinais de alerta:**
+[Como detectar isso cedo antes que se torne um problema]
+
+**Fase para abordar:**
+[Qual fase do roadmap deve prevenir isto]
+
+---
+
+### Armadilha 2: [Nome]
+
+**O que dá errado:**
+[Descrição do modo de falha]
+
+**Por que acontece:**
+[Causa raiz — por que desenvolvedores cometem este erro]
+
+**Como evitar:**
+[Estratégia específica de prevenção]
+
+**Sinais de alerta:**
+[Como detectar isso cedo antes que se torne um problema]
+
+**Fase para abordar:**
+[Qual fase do roadmap deve prevenir isto]
+
+---
+
+### Armadilha 3: [Nome]
+
+**O que dá errado:**
+[Descrição do modo de falha]
+
+**Por que acontece:**
+[Causa raiz — por que desenvolvedores cometem este erro]
+
+**Como evitar:**
+[Estratégia específica de prevenção]
+
+**Sinais de alerta:**
+[Como detectar isso cedo antes que se torne um problema]
+
+**Fase para abordar:**
+[Qual fase do roadmap deve prevenir isto]
+
+---
+
+[Continue para todas as armadilhas críticas...]
+
+## Padrões de Dívida Técnica
+
+Atalhos que parecem razoáveis mas criam problemas a longo prazo.
+
+| Atalho | Benefício Imediato | Custo a Longo Prazo | Quando É Aceitável |
+|--------|--------------------|---------------------|--------------------|
+| [atalho] | [benefício] | [custo] | [condições, ou "nunca"] |
+| [atalho] | [benefício] | [custo] | [condições, ou "nunca"] |
+| [atalho] | [benefício] | [custo] | [condições, ou "nunca"] |
+
+## Armadilhas de Integração
+
+Erros comuns ao conectar a serviços externos.
+
+| Integração | Erro Comum | Abordagem Correta |
+|------------|------------|-------------------|
+| [serviço] | [o que as pessoas fazem errado] | [o que fazer em vez disso] |
+| [serviço] | [o que as pessoas fazem errado] | [o que fazer em vez disso] |
+| [serviço] | [o que as pessoas fazem errado] | [o que fazer em vez disso] |
+
+## Armadilhas de Performance
+
+Padrões que funcionam em pequena escala mas falham com o crescimento do uso.
+
+| Armadilha | Sintomas | Prevenção | Quando Quebra |
+|-----------|----------|-----------|---------------|
+| [armadilha] | [como perceber] | [como evitar] | [limite de escala] |
+| [armadilha] | [como perceber] | [como evitar] | [limite de escala] |
+| [armadilha] | [como perceber] | [como evitar] | [limite de escala] |
+
+## Erros de Segurança
+
+Problemas de segurança específicos do domínio além da segurança web geral.
+
+| Erro | Risco | Prevenção |
+|------|-------|-----------|
+| [erro] | [o que poderia acontecer] | [como evitar] |
+| [erro] | [o que poderia acontecer] | [como evitar] |
+| [erro] | [o que poderia acontecer] | [como evitar] |
+
+## Armadilhas de UX
+
+Erros comuns de experiência do usuário neste domínio.
+
+| Armadilha | Impacto no Usuário | Melhor Abordagem |
+|-----------|-------------------|------------------|
+| [armadilha] | [como os usuários sofrem] | [o que fazer em vez disso] |
+| [armadilha] | [como os usuários sofrem] | [o que fazer em vez disso] |
+| [armadilha] | [como os usuários sofrem] | [o que fazer em vez disso] |
+
+## Checklist "Parece Pronto Mas Não Está"
+
+Coisas que parecem completas mas estão faltando peças críticas.
+
+- [ ] **[Funcionalidade]:** Frequentemente falta [coisa] — verificar [checagem]
+- [ ] **[Funcionalidade]:** Frequentemente falta [coisa] — verificar [checagem]
+- [ ] **[Funcionalidade]:** Frequentemente falta [coisa] — verificar [checagem]
+- [ ] **[Funcionalidade]:** Frequentemente falta [coisa] — verificar [checagem]
+
+## Estratégias de Recuperação
+
+Quando armadilhas ocorrem apesar da prevenção, como se recuperar.
+
+| Armadilha | Custo de Recuperação | Passos de Recuperação |
+|-----------|----------------------|----------------------|
+| [armadilha] | LOW/MEDIUM/HIGH | [o que fazer] |
+| [armadilha] | LOW/MEDIUM/HIGH | [o que fazer] |
+| [armadilha] | LOW/MEDIUM/HIGH | [o que fazer] |
+
+## Mapeamento de Armadilhas por Fase
+
+Como as fases do roadmap devem abordar estas armadilhas.
+
+| Armadilha | Fase de Prevenção | Verificação |
+|-----------|-------------------|-------------|
+| [armadilha] | Fase [X] | [como verificar se a prevenção funcionou] |
+| [armadilha] | Fase [X] | [como verificar se a prevenção funcionou] |
+| [armadilha] | Fase [X] | [como verificar se a prevenção funcionou] |
+
+## Fontes
+
+- [Post-mortems referenciados]
+- [Discussões da comunidade]
+- [Documentação oficial de "armadilhas"]
+- [Experiência pessoal / problemas conhecidos]
+
+---
+*Pesquisa de armadilhas para: [domínio]*
+*Pesquisado: [data]*
+```
+
+</template>
+
+<guidelines>
+
+**Armadilhas Críticas:**
+- Foque em problemas específicos do domínio, não em erros genéricos
+- Inclua sinais de alerta — detecção precoce evita desastres
+- Vincule a fases específicas — torna as armadilhas acionáveis
+
+**Dívida Técnica:**
+- Seja realista — alguns atalhos são aceitáveis
+- Indique quando atalhos são "nunca aceitáveis" vs. "apenas no MVP"
+- Inclua o custo a longo prazo para informar decisões de trade-off
+
+**Armadilhas de Performance:**
+- Inclua limites de escala ("quebra com 10k usuários")
+- Foque no que é relevante para a escala esperada deste projeto
+- Não super-otimize para escala hipotética
+
+**Erros de Segurança:**
+- Além das básicas do OWASP — problemas específicos do domínio
+- Exemplo: Plataformas comunitárias têm preocupações de segurança diferentes de e-commerce
+- Inclua nível de risco para priorizar
+
+**"Parece Pronto Mas Não Está":**
+- Formato de checklist para verificação durante a execução
+- Comum em demos vs. produção
+- Previne problemas de "funciona na minha máquina"
+
+**Mapeamento de Armadilhas por Fase:**
+- Crítico para a criação do roadmap
+- Cada armadilha deve mapear para uma fase que a previne
+- Informa o ordenamento de fases e critérios de sucesso
+
+</guidelines>

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

@@ -0,0 +1,120 @@
+# Template de Pesquisa de Stack
+
+Template para `.planning/research/STACK.md` — tecnologias recomendadas para o domínio do projeto.
+
+<template>
+
+```markdown
+# Pesquisa de Stack
+
+**Domínio:** [tipo de domínio]
+**Pesquisado:** [data]
+**Confiança:** [HIGH/MEDIUM/LOW]
+
+## Stack Recomendado
+
+### Tecnologias Core
+
+| Tecnologia | Versão | Propósito | Por Que Recomendada |
+|------------|--------|-----------|---------------------|
+| [nome] | [versão] | [o que faz] | [por que especialistas usam para este domínio] |
+| [nome] | [versão] | [o que faz] | [por que especialistas usam para este domínio] |
+| [nome] | [versão] | [o que faz] | [por que especialistas usam para este domínio] |
+
+### Bibliotecas de Suporte
+
+| Biblioteca | Versão | Propósito | Quando Usar |
+|------------|--------|-----------|-------------|
+| [nome] | [versão] | [o que faz] | [caso de uso específico] |
+| [nome] | [versão] | [o que faz] | [caso de uso específico] |
+| [nome] | [versão] | [o que faz] | [caso de uso específico] |
+
+### Ferramentas de Desenvolvimento
+
+| Ferramenta | Propósito | Notas |
+|------------|-----------|-------|
+| [nome] | [o que faz] | [dicas de configuração] |
+| [nome] | [o que faz] | [dicas de configuração] |
+
+## Instalação
+
+```bash
+# Core
+npm install [pacotes]
+
+# Suporte
+npm install [pacotes]
+
+# Dependências de desenvolvimento
+npm install -D [pacotes]
+```
+
+## Alternativas Consideradas
+
+| Recomendado | Alternativa | Quando Usar a Alternativa |
+|-------------|-------------|---------------------------|
+| [nossa escolha] | [outra opção] | [condições onde a alternativa é melhor] |
+| [nossa escolha] | [outra opção] | [condições onde a alternativa é melhor] |
+
+## O Que NÃO Usar
+
+| Evitar | Por Que | Usar Em Vez Disso |
+|--------|---------|-------------------|
+| [tecnologia] | [problema específico] | [alternativa recomendada] |
+| [tecnologia] | [problema específico] | [alternativa recomendada] |
+
+## Variantes de Stack por Condição
+
+**Se [condição]:**
+- Usar [variação]
+- Porque [razão]
+
+**Se [condição]:**
+- Usar [variação]
+- Porque [razão]
+
+## Compatibilidade de Versões
+
+| Pacote A | Compatível Com | Notas |
+|----------|----------------|-------|
+| [pacote@versão] | [pacote@versão] | [notas de compatibilidade] |
+
+## Fontes
+
+- [ID de biblioteca Context7] — [tópicos pesquisados]
+- [URL de documentação oficial] — [o que foi verificado]
+- [Outra fonte] — [nível de confiança]
+
+---
+*Pesquisa de stack para: [domínio]*
+*Pesquisado: [data]*
+```
+
+</template>
+
+<guidelines>
+
+**Tecnologias Core:**
+- Inclua números de versão específicos
+- Explique por que esta é a escolha padrão, não apenas o que faz
+- Foque em tecnologias que afetam decisões de arquitetura
+
+**Bibliotecas de Suporte:**
+- Inclua bibliotecas comumente necessárias para este domínio
+- Indique quando cada uma é necessária (nem todos os projetos precisam de todas)
+
+**Alternativas:**
+- Não apenas dispense alternativas
+- Explique quando as alternativas fazem sentido
+- Ajuda o usuário a tomar decisões informadas caso discorde
+
+**O Que NÃO Usar:**
+- Alerte ativamente contra escolhas desatualizadas ou problemáticas
+- Explique o problema específico, não apenas "é antigo"
+- Forneça a alternativa recomendada
+
+**Compatibilidade de Versões:**
+- Anote problemas conhecidos de compatibilidade
+- Crítico para evitar tempo de depuração mais tarde
+
+</guidelines>