@luanpdd/kit-mcp 0.2.1 → 0.4.0

package/kit/framework/templates/roadmap.md

@@ -0,0 +1,202 @@
+# Template de Roadmap
+
+Template para `.planning/ROADMAP.md`.
+
+## Roadmap Inicial (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Nome do Projeto]
+
+## Visão Geral
+
+[Um parágrafo descrevendo a jornada do início ao fim]
+
+## Fases
+
+**Numeração de Fases:**
+- Fases inteiras (1, 2, 3): Trabalho planejado do milestone
+- Fases decimais (2.1, 2.2): Inserções urgentes (marcadas com INSERIDA)
+
+Fases decimais aparecem entre seus inteiros vizinhos em ordem numérica.
+
+- [ ] **Fase 1: [Nome]** - [Descrição em uma linha]
+- [ ] **Fase 2: [Nome]** - [Descrição em uma linha]
+- [ ] **Fase 3: [Nome]** - [Descrição em uma linha]
+- [ ] **Fase 4: [Nome]** - [Descrição em uma linha]
+
+## Detalhes das Fases
+
+### Fase 1: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Depende de**: Nada (primeira fase)
+**Requisitos**: [REQ-01, REQ-02, REQ-03]  <!-- colchetes opcionais, o parser lida com ambos os formatos -->
+**Critérios de Sucesso** (o que deve ser VERDADEIRO):
+  1. [Comportamento observável da perspectiva do usuário]
+  2. [Comportamento observável da perspectiva do usuário]
+  3. [Comportamento observável da perspectiva do usuário]
+**Planos**: [Número de planos, ex.: "3 planos" ou "A definir"]
+
+Planos:
+- [ ] 01-01: [Breve descrição do primeiro plano]
+- [ ] 01-02: [Breve descrição do segundo plano]
+- [ ] 01-03: [Breve descrição do terceiro plano]
+
+### Fase 2: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Depende de**: Fase 1
+**Requisitos**: [REQ-04, REQ-05]
+**Critérios de Sucesso** (o que deve ser VERDADEIRO):
+  1. [Comportamento observável da perspectiva do usuário]
+  2. [Comportamento observável da perspectiva do usuário]
+**Planos**: [Número de planos]
+
+Planos:
+- [ ] 02-01: [Breve descrição]
+- [ ] 02-02: [Breve descrição]
+
+### Fase 2.1: Correção Crítica (INSERIDA)
+**Objetivo**: [Trabalho urgente inserido entre fases]
+**Depende de**: Fase 2
+**Critérios de Sucesso** (o que deve ser VERDADEIRO):
+  1. [O que a correção alcança]
+**Planos**: 1 plano
+
+Planos:
+- [ ] 02.1-01: [Descrição]
+
+### Fase 3: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Depende de**: Fase 2
+**Requisitos**: [REQ-06, REQ-07, REQ-08]
+**Critérios de Sucesso** (o que deve ser VERDADEIRO):
+  1. [Comportamento observável da perspectiva do usuário]
+  2. [Comportamento observável da perspectiva do usuário]
+  3. [Comportamento observável da perspectiva do usuário]
+**Planos**: [Número de planos]
+
+Planos:
+- [ ] 03-01: [Breve descrição]
+- [ ] 03-02: [Breve descrição]
+
+### Fase 4: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Depende de**: Fase 3
+**Requisitos**: [REQ-09, REQ-10]
+**Critérios de Sucesso** (o que deve ser VERDADEIRO):
+  1. [Comportamento observável da perspectiva do usuário]
+  2. [Comportamento observável da perspectiva do usuário]
+**Planos**: [Número de planos]
+
+Planos:
+- [ ] 04-01: [Breve descrição]
+
+## Progresso
+
+**Ordem de Execução:**
+As fases executam em ordem numérica: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Fase | Planos Completos | Status | Concluída |
+|------|------------------|--------|-----------|
+| 1. [Nome] | 0/3 | Não iniciada | - |
+| 2. [Nome] | 0/2 | Não iniciada | - |
+| 3. [Nome] | 0/2 | Não iniciada | - |
+| 4. [Nome] | 0/1 | Não iniciada | - |
+```
+
+<guidelines>
+**Planejamento inicial (v1.0):**
+- A contagem de fases depende da configuração de granularidade (grosseiro: 3-5, padrão: 5-8, fino: 8-12)
+- Cada fase entrega algo coerente
+- Fases podem ter 1+ planos (dividir se >3 tarefas ou múltiplos subsistemas)
+- Planos usam nomenclatura: {phase}-{plan}-PLAN.md (ex.: 01-02-PLAN.md)
+- Sem estimativas de tempo (isso não é PM enterprise)
+- Tabela de progresso atualizada pelo workflow de execução
+- Contagem de planos pode ser "A definir" inicialmente, refinada durante o planejamento
+
+**Critérios de sucesso:**
+- 2-5 comportamentos observáveis por fase (da perspectiva do usuário)
+- Verificados contra requisitos durante a criação do roadmap
+- Fluem para `must_haves` no plan-phase
+- Verificados pelo verify-phase após a execução
+- Formato: "Usuário pode [ação]" ou "[Coisa] funciona/existe"
+
+**Após milestones serem entregues:**
+- Colapsar milestones completos em tags `<details>`
+- Adicionar novas seções de milestone para trabalho futuro
+- Manter numeração contínua de fases (nunca reiniciar em 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Não iniciada
+- `In progress` - Em andamento
+- `Complete` - Concluída (adicionar data de conclusão)
+- `Deferred` - Diferida (com motivo)
+</status_values>
+
+## Roadmap Agrupado por Milestone (Após o v1.0 Ser Entregue)
+
+Após completar o primeiro milestone, reorganizar com agrupamentos de milestone:
+
+```markdown
+# Roadmap: [Nome do Projeto]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Fases 1-4 (entregue YYYY-MM-DD)
+- 🚧 **v1.1 [Nome]** - Fases 5-6 (em andamento)
+- 📋 **v2.0 [Nome]** - Fases 7-10 (planejado)
+
+## Fases
+
+<details>
+<summary>✅ v1.0 MVP (Fases 1-4) - ENTREGUE YYYY-MM-DD</summary>
+
+### Fase 1: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Planos**: 3 planos
+
+Planos:
+- [x] 01-01: [Breve descrição]
+- [x] 01-02: [Breve descrição]
+- [x] 01-03: [Breve descrição]
+
+[... fases restantes do v1.0 ...]
+
+</details>
+
+### 🚧 v1.1 [Nome] (Em Andamento)
+
+**Objetivo do Milestone:** [O que o v1.1 entrega]
+
+#### Fase 5: [Nome]
+**Objetivo**: [O que esta fase entrega]
+**Depende de**: Fase 4
+**Planos**: 2 planos
+
+Planos:
+- [ ] 05-01: [Breve descrição]
+- [ ] 05-02: [Breve descrição]
+
+[... fases restantes do v1.1 ...]
+
+### 📋 v2.0 [Nome] (Planejado)
+
+**Objetivo do Milestone:** [O que o v2.0 entrega]
+
+[... fases do v2.0 ...]
+
+## Progresso
+
+| Fase | Milestone | Planos Completos | Status | Concluída |
+|------|-----------|------------------|--------|-----------|
+| 1. Fundação | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Funcionalidades | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Segurança | v1.1 | 0/2 | Not started | - |
+```
+
+**Notas:**
+- Emoji de milestone: ✅ entregue, 🚧 em andamento, 📋 planejado
+- Milestones completos colapsados em `<details>` para legibilidade
+- Milestones atuais/futuros expandidos
+- Numeração contínua de fases (01-99)
+- Tabela de progresso inclui coluna de milestone

package/kit/framework/templates/state.md

@@ -0,0 +1,176 @@
+# Template de State
+
+Template para `.planning/STATE.md` — a memória viva do projeto.
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Estado do Projeto
+
+## Referência do Projeto
+
+Ver: .planning/PROJECT.md (atualizado em [data])
+
+**Valor central:** [Uma linha da seção Core Value do PROJECT.md]
+**Foco atual:** [Nome da fase atual]
+
+## Posição Atual
+
+Fase: [X] de [Y] ([Nome da fase])
+Plano: [A] de [B] na fase atual
+Status: [Pronto para planejar / Planejando / Pronto para executar / Em andamento / Fase concluída]
+Última atividade: [AAAA-MM-DD] — [O que aconteceu]
+
+Progresso: [░░░░░░░░░░] 0%
+
+## Métricas de Performance
+
+**Velocidade:**
+- Total de planos concluídos: [N]
+- Duração média: [X] min
+- Tempo total de execução: [X.X] horas
+
+**Por Fase:**
+
+| Fase | Planos | Total | Média/Plano |
+|------|--------|-------|-------------|
+| - | - | - | - |
+
+**Tendência Recente:**
+- Últimos 5 planos: [durações]
+- Tendência: [Melhorando / Estável / Degradando]
+
+*Atualizado após cada conclusão de plano*
+
+## Contexto Acumulado
+
+### Decisões
+
+Decisões estão registradas na tabela de Decisões Chave do PROJECT.md.
+Decisões recentes que afetam o trabalho atual:
+
+- [Fase X]: [Resumo da decisão]
+- [Fase Y]: [Resumo da decisão]
+
+### Todos Pendentes
+
+[De .planning/todos/pending/ — ideias capturadas durante as sessões]
+
+Nenhum ainda.
+
+### Bloqueios/Preocupações
+
+[Problemas que afetam trabalho futuro]
+
+Nenhum ainda.
+
+## Continuidade de Sessão
+
+Última sessão: [AAAA-MM-DD HH:MM]
+Parou em: [Descrição da última ação concluída]
+Arquivo de retomada: [Caminho para .continue-here*.md se existir, caso contrário "Nenhum"]
+```
+
+<purpose>
+
+STATE.md é a memória de curto prazo do projeto abrangendo todas as fases e sessões.
+
+**Problema que resolve:** Informações são capturadas em summaries, issues e decisões, mas não são consumidas sistematicamente. Sessões começam sem contexto.
+
+**Solução:** Um arquivo único e pequeno que:
+- É lido primeiro em todo workflow
+- É atualizado após toda ação significativa
+- Contém um digest do contexto acumulado
+- Permite restauração instantânea de sessão
+
+</purpose>
+
+<lifecycle>
+
+**Criação:** Após ROADMAP.md ser criado (durante o init)
+- Referenciar PROJECT.md (lê-lo para o contexto atual)
+- Inicializar seções de contexto acumulado vazias
+- Definir posição como "Fase 1 pronta para planejar"
+
+**Leitura:** Primeiro passo de todo workflow
+- progress: Apresentar status ao usuário
+- plan: Informar decisões de planejamento
+- execute: Saber a posição atual
+- transition: Saber o que está completo
+
+**Escrita:** Após toda ação significativa
+- execute: Após SUMMARY.md ser criado
+  - Atualizar posição (fase, plano, status)
+  - Notar novas decisões (detalhar no PROJECT.md)
+  - Adicionar bloqueios/preocupações
+- transition: Após fase marcada como completa
+  - Atualizar barra de progresso
+  - Limpar bloqueios resolvidos
+  - Atualizar data de referência do Projeto
+
+</lifecycle>
+
+<sections>
+
+### Referência do Projeto
+Aponta para PROJECT.md para contexto completo. Inclui:
+- Valor central (o UMA coisa que importa)
+- Foco atual (qual fase)
+- Data da última atualização (aciona re-leitura se desatualizada)
+
+Claude lê PROJECT.md diretamente para requisitos, restrições e decisões.
+
+### Posição Atual
+Onde estamos agora:
+- Fase X de Y — qual fase
+- Plano A de B — qual plano dentro da fase
+- Status — estado atual
+- Última atividade — o que aconteceu mais recentemente
+- Barra de progresso — indicador visual da conclusão geral
+
+Cálculo do progresso: (planos concluídos) / (total de planos em todas as fases) × 100%
+
+### Métricas de Performance
+Rastrear velocidade para entender padrões de execução:
+- Total de planos concluídos
+- Duração média por plano
+- Divisão por fase
+- Tendência recente (melhorando/estável/degradando)
+
+Atualizado após cada conclusão de plano.
+
+### Contexto Acumulado
+
+**Decisões:** Referência à tabela de Decisões Chave do PROJECT.md, mais resumo de decisões recentes para acesso rápido. Log completo de decisões fica no PROJECT.md.
+
+**Todos Pendentes:** Ideias capturadas via /add-todo
+- Contagem de todos pendentes
+- Referência a .planning/todos/pending/
+- Lista breve se poucos, contagem se muitos (ex.: "5 todos pendentes — ver /check-todos")
+
+**Bloqueios/Preocupações:** Das seções "Prontidão para Próxima Fase"
+- Problemas que afetam trabalho futuro
+- Prefixo com fase de origem
+- Limpos quando endereçados
+
+### Continuidade de Sessão
+Permite retomada instantânea:
+- Quando foi a última sessão
+- O que foi concluído por último
+- Há algum arquivo .continue-here para retomar
+
+</sections>
+
+<size_constraint>
+
+Manter STATE.md abaixo de 100 linhas.
+
+É um DIGEST, não um arquivo. Se o contexto acumulado crescer demais:
+- Manter apenas 3-5 decisões recentes no resumo (log completo no PROJECT.md)
+- Manter apenas bloqueios ativos, remover os resolvidos
+
+O objetivo é "ler uma vez, saber onde estamos" — se for muito longo, isso falha.
+
+</size_constraint>

package/kit/framework/templates/summary-complex.md

@@ -0,0 +1,59 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [categoria primária]
+tags: [tech pesquisável]
+requires:
+  - phase: [fase anterior]
+    provides: [o que aquela fase construiu]
+provides:
+  - [lista de o que foi construído/entregue]
+affects: [lista de nomes de fases ou palavras-chave]
+tech-stack:
+  added: [bibliotecas/ferramentas]
+  patterns: [padrões arquiteturais/de código]
+key-files:
+  created: [arquivos importantes criados]
+  modified: [arquivos importantes modificados]
+key-decisions:
+  - "Decisão 1"
+patterns-established:
+  - "Padrão 1: descrição"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Fase [X]: [Nome] — Resumo (Complexo)
+
+**[Uma linha substantiva descrevendo o resultado]**
+
+## Performance
+- **Duração:** [tempo]
+- **Tarefas:** [contagem concluída]
+- **Arquivos modificados:** [contagem]
+
+## Realizações
+- [Resultado chave 1]
+- [Resultado chave 2]
+
+## Commits das Tarefas
+1. **Tarefa 1: [nome da tarefa]** - `hash`
+2. **Tarefa 2: [nome da tarefa]** - `hash`
+3. **Tarefa 3: [nome da tarefa]** - `hash`
+
+## 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]
+
+## Desvios do Plano (Corrigidos Automaticamente)
+[Registros detalhados de correção automática conforme regras de desvio framework]
+
+## Problemas Encontrados
+[Problemas durante o trabalho planejado e resoluções]
+
+## Prontidão para Próxima Fase
+[O que está pronto para a próxima fase]
+[Bloqueios ou preocupações]

package/kit/framework/templates/summary-minimal.md

@@ -0,0 +1,41 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [categoria primária]
+tags: [tech pesquisável]
+provides:
+  - [lista de o que foi construído/entregue]
+affects: [lista de nomes de fases ou palavras-chave]
+tech-stack:
+  added: [bibliotecas/ferramentas]
+  patterns: [padrões arquiteturais/de código]
+key-files:
+  created: [arquivos importantes criados]
+  modified: [arquivos importantes modificados]
+key-decisions: []
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Fase [X]: [Nome] — Resumo (Mínimo)
+
+**[Uma linha substantiva descrevendo o resultado]**
+
+## Performance
+- **Duração:** [tempo]
+- **Tarefas:** [contagem]
+- **Arquivos modificados:** [contagem]
+
+## Realizações
+- [Resultado mais importante]
+- [Segunda conquista chave]
+
+## Commits das Tarefas
+1. **Tarefa 1: [nome da tarefa]** - `hash`
+2. **Tarefa 2: [nome da tarefa]** - `hash`
+
+## Arquivos Criados/Modificados
+- `path/to/file.ts` - O que faz
+
+## Prontidão para Próxima Fase
+[Pronto para próxima fase]

package/kit/framework/templates/summary-standard.md

@@ -0,0 +1,48 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [categoria primária]
+tags: [tech pesquisável]
+provides:
+  - [lista de o que foi construído/entregue]
+affects: [lista de nomes de fases ou palavras-chave]
+tech-stack:
+  added: [bibliotecas/ferramentas]
+  patterns: [padrões arquiteturais/de código]
+key-files:
+  created: [arquivos importantes criados]
+  modified: [arquivos importantes modificados]
+key-decisions:
+  - "Decisão 1"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Fase [X]: [Nome] — Resumo
+
+**[Uma linha substantiva descrevendo o resultado]**
+
+## Performance
+- **Duração:** [tempo]
+- **Tarefas:** [contagem concluída]
+- **Arquivos modificados:** [contagem]
+
+## Realizações
+- [Resultado chave 1]
+- [Resultado chave 2]
+
+## Commits das Tarefas
+1. **Tarefa 1: [nome da tarefa]** - `hash`
+2. **Tarefa 2: [nome da tarefa]** - `hash`
+3. **Tarefa 3: [nome da tarefa]** - `hash`
+
+## Arquivos Criados/Modificados
+- `path/to/file.ts` - O que faz
+- `path/to/another.ts` - O que faz
+
+## Decisões e Desvios
+[Decisões chave ou "Nenhuma — plano seguido como especificado"]
+[Desvios menores se houver, ou "Nenhum"]
+
+## Prontidão para Próxima Fase
+[O que está pronto para a próxima fase]