# Referência de Ferramentas CLI do MSD > Referência para o CLI `msd-tools` (`msd-core/bin/msd-tools.cjs`). Para comandos slash e fluxos de usuário, consulte a [Referência de Comandos](COMMANDS.md). Voltar ao [índice de documentação](README.md). --- ## Visão Geral `msd-tools.cjs` centraliza a análise de configuração, resolução de modelos, busca de fases, commits git, verificação de resumos, gerenciamento de estado e operações de templates em comandos, fluxos de trabalho e agentes do MSD. | | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Caminho instalado** | `msd-core/bin/msd-tools.cjs` | | **Implementação** | 20 módulos de domínio em `msd-core/bin/lib/` (o diretório é autoritativo) | | **Status** | Principal superfície de comandos em tempo de execução para orquestração, fluxos de trabalho e automação. | **Uso (CJS):** ```bash node msd-tools.cjs [args] [--raw] [--cwd ] ``` **Flags globais (CJS):** | Flag | Descrição | | -------------- | ---------------------------------------------------------------------------- | | `--raw` | Saída legível por máquina (JSON ou texto simples, sem formatação) | | `--cwd ` | Substitui o diretório de trabalho (para subagentes em sandbox) | | `--ws ` | Contexto de fluxo de trabalho para caminhos `.planning/workstreams/` | --- ## Comandos de Estado Gerencia `.planning/STATE.md` — a memória viva do projeto. ```bash # Carrega configuração completa do projeto + estado como JSON node msd-tools.cjs state load # Exibe o frontmatter do STATE.md como JSON node msd-tools.cjs state json # Atualiza um único campo node msd-tools.cjs state update # Obtém o conteúdo do STATE.md ou uma seção específica node msd-tools.cjs state get [section] # Atualiza múltiplos campos em lote node msd-tools.cjs state patch --field1 val1 --field2 val2 # Incrementa o contador de planos node msd-tools.cjs state advance-plan # Registra métricas de execução node msd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] # Recalcula a barra de progresso node msd-tools.cjs state update-progress # Adiciona uma decisão node msd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] # Ou a partir de arquivos: node msd-tools.cjs state add-decision --summary-file path [--rationale-file path] # Adiciona/resolve bloqueadores node msd-tools.cjs state add-blocker --text "..." node msd-tools.cjs state resolve-blocker --text "..." # Registra continuidade da sessão node msd-tools.cjs state record-session --stopped-at "..." [--resume-file path] # Início de fase — atualiza Status/Última atividade do STATE.md para uma nova fase node msd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT # Sinalização de bloqueador detectável por agentes (usado por discuss-phase / fluxos de UI) node msd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P node msd-tools.cjs state signal-resume ``` ### Snapshot de Estado Análise estruturada do STATE.md completo: ```bash node msd-tools.cjs state-snapshot ``` Retorna JSON com: posição atual, fase, plano, status, decisões, bloqueadores, métricas, última atividade. --- ## Comandos de Fase Gerencia fases — diretórios, numeração e sincronização com o roadmap. ```bash # Localiza diretório de fase pelo número node msd-tools.cjs find-phase # Calcula o próximo número de fase decimal para inserções node msd-tools.cjs phase next-decimal # Adiciona nova fase ao roadmap + cria diretório node msd-tools.cjs phase add # Insere fase decimal após a existente node msd-tools.cjs phase insert # Remove fase, renumera as subsequentes node msd-tools.cjs phase remove [--force] # Marca a fase como concluída, atualiza estado + roadmap node msd-tools.cjs phase complete # Indexa planos com ondas e status node msd-tools.cjs phase-plan-index # Lista fases com filtragem node msd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] ``` --- ## Comandos de Roadmap Analisa e atualiza o `ROADMAP.md`. ```bash # Extrai a seção de fase do ROADMAP.md node msd-tools.cjs roadmap get-phase # Análise completa do roadmap com status em disco node msd-tools.cjs roadmap analyze # Atualiza linha da tabela de progresso a partir do disco node msd-tools.cjs roadmap update-plan-progress ``` --- ## Comandos de Configuração Lê e grava em `.planning/config.json`. ```bash # Inicializa config.json com valores padrão node msd-tools.cjs config-ensure-section # Define um valor de configuração (notação de ponto) node msd-tools.cjs config-set # Obtém um valor de configuração node msd-tools.cjs config-get # Define o perfil de modelo node msd-tools.cjs config-set-model-profile ``` --- ## Resolução de Modelos ```bash # Obtém o modelo para um agente com base no perfil atual node msd-tools.cjs resolve-model # A saída bruta retorna o ID/tier do modelo selecionado. # A saída JSON também inclui o perfil e, quando o runtime ativo suporta, # reasoning_effort. ``` Nomes de agentes: `msd-planner`, `msd-executor`, `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-roadmapper`, `msd-debugger`, `msd-codebase-mapper`, `msd-nyquist-auditor` --- ## Comandos de Verificação Valida planos, fases, referências e commits. ```bash # Verifica arquivo SUMMARY.md node msd-tools.cjs verify-summary [--check-count N] # Verifica estrutura + tarefas do PLAN.md node msd-tools.cjs verify plan-structure # Verifica se todos os planos têm resumos node msd-tools.cjs verify phase-completeness # Verifica se @-refs + caminhos resolvem node msd-tools.cjs verify references # Verifica hashes de commit em lote node msd-tools.cjs verify commits [hash2] ... # Verifica must_haves.artifacts node msd-tools.cjs verify artifacts # Verifica must_haves.key_links node msd-tools.cjs verify key-links ``` --- ## Comandos de Validação Verifica a integridade do projeto. ```bash # Verifica numeração de fases, sincronização disco/roadmap node msd-tools.cjs validate consistency # Verifica integridade de .planning/, com opção de reparo node msd-tools.cjs validate health [--repair] # Verifica utilização da janela de contexto para linha de status / chamadores de hook (v1.40.0) node msd-tools.cjs validate context # Utilização de contexto como superfície JSON tipada (#455) node msd-tools.cjs validate context --json ``` `validate context` emite um envelope estruturado com `utilization`, `status` (`ok` / `warn` / `critical` nos limites de 60% / 70%), e uma string `suggestion`. Os mesmos dados sustentam `/msd-health --context`. Passe `--json` para receber o IR tipado diretamente (útil em scripts e asserções de teste). --- ## Comandos de Template Seleção e preenchimento de templates. ```bash # Seleciona o template de resumo com base na granularidade node msd-tools.cjs template select # Preenche o template com variáveis node msd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] ``` Tipos de template para `fill`: `summary`, `plan`, `verification` --- ## Comandos de Frontmatter Operações CRUD de frontmatter YAML em qualquer arquivo Markdown. ```bash # Extrai frontmatter como JSON node msd-tools.cjs frontmatter get [--field key] # Atualiza único campo node msd-tools.cjs frontmatter set --field key --value jsonVal # Mescla JSON no frontmatter node msd-tools.cjs frontmatter merge --data '{json}' # Valida campos obrigatórios node msd-tools.cjs frontmatter validate --schema plan|summary|verification ``` --- ## Comandos de Scaffold Cria arquivos e diretórios pré-estruturados. ```bash # Cria template CONTEXT.md node msd-tools.cjs scaffold context --phase N # Cria template UAT.md node msd-tools.cjs scaffold uat --phase N # Cria template VERIFICATION.md node msd-tools.cjs scaffold verification --phase N # Cria diretório de fase node msd-tools.cjs scaffold phase-dir --phase N --name "phase name" ``` --- ## Comandos Init (Carregamento de Contexto Composto) Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho. `init onboard [--fast] [--text]` retorna, para `/msd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding. ```bash node msd-tools.cjs init execute-phase node msd-tools.cjs init plan-phase node msd-tools.cjs init new-project node msd-tools.cjs init new-milestone node msd-tools.cjs init onboard [--fast] [--text] node msd-tools.cjs init quick node msd-tools.cjs init resume node msd-tools.cjs init verify-work node msd-tools.cjs init phase-op node msd-tools.cjs init todos [area] node msd-tools.cjs init milestone-op node msd-tools.cjs init map-codebase node msd-tools.cjs init progress # Init com escopo de fluxo de trabalho (flag `--ws`) node msd-tools.cjs init execute-phase --ws node msd-tools.cjs init plan-phase --ws ``` **Tratamento de payloads grandes:** Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna `@file:/tmp/msd-init-XXXXX.json`. Os fluxos de trabalho verificam o prefixo `@file:` e leem do disco: ```bash INIT=$(node msd-tools.cjs init execute-phase "1") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` --- ## Comandos de Milestone ```bash # Arquiva milestone node msd-tools.cjs milestone complete (--confirm | --dry-run) [--name ] [--no-archive-phases] [--force] [--archive-quick] # Marca requisitos como concluídos node msd-tools.cjs requirements mark-complete # Aceita: REQ-01,REQ-02 ou REQ-01 REQ-02 ou [REQ-01, REQ-02] ``` --- ## Habilidades de Agente Emite o bloco de habilidades para um tipo de agente específico. ```bash # Emite bloco XML bruto de habilidades (padrão — seguro para expansão de shell) node msd-tools.cjs agent-skills # Emite superfície JSON tipada (#455) — { agent_type, block, skills_count } node msd-tools.cjs agent-skills --json ``` A flag `--json` retorna um objeto IR tipado adequado para consumo estruturado e asserções de teste, enquanto o padrão (sem flag) preserva a saída XML bruta que as expansões de shell de fluxo de trabalho necessitam. --- ## Manifesto de Habilidades Pré-computa e armazena em cache a descoberta de habilidades para carregamento mais rápido de comandos. ```bash # Gera manifesto de habilidades (grava em .claude/skill-manifest.json) node msd-tools.cjs skill-manifest # Gera com caminho de saída personalizado node msd-tools.cjs skill-manifest --output ``` Retorna mapeamento JSON de todas as habilidades MSD disponíveis com seus metadados (nome, descrição, caminho de arquivo, dicas de argumentos). Usado pelo instalador e hooks de início de sessão para evitar varreduras repetidas do sistema de arquivos. --- ## Comandos Utilitários ```bash # Converte texto em slug seguro para URL node msd-tools.cjs generate-slug "Some Text Here" # → some-text-here # Obtém timestamp node msd-tools.cjs current-timestamp [full|date|filename] # Conta e lista tarefas pendentes node msd-tools.cjs list-todos [area] # Verifica existência de arquivo/diretório node msd-tools.cjs verify-path-exists # Agrega todos os dados de SUMMARY.md node msd-tools.cjs history-digest # Extrai dados estruturados de SUMMARY.md node msd-tools.cjs summary-extract [--fields field1,field2] # Estatísticas do projeto node msd-tools.cjs stats [json|table] # Renderização de progresso (legível por humanos) node msd-tools.cjs progress [json|table|bar] # Progresso como superfície JSON tipada (#455) node msd-tools.cjs progress --json # Conclui uma tarefa node msd-tools.cjs todo complete [--dry-run] # Auditoria UAT — verifica todas as fases em busca de itens não resolvidos node msd-tools.cjs audit-uat # Fila de auditoria entre artefatos — verifica `.planning/` em busca de itens de auditoria não resolvidos node msd-tools.cjs audit-open [--json] # Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/msd-import --from-gsd2`) node msd-tools.cjs from-gsd2 [--path ] [--force] [--dry-run] # Commit git com verificações de configuração node msd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] [--respect-staged] ``` > `--no-verify`: Ignora hooks de pré-commit. Usado por agentes executores paralelos durante a execução baseada em ondas para evitar contenção de bloqueio de build (ex.: conflitos de cargo lock em projetos Rust). O orquestrador executa os hooks uma vez após cada onda ser concluída. Não use `--no-verify` durante a execução sequencial — deixe os hooks rodarem normalmente. > `--files ` **comportamento de staging**: por padrão, `--files` executa `git add -- ` para cada arquivo nomeado antes de commitar. Isso sobrescreve qualquer staging por hunk configurado via `git add -p`. Passe `--respect-staged` para ignorar o passo `git add` e commitar apenas o que já está no índice dentro do pathspec solicitado. Se nada estiver staged nesse escopo, o comando retorna `{ committed: false, reason: 'nothing staged' }` sem erro. O `-- ` pathspec final no commit é aplicado em ambos os modos, portanto arquivos staged fora do escopo `--files` nunca são incluídos (invariante #3061). ```bash # Busca na web (requer chave de API do Brave) node msd-tools.cjs websearch [--limit N] [--freshness day|week|month] ``` --- ## Graphify Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. Requer `graphify.enabled: true` em `config.json` (consulte a [Referência de Configuração](CONFIGURATION.md#graphify-settings)). ```bash # Constrói ou reconstrói o grafo de conhecimento node msd-tools.cjs graphify build # Pesquisa um termo no grafo node msd-tools.cjs graphify query # Exibe atualidade e estatísticas do grafo node msd-tools.cjs graphify status # Exibe alterações desde a última construção node msd-tools.cjs graphify diff # Grava um snapshot nomeado do grafo atual node msd-tools.cjs graphify snapshot [name] ``` Ponto de entrada para o usuário: `/msd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#msd-graphify)). --- ## Arquitetura de Módulos | Módulo | Arquivo | Exportações | |--------|------|---------| | Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, utilitários compartilhados, re-exportações de compatibilidade | | State | `lib/state.cjs` | Todos os subcomandos `state`, `state-snapshot` | | Phase | `lib/phase.cjs` | CRUD de fase, `find-phase`, `phase-plan-index`, `phases list` | | Planning Workspace | `lib/planning-workspace.cjs` | Costura de planejamento: `planningDir`, `planningPaths`, roteamento de fluxo de trabalho ativo, `.planning/.lock` | | Roadmap | `lib/roadmap.cjs` | Análise de roadmap, extração de fase, atualizações de progresso | | Config | `lib/config.cjs` | Leitura/gravação de configuração, inicialização de seção | | Verify | `lib/verify.cjs` | Todos os comandos de verificação e validação | | Template | `lib/template.cjs` | Seleção de template e preenchimento de variáveis | | Frontmatter | `lib/frontmatter.cjs` | CRUD de frontmatter YAML | | Init | `lib/init.cjs` | Carregamento de contexto composto para todos os fluxos de trabalho | | Milestone | `lib/milestone.cjs` | Arquivamento de milestone, marcação de requisitos | | Commands | `lib/commands.cjs` | Diversos: slug, timestamp, todos, scaffold, stats, websearch | | Model Profiles | `lib/model-profiles.cjs` | Tabela de resolução de perfis | | UAT | `lib/uat.cjs` | Auditoria UAT/verificação entre fases | | Profile Output | `lib/profile-output.cjs` | Formatação de perfil do desenvolvedor | | Profile Pipeline | `lib/profile-pipeline.cjs` | Pipeline de análise de sessão | | Graphify | `lib/graphify.cjs` | Construção/consulta/status/diff/snapshot do grafo de conhecimento (suporta `/msd-graphify`) | | Learnings | `lib/learnings.cjs` | Extrai aprendizados de artefatos de fases/SUMMARY (suporta `/msd-extract-learnings`) | | Audit | `lib/audit.cjs` | Manipuladores de fila de auditoria de fase/milestone; helper `audit-open` | | MSD2 Import | `lib/gsd2-import.cjs` | Importador de migração reversa de projetos GSD-2 (suporta `/msd-import --from-gsd2`) | | Intel | `lib/intel.cjs` | Índice de inteligência de código consultável (suporta `/msd-map-codebase --query`) | --- ## Roteamento CLI do Revisor `review.models.` mapeia um sabor de revisor para um comando shell invocado pelo fluxo de trabalho de revisão de código. Defina via [`/msd-config --integrations`](COMMANDS.md#msd-config) ou diretamente: ```bash node msd-tools.cjs config-set review.models.codex "codex exec --model gpt-5" node msd-tools.cjs config-set review.models.agy "gemini-3.1-pro-preview" node msd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4" node msd-tools.cjs config-set review.models.claude "" # limpa — retorna ao modelo da sessão ``` Os slugs são validados contra `[a-zA-Z0-9_-]+`; slugs vazios ou contendo caminhos são rejeitados. Consulte [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) para a referência completa do campo. ## Tratamento de Segredos As chaves de API configuradas via `/msd-settings` (`brave_search`, `firecrawl`, `exa_search`) são gravadas em texto simples em `.planning/config.json`, mas são mascaradas (`****`) em toda saída de `config-set` / `config-get`, tabela de confirmação e prompt interativo. Consulte `msd-core/bin/lib/secrets.cjs` para a implementação do mascaramento. O próprio arquivo `config.json` é o limite de segurança — proteja-o com permissões do sistema de arquivos e mantenha-o fora do git (`.planning/` está no gitignore por padrão). --- ## Relacionados - [Comandos](COMMANDS.md) - [Configuração](CONFIGURATION.md) - [Arquitetura](ARCHITECTURE.md) - [índice de documentação](README.md)