@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/framework/templates/claude-md.md

@@ -0,0 +1,122 @@
+# Template CLAUDE.md
+
+Template para `CLAUDE.md` na raiz do projeto — gerado automaticamente por `tools generate-claude-md`.
+
+Contém 6 seções delimitadas por marcadores. Cada seção é atualizável independentemente.
+O subcomando `generate-claude-md` gerencia 5 seções (project, stack, conventions, architecture, workflow enforcement).
+A seção de perfil é gerenciada exclusivamente por `generate-claude-profile`.
+
+---
+
+## Templates de Seção
+
+### Seção Project
+```
+<!-- framework:project-start source:PROJECT.md -->
+## Project
+
+{{project_content}}
+<!-- framework:project-end -->
+```
+
+**Texto de fallback:**
+```
+Project not yet initialized. Run /novo-projeto to set up.
+```
+
+### Seção Stack
+```
+<!-- framework:stack-start source:STACK.md -->
+## Technology Stack
+
+{{stack_content}}
+<!-- framework:stack-end -->
+```
+
+**Texto de fallback:**
+```
+Technology stack not yet documented. Will populate after codebase mapping or first phase.
+```
+
+### Seção Conventions
+```
+<!-- framework:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+{{conventions_content}}
+<!-- framework:conventions-end -->
+```
+
+**Texto de fallback:**
+```
+Conventions not yet established. Will populate as patterns emerge during development.
+```
+
+### Seção Architecture
+```
+<!-- framework:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+{{architecture_content}}
+<!-- framework:architecture-end -->
+```
+
+**Texto de fallback:**
+```
+Architecture not yet mapped. Follow existing patterns found in the codebase.
+```
+
+### Seção Workflow Enforcement
+```
+<!-- framework:workflow-start source:framework defaults -->
+## framework Workflow Enforcement
+
+Before using Edit, Write, or other file-changing tools, start work through a framework command so planning artifacts and execution context stay in sync.
+
+Use these entry points:
+- `/quick` for small fixes, doc updates, and ad-hoc tasks
+- `/debug` for investigation and bug fixing
+- `/executar-fase` for planned phase work
+
+Do not make direct repo edits outside a framework workflow unless the user explicitly asks to bypass it.
+<!-- framework:workflow-end -->
+```
+
+### Seção Profile (Apenas Placeholder)
+```
+<!-- framework:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/profile-user` to generate your developer profile.
+> This section is managed by `generate-claude-profile` — do not edit manually.
+<!-- framework:profile-end -->
+```
+
+**Nota:** Esta seção NÃO é gerenciada por `generate-claude-md`. É gerenciada exclusivamente
+por `generate-claude-profile`. O placeholder acima é usado apenas ao criar um novo
+arquivo CLAUDE.md quando ainda não existe seção de perfil.
+
+---
+
+## Ordem das Seções
+
+1. **Project** — Identidade e propósito (o que é este projeto)
+2. **Stack** — Escolhas de tecnologia (quais ferramentas são usadas)
+3. **Conventions** — Padrões de código e regras (como o código é escrito)
+4. **Architecture** — Estrutura do sistema (como os componentes se encaixam)
+5. **Workflow Enforcement** — Pontos de entrada framework padrão para trabalho que altera arquivos
+6. **Profile** — Preferências comportamentais do desenvolvedor (como interagir)
+
+## Formato dos Marcadores
+
+- Início: `<!-- framework:{name}-start source:{file} -->`
+- Fim: `<!-- framework:{name}-end -->`
+- Atributo source permite atualizações direcionadas quando arquivos fonte mudam
+- Correspondência parcial no marcador de início (sem `-->` de fechamento) para detecção
+
+## Comportamento de Fallback
+
+Quando um arquivo fonte está faltando, o texto de fallback fornece orientação acionável para o Claude:
+- Orienta o comportamento do Claude na ausência de dados
+- Não são avisos de "faltando" ou placeholders
+- Cada fallback diz ao Claude o que fazer, não apenas o que está ausente

package/kit/framework/templates/codebase/architecture.md

@@ -0,0 +1,185 @@
+# Template de Arquitetura
+
+Template para `.planning/codebase/ARCHITECTURE.md` - captura a organização conceitual do código.
+
+**Propósito:** Documentar como o código está organizado em nível conceitual. Complementa STRUCTURE.md (que mostra localizações físicas de arquivos).
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Arquitetura
+
+**Data da Análise:** [AAAA-MM-DD]
+
+## Visão Geral do Padrão
+
+**Geral:** [Nome do padrão: ex.: "CLI Monolítico", "API Serverless", "MVC Full-stack"]
+
+**Características Chave:**
+- [Característica 1: ex.: "Executável único"]
+- [Característica 2: ex.: "Tratamento de requisições stateless"]
+- [Característica 3: ex.: "Orientado a eventos"]
+
+## Camadas
+
+[Descreva as camadas conceituais e suas responsabilidades]
+
+**[Nome da Camada]:**
+- Propósito: [O que esta camada faz]
+- Contém: [Tipos de código: ex.: "route handlers", "lógica de negócio"]
+- Depende de: [O que usa: ex.: "apenas camada de dados"]
+- Usado por: [O que o usa: ex.: "rotas da API"]
+
+**[Nome da Camada]:**
+- Propósito: [O que esta camada faz]
+- Contém: [Tipos de código]
+- Depende de: [O que usa]
+- Usado por: [O que o usa]
+
+## Fluxo de Dados
+
+[Descreva o ciclo de vida típico de requisição/execução]
+
+**[Nome do Fluxo] (ex.: "Requisição HTTP", "Comando CLI", "Processamento de Evento"):**
+
+1. [Ponto de entrada: ex.: "Usuário executa comando"]
+2. [Etapa de processamento: ex.: "Router corresponde ao caminho"]
+3. [Etapa de processamento: ex.: "Controller valida entrada"]
+4. [Etapa de processamento: ex.: "Service executa lógica"]
+5. [Saída: ex.: "Resposta retornada"]
+
+**Gerenciamento de Estado:**
+- [Como o estado é tratado: ex.: "Stateless - sem estado persistente", "Banco por requisição", "Cache em memória"]
+
+## Abstrações Chave
+
+[Conceitos/padrões centrais usados em todo o codebase]
+
+**[Nome da Abstração]:**
+- Propósito: [O que representa]
+- Exemplos: [ex.: "UserService, ProjectService"]
+- Padrão: [ex.: "Singleton", "Factory", "Repository"]
+
+**[Nome da Abstração]:**
+- Propósito: [O que representa]
+- Exemplos: [Exemplos concretos]
+- Padrão: [Padrão usado]
+
+## Pontos de Entrada
+
+[Onde a execução começa]
+
+**[Ponto de Entrada]:**
+- Localização: [Breve: ex.: "src/index.ts", "API Gateway triggers"]
+- Gatilhos: [O que o invoca: ex.: "invocação CLI", "requisição HTTP"]
+- Responsabilidades: [O que faz: ex.: "Analisar args, rotear para comando"]
+
+## Tratamento de Erros
+
+**Estratégia:** [Como erros são tratados: ex.: "Exception bubbling para handler de nível superior", "Middleware de erro por rota"]
+
+**Padrões:**
+- [Padrão: ex.: "try/catch no nível do controller"]
+- [Padrão: ex.: "Códigos de erro retornados ao usuário"]
+
+## Preocupações Transversais
+
+[Aspectos que afetam múltiplas camadas]
+
+**Logging:**
+- [Abordagem: ex.: "Winston logger, injetado por requisição"]
+
+**Validação:**
+- [Abordagem: ex.: "Schemas Zod no limite da API"]
+
+**Autenticação:**
+- [Abordagem: ex.: "Middleware JWT em rotas protegidas"]
+
+---
+
+*Análise de arquitetura: [data]*
+*Atualizar quando padrões principais mudarem*
+```
+
+<good_examples>
+```markdown
+# Architecture
+
+**Analysis Date:** 2025-01-20
+
+## Pattern Overview
+
+**Overall:** CLI Application with Plugin System
+
+**Key Characteristics:**
+- Single executable with subcommands
+- Plugin-based extensibility
+- File-based state (no database)
+- Synchronous execution model
+
+## Layers
+
+**Command Layer:**
+- Purpose: Parse user input and route to appropriate handler
+- Contains: Command definitions, argument parsing, help text
+- Location: `src/commands/*.ts`
+- Depends on: Service layer for business logic
+- Used by: CLI entry point (`src/index.ts`)
+
+**Service Layer:**
+- Purpose: Core business logic
+- Contains: FileService, TemplateService, InstallService
+- Location: `src/services/*.ts`
+- Depends on: File system utilities, external tools
+- Used by: Command handlers
+
+## Error Handling
+
+**Strategy:** Throw exceptions, catch at command level, log and exit
+
+**Patterns:**
+- Services throw Error with descriptive messages
+- Command handlers catch, log error to stderr, exit(1)
+- Validation errors shown before execution (fail fast)
+
+---
+
+*Architecture analysis: 2025-01-20*
+*Update when major patterns change*
+```
+</good_examples>
+
+<guidelines>
+**O que pertence ao ARCHITECTURE.md:**
+- Padrão arquitetural geral (monolito, microsserviços, em camadas, etc.)
+- Camadas conceituais e seus relacionamentos
+- Fluxo de dados / ciclo de vida da requisição
+- Abstrações e padrões chave
+- Pontos de entrada
+- Estratégia de tratamento de erros
+- Preocupações transversais (logging, auth, validação)
+
+**O que NÃO pertence aqui:**
+- Listas exaustivas de arquivos (isso é STRUCTURE.md)
+- Escolhas tecnológicas (isso é STACK.md)
+- Percurso linha a linha do código (diferir para leitura do código)
+- Detalhes de implementação de funcionalidades específicas
+
+**Caminhos de arquivo SÃO bem-vindos:**
+Inclua caminhos de arquivo como exemplos concretos de abstrações. Use formatação backtick: `src/services/user.ts`. Isso torna o documento de arquitetura acionável para o Claude durante o planejamento.
+
+**Ao preencher este template:**
+- Ler os principais pontos de entrada (index, server, main)
+- Identificar camadas lendo imports/dependências
+- Rastrear uma execução típica de requisição/comando
+- Notar padrões recorrentes (services, controllers, repositories)
+- Manter descrições conceituais, não mecânicas
+
+**Útil para planejamento de fases quando:**
+- Adicionando novas funcionalidades (onde se encaixa nas camadas?)
+- Refatorando (entendendo padrões atuais)
+- Identificando onde adicionar código (qual camada trata X?)
+- Entendendo dependências entre componentes
+</guidelines>

package/kit/framework/templates/codebase/concerns.md

@@ -0,0 +1,205 @@
+# Template de Preocupações do Codebase
+
+Template para `.planning/codebase/CONCERNS.md` - captura problemas conhecidos e áreas que requerem cuidado.
+
+**Propósito:** Apresentar avisos acionáveis sobre o codebase. Focado em "o que observar ao fazer mudanças."
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Preocupações do Codebase
+
+**Data da Análise:** [AAAA-MM-DD]
+
+## Dívida Técnica
+
+**[Área/Componente]:**
+- Problema: [Qual é o atalho/solução paliativa]
+- Por quê: [Por que foi feito assim]
+- Impacto: [O que quebra ou degrada por causa disso]
+- Abordagem de correção: [Como endereçar adequadamente]
+
+**[Área/Componente]:**
+- Problema: [Qual é o atalho/solução paliativa]
+- Por quê: [Por que foi feito assim]
+- Impacto: [O que quebra ou degrada por causa disso]
+- Abordagem de correção: [Como endereçar adequadamente]
+
+## Bugs Conhecidos
+
+**[Descrição do bug]:**
+- Sintomas: [O que acontece]
+- Gatilho: [Como reproduzir]
+- Contorno: [Mitigação temporária, se houver]
+- Causa raiz: [Se conhecida]
+- Bloqueado por: [Se aguardando algo]
+
+**[Descrição do bug]:**
+- Sintomas: [O que acontece]
+- Gatilho: [Como reproduzir]
+- Contorno: [Mitigação temporária, se houver]
+- Causa raiz: [Se conhecida]
+
+## Considerações de Segurança
+
+**[Área que requer cuidado de segurança]:**
+- Risco: [O que pode dar errado]
+- Mitigação atual: [O que está implementado agora]
+- Recomendações: [O que deveria ser adicionado]
+
+**[Área que requer cuidado de segurança]:**
+- Risco: [O que pode dar errado]
+- Mitigação atual: [O que está implementado agora]
+- Recomendações: [O que deveria ser adicionado]
+
+## Gargalos de Performance
+
+**[Operação/endpoint lento]:**
+- Problema: [O que está lento]
+- Medição: [Números reais: "500ms p95", "2s de carregamento"]
+- Causa: [Por que está lento]
+- Caminho de melhoria: [Como acelerar]
+
+**[Operação/endpoint lento]:**
+- Problema: [O que está lento]
+- Medição: [Números reais]
+- Causa: [Por que está lento]
+- Caminho de melhoria: [Como acelerar]
+
+## Áreas Frágeis
+
+**[Componente/Módulo]:**
+- Por que é frágil: [O que o faz quebrar facilmente]
+- Falhas comuns: [O que tipicamente dá errado]
+- Modificação segura: [Como mudar sem quebrar]
+- Cobertura de testes: [Está testado? Lacunas?]
+
+**[Componente/Módulo]:**
+- Por que é frágil: [O que o faz quebrar facilmente]
+- Falhas comuns: [O que tipicamente dá errado]
+- Modificação segura: [Como mudar sem quebrar]
+- Cobertura de testes: [Está testado? Lacunas?]
+
+## Limites de Escalabilidade
+
+**[Recurso/Sistema]:**
+- Capacidade atual: [Números: "100 req/seg", "10k usuários"]
+- Limite: [Onde quebra]
+- Sintomas no limite: [O que acontece]
+- Caminho de escalabilidade: [Como aumentar a capacidade]
+
+## Dependências em Risco
+
+**[Pacote/Serviço]:**
+- Risco: [ex.: "deprecado", "sem manutenção", "mudanças breaking chegando"]
+- Impacto: [O que quebra se falhar]
+- Plano de migração: [Alternativa ou caminho de upgrade]
+
+## Funcionalidades Críticas Ausentes
+
+**[Lacuna de funcionalidade]:**
+- Problema: [O que está faltando]
+- Contorno atual: [Como os usuários lidam]
+- Bloqueia: [O que não pode ser feito sem isso]
+- Complexidade de implementação: [Estimativa aproximada de esforço]
+
+## Lacunas de Cobertura de Testes
+
+**[Área não testada]:**
+- O que não está testado: [Funcionalidade específica]
+- Risco: [O que poderia quebrar despercebido]
+- Prioridade: [Alta/Média/Baixa]
+- Dificuldade de testar: [Por que ainda não está testado]
+
+---
+
+*Auditoria de preocupações: [data]*
+*Atualizar conforme problemas são corrigidos ou novos descobertos*
+```
+
+<good_examples>
+```markdown
+# Codebase Concerns
+
+**Analysis Date:** 2025-01-20
+
+## Tech Debt
+
+**Database queries in React components:**
+- Issue: Direct Supabase queries in 15+ page components instead of server actions
+- Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, `app/courses/[id]/page.tsx`
+- Why: Rapid prototyping during MVP phase
+- Impact: Can't implement RLS properly, exposes DB structure to client
+- Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies
+
+## Known Bugs
+
+**Race condition in subscription updates:**
+- Symptoms: User shows as "free" tier for 5-10 seconds after successful payment
+- Trigger: Fast navigation after Stripe checkout redirect, before webhook processes
+- Workaround: Stripe webhook eventually updates status (self-heals)
+- Root cause: Webhook processing slower than user navigation, no optimistic UI update
+
+## Security Considerations
+
+**Admin role check client-side only:**
+- Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification
+- Current mitigation: None (relying on UI hiding)
+- Recommendations: Add middleware to admin routes in `middleware.ts`, verify role server-side
+
+---
+
+*Concerns audit: 2025-01-20*
+*Update as issues are fixed or new ones discovered*
+```
+</good_examples>
+
+<guidelines>
+**O que pertence ao CONCERNS.md:**
+- Dívida técnica com impacto claro e abordagem de correção
+- Bugs conhecidos com etapas de reprodução
+- Lacunas de segurança e recomendações de mitigação
+- Gargalos de performance com medições
+- Código frágil que quebra facilmente
+- Limites de escalabilidade com números
+- Dependências que precisam de atenção
+- Funcionalidades ausentes que bloqueiam workflows
+- Lacunas de cobertura de testes
+
+**O que NÃO pertence aqui:**
+- Opiniões sem evidência ("código está bagunçado")
+- Reclamações sem soluções ("auth está ruim")
+- Ideias de funcionalidades futuras (isso é para planejamento de produto)
+- TODOs normais (esses vivem em comentários de código)
+- Decisões arquiteturais que estão funcionando bem
+- Problemas menores de estilo de código
+
+**Ao preencher este template:**
+- **Sempre incluir caminhos de arquivo** — Preocupações sem localização não são acionáveis. Use backticks: `src/file.ts`
+- Ser específico com medições ("500ms p95" não "lento")
+- Incluir etapas de reprodução para bugs
+- Sugerir abordagens de correção, não apenas problemas
+- Focar em itens acionáveis
+- Priorizar por risco/impacto
+- Atualizar conforme problemas são resolvidos
+- Adicionar novas preocupações conforme descobertas
+
+**Diretrizes de tom:**
+- Profissional, não emocional ("padrão N+1 de query" não "queries terríveis")
+- Orientado a soluções ("Correção: adicionar índice" não "precisa de correção")
+- Focado em risco ("Poderia expor dados do usuário" não "segurança está ruim")
+- Factual ("3,5s de tempo de carregamento" não "muito lento")
+
+**Útil para planejamento de fases quando:**
+- Decidindo no que trabalhar a seguir
+- Estimando risco de mudanças
+- Entendendo onde ter cuidado
+- Priorizando melhorias
+- Integrando novos contextos Claude
+- Planejando trabalho de refatoração
+
+**Como isso é populado:**
+Agentes Explore detectam esses durante o mapeamento do codebase. Adições manuais são bem-vindas para problemas descobertos por humanos. Esta é documentação viva, não uma lista de reclamações.
+</guidelines>