@luanpdd/kit-mcp 0.2.1 → 0.4.0

package/kit/framework/references/continuation-format.md

@@ -0,0 +1,249 @@
+# Formato de Continuação
+
+Formato padrão para apresentar os próximos passos após concluir um comando ou workflow.
+
+## Estrutura Principal
+
+```
+---
+
+## ▶ Próximo Passo
+
+**{identificador}: {nome}** — {descrição em uma linha}
+
+`{comando para copiar-colar}`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+
+**Também disponível:**
+- `{opção alternativa 1}` — descrição
+- `{opção alternativa 2}` — descrição
+
+---
+```
+
+## Regras de Formato
+
+1. **Sempre mostre o que é** — nome + descrição, nunca apenas um caminho de comando
+2. **Extraia contexto da fonte** — ROADMAP.md para fases, `<objective>` do PLAN.md para planos
+3. **Comando em código inline** — crases, fácil de copiar-colar, renderiza como link clicável
+4. **Explicação do `/clear`** — sempre inclua, mantém conciso mas explica o porquê
+5. **"Também disponível" não "Outras opções"** — soa mais como um app
+6. **Separadores visuais** — `---` acima e abaixo para se destacar
+
+## Variantes
+
+### Executar Próximo Plano
+
+```
+---
+
+## ▶ Próximo Passo
+
+**02-03: Rotação de Token Refresh** — Adicionar /api/auth/refresh com expiração deslizante
+
+`/executar-fase 2`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+
+**Também disponível:**
+- Revisar plano antes de executar
+- `/listar-hipoteses-fase 2` — verificar hipóteses
+
+---
+```
+
+### Executar Último Plano da Fase
+
+Adicione nota informando que este é o último plano e o que vem a seguir:
+
+```
+---
+
+## ▶ Próximo Passo
+
+**02-03: Rotação de Token Refresh** — Adicionar /api/auth/refresh com expiração deslizante
+<sub>Último plano da Fase 2</sub>
+
+`/executar-fase 2`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+
+**Após a conclusão:**
+- Transição da Fase 2 → Fase 3
+- Próximo: **Fase 3: Funcionalidades Principais** — Dashboard do usuário e configurações
+
+---
+```
+
+### Planejar uma Fase
+
+```
+---
+
+## ▶ Próximo Passo
+
+**Fase 2: Autenticação** — Fluxo de login JWT com tokens de refresh
+
+`/planejar-fase 2`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+
+**Também disponível:**
+- `/discutir-fase 2` — coletar contexto primeiro
+- `/pesquisar-fase 2` — investigar incógnitas
+- Revisar roadmap
+
+---
+```
+
+### Fase Concluída, Pronto para Próxima
+
+Mostre o status de conclusão antes da próxima ação:
+
+```
+---
+
+## ✓ Fase 2 Concluída
+
+3/3 planos executados
+
+## ▶ Próximo Passo
+
+**Fase 3: Funcionalidades Principais** — Dashboard do usuário, configurações e exportação de dados
+
+`/planejar-fase 3`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+
+**Também disponível:**
+- `/discutir-fase 3` — coletar contexto primeiro
+- `/pesquisar-fase 3` — investigar incógnitas
+- Revisar o que a Fase 2 construiu
+
+---
+```
+
+### Múltiplas Opções Iguais
+
+Quando não há uma ação primária clara:
+
+```
+---
+
+## ▶ Próximo Passo
+
+**Fase 3: Funcionalidades Principais** — Dashboard do usuário, configurações e exportação de dados
+
+**Para planejar diretamente:** `/planejar-fase 3`
+
+**Para discutir o contexto primeiro:** `/discutir-fase 3`
+
+**Para pesquisar incógnitas:** `/pesquisar-fase 3`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+```
+
+### Marco Concluído
+
+```
+---
+
+## 🎉 Marco v1.0 Concluído
+
+Todas as 4 fases lançadas
+
+## ▶ Próximo Passo
+
+**Iniciar v1.1** — questionamento → pesquisa → requisitos → roadmap
+
+`/novo-marco`
+
+<sub>`/clear` primeiro → contexto limpo</sub>
+
+---
+```
+
+## Extraindo Contexto
+
+### Para fases (do ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extraia: `**Fase 2: Autenticação** — Fluxo de login JWT com tokens de refresh`
+
+### Para planos (do ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Ou do `<objective>` do PLAN.md:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extraia: `**02-03: Rotação de Token Refresh** — Adicionar /api/auth/refresh com expiração deslizante`
+
+## Anti-Padrões
+
+### Não: Apenas o comando (sem contexto)
+
+```
+## Para Continuar
+
+Execute `/clear`, depois cole:
+/executar-fase 2
+```
+
+O usuário não tem ideia do que é o 02-03.
+
+### Não: Explicação do /clear ausente
+
+```
+`/planejar-fase 3`
+
+Execute /clear primeiro.
+```
+
+Não explica o porquê. O usuário pode pular.
+
+### Não: Linguagem "Outras opções"
+
+```
+Outras opções:
+- Revisar roadmap
+```
+
+Parece algo secundário. Use "Também disponível:" em vez disso.
+
+### Não: Blocos de código cercado para comandos
+
+```
+```
+/planejar-fase 3
+```
+```
+
+Blocos cercados dentro de templates criam ambiguidade de aninhamento. Use crases inline em vez disso.

package/kit/framework/references/decimal-phase-calculation.md

@@ -0,0 +1,64 @@
+# Cálculo de Fase Decimal
+
+Calcule o próximo número de fase decimal para inserções urgentes.
+
+## Usando tools
+
+```bash
+# Obter a próxima fase decimal após a fase 6
+node "./.claude/framework/bin/tools.cjs" phase next-decimal 6
+```
+
+Saída:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+Com decimais existentes:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extrair Valores
+
+```bash
+DECIMAL_PHASE=$(node "./.claude/framework/bin/tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(node "./.claude/framework/bin/tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick base_phase)
+```
+
+Ou com o flag --raw:
+```bash
+DECIMAL_PHASE=$(node "./.claude/framework/bin/tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+# Retorna apenas: 06.1
+```
+
+## Exemplos
+
+| Fases Existentes | Próxima Fase |
+|------------------|--------------|
+| 06 apenas | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (lacuna) | 06.4 |
+
+## Nomenclatura de Diretório
+
+Diretórios de fase decimal usam o número decimal completo:
+
+```bash
+SLUG=$(node "./.claude/framework/bin/tools.cjs" generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Exemplo: `.planning/phases/06.1-corrigir-bug-critico-auth/`

package/kit/framework/references/git-integration.md

@@ -0,0 +1,295 @@
+<overview>
+Integração git para o framework.
+</overview>
+
+<core_principle>
+
+**Commite resultados, não processos.**
+
+O log git deve parecer um changelog do que foi lançado, não um diário de atividade de planejamento.
+</core_principle>
+
+<commit_points>
+
+| Evento                        | Commitar? | Por quê                                            |
+| ----------------------------- | --------- | -------------------------------------------------- |
+| BRIEF + ROADMAP criados       | SIM       | Inicialização do projeto                           |
+| PLAN.md criado                | NÃO       | Intermediário — commitar com conclusão do plano    |
+| RESEARCH.md criado            | NÃO       | Intermediário                                      |
+| DISCOVERY.md criado           | NÃO       | Intermediário                                      |
+| **Tarefa concluída**          | SIM       | Unidade atômica de trabalho (1 commit por tarefa)  |
+| **Plano concluído**           | SIM       | Commit de metadados (SUMMARY + STATE + ROADMAP)    |
+| Handoff criado                | SIM       | Estado WIP preservado                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+Se NO_GIT: Execute `git init` silenciosamente. Projetos framework sempre têm seu próprio repositório.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Inicialização do Projeto (brief + roadmap juntos)
+
+```
+docs: initialize [nome-do-projeto] ([N] phases)
+
+[Linha única do PROJECT.md]
+
+Phases:
+1. [nome-da-fase]: [objetivo]
+2. [nome-da-fase]: [objetivo]
+3. [nome-da-fase]: [objetivo]
+```
+
+O que commitar:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs: initialize [nome-do-projeto] ([N] phases)" --files .planning/
+```
+
+</format>
+
+<format name="task-completion">
+## Conclusão de Tarefa (Durante Execução do Plano)
+
+Cada tarefa recebe seu próprio commit imediatamente após a conclusão.
+
+> **Agentes paralelos:** Quando executando como executor paralelo (spawnado por execute-phase),
+> use `--no-verify` em todos os commits para evitar contenção de bloqueio de hooks pré-commit.
+> O orquestrador valida os hooks uma vez após todos os agentes concluírem.
+
+```
+{tipo}({fase}-{plano}): {nome-da-tarefa}
+
+- [Alteração chave 1]
+- [Alteração chave 2]
+- [Alteração chave 3]
+```
+
+**Tipos de commit:**
+- `feat` - Nova funcionalidade/recurso
+- `fix` - Correção de bug
+- `test` - Apenas testes (fase TDD VERMELHO)
+- `refactor` - Limpeza de código (fase TDD REFATORAR)
+- `perf` - Melhoria de desempenho
+- `chore` - Dependências, configuração, ferramental
+
+**Exemplos:**
+
+```bash
+# Tarefa padrão
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# Tarefa TDD - fase VERMELHO
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# Tarefa TDD - fase VERDE
+git add src/utils/jwt.ts
+git commit -m "feat(07-02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## Conclusão do Plano (Após Todas as Tarefas Concluídas)
+
+Após todas as tarefas commitadas, um commit final de metadados captura a conclusão do plano.
+
+```
+docs({fase}-{plano}): complete [nome-do-plano] plan
+
+Tasks completed: [N]/[N]
+- [Nome da Tarefa 1]
+- [Nome da Tarefa 2]
+- [Nome da Tarefa 3]
+
+SUMMARY: .planning/phases/XX-nome/{fase}-{plano}-SUMMARY.md
+```
+
+O que commitar:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs({fase}-{plano}): complete [nome-do-plano] plan" --files .planning/phases/XX-nome/{fase}-{plano}-PLAN.md .planning/phases/XX-nome/{fase}-{plano}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+```
+
+**Nota:** Arquivos de código NÃO incluídos — já commitados por tarefa.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [nome-da-fase] paused at task [X]/[Y]
+
+Current: [nome da tarefa]
+[Se bloqueado:] Blocked: [motivo]
+```
+
+O que commitar:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "wip: [nome-da-fase] paused at task [X]/[Y]" --files .planning/
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Abordagem antiga (commits por plano):**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 phases)
+```
+
+**Nova abordagem (commits por tarefa):**
+```
+# Fase 04 - Checkout
+1a2b3c docs(04-01): complete checkout flow plan
+4d5e6f feat(04-01): add webhook signature verification
+7g8h9i feat(04-01): implement payment session creation
+0j1k2l feat(04-01): create checkout page component
+
+# Fase 03 - Products
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Fase 02 - Auth
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+4h5i6j docs(02-01): complete JWT setup plan
+7k8l9m feat(02-01): add JWT generation and validation
+0n1o2p chore(02-01): install jose library
+
+# Fase 01 - Foundation
+3q4r5s docs(01-01): complete scaffold plan
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Inicialização
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+Cada plano produz 2-4 commits (tarefas + metadados). Claro, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Ainda não commitar (artefatos intermediários):**
+- Criação do PLAN.md (commitar com conclusão do plano)
+- RESEARCH.md (intermediário)
+- DISCOVERY.md (intermediário)
+- Ajustes menores de planejamento
+- "Corrigi typo no roadmap"
+
+**Commitar (resultados):**
+- Cada conclusão de tarefa (feat/fix/test/refactor)
+- Metadados de conclusão de plano (docs)
+- Inicialização do projeto (docs)
+
+**Princípio chave:** Commite código funcionando e resultados lançados, não processo de planejamento.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Por Que Commits Por Tarefa?
+
+**Engenharia de contexto para IA:**
+- O histórico git torna-se a fonte primária de contexto para sessões futuras do Claude
+- `git log --grep="{fase}-{plano}"` mostra todo o trabalho de um plano
+- `git diff <hash>^..<hash>` mostra as alterações exatas por tarefa
+- Menos dependência de análise do SUMMARY.md = mais contexto para o trabalho real
+
+**Recuperação de falha:**
+- Tarefa 1 commitada ✅, Tarefa 2 falhou ❌
+- Claude na próxima sessão: vê tarefa 1 concluída, pode tentar novamente a tarefa 2
+- Pode `git reset --hard` para a última tarefa bem-sucedida
+
+**Debugging:**
+- `git bisect` encontra a tarefa exata falhando, não apenas o plano falhando
+- `git blame` rastreia a linha até o contexto específico da tarefa
+- Cada commit é revertível independentemente
+
+**Observabilidade:**
+- Workflow de desenvolvedor solo + Claude se beneficia de atribuição granular
+- Commits atômicos são boas práticas de git
+- "Ruído de commit" irrelevante quando o consumidor é o Claude, não humanos
+
+</commit_strategy_rationale>
+
+<sub_repos_support>
+
+## Suporte a Workspace Multi-Repositório (sub_repos)
+
+Para workspaces com repositórios git separados (ex: `backend/`, `frontend/`, `shared/`), o framework roteia commits para cada repositório independentemente.
+
+### Configuração
+
+Em `.planning/config.json`, liste os diretórios de sub-repositório em `planning.sub_repos`:
+
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "sub_repos": ["backend", "frontend", "shared"]
+  }
+}
+```
+
+Defina `commit_docs: false` para que os docs de planejamento permaneçam locais e não sejam commitados em nenhum sub-repositório.
+
+### Como Funciona
+
+1. **Auto-detecção:** Durante `/novo-projeto`, diretórios com sua própria pasta `.git` são detectados e oferecidos para seleção como sub-repositórios. Em execuções subsequentes, `loadConfig` sincroniza automaticamente a lista `sub_repos` com o sistema de arquivos — adicionando repositórios recém-criados e removendo os deletados. Isso significa que `config.json` pode ser reescrito automaticamente quando os repositórios mudam no disco.
+2. **Agrupamento de arquivos:** Arquivos de código são agrupados pelo prefixo do sub-repositório (ex: `backend/src/api/users.ts` pertence ao repositório `backend/`).
+3. **Commits independentes:** Cada sub-repositório recebe seu próprio commit atômico via `tools.cjs commit-to-subrepo`. Os caminhos de arquivo são tornados relativos à raiz do sub-repositório antes do staging.
+4. **Planejamento permanece local:** O diretório `.planning/` não é commitado; ele age como coordenação entre repositórios.
+
+### Roteamento de Commit
+
+Em vez do comando `commit` padrão, use `commit-to-subrepo` quando `sub_repos` estiver configurado:
+
+```bash
+node ./.claude/framework/bin/tools.cjs commit-to-subrepo "feat(02-01): add user API" \
+  --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
+```
+
+Isso faz staging de `src/api/users.ts` e `src/types/user.ts` no repositório `backend/`, e `src/components/UserForm.tsx` no repositório `frontend/`, commitando cada um independentemente com a mesma mensagem.
+
+Arquivos que não correspondem a nenhum sub-repositório configurado são reportados como sem correspondência.
+
+</sub_repos_support>

package/kit/framework/references/git-planning-commit.md

@@ -0,0 +1,38 @@
+# Commit de Planejamento Git
+
+Commite artefatos de planejamento usando o CLI tools, que verifica automaticamente a configuração `commit_docs` e o status do gitignore.
+
+## Commit via CLI
+
+Sempre use `tools.cjs commit` para arquivos `.planning/` — ele trata `commit_docs` e verificações do gitignore automaticamente:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs({scope}): {descrição}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+O CLI retornará `skipped` (com motivo) se `commit_docs` for `false` ou `.planning/` estiver no gitignore. Não são necessárias verificações condicionais manuais.
+
+## Emenda do Commit Anterior
+
+Para incorporar alterações de arquivos `.planning/` no commit anterior:
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "" --files .planning/codebase/*.md --amend
+```
+
+## Padrões de Mensagem de Commit
+
+| Comando | Escopo | Exemplo |
+|---------|--------|---------|
+| planejar-fase | fase | `docs(phase-03): create authentication plans` |
+| executar-fase | fase | `docs(phase-03): complete authentication phase` |
+| novo-marco | marco | `docs: start milestone v1.1` |
+| remover-fase | chore | `chore: remove phase 17 (dashboard)` |
+| inserir-fase | fase | `docs: insert phase 16.1 (critical fix)` |
+| adicionar-fase | fase | `docs: add phase 07 (settings page)` |
+
+## Quando Pular
+
+- `commit_docs: false` no config
+- `.planning/` está no gitignore
+- Nenhuma alteração a commitar (verifique com `git status --porcelain .planning/`)

package/kit/framework/references/model-profile-resolution.md

@@ -0,0 +1,36 @@
+# Resolução de Perfil de Modelo
+
+Resolva o perfil de modelo uma vez no início da orquestração, depois use-o para todos os spawns de Task.
+
+## Padrão de Resolução
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Padrão: `balanced` se não configurado ou config ausente.
+
+## Tabela de Consulta
+
+@./.claude/framework/references/model-profiles.md
+
+Consulte o agente na tabela para o perfil resolvido. Passe o parâmetro model para chamadas Task:
+
+```
+Task(
+  prompt="...",
+  subagent_type="planner",
+  model="{resolved_model}"  # "inherit", "sonnet", ou "haiku"
+)
+```
+
+**Nota:** Agentes de nível Opus resolvem para `"inherit"` (não `"opus"`). Isso faz o agente usar o modelo da sessão pai, evitando conflitos com políticas organizacionais que podem bloquear versões específicas do opus.
+
+Se `model_profile` for `"inherit"`, todos os agentes resolvem para `"inherit"` (útil para `/model` do OpenCode).
+
+## Uso
+
+1. Resolva uma vez no início da orquestração
+2. Armazene o valor do perfil
+3. Consulte o modelo de cada agente na tabela ao spawnar
+4. Passe o parâmetro model para cada chamada Task (valores: `"inherit"`, `"sonnet"`, `"haiku"`)