@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/commands/depurar.md

@@ -0,0 +1,173 @@
+---
+name: depurar
+description: Depuração sistemática com estado persistente entre resets de contexto
+argument-hint: [descrição do problema]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Depurar problemas usando o método científico com isolamento de subagente.
+
+**Papel do orquestrador:** Coletar sintomas, invocar agente debugger, tratar checkpoints, invocar continuações.
+
+**Por que subagente:** Investigação consome contexto rapidamente (ler arquivos, formar hipóteses, testar). Contexto fresco de 200k por investigação. Contexto principal permanece enxuto para interação com o usuário.
+</objective>
+
+<available_agent_types>
+Tipos de subagente framework válidos (usar nomes exatos — não usar 'general-purpose'):
+- debugger — Diagnostica e corrige problemas
+</available_agent_types>
+
+<context>
+Problema do usuário: $ARGUMENTS
+
+Verificar sessões ativas:
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. Inicializar Contexto
+
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extrair `commit_docs` do JSON de init. Resolver modelo do depurador:
+```bash
+debugger_model=$(node "./.claude/framework/bin/tools.cjs" resolve-model debugger --raw)
+```
+
+## 1. Verificar Sessões Ativas
+
+Se existirem sessões ativas E sem $ARGUMENTS:
+- Listar sessões com status, hipótese, próxima ação
+- Usuário escolhe número para retomar OU descreve novo problema
+
+Se $ARGUMENTS fornecido OU usuário descreve novo problema:
+- Continuar para coleta de sintomas
+
+## 2. Coletar Sintomas (se novo problema)
+
+Usar AskUserQuestion para cada:
+
+1. **Comportamento esperado** - O que deveria acontecer?
+2. **Comportamento atual** - O que acontece em vez disso?
+3. **Mensagens de erro** - Algum erro? (colar ou descrever)
+4. **Cronologia** - Quando isso começou? Já funcionou?
+5. **Reprodução** - Como você aciona o problema?
+
+Após todos coletados, confirmar pronto para investigar.
+
+## 3. Invocar Agente debugger
+
+Preencher prompt e invocar:
+
+```markdown
+<objective>
+Investigar problema: {slug}
+
+**Resumo:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Criar: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="debugger",
+  model="{debugger_model}",
+  description="Depurar {slug}"
+)
+```
+
+## 4. Tratar Retorno do Agente
+
+**Se `## CAUSA RAIZ ENCONTRADA`:**
+- Exibir causa raiz e resumo de evidências
+- Oferecer opções:
+  - "Corrigir agora" - invocar subagente de correção
+  - "Planejar correção" - sugerir /planejar-fase --gaps
+  - "Correção manual" - concluído
+
+**Se `## CHECKPOINT ATINGIDO`:**
+- Apresentar detalhes do checkpoint ao usuário
+- Obter resposta do usuário
+- Se tipo de checkpoint for `human-verify`:
+  - Se usuário confirmar corrigido: continuar para o agente finalizar/resolver/arquivar
+  - Se usuário reportar problemas: continuar para o agente retornar à investigação/correção
+- Invocar agente de continuação (ver passo 5)
+
+**Se `## INVESTIGAÇÃO INCONCLUSIVA`:**
+- Mostrar o que foi verificado e eliminado
+- Oferecer opções:
+  - "Continuar investigando" - invocar novo agente com contexto adicional
+  - "Investigação manual" - concluído
+  - "Adicionar mais contexto" - coletar mais sintomas, invocar novamente
+
+## 5. Invocar Agente de Continuação (Após Checkpoint)
+
+Quando usuário responde ao checkpoint, invocar agente fresco:
+
+```markdown
+<objective>
+Continuar depuração de {slug}. Evidências estão no arquivo de depuração.
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/debug/{slug}.md (Estado da sessão de depuração)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Tipo:** {checkpoint_type}
+**Resposta:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="debugger",
+  model="{debugger_model}",
+  description="Continuar depuração {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Sessões ativas verificadas
+- [ ] Sintomas coletados (se novo)
+- [ ] debugger invocado com contexto
+- [ ] Checkpoints tratados corretamente
+- [ ] Causa raiz confirmada antes de corrigir
+</success_criteria>

package/kit/commands/discutir-fase.md

@@ -0,0 +1,64 @@
+---
+name: discutir-fase
+description: Reúne contexto da fase por questionamento adaptativo antes do planejamento. Use --auto para pular perguntas interativas (Claude escolhe os padrões recomendados).
+argument-hint: "<phase> [--auto] [--batch] [--analyze] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+---
+
+<objective>
+Extrair decisões de implementação que os agentes subsequentes precisam — o pesquisador e o planejador usarão o CONTEXT.md para saber o que investigar e quais escolhas estão travadas.
+
+**Como funciona:**
+1. Carregar contexto anterior (PROJECT.md, REQUIREMENTS.md, STATE.md, arquivos CONTEXT.md anteriores)
+2. Explorar base de código em busca de recursos e padrões reutilizáveis
+3. Analisar a fase — pular áreas cinzentas já decididas em fases anteriores
+4. Apresentar áreas cinzentas restantes — usuário seleciona quais discutir
+5. Aprofundar cada área selecionada até satisfação
+6. Criar CONTEXT.md com decisões que guiam pesquisa e planejamento
+
+**Saída:** `{phase_num}-CONTEXT.md` — decisões claras o suficiente para que agentes subsequentes possam agir sem perguntar ao usuário novamente
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/discuss-phase.md
+@./.claude/framework/workflows/discuss-phase-assumptions.md
+@./.claude/framework/templates/context.md
+</execution_context>
+
+<context>
+Número da fase: $ARGUMENTS (obrigatório)
+
+Arquivos de contexto são resolvidos no workflow usando `init phase-op` e chamadas de ferramentas de roadmap/estado.
+</context>
+
+<process>
+**Roteamento de modo:**
+```bash
+DISCUSS_MODE=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+```
+
+Se `DISCUSS_MODE` for `"assumptions"`: Ler e executar @./.claude/framework/workflows/discuss-phase-assumptions.md do início ao fim.
+
+Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): Ler e executar @./.claude/framework/workflows/discuss-phase.md do início ao fim.
+
+**OBRIGATÓRIO:** Os arquivos execution_context listados acima SÃO as instruções. Ler o arquivo de workflow ANTES de tomar qualquer ação. As seções de objective e success_criteria neste arquivo de comando são resumos — o arquivo de workflow contém o processo completo passo a passo com todos os comportamentos obrigatórios, verificações de configuração e padrões de interação. Não improvisar a partir do resumo.
+</process>
+
+<success_criteria>
+- Contexto anterior carregado e aplicado (sem re-perguntar questões já decididas)
+- Áreas cinzentas identificadas através de análise inteligente
+- Usuário escolheu quais áreas discutir
+- Cada área selecionada explorada até satisfação
+- Expansão de escopo redirecionada para ideias adiadas
+- CONTEXT.md captura decisões, não visão vaga
+- Usuário conhece os próximos passos
+</success_criteria>

package/kit/commands/entrar-discord.md

@@ -0,0 +1,18 @@
+---
+name: entrar-discord
+description: Entrar na comunidade framework no Discord
+---
+
+<objective>
+Exibir o link de convite para o servidor da comunidade framework no Discord.
+</objective>
+
+<output>
+# Entre no Discord do framework
+
+Conecte-se com outros usuários do framework, obtenha ajuda, compartilhe o que está criando e fique atualizado.
+
+**Link de convite:** https://discord.gg/framework
+
+Clique no link ou cole-o no seu navegador para entrar.
+</output>

package/kit/commands/estatisticas.md

@@ -0,0 +1,18 @@
+---
+name: estatisticas
+description: Exibe estatísticas do projeto — fases, planos, requisitos, métricas git e linha do tempo
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Exibe estatísticas abrangentes do projeto incluindo progresso de fases, métricas de execução de planos, conclusão de requisitos, estatísticas de histórico git e linha do tempo do projeto.
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/stats.md
+</execution_context>
+
+<process>
+Execute o workflow stats de @./.claude/framework/workflows/stats.md do início ao fim.
+</process>

package/kit/commands/executar-fase.md

@@ -0,0 +1,59 @@
+---
+name: executar-fase
+description: Executa todos os planos de uma fase com paralelização por ondas
+argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TodoWrite
+  - AskUserQuestion
+---
+<objective>
+Executa todos os planos de uma fase usando execução paralela por ondas.
+
+O orquestrador se mantém enxuto: descobrir planos, analisar dependências, agrupar em ondas, invocar subagentes, coletar resultados. Cada subagente carrega o contexto completo de execute-plan e cuida do seu próprio plano.
+
+Filtro de onda opcional:
+- `--wave N` executa apenas a Onda `N` para controle de ritmo, gestão de cota ou lançamento em etapas
+- verificação/conclusão da fase ainda ocorre apenas quando não há planos incompletos restantes após a onda selecionada terminar
+
+Regra de tratamento de flags:
+- As flags opcionais documentadas abaixo são comportamentos disponíveis, não comportamentos ativos implícitos
+- Uma flag está ativa apenas quando seu token literal aparece em `$ARGUMENTS`
+- Se uma flag documentada estiver ausente de `$ARGUMENTS`, trate-a como inativa
+
+Orçamento de contexto: ~15% orquestrador, 100% fresco por subagente.
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/execute-phase.md
+@./.claude/framework/references/ui-brand.md
+</execution_context>
+
+<context>
+Fase: $ARGUMENTS
+
+**Flags opcionais disponíveis (somente documentação — não automaticamente ativas):**
+- `--wave N` — Executar apenas a Onda `N` na fase. Use quando quiser controlar o ritmo da execução ou ficar dentro dos limites de uso.
+- `--gaps-only` — Executar apenas planos de fechamento de lacunas (planos com `gap_closure: true` no frontmatter). Use após verify-work criar planos de correção.
+- `--interactive` — Executar planos sequencialmente inline (sem subagentes) com checkpoints de usuário entre tarefas. Menor uso de tokens, estilo programação em par. Melhor para fases pequenas, correções de bugs e lacunas de verificação.
+
+**Flags ativas devem ser derivadas de `$ARGUMENTS`:**
+- `--wave N` está ativa somente se o token literal `--wave` estiver presente em `$ARGUMENTS`
+- `--gaps-only` está ativa somente se o token literal `--gaps-only` estiver presente em `$ARGUMENTS`
+- `--interactive` está ativa somente se o token literal `--interactive` estiver presente em `$ARGUMENTS`
+- Se nenhum desses tokens aparecer, executar o fluxo padrão de execução completa da fase sem filtragem específica de flag
+- Não inferir que uma flag está ativa apenas porque está documentada neste prompt
+
+Arquivos de contexto são resolvidos dentro do workflow via `tools init execute-phase` e blocos `<files_to_read>` por subagente.
+</context>
+
+<process>
+Execute o workflow execute-phase de @./.claude/framework/workflows/execute-phase.md do início ao fim.
+Preserve todos os checkpoints do workflow (execução de ondas, tratamento de checkpoints, verificação, atualizações de estado, roteamento).
+</process>

package/kit/commands/expresso.md

@@ -0,0 +1,47 @@
+---
+name: expresso
+description: Executa uma tarefa rápida com garantias framework (commits atômicos, rastreamento de estado) mas pula agentes opcionais
+argument-hint: "[--full] [--discuss] [--research]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Executar tarefas pequenas e ad-hoc com garantias framework (commits atômicos, rastreamento no STATE.md).
+
+Modo expresso é o mesmo sistema com um caminho mais curto:
+- Invoca planner (modo rápido) + executor(s)
+- Tarefas expressas ficam em `.planning/quick/` separado das fases planejadas
+- Atualiza tabela "Quick Tasks Completed" do STATE.md (NÃO ROADMAP.md)
+
+**Padrão:** Pula pesquisa, discussão, plan-checker, verificador. Use quando você sabe exatamente o que fazer.
+
+**Flag `--discuss`:** Fase de discussão leve antes do planejamento. Apresenta hipóteses, esclarece áreas cinzentas, captura decisões em CONTEXT.md. Use quando a tarefa tem ambiguidade que vale a pena resolver antecipadamente.
+
+**Flag `--full`:** Habilita verificação de plano (máximo 2 iterações) e verificação pós-execução. Use quando você quer garantias de qualidade sem a cerimônia completa de milestone.
+
+**Flag `--research`:** Invoca um agente de pesquisa focado antes do planejamento. Investiga abordagens de implementação, opções de biblioteca e armadilhas para a tarefa. Use quando não tem certeza da melhor abordagem.
+
+Flags são combináveis: `--discuss --research --full` dá discussão + pesquisa + verificação de plano + verificação.
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Arquivos de contexto são resolvidos dentro do workflow (`init quick`) e delegados via blocos `<files_to_read>`.
+</context>
+
+<process>
+Execute o workflow quick de @./.claude/framework/workflows/quick.md do início ao fim.
+Preserve todos os checkpoints do workflow (validação, descrição de tarefa, planejamento, execução, atualizações de estado, commits).
+</process>

package/kit/commands/fase-ui.md

@@ -0,0 +1,34 @@
+---
+name: fase-ui
+description: Gera contrato de design UI (UI-SPEC.md) para fases de frontend
+argument-hint: "[fase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - AskUserQuestion
+  - mcp__context7__*
+---
+<objective>
+Cria um contrato de design UI (UI-SPEC.md) para uma fase de frontend.
+Orquestra os agentes ui-researcher e ui-checker.
+Fluxo: Validar → Pesquisar UI → Verificar UI-SPEC → Concluído
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/ui-phase.md
+@./.claude/framework/references/ui-brand.md
+</execution_context>
+
+<context>
+Número da fase: $ARGUMENTS — opcional, auto-detecta a próxima fase não planejada se omitido.
+</context>
+
+<process>
+Execute @./.claude/framework/workflows/ui-phase.md do início ao fim.
+Preserve todos os gates do workflow.
+</process>

package/kit/commands/fazer.md

@@ -0,0 +1,30 @@
+---
+name: fazer
+description: Roteia texto livre para o comando do framework correto automaticamente
+argument-hint: "<descrição do que você quer fazer>"
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Analisar entrada em linguagem natural e despachar para o comando do framework mais adequado.
+
+Age como um despachante inteligente — nunca faz o trabalho diretamente. Combina a intenção com o melhor comando do framework usando regras de roteamento, confirma a correspondência e então transfere.
+
+Use quando você sabe o que quer mas não sabe qual comando `/*` executar.
+</objective>
+
+<execution_context>
+@./.claude/framework/workflows/do.md
+@./.claude/framework/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute o workflow do de @./.claude/framework/workflows/do.md do início ao fim.
+Rotear a intenção do usuário para o melhor comando do framework e invocá-lo.
+</process>

package/kit/commands/fio.md

@@ -0,0 +1,126 @@
+---
+name: fio
+description: Gerencia threads de contexto persistentes para trabalho entre sessões
+argument-hint: [nome | descrição]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Criar, listar ou retomar threads de contexto persistentes. Threads são armazenamentos leves
+de conhecimento entre sessões para trabalho que abrange múltiplas sessões mas
+não pertence a nenhuma fase específica.
+</objective>
+
+<process>
+
+**Analisar $ARGUMENTS para determinar o modo:**
+
+<mode_list>
+**Se sem argumentos ou $ARGUMENTS estiver vazio:**
+
+Listar todos os threads:
+```bash
+ls .planning/threads/*.md 2>/dev/null
+```
+
+Para cada thread, ler as primeiras linhas para mostrar título e status:
+```
+## Threads Ativos
+
+| Thread | Status | Última Atualização |
+|--------|--------|--------------------|
+| fix-deploy-key-auth | ABERTO | 2026-03-15 |
+| pasta-tcp-timeout | RESOLVIDO | 2026-03-12 |
+| perf-investigation | EM ANDAMENTO | 2026-03-17 |
+```
+
+Se não existirem threads, mostrar:
+```
+Nenhum thread encontrado. Crie um com: /fio <descrição>
+```
+</mode_list>
+
+<mode_resume>
+**Se $ARGUMENTS corresponder a um nome de thread existente (arquivo existe):**
+
+Retomar o thread — carregar seu contexto na sessão atual:
+```bash
+cat ".planning/threads/${THREAD_NAME}.md"
+```
+
+Exibir o conteúdo do thread e perguntar ao usuário o que deseja trabalhar a seguir.
+Atualizar o status do thread para `IN PROGRESS` se estava `OPEN`.
+</mode_resume>
+
+<mode_create>
+**Se $ARGUMENTS for uma nova descrição (nenhum arquivo de thread correspondente):**
+
+Criar um novo thread:
+
+1. Gerar slug a partir da descrição:
+   ```bash
+   SLUG=$(node "./.claude/framework/bin/tools.cjs" generate-slug "$ARGUMENTS")
+   ```
+
+2. Criar o diretório de threads se necessário:
+   ```bash
+   mkdir -p .planning/threads
+   ```
+
+3. Escrever o arquivo do thread:
+   ```bash
+   cat > ".planning/threads/${SLUG}.md" << 'EOF'
+   # Thread: {descrição}
+
+   ## Status: OPEN
+
+   ## Objetivo
+
+   {descrição}
+
+   ## Contexto
+
+   *Criado a partir de conversa em {data de hoje}.*
+
+   ## Referências
+
+   - *(adicionar links, caminhos de arquivo ou números de issue)*
+
+   ## Próximos Passos
+
+   - *(o que a próxima sessão deve fazer primeiro)*
+   EOF
+   ```
+
+4. Se houver contexto relevante na conversa atual (trechos de código,
+   mensagens de erro, resultados de investigação), extrair e adicionar à seção Contexto.
+
+5. Commitar:
+   ```bash
+   node "./.claude/framework/bin/tools.cjs" commit "docs: criar thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   ```
+
+6. Reportar:
+   ```
+   ## Thread Criado
+
+   Thread: {slug}
+   Arquivo: .planning/threads/{slug}.md
+
+   Retome a qualquer momento com: /fio {slug}
+   ```
+</mode_create>
+
+</process>
+
+<notes>
+- Threads NÃO têm escopo de fase — existem independentemente do roadmap
+- Mais leve que /pausar-trabalho — sem estado de fase, sem contexto de plano
+- O valor está em Contexto e Próximos Passos — uma sessão fria pode começar imediatamente
+- Threads podem ser promovidos para fases ou itens de backlog quando amadurecem:
+  /adicionar-fase ou /adicionar-backlog com contexto do thread
+- Arquivos de thread ficam em .planning/threads/ — sem colisão com fases ou outras estruturas framework
+</notes>

package/kit/commands/fluxos-trabalho.md

@@ -0,0 +1,64 @@
+---
+name: fluxos-trabalho
+description: Gerencia fluxos de trabalho paralelos — listar, criar, alternar, status, progresso, concluir e retomar
+---
+
+# /fluxos-trabalho
+
+Gerencia fluxos de trabalho paralelos para trabalho concurrent em milestones.
+
+## Uso
+
+`/fluxos-trabalho [subcomando] [argumentos]`
+
+### Subcomandos
+
+| Comando | Descrição |
+|---------|-----------|
+| `list` | Listar todos os fluxos com status |
+| `create <nome>` | Criar um novo fluxo de trabalho |
+| `status <nome>` | Status detalhado de um fluxo |
+| `switch <nome>` | Definir fluxo ativo |
+| `progress` | Resumo de progresso de todos os fluxos |
+| `complete <nome>` | Arquivar um fluxo concluído |
+| `resume <nome>` | Retomar trabalho em um fluxo |
+
+## Passo 1: Analisar Subcomando
+
+Analisar a entrada do usuário para determinar qual operação de fluxo executar.
+Se nenhum subcomando for fornecido, padrão é `list`.
+
+## Passo 2: Executar Operação
+
+### list
+Executar: `node "$TOOLS" workstream list --raw --cwd "$CWD"`
+Exibir os fluxos em formato de tabela mostrando nome, status, fase atual e progresso.
+
+### create
+Executar: `node "$TOOLS" workstream create <nome> --raw --cwd "$CWD"`
+Após criação, exibir o caminho do novo fluxo e sugerir próximos passos:
+- `/novo-marco --ws <nome>` para configurar o milestone
+
+### status
+Executar: `node "$TOOLS" workstream status <nome> --raw --cwd "$CWD"`
+Exibir detalhamento de fases e informações de estado.
+
+### switch
+Executar: `node "$TOOLS" workstream set <nome> --raw --cwd "$CWD"`
+Também definir variável de ambiente `WORKSTREAM` para a sessão atual.
+
+### progress
+Executar: `node "$TOOLS" workstream progress --raw --cwd "$CWD"`
+Exibir visão geral de progresso de todos os fluxos.
+
+### complete
+Executar: `node "$TOOLS" workstream complete <nome> --raw --cwd "$CWD"`
+Arquivar o fluxo em milestones/.
+
+### resume
+Definir o fluxo como ativo e sugerir `/retomar-trabalho --ws <nome>`.
+
+## Passo 3: Exibir Resultados
+
+Formatar a saída JSON do tools em exibição legível por humanos.
+Incluir a flag `${WS}` em qualquer sugestão de roteamento.