@luanpdd/kit-mcp 0.2.1 → 0.3.0

package/kit/framework/templates/summary.md

@@ -0,0 +1,209 @@
+# Template de Summary
+
+Template para `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - documentação de conclusão de fase.
+
+---
+
+## Template do Arquivo
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [categoria primária: auth, payments, ui, api, database, infra, testing, etc.]
+tags: [tech pesquisável: jwt, stripe, react, postgres, prisma]
+
+# Grafo de dependências
+requires:
+  - phase: [fase anterior da qual esta depende]
+    provides: [o que aquela fase construiu e esta usa]
+provides:
+  - [lista de o que esta fase construiu/entregou]
+affects: [lista de nomes de fases ou palavras-chave que precisarão deste contexto]
+
+# Rastreamento de tecnologia
+tech-stack:
+  added: [bibliotecas/ferramentas adicionadas nesta fase]
+  patterns: [padrões arquiteturais/de código estabelecidos]
+
+key-files:
+  created: [arquivos importantes criados]
+  modified: [arquivos importantes modificados]
+
+key-decisions:
+  - "Decisão 1"
+  - "Decisão 2"
+
+patterns-established:
+  - "Padrão 1: descrição"
+  - "Padrão 2: descrição"
+
+requirements-completed: []  # OBRIGATÓRIO — Copiar TODOS os IDs de requisitos do campo `requirements` do frontmatter deste plano.
+
+# Métricas
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Fase [X]: [Nome] — Resumo
+
+**[Uma linha substantiva descrevendo o resultado - NÃO "fase completa" ou "implementação finalizada"]**
+
+## Performance
+
+- **Duração:** [tempo] (ex.: 23 min, 1h 15m)
+- **Iniciado:** [timestamp ISO]
+- **Concluído:** [timestamp ISO]
+- **Tarefas:** [contagem concluída]
+- **Arquivos modificados:** [contagem]
+
+## Realizações
+- [Resultado mais importante]
+- [Segunda conquista chave]
+- [Terceira se aplicável]
+
+## Commits das Tarefas
+
+Cada tarefa foi comitada atomicamente:
+
+1. **Tarefa 1: [nome da tarefa]** - `abc123f` (feat/fix/test/refactor)
+2. **Tarefa 2: [nome da tarefa]** - `def456g` (feat/fix/test/refactor)
+3. **Tarefa 3: [nome da tarefa]** - `hij789k` (feat/fix/test/refactor)
+
+**Metadados do plano:** `lmn012o` (docs: plano completo)
+
+_Nota: Tarefas TDD podem ter múltiplos commits (test → feat → refactor)_
+
+## Arquivos Criados/Modificados
+- `path/to/file.ts` - O que faz
+- `path/to/another.ts` - O que faz
+
+## Decisões Tomadas
+[Decisões chave com breve justificativa, ou "Nenhuma — plano seguido como especificado"]
+
+## Desvios do Plano
+
+[Se sem desvios: "Nenhum — plano executado exatamente como escrito"]
+
+[Se desvios ocorreram:]
+
+### Problemas Corrigidos Automaticamente
+
+**1. [Regra X - Categoria] Breve descrição**
+- **Encontrado durante:** Tarefa [N] ([nome da tarefa])
+- **Problema:** [O que estava errado]
+- **Correção:** [O que foi feito]
+- **Arquivos modificados:** [caminhos dos arquivos]
+- **Verificação:** [Como foi verificado]
+- **Comitado em:** [hash] (parte do commit da tarefa)
+
+[... repetir para cada correção automática ...]
+
+---
+
+**Total de desvios:** [N] corrigidos automaticamente ([breakdown por regra])
+**Impacto no plano:** [Breve avaliação - ex.: "Todas as correções automáticas necessárias para correção/segurança. Sem expansão de escopo."]
+
+## Problemas Encontrados
+[Problemas e como foram resolvidos, ou "Nenhum"]
+
+[Nota: "Desvios do Plano" documenta trabalho não planejado que foi tratado automaticamente via regras de desvio. "Problemas Encontrados" documenta problemas durante o trabalho planejado que requeriram resolução de problemas.]
+
+## Configuração Manual Necessária
+
+[Se USER-SETUP.md foi gerado:]
+**Serviços externos requerem configuração manual.** Ver [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) para:
+- Variáveis de ambiente a adicionar
+- Etapas de configuração do dashboard
+- Comandos de verificação
+
+[Se sem USER-SETUP.md:]
+Nenhuma — sem configuração de serviço externo necessária.
+
+## Prontidão para Próxima Fase
+[O que está pronto para a próxima fase]
+[Quaisquer bloqueios ou preocupações]
+
+---
+*Fase: XX-nome*
+*Concluída: [data]*
+```
+
+<frontmatter_guidance>
+**Propósito:** Habilitar montagem automática de contexto via grafo de dependências. O frontmatter torna os metadados do summary legíveis por máquina para que o plan-phase possa escanear todos os summaries rapidamente e selecionar os relevantes com base em dependências.
+
+**Escaneamento rápido:** O frontmatter está nas primeiras ~25 linhas, barato de escanear em todos os summaries sem ler o conteúdo completo.
+
+**Grafo de dependências:** `requires`/`provides`/`affects` criam links explícitos entre fases, habilitando fechamento transitivo para seleção de contexto.
+
+**Subsystem:** Categorização primária (auth, payments, ui, api, database, infra, testing) para detectar fases relacionadas.
+
+**Tags:** Palavras-chave técnicas pesquisáveis (bibliotecas, frameworks, ferramentas) para consciência do stack tecnológico.
+
+**Key-files:** Arquivos importantes para referências @context no PLAN.md.
+
+**Patterns:** Convenções estabelecidas que fases futuras devem manter.
+
+**Preenchimento:** O frontmatter é preenchido durante a criação do summary no execute-plan.md. Ver `<step name="create_summary">` para orientação campo a campo.
+</frontmatter_guidance>
+
+<one_liner_rules>
+O one-liner DEVE ser substantivo:
+
+**Bom:**
+- "Auth JWT com rotação de refresh usando biblioteca jose"
+- "Schema Prisma com models User, Session e Product"
+- "Dashboard com métricas em tempo real via Server-Sent Events"
+
+**Ruim:**
+- "Fase completa"
+- "Autenticação implementada"
+- "Fundação finalizada"
+- "Todas as tarefas concluídas"
+
+O one-liner deve dizer a alguém o que realmente foi entregue.
+</one_liner_rules>
+
+<example>
+```markdown
+# Phase 1: Foundation Summary
+
+**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
+
+## Performance
+
+- **Duration:** 28 min
+- **Started:** 2025-01-15T14:22:10Z
+- **Completed:** 2025-01-15T14:50:33Z
+- **Tasks:** 5
+- **Files modified:** 8
+
+## Accomplishments
+- User model with email/password auth
+- Login/logout endpoints with httpOnly JWT cookies
+- Protected route middleware checking token validity
+- Refresh token rotation on each request
+
+## Decisions Made
+- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
+- 15-min access tokens with 7-day refresh tokens
+- Storing refresh tokens in database for revocation capability
+
+## Next Phase Readiness
+- Auth foundation complete, ready for feature development
+- User registration endpoint needed before public launch
+```
+</example>
+
+<guidelines>
+**Frontmatter:** OBRIGATÓRIO — completar todos os campos. Habilita montagem automática de contexto para planejamento futuro.
+
+**One-liner:** Deve ser substantivo. "Auth JWT com rotação de refresh usando biblioteca jose" não "Autenticação implementada".
+
+**Seção de Decisões:**
+- Decisões chave tomadas durante a execução com justificativa
+- Extraídas para o contexto acumulado do STATE.md
+- Usar "Nenhuma — plano seguido como especificado" se sem desvios
+
+**Após a criação:** STATE.md atualizado com posição, decisões, problemas.
+</guidelines>

package/kit/framework/templates/user-profile.md

@@ -0,0 +1,146 @@
+# Perfil do Desenvolvedor
+
+> Este perfil foi gerado a partir da análise de sessões. Contém diretivas comportamentais
+> para o Claude seguir ao trabalhar com este desenvolvedor. Dimensões com confiança ALTA
+> devem ser aplicadas diretamente. Dimensões com confiança BAIXA devem ser abordadas com
+> ressalva ("Com base no seu perfil, vou tentar X — me diga se estiver errado").
+
+**Gerado em:** {{generated_at}}
+**Fonte:** {{data_source}}
+**Projetos Analisados:** {{projects_list}}
+**Mensagens Analisadas:** {{message_count}}
+
+---
+
+## Referência Rápida
+
+{{summary_instructions}}
+
+---
+
+## Estilo de Comunicação
+
+**Classificação:** {{communication_style.rating}} | **Confiança:** {{communication_style.confidence}}
+
+**Diretiva:** {{communication_style.claude_instruction}}
+
+{{communication_style.summary}}
+
+**Evidências:**
+
+{{communication_style.evidence}}
+
+---
+
+## Velocidade de Decisão
+
+**Classificação:** {{decision_speed.rating}} | **Confiança:** {{decision_speed.confidence}}
+
+**Diretiva:** {{decision_speed.claude_instruction}}
+
+{{decision_speed.summary}}
+
+**Evidências:**
+
+{{decision_speed.evidence}}
+
+---
+
+## Profundidade de Explicação
+
+**Classificação:** {{explanation_depth.rating}} | **Confiança:** {{explanation_depth.confidence}}
+
+**Diretiva:** {{explanation_depth.claude_instruction}}
+
+{{explanation_depth.summary}}
+
+**Evidências:**
+
+{{explanation_depth.evidence}}
+
+---
+
+## Abordagem de Debug
+
+**Classificação:** {{debugging_approach.rating}} | **Confiança:** {{debugging_approach.confidence}}
+
+**Diretiva:** {{debugging_approach.claude_instruction}}
+
+{{debugging_approach.summary}}
+
+**Evidências:**
+
+{{debugging_approach.evidence}}
+
+---
+
+## Filosofia de UX
+
+**Classificação:** {{ux_philosophy.rating}} | **Confiança:** {{ux_philosophy.confidence}}
+
+**Diretiva:** {{ux_philosophy.claude_instruction}}
+
+{{ux_philosophy.summary}}
+
+**Evidências:**
+
+{{ux_philosophy.evidence}}
+
+---
+
+## Filosofia de Vendor
+
+**Classificação:** {{vendor_philosophy.rating}} | **Confiança:** {{vendor_philosophy.confidence}}
+
+**Diretiva:** {{vendor_philosophy.claude_instruction}}
+
+{{vendor_philosophy.summary}}
+
+**Evidências:**
+
+{{vendor_philosophy.evidence}}
+
+---
+
+## Gatilhos de Frustração
+
+**Classificação:** {{frustration_triggers.rating}} | **Confiança:** {{frustration_triggers.confidence}}
+
+**Diretiva:** {{frustration_triggers.claude_instruction}}
+
+{{frustration_triggers.summary}}
+
+**Evidências:**
+
+{{frustration_triggers.evidence}}
+
+---
+
+## Estilo de Aprendizado
+
+**Classificação:** {{learning_style.rating}} | **Confiança:** {{learning_style.confidence}}
+
+**Diretiva:** {{learning_style.claude_instruction}}
+
+{{learning_style.summary}}
+
+**Evidências:**
+
+{{learning_style.evidence}}
+
+---
+
+## Metadados do Perfil
+
+| Campo | Valor |
+|-------|-------|
+| Versão do Perfil | {{profile_version}} |
+| Gerado em | {{generated_at}} |
+| Fonte | {{data_source}} |
+| Projetos | {{projects_count}} |
+| Mensagens | {{message_count}} |
+| Dimensões Pontuadas | {{dimensions_scored}}/8 |
+| Confiança Alta | {{high_confidence_count}} |
+| Confiança Média | {{medium_confidence_count}} |
+| Confiança Baixa | {{low_confidence_count}} |
+| Conteúdo Sensível Excluído | {{sensitive_excluded_summary}} |

package/kit/framework/templates/user-setup.md

@@ -0,0 +1,256 @@
+# Template de User Setup
+
+Template para `.planning/phases/XX-name/{phase}-USER-SETUP.md` - configuração manual necessária que Claude não pode automatizar.
+
+**Propósito:** Documentar tarefas de configuração que literalmente requerem ação humana — criação de conta, configuração de dashboard, recuperação de segredos. Claude automatiza tudo que é possível; este arquivo captura apenas o que resta.
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Fase {X}: Configuração Manual Necessária
+
+**Gerado:** [AAAA-MM-DD]
+**Fase:** {nome-da-fase}
+**Status:** Incompleto
+
+Complete estes itens para que a integração funcione. Claude automatizou tudo que foi possível; estes itens requerem acesso humano a dashboards/contas externas.
+
+## Variáveis de Ambiente
+
+| Status | Variável | Fonte | Adicionar em |
+|--------|----------|-------|--------------|
+| [ ] | `NOME_DA_VAR` | [Dashboard do Serviço → Caminho → Para → Valor] | `.env.local` |
+| [ ] | `OUTRA_VAR` | [Dashboard do Serviço → Caminho → Para → Valor] | `.env.local` |
+
+## Configuração de Conta
+
+[Apenas se criação de nova conta for necessária]
+
+- [ ] **Criar conta no [Serviço]**
+  - URL: [URL de cadastro]
+  - Pular se: Já tem conta
+
+## Configuração do Dashboard
+
+[Apenas se configuração do dashboard for necessária]
+
+- [ ] **[Tarefa de configuração]**
+  - Local: [Dashboard do Serviço → Caminho → Para → Configuração]
+  - Definir como: [Valor ou configuração necessária]
+  - Notas: [Detalhes importantes]
+
+## Verificação
+
+Após completar a configuração, verificar com:
+
+```bash
+# [Comandos de verificação]
+```
+
+Resultados esperados:
+- [Como o sucesso se parece]
+
+---
+
+**Quando todos os itens estiverem completos:** Marcar status como "Completo" no topo do arquivo.
+```
+
+---
+
+## Quando Gerar
+
+Gerar `{phase}-USER-SETUP.md` quando o frontmatter do plano contiver o campo `user_setup`.
+
+**Gatilho:** `user_setup` existe no frontmatter do PLAN.md e tem itens.
+
+**Local:** Mesmo diretório que PLAN.md e SUMMARY.md.
+
+**Timing:** Gerado durante execute-plan.md após as tarefas concluírem, antes da criação do SUMMARY.md.
+
+---
+
+## Schema do Frontmatter
+
+No PLAN.md, `user_setup` declara configuração manual necessária:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "Payment processing requires API keys"
+    env_vars:
+      - name: STRIPE_SECRET_KEY
+        source: "Stripe Dashboard → Developers → API keys → Secret key"
+      - name: STRIPE_WEBHOOK_SECRET
+        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
+    dashboard_config:
+      - task: "Create webhook endpoint"
+        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed, customer.subscription.*"
+    local_dev:
+      - "Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+      - "Use the webhook secret from CLI output for local testing"
+```
+
+---
+
+## A Regra Automation-First
+
+**USER-SETUP.md contém APENAS o que Claude literalmente não pode fazer.**
+
+| Claude PODE Fazer (não vai em USER-SETUP) | Claude NÃO PODE Fazer (→ USER-SETUP) |
+|-------------------------------------------|--------------------------------------|
+| `npm install stripe` | Criar conta no Stripe |
+| Escrever código do webhook handler | Obter chaves de API do dashboard |
+| Criar estrutura do arquivo `.env.local` | Copiar valores reais dos segredos |
+| Executar `stripe listen` | Autenticar o Stripe CLI (OAuth no browser) |
+| Configurar package.json | Acessar dashboards de serviços externos |
+| Escrever qualquer código | Recuperar segredos de sistemas de terceiros |
+
+**O teste:** "Isso requer um humano no browser, acessando uma conta que Claude não tem credenciais?"
+- Sim → USER-SETUP.md
+- Não → Claude faz automaticamente
+
+---
+
+## Exemplos por Serviço
+
+<stripe_example>
+```markdown
+# Fase 10: Configuração Manual Necessária
+
+**Gerado:** 2025-01-14
+**Fase:** 10-monetization
+**Status:** Incompleto
+
+Complete estes itens para que a integração com Stripe funcione.
+
+## Variáveis de Ambiente
+
+| Status | Variável | Fonte | Adicionar em |
+|--------|----------|-------|--------------|
+| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
+| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe Dashboard → Developers → API keys → Publishable key | `.env.local` |
+| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → [endpoint] → Signing secret | `.env.local` |
+
+## Configuração de Conta
+
+- [ ] **Criar conta no Stripe** (se necessário)
+  - URL: https://dashboard.stripe.com/register
+  - Pular se: Já tem conta no Stripe
+
+## Configuração do Dashboard
+
+- [ ] **Criar endpoint de webhook**
+  - Local: Stripe Dashboard → Developers → Webhooks → Add endpoint
+  - URL do endpoint: `https://[seu-dominio]/api/webhooks/stripe`
+  - Eventos a enviar:
+    - `checkout.session.completed`
+    - `customer.subscription.created`
+    - `customer.subscription.updated`
+    - `customer.subscription.deleted`
+
+- [ ] **Criar produtos e preços** (se usando tiers de assinatura)
+  - Local: Stripe Dashboard → Products → Add product
+  - Criar cada tier de assinatura
+  - Copiar Price IDs para:
+    - `STRIPE_STARTER_PRICE_ID`
+    - `STRIPE_PRO_PRICE_ID`
+
+## Desenvolvimento Local
+
+Para testar webhooks localmente:
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+Use o webhook signing secret da saída do CLI (começa com `whsec_`).
+
+## Verificação
+
+Após completar a configuração:
+
+```bash
+# Verificar se as variáveis de ambiente estão definidas
+grep STRIPE .env.local
+
+# Verificar se o build passa
+npm run build
+
+# Testar endpoint do webhook (deve retornar 400 bad signature, não 500 crash)
+curl -X POST http://localhost:3000/api/webhooks/stripe \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Esperado: Build passa, webhook retorna 400 (validação de assinatura funcionando).
+
+---
+
+**Quando todos os itens estiverem completos:** Marcar status como "Completo" no topo do arquivo.
+```
+</stripe_example>
+
+<supabase_example>
+```markdown
+# Fase 2: Configuração Manual Necessária
+
+**Gerado:** 2025-01-14
+**Fase:** 02-authentication
+**Status:** Incompleto
+
+Complete estes itens para que o Supabase Auth funcione.
+
+## Variáveis de Ambiente
+
+| Status | Variável | Fonte | Adicionar em |
+|--------|----------|-------|--------------|
+| [ ] | `NEXT_PUBLIC_SUPABASE_URL` | Supabase Dashboard → Settings → API → Project URL | `.env.local` |
+| [ ] | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase Dashboard → Settings → API → anon public | `.env.local` |
+| [ ] | `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard → Settings → API → service_role | `.env.local` |
+
+## Configuração de Conta
+
+- [ ] **Criar projeto no Supabase**
+  - URL: https://supabase.com/dashboard/new
+  - Pular se: Já tem projeto para este app
+
+## Configuração do Dashboard
+
+- [ ] **Habilitar Email Auth**
+  - Local: Supabase Dashboard → Authentication → Providers
+  - Habilitar: provedor de Email
+  - Configurar: Confirmar email (on/off conforme preferência)
+
+- [ ] **Configurar provedores OAuth** (se usando login social)
+  - Local: Supabase Dashboard → Authentication → Providers
+  - Para Google: Adicionar Client ID e Secret do Google Cloud Console
+  - Para GitHub: Adicionar Client ID e Secret do GitHub OAuth Apps
+
+## Verificação
+
+Após completar a configuração:
+
+```bash
+# Verificar variáveis de ambiente
+grep SUPABASE .env.local
+
+# Verificar conexão (executar no diretório do projeto)
+npx supabase status
+```
+
+---
+
+**Quando todos os itens estiverem completos:** Marcar status como "Completo" no topo do arquivo.
+```
+</supabase_example>
+
+---
+
+## Diretrizes
+
+**Nunca incluir:** Valores reais de segredos. Passos que Claude pode automatizar (instalação de pacotes, mudanças de código).
+
+**Nomenclatura:** `{phase}-USER-SETUP.md` corresponde ao padrão de número de fase.
+**Rastreamento de status:** Usuário marca checkboxes e atualiza linha de status quando completo.
+**Busca:** `grep -r "USER-SETUP" .planning/` encontra todas as fases com requisitos do usuário.