@luanpdd/kit-mcp 0.2.1 → 0.4.0

package/kit/framework/templates/planner-subagent-prompt.md

@@ -0,0 +1,117 @@
+# Template de Prompt do Subagente Planejador
+
+Template para spawnar o agente planner. O agente contém toda a expertise de planejamento — este template fornece apenas o contexto de planejamento.
+
+---
+
+## Template
+
+```markdown
+<planning_context>
+
+**Phase:** {phase_number}
+**Mode:** {standard | gap_closure}
+
+**Project State:**
+@.planning/STATE.md
+
+**Roadmap:**
+@.planning/ROADMAP.md
+
+**Requirements (if exists):**
+@.planning/REQUIREMENTS.md
+
+**Phase Context (if exists):**
+@.planning/phases/{phase_dir}/{phase_num}-CONTEXT.md
+
+**Research (if exists):**
+@.planning/phases/{phase_dir}/{phase_num}-RESEARCH.md
+
+**Gap Closure (if --gaps mode):**
+@.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+@.planning/phases/{phase_dir}/{phase_num}-UAT.md
+
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /executar-fase
+Plans must be executable prompts with:
+- Frontmatter (wave, depends_on, files_modified, autonomous)
+- Tasks in XML format
+- Verification criteria
+- must_haves for goal-backward verification
+</downstream_consumer>
+
+<quality_gate>
+Before returning PLANNING COMPLETE:
+- [ ] PLAN.md files created in phase directory
+- [ ] Each plan has valid frontmatter
+- [ ] Tasks are specific and actionable
+- [ ] Dependencies correctly identified
+- [ ] Waves assigned for parallel execution
+- [ ] must_haves derived from phase goal
+</quality_gate>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Fonte | Exemplo |
+|-------------|-------|---------|
+| `{phase_number}` | Do roadmap/argumentos | `5` ou `2.1` |
+| `{phase_dir}` | Nome do diretório da fase | `05-user-profiles` |
+| `{phase}` | Prefixo da fase | `05` |
+| `{standard \| gap_closure}` | Flag de modo | `standard` |
+
+---
+
+## Uso
+
+**A partir de /planejar-fase (modo padrão):**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="planner",
+  description="Plan Phase {phase}"
+)
+```
+
+**A partir de /planejar-fase --gaps (modo gap closure):**
+```python
+Task(
+  prompt=filled_template,  # with mode: gap_closure
+  subagent_type="planner",
+  description="Plan gaps for Phase {phase}"
+)
+```
+
+---
+
+## Continuação
+
+Para checkpoints, spawnar novo agente com:
+
+```markdown
+<objective>
+Continue planning for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+Phase directory: @.planning/phases/{phase_dir}/
+Existing plans: @.planning/phases/{phase_dir}/*-PLAN.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+Continue: {standard | gap_closure}
+</mode>
+```
+
+---
+
+**Nota:** Metodologia de planejamento, decomposição de tarefas, análise de dependências, atribuição de waves, detecção de TDD e derivação goal-backward estão incorporados no agente planner. Este template apenas passa contexto.

package/kit/framework/templates/project.md

@@ -0,0 +1,186 @@
+# Template PROJECT.md
+
+Template para `.planning/PROJECT.md` — o documento de contexto do projeto em evolução.
+
+<template>
+
+```markdown
+# [Nome do Projeto]
+
+## O Que É
+
+[Descrição precisa e atual — 2-3 frases. O que este produto faz e para quem é?
+Use a linguagem e o enquadramento do usuário. Atualizar quando a realidade divergir desta descrição.]
+
+## Valor Central
+
+[A UMA coisa que mais importa. Se tudo mais falhar, isso deve funcionar.
+Uma frase que orienta a priorização quando surgem trade-offs.]
+
+## Requisitos
+
+### Validados
+
+<!-- Lançados e confirmados como valiosos. -->
+
+(Nenhum ainda — lançar para validar)
+
+### Ativos
+
+<!-- Escopo atual. Construindo em direção a estes. -->
+
+- [ ] [Requisito 1]
+- [ ] [Requisito 2]
+- [ ] [Requisito 3]
+
+### Fora do Escopo
+
+<!-- Limites explícitos. Inclui raciocínio para evitar re-adição. -->
+
+- [Exclusão 1] — [por quê]
+- [Exclusão 2] — [por quê]
+
+## Contexto
+
+[Informações de fundo que informam a implementação:
+- Ambiente técnico ou ecossistema
+- Trabalho anterior relevante ou experiência
+- Temas de pesquisa com usuários ou feedback
+- Problemas conhecidos a serem endereçados]
+
+## Restrições
+
+- **[Tipo]**: [O quê] — [Por quê]
+- **[Tipo]**: [O quê] — [Por quê]
+
+Tipos comuns: Stack de tecnologia, Prazo, Orçamento, Dependências, Compatibilidade, Performance, Segurança
+
+## Decisões Chave
+
+<!-- Decisões que restringem trabalho futuro. Adicionar ao longo do ciclo de vida do projeto. -->
+
+| Decisão | Justificativa | Resultado |
+|---------|---------------|-----------|
+| [Escolha] | [Por quê] | [✓ Boa / ⚠️ Revisar / — Pendente] |
+
+---
+*Última atualização: [data] após [gatilho]*
+```
+
+</template>
+
+<guidelines>
+
+**O Que É:**
+- Descrição precisa e atual do produto
+- 2-3 frases capturando o que faz e para quem é
+- Use as palavras e o enquadramento do usuário
+- Atualizar quando o produto evoluir além desta descrição
+
+**Valor Central:**
+- A coisa mais importante
+- Tudo mais pode falhar; isso não pode
+- Orienta a priorização quando surgem trade-offs
+- Raramente muda; se mudar, é uma virada significativa
+
+**Requisitos — Validados:**
+- Requisitos que foram lançados e se mostraram valiosos
+- Formato: `- ✓ [Requisito] — [versão/fase]`
+- Estes estão travados — alterá-los requer discussão explícita
+
+**Requisitos — Ativos:**
+- Escopo atual sendo construído
+- São hipóteses até serem lançados e validados
+- Mover para Validados quando lançados, Fora do Escopo se invalidados
+
+**Requisitos — Fora do Escopo:**
+- Limites explícitos sobre o que não estamos construindo
+- Sempre incluir raciocínio (evita re-adição depois)
+- Inclui: considerados e rejeitados, diferidos para o futuro, explicitamente excluídos
+
+**Contexto:**
+- Fundo que informa decisões de implementação
+- Ambiente técnico, trabalho anterior, feedback de usuário
+- Problemas conhecidos ou dívida técnica a ser endereçada
+- Atualizar conforme novo contexto emerge
+
+**Restrições:**
+- Limites rígidos nas escolhas de implementação
+- Stack tecnológico, prazo, orçamento, compatibilidade, dependências
+- Incluir o "por quê" — restrições sem justificativa são questionadas
+
+**Decisões Chave:**
+- Escolhas significativas que afetam trabalho futuro
+- Adicionar decisões conforme são tomadas ao longo do projeto
+- Rastrear resultado quando conhecido:
+  - ✓ Boa — decisão se mostrou correta
+  - ⚠️ Revisar — decisão pode precisar de reconsideração
+  - — Pendente — cedo demais para avaliar
+
+**Última Atualização:**
+- Sempre anotar quando e por que o documento foi atualizado
+- Formato: `após Fase 2` ou `após milestone v1.0`
+- Aciona revisão de se o conteúdo ainda está preciso
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md evolui ao longo do ciclo de vida do projeto.
+Estas regras estão incorporadas no PROJECT.md gerado (seção ## Evolução)
+e implementadas por workflows/transition.md e workflows/complete-milestone.md.
+
+**Após cada transição de fase:**
+1. Requisitos invalidados? → Mover para Fora do Escopo com motivo
+2. Requisitos validados? → Mover para Validados com referência de fase
+3. Novos requisitos emergiram? → Adicionar em Ativos
+4. Decisões a registrar? → Adicionar em Decisões Chave
+5. "O Que É" ainda está preciso? → Atualizar se divergiu
+
+**Após cada milestone:**
+1. Revisão completa de todas as seções
+2. Verificação do Valor Central — ainda é a prioridade certa?
+3. Auditoria de Fora do Escopo — os motivos ainda são válidos?
+4. Atualizar Contexto com estado atual (usuários, feedback, métricas)
+
+</evolution>
+
+<brownfield>
+
+Para codebases existentes:
+
+1. **Mapear o codebase primeiro** via `/map-codebase`
+
+2. **Inferir requisitos Validados** do código existente:
+   - O que o codebase realmente faz?
+   - Quais padrões estão estabelecidos?
+   - O que está claramente funcionando e sendo utilizado?
+
+3. **Coletar requisitos Ativos** do usuário:
+   - Apresentar o estado atual inferido
+   - Perguntar o que querem construir a seguir
+
+4. **Inicializar:**
+   - Validados = inferidos do código existente
+   - Ativos = objetivos do usuário para este trabalho
+   - Fora do Escopo = limites especificados pelo usuário
+   - Contexto = inclui o estado atual do codebase
+
+</brownfield>
+
+<state_reference>
+
+STATE.md referencia PROJECT.md:
+
+```markdown
+## Referência do Projeto
+
+Ver: .planning/PROJECT.md (atualizado em [data])
+
+**Valor central:** [Uma linha da seção Valor Central]
+**Foco atual:** [Nome da fase atual]
+```
+
+Isso garante que Claude leia o contexto atual do PROJECT.md.
+
+</state_reference>

package/kit/framework/templates/requirements.md

@@ -0,0 +1,231 @@
+# Template de Requirements
+
+Template para `.planning/REQUIREMENTS.md` — requisitos verificáveis que definem "pronto."
+
+<template>
+
+```markdown
+# Requisitos: [Nome do Projeto]
+
+**Definidos:** [data]
+**Valor Central:** [de PROJECT.md]
+
+## Requisitos v1
+
+Requisitos para o lançamento inicial. Cada um mapeia para fases do roadmap.
+
+### Autenticação
+
+- [ ] **AUTH-01**: Usuário pode se cadastrar com email e senha
+- [ ] **AUTH-02**: Usuário recebe verificação por email após o cadastro
+- [ ] **AUTH-03**: Usuário pode redefinir senha via link por email
+- [ ] **AUTH-04**: Sessão do usuário persiste após atualização do navegador
+
+### [Categoria 2]
+
+- [ ] **[CAT]-01**: [Descrição do requisito]
+- [ ] **[CAT]-02**: [Descrição do requisito]
+- [ ] **[CAT]-03**: [Descrição do requisito]
+
+### [Categoria 3]
+
+- [ ] **[CAT]-01**: [Descrição do requisito]
+- [ ] **[CAT]-02**: [Descrição do requisito]
+
+## Requisitos v2
+
+Diferidos para lançamento futuro. Rastreados mas não no roadmap atual.
+
+### [Categoria]
+
+- **[CAT]-01**: [Descrição do requisito]
+- **[CAT]-02**: [Descrição do requisito]
+
+## Fora do Escopo
+
+Explicitamente excluídos. Documentados para prevenir expansão de escopo.
+
+| Funcionalidade | Motivo |
+|----------------|--------|
+| [Funcionalidade] | [Por que excluída] |
+| [Funcionalidade] | [Por que excluída] |
+
+## Rastreabilidade
+
+Quais fases cobrem quais requisitos. Atualizado durante a criação do roadmap.
+
+| Requisito | Fase | Status |
+|-----------|------|--------|
+| AUTH-01 | Fase 1 | Pending |
+| AUTH-02 | Fase 1 | Pending |
+| AUTH-03 | Fase 1 | Pending |
+| AUTH-04 | Fase 1 | Pending |
+| [REQ-ID] | Fase [N] | Pending |
+
+**Cobertura:**
+- Requisitos v1: [X] total
+- Mapeados para fases: [Y]
+- Não mapeados: [Z] ⚠️
+
+---
+*Requisitos definidos: [data]*
+*Última atualização: [data] após [gatilho]*
+```
+
+</template>
+
+<guidelines>
+
+**Formato de Requisito:**
+- ID: `[CATEGORIA]-[NÚMERO]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- Descrição: Centrada no usuário, testável, atômica
+- Checkbox: Apenas para requisitos v1 (v2 ainda não são acionáveis)
+
+**Categorias:**
+- Derivar das categorias FEATURES.md da pesquisa
+- Manter consistente com convenções do domínio
+- Típicas: Autenticação, Conteúdo, Social, Notificações, Moderação, Pagamentos, Admin
+
+**v1 vs v2:**
+- v1: Escopo comprometido, estará nas fases do roadmap
+- v2: Reconhecido mas diferido, não no roadmap atual
+- Mover v2 → v1 requer atualização do roadmap
+
+**Fora do Escopo:**
+- Exclusões explícitas com raciocínio
+- Evita "por que você não incluiu X?" depois
+- Anti-funcionalidades da pesquisa pertencem aqui com alertas
+
+**Rastreabilidade:**
+- Vazio inicialmente, preenchido durante a criação do roadmap
+- Cada requisito mapeia para exatamente uma fase
+- Requisitos não mapeados = lacuna no roadmap
+
+**Valores de Status:**
+- Pending: Não iniciado
+- In Progress: Fase está ativa
+- Complete: Requisito verificado
+- Blocked: Aguardando fator externo
+
+</guidelines>
+
+<evolution>
+
+**Após cada fase ser concluída:**
+1. Marcar requisitos cobertos como Complete
+2. Atualizar status de rastreabilidade
+3. Anotar quaisquer requisitos que mudaram de escopo
+
+**Após atualizações do roadmap:**
+1. Verificar se todos os requisitos v1 ainda estão mapeados
+2. Adicionar novos requisitos se o escopo expandiu
+3. Mover requisitos para v2/fora do escopo se foram descartados
+
+**Critérios de conclusão de requisito:**
+- Requisito está "Complete" quando:
+  - Funcionalidade está implementada
+  - Funcionalidade está verificada (testes passam, verificação manual feita)
+  - Funcionalidade está comitada
+
+</evolution>
+
+<example>
+
+```markdown
+# Requisitos: CommunityApp
+
+**Definidos:** 2025-01-14
+**Valor Central:** Usuários podem compartilhar e discutir conteúdo com pessoas que compartilham seus interesses
+
+## Requisitos v1
+
+### Autenticação
+
+- [ ] **AUTH-01**: Usuário pode se cadastrar com email e senha
+- [ ] **AUTH-02**: Usuário recebe verificação por email após o cadastro
+- [ ] **AUTH-03**: Usuário pode redefinir senha via link por email
+- [ ] **AUTH-04**: Sessão do usuário persiste após atualização do navegador
+
+### Perfis
+
+- [ ] **PROF-01**: Usuário pode criar perfil com nome de exibição
+- [ ] **PROF-02**: Usuário pode fazer upload de foto de avatar
+- [ ] **PROF-03**: Usuário pode escrever bio (máx 500 chars)
+- [ ] **PROF-04**: Usuário pode visualizar perfis de outros usuários
+
+### Conteúdo
+
+- [ ] **CONT-01**: Usuário pode criar post de texto
+- [ ] **CONT-02**: Usuário pode fazer upload de imagem com post
+- [ ] **CONT-03**: Usuário pode editar próprios posts
+- [ ] **CONT-04**: Usuário pode deletar próprios posts
+- [ ] **CONT-05**: Usuário pode visualizar feed de posts
+
+### Social
+
+- [ ] **SOCL-01**: Usuário pode seguir outros usuários
+- [ ] **SOCL-02**: Usuário pode deixar de seguir usuários
+- [ ] **SOCL-03**: Usuário pode curtir posts
+- [ ] **SOCL-04**: Usuário pode comentar em posts
+- [ ] **SOCL-05**: Usuário pode visualizar feed de atividades (posts de usuários seguidos)
+
+## Requisitos v2
+
+### Notificações
+
+- **NOTF-01**: Usuário recebe notificações no app
+- **NOTF-02**: Usuário recebe email para novos seguidores
+- **NOTF-03**: Usuário recebe email para comentários em seus posts
+- **NOTF-04**: Usuário pode configurar preferências de notificação
+
+### Moderação
+
+- **MODR-01**: Usuário pode denunciar conteúdo
+- **MODR-02**: Usuário pode bloquear outros usuários
+- **MODR-03**: Admin pode visualizar conteúdo denunciado
+- **MODR-04**: Admin pode remover conteúdo
+- **MODR-05**: Admin pode banir usuários
+
+## Fora do Escopo
+
+| Funcionalidade | Motivo |
+|----------------|--------|
+| Chat em tempo real | Alta complexidade, não é central para o valor da comunidade |
+| Posts em vídeo | Custos de armazenamento/banda, diferir para v2+ |
+| Login OAuth | Email/senha suficiente para v1 |
+| App mobile | Web primeiro, mobile depois |
+
+## Rastreabilidade
+
+| Requisito | Fase | Status |
+|-----------|------|--------|
+| AUTH-01 | Fase 1 | Pending |
+| AUTH-02 | Fase 1 | Pending |
+| AUTH-03 | Fase 1 | Pending |
+| AUTH-04 | Fase 1 | Pending |
+| PROF-01 | Fase 2 | Pending |
+| PROF-02 | Fase 2 | Pending |
+| PROF-03 | Fase 2 | Pending |
+| PROF-04 | Fase 2 | Pending |
+| CONT-01 | Fase 3 | Pending |
+| CONT-02 | Fase 3 | Pending |
+| CONT-03 | Fase 3 | Pending |
+| CONT-04 | Fase 3 | Pending |
+| CONT-05 | Fase 3 | Pending |
+| SOCL-01 | Fase 4 | Pending |
+| SOCL-02 | Fase 4 | Pending |
+| SOCL-03 | Fase 4 | Pending |
+| SOCL-04 | Fase 4 | Pending |
+| SOCL-05 | Fase 4 | Pending |
+
+**Cobertura:**
+- Requisitos v1: 18 total
+- Mapeados para fases: 18
+- Não mapeados: 0 ✓
+
+---
+*Requisitos definidos: 2025-01-14*
+*Última atualização: 2025-01-14 após definição inicial*
+```
+
+</example>