19 KiB
Referência de Ferramentas CLI do GSD
Referência para o CLI
gsd-tools(get-shit-done/bin/gsd-tools.cjs). Para comandos slash e fluxos de usuário, consulte a Referência de Comandos. Voltar ao índice de documentação.
Visão Geral
gsd-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 GSD.
| Caminho instalado | get-shit-done/bin/gsd-tools.cjs |
| Implementação | 20 módulos de domínio em get-shit-done/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):
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
Flags globais (CJS):
| Flag | Descrição |
|---|---|
--raw |
Saída legível por máquina (JSON ou texto simples, sem formatação) |
--cwd <path> |
Substitui o diretório de trabalho (para subagentes em sandbox) |
--ws <name> |
Contexto de fluxo de trabalho para caminhos .planning/workstreams/<name> |
Comandos de Estado
Gerencia .planning/STATE.md — a memória viva do projeto.
# Carrega configuração completa do projeto + estado como JSON
node gsd-tools.cjs state load
# Exibe o frontmatter do STATE.md como JSON
node gsd-tools.cjs state json
# Atualiza um único campo
node gsd-tools.cjs state update <field> <value>
# Obtém o conteúdo do STATE.md ou uma seção específica
node gsd-tools.cjs state get [section]
# Atualiza múltiplos campos em lote
node gsd-tools.cjs state patch --field1 val1 --field2 val2
# Incrementa o contador de planos
node gsd-tools.cjs state advance-plan
# Registra métricas de execução
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
# Recalcula a barra de progresso
node gsd-tools.cjs state update-progress
# Adiciona uma decisão
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# Ou a partir de arquivos:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# Adiciona/resolve bloqueadores
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."
# Registra continuidade da sessão
node gsd-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 gsd-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 gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
Snapshot de Estado
Análise estruturada do STATE.md completo:
node gsd-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.
# Localiza diretório de fase pelo número
node gsd-tools.cjs find-phase <phase>
# Calcula o próximo número de fase decimal para inserções
node gsd-tools.cjs phase next-decimal <phase>
# Adiciona nova fase ao roadmap + cria diretório
node gsd-tools.cjs phase add <description>
# Insere fase decimal após a existente
node gsd-tools.cjs phase insert <after> <description>
# Remove fase, renumera as subsequentes
node gsd-tools.cjs phase remove <phase> [--force]
# Marca a fase como concluída, atualiza estado + roadmap
node gsd-tools.cjs phase complete <phase>
# Indexa planos com ondas e status
node gsd-tools.cjs phase-plan-index <phase>
# Lista fases com filtragem
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
Comandos de Roadmap
Analisa e atualiza o ROADMAP.md.
# Extrai a seção de fase do ROADMAP.md
node gsd-tools.cjs roadmap get-phase <phase>
# Análise completa do roadmap com status em disco
node gsd-tools.cjs roadmap analyze
# Atualiza linha da tabela de progresso a partir do disco
node gsd-tools.cjs roadmap update-plan-progress <N>
Comandos de Configuração
Lê e grava em .planning/config.json.
# Inicializa config.json com valores padrão
node gsd-tools.cjs config-ensure-section
# Define um valor de configuração (notação de ponto)
node gsd-tools.cjs config-set <key> <value>
# Obtém um valor de configuração
node gsd-tools.cjs config-get <key>
# Define o perfil de modelo
node gsd-tools.cjs config-set-model-profile <profile>
Resolução de Modelos
# Obtém o modelo para um agente com base no perfil atual
node gsd-tools.cjs resolve-model <agent-name>
# 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: gsd-planner, gsd-executor, gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-roadmapper, gsd-debugger, gsd-codebase-mapper, gsd-nyquist-auditor
Comandos de Verificação
Valida planos, fases, referências e commits.
# Verifica arquivo SUMMARY.md
node gsd-tools.cjs verify-summary <path> [--check-count N]
# Verifica estrutura + tarefas do PLAN.md
node gsd-tools.cjs verify plan-structure <file>
# Verifica se todos os planos têm resumos
node gsd-tools.cjs verify phase-completeness <phase>
# Verifica se @-refs + caminhos resolvem
node gsd-tools.cjs verify references <file>
# Verifica hashes de commit em lote
node gsd-tools.cjs verify commits <hash1> [hash2] ...
# Verifica must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>
# Verifica must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>
Comandos de Validação
Verifica a integridade do projeto.
# Verifica numeração de fases, sincronização disco/roadmap
node gsd-tools.cjs validate consistency
# Verifica integridade de .planning/, com opção de reparo
node gsd-tools.cjs validate health [--repair]
# Verifica utilização da janela de contexto para linha de status / chamadores de hook (v1.40.0)
node gsd-tools.cjs validate context
# Utilização de contexto como superfície JSON tipada (#455)
node gsd-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 /gsd-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.
# Seleciona o template de resumo com base na granularidade
node gsd-tools.cjs template select <type>
# Preenche o template com variáveis
node gsd-tools.cjs template fill <type> --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.
# Extrai frontmatter como JSON
node gsd-tools.cjs frontmatter get <file> [--field key]
# Atualiza único campo
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
# Mescla JSON no frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
# Valida campos obrigatórios
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
Comandos de Scaffold
Cria arquivos e diretórios pré-estruturados.
# Cria template CONTEXT.md
node gsd-tools.cjs scaffold context --phase N
# Cria template UAT.md
node gsd-tools.cjs scaffold uat --phase N
# Cria template VERIFICATION.md
node gsd-tools.cjs scaffold verification --phase N
# Cria diretório de fase
node gsd-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 /gsd-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.
node gsd-tools.cjs init execute-phase <phase>
node gsd-tools.cjs init plan-phase <phase>
node gsd-tools.cjs init new-project
node gsd-tools.cjs init new-milestone
node gsd-tools.cjs init onboard [--fast] [--text]
node gsd-tools.cjs init quick <description>
node gsd-tools.cjs init resume
node gsd-tools.cjs init verify-work <phase>
node gsd-tools.cjs init phase-op <phase>
node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# Init com escopo de fluxo de trabalho (flag `--ws`)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
Tratamento de payloads grandes: Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna @file:/tmp/gsd-init-XXXXX.json. Os fluxos de trabalho verificam o prefixo @file: e leem do disco:
INIT=$(node gsd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
Comandos de Milestone
# Arquiva milestone
node gsd-tools.cjs milestone complete <version> [--name <name>] [--no-archive-phases]
# Marca requisitos como concluídos
node gsd-tools.cjs requirements mark-complete <ids>
# 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.
# Emite bloco XML bruto de habilidades (padrão — seguro para expansão de shell)
node gsd-tools.cjs agent-skills <agent-type>
# Emite superfície JSON tipada (#455) — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --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.
# Gera manifesto de habilidades (grava em .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest
# Gera com caminho de saída personalizado
node gsd-tools.cjs skill-manifest --output <path>
Retorna mapeamento JSON de todas as habilidades GSD 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
# Converte texto em slug seguro para URL
node gsd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# Obtém timestamp
node gsd-tools.cjs current-timestamp [full|date|filename]
# Conta e lista tarefas pendentes
node gsd-tools.cjs list-todos [area]
# Verifica existência de arquivo/diretório
node gsd-tools.cjs verify-path-exists <path>
# Agrega todos os dados de SUMMARY.md
node gsd-tools.cjs history-digest
# Extrai dados estruturados de SUMMARY.md
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# Estatísticas do projeto
node gsd-tools.cjs stats [json|table]
# Renderização de progresso (legível por humanos)
node gsd-tools.cjs progress [json|table|bar]
# Progresso como superfície JSON tipada (#455)
node gsd-tools.cjs progress --json
# Conclui uma tarefa
node gsd-tools.cjs todo complete <filename>
# Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
node gsd-tools.cjs audit-uat
# Fila de auditoria entre artefatos — verifica `.planning/` em busca de itens de auditoria não resolvidos
node gsd-tools.cjs audit-open [--json]
# Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/gsd-import --from-gsd2`)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# Commit git com verificações de configuração
node gsd-tools.cjs commit <message> [--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-verifydurante a execução sequencial — deixe os hooks rodarem normalmente.--files <paths>comportamento de staging: por padrão,--filesexecutagit add -- <path>para cada arquivo nomeado antes de commitar. Isso sobrescreve qualquer staging por hunk configurado viagit add -p. Passe--respect-stagedpara ignorar o passogit adde 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-- <paths>pathspec final no commit é aplicado em ambos os modos, portanto arquivos staged fora do escopo--filesnunca são incluídos (invariante #3061).
# Busca na web (requer chave de API do Brave)
node gsd-tools.cjs websearch <query> [--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).
# Constrói ou reconstrói o grafo de conhecimento
node gsd-tools.cjs graphify build
# Pesquisa um termo no grafo
node gsd-tools.cjs graphify query <term>
# Exibe atualidade e estatísticas do grafo
node gsd-tools.cjs graphify status
# Exibe alterações desde a última construção
node gsd-tools.cjs graphify diff
# Grava um snapshot nomeado do grafo atual
node gsd-tools.cjs graphify snapshot [name]
Ponto de entrada para o usuário: /gsd-graphify (consulte a Referência de Comandos).
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 /gsd-graphify) |
| Learnings | lib/learnings.cjs |
Extrai aprendizados de artefatos de fases/SUMMARY (suporta /gsd-extract-learnings) |
| Audit | lib/audit.cjs |
Manipuladores de fila de auditoria de fase/milestone; helper audit-open |
| GSD2 Import | lib/gsd2-import.cjs |
Importador de migração reversa de projetos GSD-2 (suporta /gsd-import --from-gsd2) |
| Intel | lib/intel.cjs |
Índice de inteligência de código consultável (suporta /gsd-map-codebase --query) |
Roteamento CLI do Revisor
review.models.<cli> mapeia um sabor de revisor para um comando shell invocado pelo fluxo de trabalho de revisão de código. Defina via /gsd-config --integrations ou diretamente:
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-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 para a referência completa do campo.
Tratamento de Segredos
As chaves de API configuradas via /gsd-settings (brave_search, firecrawl, exa_search) são gravadas em texto simples em .planning/config.json, mas são mascaradas (****<last-4>) em toda saída de config-set / config-get, tabela de confirmação e prompt interativo. Consulte get-shit-done/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).