@luanpdd/kit-mcp 1.20.0 → 1.21.0

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

@@ -1,36 +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"`)
+# 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"`)

package/kit/framework/references/model-profiles.md

@@ -1,139 +1,139 @@
-# Perfis de Modelo
-
-Perfis de modelo controlam qual modelo Claude cada agente framework usa. Isso permite equilibrar qualidade vs. custo de tokens, ou herdar o modelo de sessão selecionado atualmente.
-
-## Definições de Perfil
-
-| Agente | `quality` | `balanced` | `budget` | `inherit` |
-|--------|-----------|------------|----------|-----------|
-| planner | opus | opus | sonnet | inherit |
-| roadmapper | opus | sonnet | sonnet | inherit |
-| executor | opus | sonnet | sonnet | inherit |
-| phase-researcher | opus | sonnet | haiku | inherit |
-| project-researcher | opus | sonnet | haiku | inherit |
-| research-synthesizer | sonnet | sonnet | haiku | inherit |
-| debugger | opus | sonnet | sonnet | inherit |
-| codebase-mapper | sonnet | haiku | haiku | inherit |
-| verifier | sonnet | sonnet | haiku | inherit |
-| plan-checker | sonnet | sonnet | haiku | inherit |
-| integration-checker | sonnet | sonnet | haiku | inherit |
-| nyquist-auditor | sonnet | sonnet | haiku | inherit |
-
-## Filosofia dos Perfis
-
-**quality** - Máximo poder de raciocínio
-- Opus para todos os agentes de tomada de decisão
-- Sonnet para verificação somente-leitura
-- Use quando: cota disponível, trabalho crítico de arquitetura
-
-**balanced** (padrão) - Alocação inteligente
-- Opus apenas para planejamento (onde decisões de arquitetura acontecem)
-- Sonnet para execução e pesquisa (segue instruções explícitas)
-- Sonnet para verificação (precisa de raciocínio, não apenas correspondência de padrões)
-- Use quando: desenvolvimento normal, bom equilíbrio de qualidade e custo
-
-**budget** - Uso mínimo de Opus
-- Sonnet para qualquer coisa que escreva código
-- Haiku para pesquisa e verificação
-- Use quando: conservando cota, trabalho de alto volume, fases menos críticas
-
-**inherit** - Seguir o modelo de sessão atual
-- Todos os agentes resolvem para `inherit`
-- Melhor quando você troca modelos interativamente (por exemplo `/model` do OpenCode)
-- **Obrigatório ao usar provedores não-Anthropic** (OpenRouter, modelos locais, etc.) — caso contrário o framework pode chamar modelos Anthropic diretamente, gerando custos inesperados
-- Use quando: você quer que o framework siga seu modelo de runtime selecionado atualmente
-
-## Usando Runtimes Não-Claude (Codex, OpenCode, Gemini CLI)
-
-Quando instalado para um runtime não-Claude, o instalador do framework define `resolve_model_ids: "omit"` em `~/.framework/defaults.json`. Isso retorna um parâmetro model vazio para todos os agentes, então cada agente usa o modelo padrão do runtime. Nenhuma configuração manual é necessária.
-
-Para atribuir modelos diferentes a agentes diferentes, adicione `model_overrides` com IDs de modelo que seu runtime reconhece:
-
-```json
-{
-  "resolve_model_ids": "omit",
-  "model_overrides": {
-    "planner": "o3",
-    "executor": "o4-mini",
-    "debugger": "o3",
-    "codebase-mapper": "o4-mini"
-  }
-}
-```
-
-A mesma lógica de níveis se aplica: modelos mais fortes para planejamento e debugging, modelos mais baratos para execução e mapeamento.
-
-## Usando Claude Code com Provedores Não-Anthropic (OpenRouter, Local)
-
-Se você estiver usando Claude Code com OpenRouter, um modelo local, ou qualquer provedor não-Anthropic, defina o perfil `inherit` para evitar que o framework chame modelos Anthropic para subagentes:
-
-```bash
-# Via comando de configurações
-/configuracoes
-# → Selecione "Inherit" para perfil de modelo
-
-# Ou manualmente em .planning/config.json
-{
-  "model_profile": "inherit"
-}
-```
-
-Sem `inherit`, o perfil `balanced` padrão do framework spawna modelos Anthropic específicos (`opus`, `sonnet`, `haiku`) para cada tipo de agente, o que pode resultar em custos adicionais de API pelo seu provedor não-Anthropic.
-
-## Lógica de Resolução
-
-Orquestradores resolvem o modelo antes de spawnar:
-
-```
-1. Ler .planning/config.json
-2. Verificar model_overrides para override específico de agente
-3. Se não houver override, consultar agente na tabela de perfil
-4. Passar parâmetro model para chamada Task
-```
-
-## Overrides Por Agente
-
-Sobrescreva agentes específicos sem alterar o perfil inteiro:
-
-```json
-{
-  "model_profile": "balanced",
-  "model_overrides": {
-    "executor": "opus",
-    "planner": "haiku"
-  }
-}
-```
-
-Overrides têm precedência sobre o perfil. Valores válidos: `opus`, `sonnet`, `haiku`, `inherit`, ou qualquer ID de modelo totalmente qualificado (ex: `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
-
-## Alternando Perfis
-
-Runtime: `/definir-perfil <perfil>`
-
-Padrão por projeto: Defina em `.planning/config.json`:
-```json
-{
-  "model_profile": "balanced"
-}
-```
-
-## Justificativa do Design
-
-**Por que Opus para planner?**
-O planejamento envolve decisões de arquitetura, decomposição de objetivos e design de tarefas. É onde a qualidade do modelo tem o maior impacto.
-
-**Por que Sonnet para executor?**
-Executores seguem instruções explícitas do PLAN.md. O plano já contém o raciocínio; a execução é implementação.
-
-**Por que Sonnet (não Haiku) para verificadores no balanced?**
-A verificação requer raciocínio regressivo de objetivos — verificar se o código *entrega* o que a fase prometeu, não apenas correspondência de padrões. Sonnet lida bem com isso; Haiku pode perder lacunas sutis.
-
-**Por que Haiku para codebase-mapper?**
-Exploração somente-leitura e extração de padrões. Não requer raciocínio, apenas saída estruturada do conteúdo dos arquivos.
-
-**Por que `inherit` em vez de passar `opus` diretamente?**
-O alias `"opus"` do Claude Code mapeia para uma versão específica do modelo. Organizações podem bloquear versões mais antigas do opus enquanto permitem versões mais novas. O framework retorna `"inherit"` para agentes de nível opus, fazendo-os usar qualquer versão do opus que o usuário configurou na sessão. Isso evita conflitos de versão e fallbacks silenciosos para Sonnet.
-
-**Por que o perfil `inherit`?**
-Alguns runtimes (incluindo OpenCode) permitem que usuários troquem modelos em runtime (`/model`). O perfil `inherit` mantém todos os subagentes framework alinhados com essa seleção ao vivo.
+# Perfis de Modelo
+
+Perfis de modelo controlam qual modelo Claude cada agente framework usa. Isso permite equilibrar qualidade vs. custo de tokens, ou herdar o modelo de sessão selecionado atualmente.
+
+## Definições de Perfil
+
+| Agente | `quality` | `balanced` | `budget` | `inherit` |
+|--------|-----------|------------|----------|-----------|
+| planner | opus | opus | sonnet | inherit |
+| roadmapper | opus | sonnet | sonnet | inherit |
+| executor | opus | sonnet | sonnet | inherit |
+| phase-researcher | opus | sonnet | haiku | inherit |
+| project-researcher | opus | sonnet | haiku | inherit |
+| research-synthesizer | sonnet | sonnet | haiku | inherit |
+| debugger | opus | sonnet | sonnet | inherit |
+| codebase-mapper | sonnet | haiku | haiku | inherit |
+| verifier | sonnet | sonnet | haiku | inherit |
+| plan-checker | sonnet | sonnet | haiku | inherit |
+| integration-checker | sonnet | sonnet | haiku | inherit |
+| nyquist-auditor | sonnet | sonnet | haiku | inherit |
+
+## Filosofia dos Perfis
+
+**quality** - Máximo poder de raciocínio
+- Opus para todos os agentes de tomada de decisão
+- Sonnet para verificação somente-leitura
+- Use quando: cota disponível, trabalho crítico de arquitetura
+
+**balanced** (padrão) - Alocação inteligente
+- Opus apenas para planejamento (onde decisões de arquitetura acontecem)
+- Sonnet para execução e pesquisa (segue instruções explícitas)
+- Sonnet para verificação (precisa de raciocínio, não apenas correspondência de padrões)
+- Use quando: desenvolvimento normal, bom equilíbrio de qualidade e custo
+
+**budget** - Uso mínimo de Opus
+- Sonnet para qualquer coisa que escreva código
+- Haiku para pesquisa e verificação
+- Use quando: conservando cota, trabalho de alto volume, fases menos críticas
+
+**inherit** - Seguir o modelo de sessão atual
+- Todos os agentes resolvem para `inherit`
+- Melhor quando você troca modelos interativamente (por exemplo `/model` do OpenCode)
+- **Obrigatório ao usar provedores não-Anthropic** (OpenRouter, modelos locais, etc.) — caso contrário o framework pode chamar modelos Anthropic diretamente, gerando custos inesperados
+- Use quando: você quer que o framework siga seu modelo de runtime selecionado atualmente
+
+## Usando Runtimes Não-Claude (Codex, OpenCode, Gemini CLI)
+
+Quando instalado para um runtime não-Claude, o instalador do framework define `resolve_model_ids: "omit"` em `~/.framework/defaults.json`. Isso retorna um parâmetro model vazio para todos os agentes, então cada agente usa o modelo padrão do runtime. Nenhuma configuração manual é necessária.
+
+Para atribuir modelos diferentes a agentes diferentes, adicione `model_overrides` com IDs de modelo que seu runtime reconhece:
+
+```json
+{
+  "resolve_model_ids": "omit",
+  "model_overrides": {
+    "planner": "o3",
+    "executor": "o4-mini",
+    "debugger": "o3",
+    "codebase-mapper": "o4-mini"
+  }
+}
+```
+
+A mesma lógica de níveis se aplica: modelos mais fortes para planejamento e debugging, modelos mais baratos para execução e mapeamento.
+
+## Usando Claude Code com Provedores Não-Anthropic (OpenRouter, Local)
+
+Se você estiver usando Claude Code com OpenRouter, um modelo local, ou qualquer provedor não-Anthropic, defina o perfil `inherit` para evitar que o framework chame modelos Anthropic para subagentes:
+
+```bash
+# Via comando de configurações
+/configuracoes
+# → Selecione "Inherit" para perfil de modelo
+
+# Ou manualmente em .planning/config.json
+{
+  "model_profile": "inherit"
+}
+```
+
+Sem `inherit`, o perfil `balanced` padrão do framework spawna modelos Anthropic específicos (`opus`, `sonnet`, `haiku`) para cada tipo de agente, o que pode resultar em custos adicionais de API pelo seu provedor não-Anthropic.
+
+## Lógica de Resolução
+
+Orquestradores resolvem o modelo antes de spawnar:
+
+```
+1. Ler .planning/config.json
+2. Verificar model_overrides para override específico de agente
+3. Se não houver override, consultar agente na tabela de perfil
+4. Passar parâmetro model para chamada Task
+```
+
+## Overrides Por Agente
+
+Sobrescreva agentes específicos sem alterar o perfil inteiro:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "executor": "opus",
+    "planner": "haiku"
+  }
+}
+```
+
+Overrides têm precedência sobre o perfil. Valores válidos: `opus`, `sonnet`, `haiku`, `inherit`, ou qualquer ID de modelo totalmente qualificado (ex: `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+
+## Alternando Perfis
+
+Runtime: `/definir-perfil <perfil>`
+
+Padrão por projeto: Defina em `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Justificativa do Design
+
+**Por que Opus para planner?**
+O planejamento envolve decisões de arquitetura, decomposição de objetivos e design de tarefas. É onde a qualidade do modelo tem o maior impacto.
+
+**Por que Sonnet para executor?**
+Executores seguem instruções explícitas do PLAN.md. O plano já contém o raciocínio; a execução é implementação.
+
+**Por que Sonnet (não Haiku) para verificadores no balanced?**
+A verificação requer raciocínio regressivo de objetivos — verificar se o código *entrega* o que a fase prometeu, não apenas correspondência de padrões. Sonnet lida bem com isso; Haiku pode perder lacunas sutis.
+
+**Por que Haiku para codebase-mapper?**
+Exploração somente-leitura e extração de padrões. Não requer raciocínio, apenas saída estruturada do conteúdo dos arquivos.
+
+**Por que `inherit` em vez de passar `opus` diretamente?**
+O alias `"opus"` do Claude Code mapeia para uma versão específica do modelo. Organizações podem bloquear versões mais antigas do opus enquanto permitem versões mais novas. O framework retorna `"inherit"` para agentes de nível opus, fazendo-os usar qualquer versão do opus que o usuário configurou na sessão. Isso evita conflitos de versão e fallbacks silenciosos para Sonnet.
+
+**Por que o perfil `inherit`?**
+Alguns runtimes (incluindo OpenCode) permitem que usuários troquem modelos em runtime (`/model`). O perfil `inherit` mantém todos os subagentes framework alinhados com essa seleção ao vivo.

package/kit/framework/references/phase-argument-parsing.md

@@ -1,61 +1,61 @@
-# Análise de Argumentos de Fase
-
-Analise e normalize argumentos de fase para comandos que operam em fases.
-
-## Extração
-
-De `$ARGUMENTS`:
-- Extraia o número da fase (primeiro argumento numérico)
-- Extraia flags (prefixados com `--`)
-- O texto restante é a descrição (para comandos de inserir/adicionar)
-
-## Usando tools
-
-O comando `find-phase` trata normalização e validação em uma única etapa:
-
-```bash
-PHASE_INFO=$(node "./.claude/framework/bin/tools.cjs" find-phase "${PHASE}")
-```
-
-Retorna JSON com:
-- `found`: true/false
-- `directory`: Caminho completo para o diretório da fase
-- `phase_number`: Número normalizado (ex: "06", "06.1")
-- `phase_name`: Parte do nome (ex: "foundation")
-- `plans`: Array de arquivos PLAN.md
-- `summaries`: Array de arquivos SUMMARY.md
-
-## Normalização Manual (Legado)
-
-Preencha fases inteiras com zero até 2 dígitos. Preserve sufixos decimais.
-
-```bash
-# Normalizar número da fase
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Inteiro: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validação
-
-Use `roadmap get-phase` para validar se a fase existe:
-
-```bash
-PHASE_CHECK=$(node "./.claude/framework/bin/tools.cjs" roadmap get-phase "${PHASE}" --pick found)
-if [ "$PHASE_CHECK" = "false" ]; then
-  echo "ERRO: Fase ${PHASE} não encontrada no roadmap"
-  exit 1
-fi
-```
-
-## Busca de Diretório
-
-Use `find-phase` para busca de diretório:
-
-```bash
-PHASE_DIR=$(node "./.claude/framework/bin/tools.cjs" find-phase "${PHASE}" --raw)
-```
+# Análise de Argumentos de Fase
+
+Analise e normalize argumentos de fase para comandos que operam em fases.
+
+## Extração
+
+De `$ARGUMENTS`:
+- Extraia o número da fase (primeiro argumento numérico)
+- Extraia flags (prefixados com `--`)
+- O texto restante é a descrição (para comandos de inserir/adicionar)
+
+## Usando tools
+
+O comando `find-phase` trata normalização e validação em uma única etapa:
+
+```bash
+PHASE_INFO=$(node "./.claude/framework/bin/tools.cjs" find-phase "${PHASE}")
+```
+
+Retorna JSON com:
+- `found`: true/false
+- `directory`: Caminho completo para o diretório da fase
+- `phase_number`: Número normalizado (ex: "06", "06.1")
+- `phase_name`: Parte do nome (ex: "foundation")
+- `plans`: Array de arquivos PLAN.md
+- `summaries`: Array de arquivos SUMMARY.md
+
+## Normalização Manual (Legado)
+
+Preencha fases inteiras com zero até 2 dígitos. Preserve sufixos decimais.
+
+```bash
+# Normalizar número da fase
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Inteiro: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validação
+
+Use `roadmap get-phase` para validar se a fase existe:
+
+```bash
+PHASE_CHECK=$(node "./.claude/framework/bin/tools.cjs" roadmap get-phase "${PHASE}" --pick found)
+if [ "$PHASE_CHECK" = "false" ]; then
+  echo "ERRO: Fase ${PHASE} não encontrada no roadmap"
+  exit 1
+fi
+```
+
+## Busca de Diretório
+
+Use `find-phase` para busca de diretório:
+
+```bash
+PHASE_DIR=$(node "./.claude/framework/bin/tools.cjs" find-phase "${PHASE}" --raw)
+```