@luanpdd/kit-mcp 0.2.0 → 0.3.0

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

@@ -0,0 +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.

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

@@ -0,0 +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)
+```

package/kit/framework/references/planning-config.md

@@ -0,0 +1,202 @@
+<planning_config>
+
+Opções de configuração para o comportamento do diretório `.planning/`.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "framework/phase-{phase}-{slug}",
+  "milestone_branch_template": "framework/{milestone}-{slug}",
+  "quick_branch_template": null
+}
+```
+
+| Opção | Padrão | Descrição |
+|-------|--------|-----------|
+| `commit_docs` | `true` | Se deve commitar artefatos de planejamento no git |
+| `search_gitignored` | `false` | Adicionar `--no-ignore` a buscas amplas com rg |
+| `git.branching_strategy` | `"none"` | Abordagem de branching git: `"none"`, `"phase"`, ou `"milestone"` |
+| `git.phase_branch_template` | `"framework/phase-{phase}-{slug}"` | Template de branch para estratégia phase |
+| `git.milestone_branch_template` | `"framework/{milestone}-{slug}"` | Template de branch para estratégia milestone |
+| `git.quick_branch_template` | `null` | Template de branch opcional para execuções de tarefa rápida |
+</config_schema>
+
+<commit_docs_behavior>
+
+**Quando `commit_docs: true` (padrão):**
+- Arquivos de planejamento commitados normalmente
+- SUMMARY.md, STATE.md, ROADMAP.md rastreados no git
+- Histórico completo de decisões de planejamento preservado
+
+**Quando `commit_docs: false`:**
+- Pular todos os `git add`/`git commit` para arquivos `.planning/`
+- O usuário deve adicionar `.planning/` ao `.gitignore`
+- Útil para: contribuições OSS, projetos de clientes, manter o planejamento privado
+
+**Usando tools.cjs (preferido):**
+
+```bash
+# Commit com verificações automáticas de commit_docs + gitignore:
+node "./.claude/framework/bin/tools.cjs" commit "docs: update state" --files .planning/STATE.md
+
+# Carregar config via state load (retorna JSON):
+INIT=$(node "./.claude/framework/bin/tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs está disponível na saída JSON
+
+# Ou use comandos init que incluem commit_docs:
+INIT=$(node "./.claude/framework/bin/tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs está incluído em todas as saídas de comandos init
+```
+
+**Auto-detecção:** Se `.planning/` estiver no gitignore, `commit_docs` é automaticamente `false` independentemente do config.json. Isso evita erros de git quando usuários têm `.planning/` no `.gitignore`.
+
+**Commit via CLI (trata verificações automaticamente):**
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs: update state" --files .planning/STATE.md
+```
+
+O CLI verifica a configuração `commit_docs` e o status do gitignore internamente — sem condicionais manuais.
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**Quando `search_gitignored: false` (padrão):**
+- Comportamento padrão do rg (respeita .gitignore)
+- Buscas por caminho direto funcionam: `rg "padrão" .planning/` encontra arquivos
+- Buscas amplas pulam ignorados: `rg "padrão"` pula `.planning/`
+
+**Quando `search_gitignored: true`:**
+- Adicionar `--no-ignore` a buscas amplas com rg que devem incluir `.planning/`
+- Necessário apenas ao buscar em todo o repositório e esperando correspondências em `.planning/`
+
+**Nota:** A maioria das operações framework usa leituras diretas de arquivo ou caminhos explícitos, que funcionam independentemente do status do gitignore.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+Para usar o modo não-commitado:
+
+1. **Defina o config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Adicione ao .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Arquivos rastreados existentes:** Se `.planning/` foi rastreado anteriormente:
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Merges de branch:** Ao usar `branching_strategy: phase` ou `milestone`, o workflow `complete-milestone` remove automaticamente arquivos `.planning/` do staging antes de commits de merge quando `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Estratégias de Branching:**
+
+| Estratégia | Quando o branch é criado | Escopo do branch | Ponto de merge |
+|------------|--------------------------|------------------|----------------|
+| `none` | Nunca | N/A | N/A |
+| `phase` | No início do `execute-phase` | Fase única | Usuário faz merge após a fase |
+| `milestone` | No primeiro `execute-phase` do marco | Marco inteiro | Em `complete-milestone` |
+
+**Quando `git.branching_strategy: "none"` (padrão):**
+- Todo o trabalho commita para o branch atual
+- Comportamento padrão do framework
+
+**Quando `git.branching_strategy: "phase"`:**
+- `execute-phase` cria/alterna para um branch antes da execução
+- Nome do branch a partir de `phase_branch_template` (ex: `framework/phase-03-authentication`)
+- Todos os commits do plano vão para aquele branch
+- Usuário faz merge dos branches manualmente após a conclusão da fase
+- `complete-milestone` oferece fazer merge de todos os branches de fase
+
+**Quando `git.branching_strategy: "milestone"`:**
+- O primeiro `execute-phase` do marco cria o branch do marco
+- Nome do branch a partir de `milestone_branch_template` (ex: `framework/v1.0-mvp`)
+- Todas as fases do marco commitam para o mesmo branch
+- `complete-milestone` oferece fazer merge do branch do marco para main
+
+**Variáveis de template:**
+
+| Variável | Disponível em | Descrição |
+|----------|---------------|-----------|
+| `{phase}` | phase_branch_template | Número de fase com zero à esquerda (ex: "03") |
+| `{slug}` | Ambos | Nome em minúsculas com hífens |
+| `{milestone}` | milestone_branch_template | Versão do marco (ex: "v1.0") |
+
+**Verificando o config:**
+
+Use `init execute-phase` que retorna toda a config como JSON:
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Saída JSON inclui: branching_strategy, phase_branch_template, milestone_branch_template
+```
+
+Ou use `state load` para os valores de config:
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Analise branching_strategy, phase_branch_template, milestone_branch_template do JSON
+```
+
+**Criação de branch:**
+
+```bash
+# Para estratégia phase
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# Para estratégia milestone
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Opções de merge em complete-milestone:**
+
+| Opção | Comando git | Resultado |
+|-------|-------------|-----------|
+| Squash merge (recomendado) | `git merge --squash` | Único commit limpo por branch |
+| Merge com histórico | `git merge --no-ff` | Preserva todos os commits individuais |
+| Deletar sem merge | `git branch -D` | Descartar trabalho do branch |
+| Manter branches | (nenhum) | Tratamento manual depois |
+
+Squash merge é recomendado — mantém o histórico do branch main limpo enquanto preserva o histórico de desenvolvimento completo no branch (até ser deletado).
+
+**Casos de uso:**
+
+| Estratégia | Melhor para |
+|------------|-------------|
+| `none` | Desenvolvimento solo, projetos simples |
+| `phase` | Code review por fase, rollback granular, colaboração em equipe |
+| `milestone` | Branches de release, ambientes de staging, PR por versão |
+
+</branching_strategy_behavior>
+
+</planning_config>

package/kit/framework/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+
+A inicialização do projeto é extração de sonhos, não coleta de requisitos. Você está ajudando o usuário a descobrir e articular o que quer construir. Isso não é uma negociação de contrato — é um pensamento colaborativo.
+
+<philosophy>
+
+**Você é um parceiro de pensamento, não um entrevistador.**
+
+O usuário frequentemente tem uma ideia difusa. Seu trabalho é ajudá-lo a refiná-la. Faça perguntas que os façam pensar "ah, não tinha considerado isso" ou "sim, é exatamente isso que quis dizer."
+
+Não interrogue. Colabore. Não siga um roteiro. Siga o fio.
+
+</philosophy>
+
+<the_goal>
+
+Ao final do questionamento, você precisa de clareza suficiente para escrever um PROJECT.md em que as fases posteriores possam agir:
+
+- **Pesquisa** precisa de: que domínio pesquisar, o que o usuário já sabe, que incógnitas existem
+- **Requisitos** precisa de: visão clara o suficiente para delimitar as funcionalidades da v1
+- **Roadmap** precisa de: visão clara o suficiente para decompor em fases, como "pronto" se parece
+- **planejar-fase** precisa de: requisitos específicos para dividir em tarefas, contexto para escolhas de implementação
+- **executar-fase** precisa de: critérios de sucesso para verificar, o "porquê" por trás dos requisitos
+
+Um PROJECT.md vago força cada fase posterior a adivinhar. O custo se multiplica.
+
+</the_goal>
+
+<how_to_question>
+
+**Comece aberto.** Deixe-os despejar seu modelo mental. Não interrompa com estrutura.
+
+**Siga a energia.** O que eles enfatizaram, aprofunde nisso. O que os animou? Que problema gerou isso?
+
+**Desafie a vagueza.** Nunca aceite respostas difusas. "Bom" significa o quê? "Usuários" significa quem? "Simples" significa como?
+
+**Torne o abstrato concreto.** "Me guie pelo uso disso." "Como isso realmente parece?"
+
+**Esclareça ambiguidades.** "Quando você diz Z, quer dizer A ou B?" "Você mencionou X — me conte mais."
+
+**Saiba quando parar.** Quando você entender o que eles querem, por que querem, para quem é, e como "pronto" parece — ofereça prosseguir.
+
+</how_to_question>
+
+<question_types>
+
+Use isso como inspiração, não como checklist. Escolha o que é relevante para o fio.
+
+**Motivação — por que isso existe:**
+- "O que motivou isso?"
+- "O que você faz hoje que isso substituiria?"
+- "O que você faria se isso existisse?"
+
+**Concretude — o que realmente é:**
+- "Me guie pelo uso disso"
+- "Você disse X — como isso realmente parece?"
+- "Me dê um exemplo"
+
+**Esclarecimento — o que eles querem dizer:**
+- "Quando você diz Z, quer dizer A ou B?"
+- "Você mencionou X — me conte mais sobre isso"
+
+**Sucesso — como você saberá que está funcionando:**
+- "Como você saberá que isso está funcionando?"
+- "Como 'pronto' parece?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion para ajudar os usuários a pensar apresentando opções concretas para reagir.
+
+**Boas opções:**
+- Interpretações do que eles podem querer dizer
+- Exemplos específicos para confirmar ou negar
+- Escolhas concretas que revelam prioridades
+
+**Opções ruins:**
+- Categorias genéricas ("Técnico", "Negócios", "Outro")
+- Opções tendenciosas que presumem uma resposta
+- Muitas opções (2-4 é ideal)
+- Cabeçalhos com mais de 12 caracteres (limite rígido — a validação rejeitará)
+
+**Exemplo — resposta vaga:**
+O usuário diz "deve ser rápido"
+
+- header: "Rápido"
+- question: "Rápido como?"
+- options: ["Resposta abaixo de 1 segundo", "Lida com grandes datasets", "Rápido de construir", "Deixa eu explicar"]
+
+**Exemplo — seguindo um fio:**
+O usuário menciona "frustrado com as ferramentas atuais"
+
+- header: "Frustração"
+- question: "O que especificamente te frustra?"
+- options: ["Muitos cliques", "Funcionalidades ausentes", "Não é confiável", "Deixa eu explicar"]
+
+**Dica para usuários — modificar uma opção:**
+Usuários que querem uma versão ligeiramente modificada de uma opção podem selecionar "Outro" e referenciar a opção pelo número: `#1 mas apenas para juntas de dedo` ou `#2 com paginação desabilitada`. Isso evita redigitar o texto completo da opção.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**Quando o usuário quer explicar livremente, PARE de usar AskUserQuestion.**
+
+Se um usuário seleciona "Outro" e a resposta sinaliza que quer descrever algo com suas próprias palavras (ex: "deixa eu descrever", "vou explicar", "outra coisa", ou qualquer resposta aberta que não seja escolher/modificar uma opção existente), você DEVE:
+
+1. **Fazer seu acompanhamento como texto simples** — NÃO via AskUserQuestion
+2. **Aguardar digitarem no prompt normal**
+3. **Retomar AskUserQuestion** apenas após processar a resposta livre
+
+O mesmo se aplica se VOCÊ incluir uma opção indicadora de resposta livre (como "Deixa eu explicar" ou "Descrever em detalhes") e o usuário a selecionar.
+
+**Errado:** Usuário diz "deixa eu descrever" → AskUserQuestion("Que funcionalidade?", ["Funcionalidade A", "Funcionalidade B", "Descrever em detalhes"])
+**Certo:** Usuário diz "deixa eu descrever" → "Pode falar — o que você está pensando?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use isso como **checklist de fundo**, não como estrutura de conversa. Verifique mentalmente enquanto avança. Se houver lacunas, faça perguntas naturalmente.
+
+- [ ] O que estão construindo (concreto o suficiente para explicar a um estranho)
+- [ ] Por que precisa existir (o problema ou desejo que o motiva)
+- [ ] Para quem é (mesmo que seja apenas para eles mesmos)
+- [ ] Como "pronto" parece (resultados observáveis)
+
+Quatro coisas. Se voluntariarem mais, capture.
+
+</context_checklist>
+
+<decision_gate>
+
+Quando você poderia escrever um PROJECT.md claro, ofereça prosseguir:
+
+- header: "Pronto?"
+- question: "Acho que entendi o que você está buscando. Pronto para criar o PROJECT.md?"
+- options:
+  - "Criar PROJECT.md" — Vamos em frente
+  - "Continuar explorando" — Quero compartilhar mais / me faça mais perguntas
+
+Se "Continuar explorando" — pergunte o que eles querem adicionar ou identifique lacunas e aprofunde naturalmente.
+
+Repita até "Criar PROJECT.md" ser selecionado.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Caminhando pelo checklist** — Percorrendo domínios independentemente do que disseram
+- **Perguntas enlatadas** — "Qual é seu valor principal?" "O que está fora do escopo?" independente do contexto
+- **Linguagem corporativa** — "Quais são seus critérios de sucesso?" "Quem são suas partes interessadas?"
+- **Interrogação** — Disparar perguntas sem construir sobre as respostas
+- **Pressa** — Minimizar perguntas para chegar "ao trabalho"
+- **Aceitação superficial** — Aceitar respostas vagas sem aprofundar
+- **Restrições prematuras** — Perguntar sobre stack tecnológico antes de entender a ideia
+- **Habilidades do usuário** — NUNCA pergunte sobre a experiência técnica do usuário. O Claude constrói.
+
+</anti_patterns>
+
+</questioning_guide>