@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/framework/workflows/new-workspace.md

@@ -0,0 +1,237 @@
+<purpose>
+Create an isolated workspace directory with git repo copies (worktrees or clones) and an independent `.planning/` directory. Supports multi-repo orchestration and single-repo feature branch isolation.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 1. Setup
+
+**MANDATORY FIRST STEP — Execute init command:**
+
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" init new-workspace)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `default_workspace_base`, `child_repos`, `child_repo_count`, `worktree_available`, `is_git_repo`, `cwd_repo_name`, `project_root`.
+
+## 2. Parse Arguments
+
+Extract from $ARGUMENTS:
+- `--name` → `WORKSPACE_NAME` (required)
+- `--repos` → `REPO_LIST` (comma-separated paths or names)
+- `--path` → `TARGET_PATH` (defaults to `$default_workspace_base/$WORKSPACE_NAME`)
+- `--strategy` → `STRATEGY` (defaults to `worktree`)
+- `--branch` → `BRANCH_NAME` (defaults to `workspace/$WORKSPACE_NAME`)
+- `--auto` → skip interactive questions
+
+**If `--name` is missing and not `--auto`:**
+
+Use AskUserQuestion:
+- header: "Workspace Name"
+- question: "What should this workspace be called?"
+- requireAnswer: true
+
+## 3. Select Repos
+
+**If `--repos` is provided:** Parse comma-separated values. For each value:
+- If it's an absolute path, use it directly
+- If it's a relative path or name, resolve against `$project_root`
+- Special case: `.` means current repo (use `$project_root`, name it `$cwd_repo_name`)
+
+**If `--repos` is NOT provided and not `--auto`:**
+
+**If `child_repo_count` > 0:**
+
+Present child repos for selection:
+
+Use AskUserQuestion:
+- header: "Select Repos"
+- question: "Which repos should be included in the workspace?"
+- options: List each child repo from `child_repos` array by name
+- multiSelect: true
+
+**If `child_repo_count` is 0 and `is_git_repo` is true:**
+
+Use AskUserQuestion:
+- header: "Current Repo"
+- question: "No child repos found. Create a workspace with the current repo?"
+- options:
+  - "Yes — create workspace with current repo" → use current repo
+  - "Cancel" → exit
+
+**If `child_repo_count` is 0 and `is_git_repo` is false:**
+
+Error:
+```
+No git repos found in the current directory and this is not a git repo.
+
+Run this command from a directory containing git repos, or specify repos explicitly:
+  /new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2
+```
+Exit.
+
+**If `--auto` and `--repos` is NOT provided:**
+
+Error:
+```
+Error: --auto requires --repos to specify which repos to include.
+
+Usage:
+  /new-workspace --name my-workspace --repos repo1,repo2 --auto
+```
+Exit.
+
+## 4. Select Strategy
+
+**If `--strategy` is provided:** Use it (validate: must be `worktree` or `clone`).
+
+**If `--strategy` is NOT provided and not `--auto`:**
+
+Use AskUserQuestion:
+- header: "Strategy"
+- question: "How should repos be copied into the workspace?"
+- options:
+  - "Worktree (recommended) — lightweight, shares .git objects with source repo" → `worktree`
+  - "Clone — fully independent copy, no connection to source repo" → `clone`
+
+**If `--auto`:** Default to `worktree`.
+
+## 5. Validate
+
+Before creating anything, validate:
+
+1. **Target path** — must not exist or must be empty:
+```bash
+if [ -d "$TARGET_PATH" ] && [ "$(ls -A "$TARGET_PATH" 2>/dev/null)" ]; then
+  echo "Error: Target path already exists and is not empty: $TARGET_PATH"
+  echo "Choose a different --name or --path."
+  exit 1
+fi
+```
+
+2. **Source repos exist and are git repos** — for each repo path:
+```bash
+if [ ! -d "$REPO_PATH/.git" ]; then
+  echo "Error: Not a git repo: $REPO_PATH"
+  exit 1
+fi
+```
+
+3. **Worktree availability** — if strategy is `worktree` and `worktree_available` is false:
+```
+Error: git is not available. Install git or use --strategy clone.
+```
+
+Report all validation errors at once, not one at a time.
+
+## 6. Create Workspace
+
+```bash
+mkdir -p "$TARGET_PATH"
+```
+
+### For each repo:
+
+**Worktree strategy:**
+```bash
+cd "$SOURCE_REPO_PATH"
+git worktree add "$TARGET_PATH/$REPO_NAME" -b "$BRANCH_NAME" 2>&1
+```
+
+If `git worktree add` fails because the branch already exists, try with a timestamped branch:
+```bash
+TIMESTAMP=$(date +%Y%m%d%H%M%S)
+git worktree add "$TARGET_PATH/$REPO_NAME" -b "${BRANCH_NAME}-${TIMESTAMP}" 2>&1
+```
+
+If that also fails, report the error and continue with remaining repos.
+
+**Clone strategy:**
+```bash
+git clone "$SOURCE_REPO_PATH" "$TARGET_PATH/$REPO_NAME" 2>&1
+cd "$TARGET_PATH/$REPO_NAME"
+git checkout -b "$BRANCH_NAME" 2>&1
+```
+
+Track results: which repos succeeded, which failed, what branch was used.
+
+## 7. Write WORKSPACE.md
+
+Write the workspace manifest at `$TARGET_PATH/WORKSPACE.md`:
+
+```markdown
+# Workspace: $WORKSPACE_NAME
+
+Created: $DATE
+Strategy: $STRATEGY
+
+## Member Repos
+
+| Repo | Source | Branch | Strategy |
+|------|--------|--------|----------|
+| $REPO_NAME | $SOURCE_PATH | $BRANCH | $STRATEGY |
+...for each repo...
+
+## Notes
+
+[Add context about what this workspace is for]
+```
+
+## 8. Initialize .planning/
+
+```bash
+mkdir -p "$TARGET_PATH/.planning"
+```
+
+## 9. Report and Next Steps
+
+**If all repos succeeded:**
+
+```
+Workspace created: $TARGET_PATH
+
+  Repos: $REPO_COUNT
+  Strategy: $STRATEGY
+  Branch: $BRANCH_NAME
+
+Next steps:
+  cd $TARGET_PATH
+  /new-project    # Initialize framework in the workspace
+```
+
+**If some repos failed:**
+
+```
+Workspace created with $SUCCESS_COUNT of $TOTAL_COUNT repos: $TARGET_PATH
+
+  Succeeded: repo1, repo2
+  Failed: repo3 (branch already exists), repo4 (not a git repo)
+
+Next steps:
+  cd $TARGET_PATH
+  /new-project    # Initialize framework in the workspace
+```
+
+**Offer to initialize framework (if not `--auto`):**
+
+Use AskUserQuestion:
+- header: "Initialize framework"
+- question: "Would you like to initialize a framework project in the new workspace?"
+- options:
+  - "Yes — run /new-project" → tell user to `cd $TARGET_PATH` first, then run `/new-project`
+  - "No — I'll set it up later" → done
+
+</process>
+
+<success_criteria>
+- [ ] Workspace directory created at target path
+- [ ] All specified repos copied (worktree or clone) into workspace
+- [ ] WORKSPACE.md manifest written with correct repo table
+- [ ] `.planning/` directory initialized at workspace root
+- [ ] User informed of workspace path and next steps
+</success_criteria>

package/kit/framework/workflows/next.md

@@ -0,0 +1,97 @@
+<purpose>
+Detectar o estado atual do projeto e avançar automaticamente para o próximo passo lógico do workflow framework.
+Lê o estado do projeto para determinar a progressão: discussão → planejamento → execução → verificação → conclusão.
+</purpose>
+
+<required_reading>
+Ler todos os arquivos referenciados pelo execution_context do prompt invocador antes de começar.
+</required_reading>
+
+<process>
+
+<step name="detect_state">
+Ler o estado do projeto para determinar a posição atual:
+
+```bash
+# Obter snapshot do estado
+node "./.claude/framework/bin/tools.cjs" state json 2>/dev/null || echo "{}"
+```
+
+Também ler:
+- `.planning/STATE.md` — fase atual, progresso, contagens de planos
+- `.planning/ROADMAP.md` — estrutura do milestone e lista de fases
+
+Extrair:
+- `current_phase` — qual fase está ativa
+- `plan_of` / `plans_total` — progresso de execução de planos
+- `progress` — percentual geral
+- `status` — ativo, pausado, etc.
+
+Se o diretório `.planning/` não existir:
+```
+Nenhum projeto framework detectado. Execute `/novo-projeto` para começar.
+```
+Sair.
+</step>
+
+<step name="determine_next_action">
+Aplicar regras de roteamento com base no estado:
+
+**Rota 1: Nenhuma fase existe ainda → discussão**
+Se o ROADMAP tem fases mas nenhum diretório de fase existe no disco:
+→ Próxima ação: `/discutir-fase <primeira-fase>`
+
+**Rota 2: Fase existe mas não tem CONTEXT.md ou RESEARCH.md → discussão**
+Se o diretório da fase atual existe mas não tem CONTEXT.md nem RESEARCH.md:
+→ Próxima ação: `/discutir-fase <fase-atual>`
+
+**Rota 3: Fase tem contexto mas sem planos → planejamento**
+Se a fase atual tem CONTEXT.md (ou RESEARCH.md) mas nenhum arquivo PLAN.md:
+→ Próxima ação: `/planejar-fase <fase-atual>`
+
+**Rota 4: Fase tem planos mas summaries incompletos → execução**
+Se planos existem mas nem todos têm summaries correspondentes:
+→ Próxima ação: `/executar-fase <fase-atual>`
+
+**Rota 5: Todos os planos têm summaries → verificar e concluir**
+Se todos os planos na fase atual têm summaries:
+→ Próxima ação: `/verificar-trabalho` então `/complete-phase`
+
+**Rota 6: Fase concluída, próxima fase existe → avançar**
+Se a fase atual está concluída e a próxima fase existe no ROADMAP:
+→ Próxima ação: `/discutir-fase <proxima-fase>`
+
+**Rota 7: Todas as fases concluídas → concluir milestone**
+Se todas as fases estão concluídas:
+→ Próxima ação: `/concluir-marco`
+
+**Rota 8: Pausado → retomar**
+Se STATE.md mostra paused_at:
+→ Próxima ação: `/retomar-trabalho`
+</step>
+
+<step name="show_and_execute">
+Exibir a determinação:
+
+```
+## framework Próximo
+
+**Atual:** Fase [N] — [nome] | [progresso]%
+**Status:** [descrição do status]
+
+▶ **Próximo passo:** `/[comando] [args]`
+  [Explicação em uma linha de por que este é o próximo passo]
+```
+
+Então invocar imediatamente o comando determinado via SlashCommand.
+Não pedir confirmação — o objetivo do `/proximo` é avanço sem fricção.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Estado do projeto detectado corretamente
+- [ ] Próxima ação determinada corretamente pelas regras de roteamento
+- [ ] Comando invocado imediatamente sem confirmação do usuário
+- [ ] Status claro mostrado antes de invocar
+</success_criteria>

package/kit/framework/workflows/node-repair.md

@@ -0,0 +1,92 @@
+<purpose>
+Operador de reparo autônomo para verificação de tarefas com falha. Invocado pelo execute-plan quando uma tarefa não passa nos critérios de conclusão. Propõe e tenta correções estruturadas antes de escalar ao usuário.
+</purpose>
+
+<inputs>
+- FAILED_TASK: Número, nome e critérios de conclusão da tarefa no plano
+- ERROR: O que a verificação produziu — resultado real vs. esperado
+- PLAN_CONTEXT: Tarefas adjacentes e objetivo da fase (para consciência de restrições)
+- REPAIR_BUDGET: Máximo de tentativas de reparo restantes (padrão: 2)
+</inputs>
+
+<repair_directive>
+Analise a falha e escolha exatamente uma estratégia de reparo:
+
+**RETRY** — A abordagem estava correta, mas a execução falhou. Tente novamente com um ajuste concreto.
+- Usar quando: erro de comando, dependência ausente, caminho errado, problema de ambiente, falha transiente
+- Saída: `RETRY: [ajuste específico a fazer antes de tentar novamente]`
+
+**DECOMPOSE** — A tarefa é muito ampla. Divida em sub-etapas menores verificáveis.
+- Usar quando: os critérios de conclusão cobrem múltiplos aspectos, lacunas de implementação são estruturais
+- Saída: `DECOMPOSE: [sub-tarefa 1] | [sub-tarefa 2] | ...` (máx. 3 sub-tarefas)
+- Sub-tarefas devem ter, cada uma, um único resultado verificável
+
+**PRUNE** — A tarefa é inviável dadas as restrições atuais. Pule com justificativa.
+- Usar quando: pré-requisito ausente e não corrigível aqui, fora do escopo, contradiz uma decisão anterior
+- Saída: `PRUNE: [justificativa em uma frase]`
+
+**ESCALATE** — Orçamento de reparo esgotado, ou esta é uma decisão arquitetural (Regra 4).
+- Usar quando: RETRY falhou mais de uma vez com abordagens diferentes, ou a correção requer mudança estrutural
+- Saída: `ESCALATE: [o que foi tentado] | [qual decisão é necessária]`
+</repair_directive>
+
+<process>
+
+<step name="diagnose">
+Leia o erro e os critérios de conclusão com atenção. Pergunte:
+1. É um problema transitório/ambiental? → RETRY
+2. A tarefa é verificavelmente muito ampla? → DECOMPOSE
+3. Um pré-requisito está genuinamente ausente e não pode ser corrigido no escopo? → PRUNE
+4. RETRY já foi tentado para esta tarefa? Verifique REPAIR_BUDGET. Se 0 → ESCALATE
+</step>
+
+<step name="execute_retry">
+Se RETRY:
+1. Aplique o ajuste específico declarado na diretiva
+2. Execute novamente a implementação da tarefa
+3. Execute novamente a verificação
+4. Se passar → continue normalmente, registre `[Node Repair - RETRY] Tarefa [X]: [ajuste feito]`
+5. Se falhar novamente → decremente REPAIR_BUDGET, invoque node-repair novamente com contexto atualizado
+</step>
+
+<step name="execute_decompose">
+Se DECOMPOSE:
+1. Substitua a tarefa com falha pelas sub-tarefas inline (não modifique PLAN.md em disco)
+2. Execute as sub-tarefas sequencialmente, cada uma com sua própria verificação
+3. Se todas passarem → trate a tarefa original como bem-sucedida, registre `[Node Repair - DECOMPOSE] Tarefa [X] → [N] sub-tarefas`
+4. Se uma sub-tarefa falhar → invoque node-repair novamente para essa sub-tarefa (REPAIR_BUDGET aplica-se por sub-tarefa)
+</step>
+
+<step name="execute_prune">
+Se PRUNE:
+1. Marque a tarefa como pulada com justificativa
+2. Registre no SUMMARY "Problemas Encontrados": `[Node Repair - PRUNE] Tarefa [X]: [justificativa]`
+3. Continue para a próxima tarefa
+</step>
+
+<step name="execute_escalate">
+Se ESCALATE:
+1. Suba para o usuário via verification_failure_gate com histórico completo de reparo
+2. Apresente: o que foi tentado (cada tentativa RETRY/DECOMPOSE), qual é o bloqueador, opções disponíveis
+3. Aguarde a direção do usuário antes de continuar
+</step>
+
+</process>
+
+<logging>
+Todas as ações de reparo devem aparecer no SUMMARY.md em "## Desvios do Plano":
+
+| Tipo | Formato |
+|------|--------|
+| RETRY com sucesso | `[Node Repair - RETRY] Tarefa X: [ajuste] — resolvido` |
+| RETRY falha → ESCALATE | `[Node Repair - RETRY] Tarefa X: [N] tentativas esgotadas — escalado ao usuário` |
+| DECOMPOSE | `[Node Repair - DECOMPOSE] Tarefa X dividida em [N] sub-tarefas — todas passaram` |
+| PRUNE | `[Node Repair - PRUNE] Tarefa X pulada: [justificativa]` |
+</logging>
+
+<constraints>
+- REPAIR_BUDGET padrão é 2 por tarefa. Configurável via config.json `workflow.node_repair_budget`.
+- Nunca modifique PLAN.md em disco — sub-tarefas decompostas existem apenas em memória.
+- Sub-tarefas DECOMPOSE devem ser mais específicas que a original, não apenas reescritas sinônimas.
+- Se config.json `workflow.node_repair` for `false`, pule diretamente para verification_failure_gate (o usuário mantém o comportamento original).
+</constraints>

package/kit/framework/workflows/note.md

@@ -0,0 +1,156 @@
+<purpose>
+Captura de ideias sem fricção. Uma chamada Write, uma linha de confirmação. Sem perguntas, sem prompts.
+Executa inline — sem Task, sem AskUserQuestion, sem Bash.
+</purpose>
+
+<required_reading>
+Ler todos os arquivos referenciados pelo execution_context do prompt invocador antes de começar.
+</required_reading>
+
+<process>
+
+<step name="storage_format">
+**Formato de armazenamento de notas.**
+
+Notas são armazenadas como arquivos markdown individuais:
+
+- **Escopo do projeto**: `.planning/notes/{AAAA-MM-DD}-{slug}.md` — usado quando `.planning/` existe no cwd
+- **Escopo global**: `./.claude/notes/{AAAA-MM-DD}-{slug}.md` — fallback quando não há `.planning/`, ou quando a flag `--global` está presente
+
+Cada arquivo de nota:
+
+```markdown
+---
+date: "AAAA-MM-DD HH:mm"
+promoted: false
+---
+
+{texto da nota verbatim}
+```
+
+**Flag `--global`**: Remover `--global` de qualquer lugar em `$ARGUMENTS` antes de analisar. Quando presente, forçar escopo global independentemente de `.planning/` existir.
+
+**Importante**: NÃO criar `.planning/` se não existir. Usar escopo global silenciosamente como fallback.
+</step>
+
+<step name="parse_subcommand">
+**Analisar subcomando de $ARGUMENTS (após remover --global).**
+
+| Condição | Subcomando |
+|----------|------------|
+| Argumentos são exatamente `list` (sem distinção maiúscula/minúscula) | **list** |
+| Argumentos são exatamente `promote <N>` onde N é um número | **promote** |
+| Argumentos estão vazios (sem texto algum) | **list** |
+| Qualquer outra coisa | **append** (o texto É a nota) |
+
+**Crítico**: `list` é somente um subcomando quando é o ARGUMENTO INTEIRO. `/nota lista de compras` salva uma nota com o texto "lista de compras". O mesmo para `promote` — somente um subcomando quando seguido por exatamente um número.
+</step>
+
+<step name="append">
+**Subcomando: append — criar um arquivo de nota com timestamp.**
+
+1. Determinar escopo (projeto ou global) conforme formato de armazenamento acima
+2. Garantir que o diretório de notas existe (`.planning/notes/` ou `./.claude/notes/`)
+3. Gerar slug: primeiras ~4 palavras significativas do texto da nota, minúsculo, separado por hífen (remover artigos/preposições do início)
+4. Gerar nome de arquivo: `{AAAA-MM-DD}-{slug}.md`
+   - Se um arquivo com esse nome já existir, adicionar `-2`, `-3`, etc.
+5. Escrever o arquivo com frontmatter e texto da nota (ver formato de armazenamento)
+6. Confirmar com exatamente uma linha: `Anotado ({escopo}): {texto da nota}`
+   - Onde `{escopo}` é "projeto" ou "global"
+
+**Restrições:**
+- **Nunca modificar o texto da nota** — capturar verbatim, incluindo erros de digitação
+- **Nunca fazer perguntas** — apenas escrever e confirmar
+- **Formato de timestamp**: Usar horário local, `AAAA-MM-DD HH:mm` (24 horas, sem segundos)
+</step>
+
+<step name="list">
+**Subcomando: list — mostrar notas de ambos os escopos.**
+
+1. Glob `.planning/notes/*.md` (se diretório existir) — notas do projeto
+2. Glob `./.claude/notes/*.md` (se diretório existir) — notas globais
+3. Para cada arquivo, ler frontmatter para obter `date` e status `promoted`
+4. Excluir arquivos onde `promoted: true` das contagens ativas (mas ainda mostrar, dimmed)
+5. Ordenar por data, numerar todas as entradas ativas sequencialmente começando em 1
+6. Se total de entradas ativas > 20, mostrar apenas as últimas 10 com nota sobre quantas foram omitidas
+
+**Formato de exibição:**
+
+```
+Notas:
+
+Projeto (.planning/notes/):
+  1. [2026-02-08 14:32] refatorar o sistema de hook para suportar validadores assíncronos
+  2. [promovido] [2026-02-08 14:40] adicionar rate limiting nos endpoints da API
+  3. [2026-02-08 15:10] considerar adicionar flag --dry-run ao build
+
+Global (./.claude/notes/):
+  4. [2026-02-08 10:00] ideia entre projetos sobre config compartilhada
+
+{contagem} nota(s) ativa(s). Use `/nota promote <N>` para converter em uma tarefa.
+```
+
+Se um escopo não tiver diretório ou entradas, mostrar: `(sem notas)`
+</step>
+
+<step name="promote">
+**Subcomando: promote — converter uma nota em uma tarefa.**
+
+1. Executar a lógica de **list** para construir o índice numerado (ambos os escopos)
+2. Encontrar a entrada N da lista numerada
+3. Se N for inválido ou referir a uma nota já promovida, informar o usuário e parar
+4. **Requer diretório `.planning/`** — se não existir, avisar: "Tarefas requerem um projeto framework. Execute `/novo-projeto` para inicializar um."
+5. Garantir que o diretório `.planning/todos/pending/` existe
+6. Gerar ID da tarefa: `{NNN}-{slug}` onde NNN é o próximo número sequencial (escanear tanto `.planning/todos/pending/` quanto `.planning/todos/done/` pelo maior número existente, incrementar em 1, preencher com zeros à esquerda até 3 dígitos) e slug são as primeiras ~4 palavras significativas do texto da nota
+7. Extrair o texto da nota do arquivo fonte (corpo após frontmatter)
+8. Criar `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+title: "{texto da nota}"
+status: pending
+priority: P2
+source: "promoted from /nota"
+created: {AAAA-MM-DD}
+theme: general
+---
+
+## Objetivo
+
+{texto da nota}
+
+## Contexto
+
+Promovido de nota rápida capturada em {data original}.
+
+## Critérios de Aceitação
+
+- [ ] {critério principal derivado do texto da nota}
+```
+
+9. Marcar o arquivo de nota fonte como promovido: atualizar seu frontmatter para `promoted: true`
+10. Confirmar: `Nota {N} promovida para tarefa {id}: {texto da nota}`
+</step>
+
+</process>
+
+<edge_cases>
+1. **"list" como texto de nota**: `/nota lista de coisas` salva nota "lista de coisas" (subcomando apenas quando `list` é o argumento inteiro)
+2. **Sem `.planning/`**: Fallback para `./.claude/notes/` global — funciona em qualquer diretório
+3. **Promote sem projeto**: Avisa que tarefas requerem `.planning/`, sugere `/novo-projeto`
+4. **Arquivos grandes**: `list` mostra as últimas 10 quando há > 20 entradas ativas
+5. **Slugs duplicados**: Adicionar `-2`, `-3` etc. ao nome do arquivo se slug já usado na mesma data
+6. **Posição de `--global`**: Removido de qualquer lugar — `--global minha ideia` e `minha ideia --global` ambos salvam "minha ideia" globalmente
+7. **Promote já promovido**: Informar usuário "Nota {N} já está promovida" e parar
+8. **Texto de nota vazio após remover flags**: Tratar como subcomando `list`
+</edge_cases>
+
+<success_criteria>
+- [ ] Append: Arquivo de nota escrito com frontmatter correto e texto verbatim
+- [ ] Append: Nenhuma pergunta feita — captura instantânea
+- [ ] List: Ambos os escopos mostrados com numeração sequencial
+- [ ] List: Notas promovidas mostradas mas dimmed
+- [ ] Promote: Tarefa criada com formato correto
+- [ ] Promote: Nota fonte marcada como promovida
+- [ ] Fallback global: Funciona quando `.planning/` não existe
+</success_criteria>