eliott/get-shit-done
1
0
Fork 0
mirror of https://github.com/glittercowboy/get-shit-done synced 2026-04-25 17:25:23 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
2404b40a15e97c7a4d11a025421db34549703a51
get-shit-done/docs/CLI-TOOLS.md
Rezolv 86fb9c85c3 docs(sdk): registry docs and gsd-sdk query call sites (#2302 Track B) (#2340) 
* feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A)

Golden/read-only parity tests and registry alignment, query handler fixes
(check-completion, state-mutation, commit, validate, summary, etc.), and
WAITING.json dual-write for .gsd/.planning readers.

Refs gsd-build/get-shit-done#2341

* fix(sdk): getMilestoneInfo matches GSD ROADMAP (🟡, last bold, STATE fallback)

- Recognize in-flight 🟡 milestone bullets like 🚧.
- Derive from last **vX.Y Title** before ## Phases when emoji absent.
- Fall back to STATE.md milestone when ROADMAP is missing; use last bare vX.Y
  in cleaned text instead of first (avoids v1.0 from shipped list).
- Fixes init.execute-phase milestone_version and buildStateFrontmatter after
  state.begin-phase (syncStateFrontmatter).

* feat(sdk): phase list, plan task structure, requirements extract handlers

- Register phase.list-plans, phase.list-artifacts, plan.task-structure,
  requirements.extract-from-plans (SDK-only; golden-policy exceptions).
- Add unit tests; document in QUERY-HANDLERS.md.
- writeProfile: honor --output, render dimensions, return profile_path and dimensions_scored.

* feat(sdk): centralize getGsdAgentsDir in query helpers

Extract agent directory resolution to helpers (GSD_AGENTS_DIR, primary
~/.claude/agents, legacy path). Use from init and docs-init init bundles.

docs(15): add 15-CONTEXT for autonomous phase-15 run.

* feat(sdk): query CLI CJS fallback and session correlation

- createRegistry(eventStream, sessionId) threads correlation into mutation events
- gsd-sdk query falls back to gsd-tools.cjs when no native handler matches
  (disable with GSD_QUERY_FALLBACK=off); stderr bridge warnings
- Export createRegistry from @gsd-build/sdk; add sdk/README.md
- Update QUERY-HANDLERS.md and registry module docs for fallback + sessionId
- Agents: prefer node dist/cli.js query over cat/grep for STATE and plans

* fix(sdk): init phase_found parity, docs-init agents path, state field extract

- Normalize findPhase not-found to null before roadmap fallback (matches findPhaseInternal)

- docs-init: use detectRuntime + resolveAgentsDir for checkAgentsInstalled

- state.cjs stateExtractField: horizontal whitespace only after colon (YAML progress guard)

- Tests: commit_docs default true; config-get golden uses temp config; golden integration green

Refs: #2302

* refactor(sdk): share SessionJsonlRecord in profile-extract-messages

CodeRabbit nit: dedupe JSONL record shape for isGenuineUserMessage and streamExtractMessages.

* fix(sdk): address CodeRabbit major threads (paths, gates, audit, verify)

- Resolve @file: and CLI JSON indirection relative to projectDir; guard empty normalized query command

- plan.task-structure + intel extract/patch-meta: resolvePathUnderProject containment

- check.config-gates: safe string booleans; plan_checker alias precedence over plan_check default

- state.validate/sync: phaseTokenMatches + comparePhaseNum ordering

- verify.schema-drift: token match phase dirs; files_modified from parsed frontmatter

- audit-open: has_scan_errors, unreadable rows, human report when scans fail

- requirements PLANNED key PLAN for root PLAN.md; gsd-tools timeout note

- ingest-docs: repo-root path containment; classifier output slug-hash

Golden parity test strips has_scan_errors until CJS adds field.

* fix: Resolve CodeRabbit security and quality findings
- Secure intel.ts and cli.ts against path traversal
- Catch and validate git add status in commit.ts
- Expand roadmap milestone marker extraction
- Fix parsing array-of-objects in frontmatter YAML
- Fix unhandled config evaluations
- Improve coverage test parity mapping

* docs(sdk): registry docs and gsd-sdk query call sites (#2302 Track B)

Update CHANGELOG, architecture and user guides, workflow call sites, and read-guard tests for gsd-sdk query; sync ARCHITECTURE.md command/workflow counts and directory-tree totals with the repo (80 commands, 77 workflows).

Address CodeRabbit: fix markdown tables and emphasis; align CLI-TOOLS GSDTools and state.read docs with implementation; correct roadmap handler name in universal-anti-patterns; resolve settings workflow config path without relying on config_path from state.load.

Refs gsd-build/get-shit-done#2340

* test: raise planner character extraction limit to 48K

* fix(sdk): resolve build TS error and doc conflict markers
2026-04-20 18:09:21 -04:00

17 KiB
Raw Blame History

GSD CLI Tools Reference

Surface-area reference for get-shit-done/bin/gsd-tools.cjs (legacy Node CLI). Workflows and agents should prefer gsd-sdk query or @gsd-build/sdk where a handler exists — see SDK and programmatic access. For slash commands and user flows, see Command Reference.

Overview

gsd-tools.cjs centralizes config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations across GSD commands, workflows, and agents.
Shipped path get-shit-done/bin/gsd-tools.cjs
Implementation 20 domain modules under get-shit-done/bin/lib/ (the directory is authoritative)
Status Maintained for parity tests and CJS-only entrypoints; gsd-sdk query / SDK registry are the supported path for new orchestration (see QUERY-HANDLERS.md).

Usage (CJS):

node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]

Global flags (CJS):

Flag Description
--raw Machine-readable output (JSON or plain text, no formatting)
--cwd <path> Override working directory (for sandboxed subagents)
--ws <name> Workstream context (also honored when the SDK spawns this binary; see below)

SDK and programmatic access

Use this when authoring workflows, not when you only need the command list below.

1. CLI — gsd-sdk query <argv…>

  • Resolves argv with the same longest-prefix rules as the typed registry (resolveQueryArgv in sdk/src/query/registry.ts). Unregistered commands fail fast — use node …/gsd-tools.cjs only for handlers not in the registry.
  • Full matrix (CJS command → registry key, CLI-only tools, aliases, golden tiers): sdk/src/query/QUERY-HANDLERS.md.

2. TypeScript — @gsd-build/sdk (GSDTools, createRegistry)

  • GSDTools (used by PhaseRunner, InitRunner, and GSD.createTools()) always shells out to gsd-tools.cjs via execFile — there is no in-process registry path on this class. For typed, in-process dispatch use createRegistry() from sdk/src/query/index.ts, or invoke gsd-sdk query (see QUERY-HANDLERS.md).
  • Conventions: mutation event wiring, GSDError vs { data: { error } }, locks, and stubs — QUERY-HANDLERS.md.

CJS → SDK examples (same project directory):

Legacy CJS Preferred gsd-sdk query (examples)
node gsd-tools.cjs init phase-op 12 gsd-sdk query init phase-op 12
node gsd-tools.cjs phase-plan-index 12 gsd-sdk query phase-plan-index 12
node gsd-tools.cjs state json gsd-sdk query state json
node gsd-tools.cjs roadmap analyze gsd-sdk query roadmap analyze

SDK state reads: gsd-sdk query state json / state.json and gsd-sdk query state load / state.load currently share one native handler (rebuilt STATE.md frontmatter — CJS cmdStateJson). The legacy CJS state load payload (config, state_raw, existence flags) is still CLI-only via node …/gsd-tools.cjs state load until a separate registry handler exists. Full routing and golden rules: QUERY-HANDLERS.md.

CLI-only (not in registry): e.g. graphify, from-gsd2 / gsd2-import — call gsd-tools.cjs until registered.

Mutation events (SDK): QUERY_MUTATION_COMMANDS in sdk/src/query/index.ts lists commands that may emit structured events after a successful dispatch. Exceptions called out in QUERY-HANDLERS: state validate (read-only), skill-manifest (writes only with --write), intel update (stub).

Golden parity: Policy and CJS↔SDK test categories are documented under Golden parity in QUERY-HANDLERS.md.

State Commands

Manage .planning/STATE.md — the project's living memory.

# Load full project config + state as JSON
node gsd-tools.cjs state load

# Output STATE.md frontmatter as JSON
node gsd-tools.cjs state json

# Update a single field
node gsd-tools.cjs state update <field> <value>

# Get STATE.md content or a specific section
node gsd-tools.cjs state get [section]

# Batch update multiple fields
node gsd-tools.cjs state patch --field1 val1 --field2 val2

# Increment plan counter
node gsd-tools.cjs state advance-plan

# Record execution metrics
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]

# Recalculate progress bar
node gsd-tools.cjs state update-progress

# Add a decision
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# Or from files:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]

# Add/resolve blockers
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."

# Record session continuity
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]

# Phase start — update STATE.md Status/Last activity for a new phase
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT

# Agent-discoverable blocker signalling (used by discuss-phase / UI flows)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume

State Snapshot

Structured parse of the full STATE.md:

node gsd-tools.cjs state-snapshot

Returns JSON with: current position, phase, plan, status, decisions, blockers, metrics, last activity.

Phase Commands

Manage phases — directories, numbering, and roadmap sync.

# Find phase directory by number
node gsd-tools.cjs find-phase <phase>

# Calculate next decimal phase number for insertions
node gsd-tools.cjs phase next-decimal <phase>

# Append new phase to roadmap + create directory
node gsd-tools.cjs phase add <description>

# Insert decimal phase after existing
node gsd-tools.cjs phase insert <after> <description>

# Remove phase, renumber subsequent
node gsd-tools.cjs phase remove <phase> [--force]

# Mark phase complete, update state + roadmap
node gsd-tools.cjs phase complete <phase>

# Index plans with waves and status
node gsd-tools.cjs phase-plan-index <phase>

# List phases with filtering
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]

Roadmap Commands

Parse and update ROADMAP.md.

# Extract phase section from ROADMAP.md
node gsd-tools.cjs roadmap get-phase <phase>

# Full roadmap parse with disk status
node gsd-tools.cjs roadmap analyze

# Update progress table row from disk
node gsd-tools.cjs roadmap update-plan-progress <N>

Config Commands

Read and write .planning/config.json.

# Initialize config.json with defaults
node gsd-tools.cjs config-ensure-section

# Set a config value (dot notation)
node gsd-tools.cjs config-set <key> <value>

# Get a config value
node gsd-tools.cjs config-get <key>

# Set model profile
node gsd-tools.cjs config-set-model-profile <profile>

Model Resolution

# Get model for agent based on current profile
node gsd-tools.cjs resolve-model <agent-name>
# Returns: opus | sonnet | haiku | inherit

Agent names: 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

Verification Commands

Validate plans, phases, references, and commits.

# Verify SUMMARY.md file
node gsd-tools.cjs verify-summary <path> [--check-count N]

# Check PLAN.md structure + tasks
node gsd-tools.cjs verify plan-structure <file>

# Check all plans have summaries
node gsd-tools.cjs verify phase-completeness <phase>

# Check @-refs + paths resolve
node gsd-tools.cjs verify references <file>

# Batch verify commit hashes
node gsd-tools.cjs verify commits <hash1> [hash2] ...

# Check must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>

# Check must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>

Validation Commands

Check project integrity.

# Check phase numbering, disk/roadmap sync
node gsd-tools.cjs validate consistency

# Check .planning/ integrity, optionally repair
node gsd-tools.cjs validate health [--repair]

Template Commands

Template selection and filling.

# Select summary template based on granularity
node gsd-tools.cjs template select <type>

# Fill template with variables
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']

Template types for fill: summary, plan, verification

Frontmatter Commands

YAML frontmatter CRUD operations on any Markdown file.

# Extract frontmatter as JSON
node gsd-tools.cjs frontmatter get <file> [--field key]

# Update single field
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal

# Merge JSON into frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'

# Validate required fields
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification

Scaffold Commands

Create pre-structured files and directories.

# Create CONTEXT.md template
node gsd-tools.cjs scaffold context --phase N

# Create UAT.md template
node gsd-tools.cjs scaffold uat --phase N

# Create VERIFICATION.md template
node gsd-tools.cjs scaffold verification --phase N

# Create phase directory
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"

Init Commands (Compound Context Loading)

Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data.

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 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

# Workstream-scoped init (SDK --ws flag)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>

Large payload handling: When output exceeds ~50KB, the CLI writes to a temp file and returns @file:/tmp/gsd-init-XXXXX.json. Workflows check for the @file: prefix and read from disk:

INIT=$(node gsd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Milestone Commands

# Archive milestone
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]

# Mark requirements as complete
node gsd-tools.cjs requirements mark-complete <ids>
# Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02]

Skill Manifest

Pre-compute and cache skill discovery for faster command loading.

# Generate skill manifest (writes to .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest

# Generate with custom output path
node gsd-tools.cjs skill-manifest --output <path>

Returns JSON mapping of all available GSD skills with their metadata (name, description, file path, argument hints). Used by the installer and session-start hooks to avoid repeated filesystem scans.

Utility Commands

# Convert text to URL-safe slug
node gsd-tools.cjs generate-slug "Some Text Here"
# → some-text-here

# Get timestamp
node gsd-tools.cjs current-timestamp [full|date|filename]

# Count and list pending todos
node gsd-tools.cjs list-todos [area]

# Check file/directory existence
node gsd-tools.cjs verify-path-exists <path>

# Aggregate all SUMMARY.md data
node gsd-tools.cjs history-digest

# Extract structured data from SUMMARY.md
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]

# Project statistics
node gsd-tools.cjs stats [json|table]

# Progress rendering
node gsd-tools.cjs progress [json|table|bar]

# Complete a todo
node gsd-tools.cjs todo complete <filename>

# UAT audit — scan all phases for unresolved items
node gsd-tools.cjs audit-uat

# Cross-artifact audit queue — scan `.planning/` for unresolved audit items
node gsd-tools.cjs audit-open [--json]

# Reverse-migrate a GSD-2 project into the current structure (backs `/gsd-from-gsd2`)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]

# Git commit with config checks
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]

--no-verify: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use --no-verify during sequential execution — let hooks run normally.

Web search (requires Brave API key)

node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month]


---

## Graphify

Build, query, and inspect the project knowledge graph in `.planning/graphs/`. Requires `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)). Graphify is **CJS-only**: `gsd-sdk query` does not yet register graphify handlers — always use `node gsd-tools.cjs graphify …`.

```bash
# Build or rebuild the knowledge graph
node gsd-tools.cjs graphify build

# Search the graph for a term
node gsd-tools.cjs graphify query <term>

# Show graph freshness and statistics
node gsd-tools.cjs graphify status

# Show changes since the last build
node gsd-tools.cjs graphify diff

# Write a named snapshot of the current graph
node gsd-tools.cjs graphify snapshot [name]

User-facing entry point: /gsd-graphify (see Command Reference).

Module Architecture

Module File Exports
Core lib/core.cjs error(), output(), parseArgs(), shared utilities
State lib/state.cjs All state subcommands, state-snapshot
Phase lib/phase.cjs Phase CRUD, find-phase, phase-plan-index, phases list
Roadmap lib/roadmap.cjs Roadmap parsing, phase extraction, progress updates
Config lib/config.cjs Config read/write, section initialization
Verify lib/verify.cjs All verification and validation commands
Template lib/template.cjs Template selection and variable filling
Frontmatter lib/frontmatter.cjs YAML frontmatter CRUD
Init lib/init.cjs Compound context loading for all workflows
Milestone lib/milestone.cjs Milestone archival, requirements marking
Commands lib/commands.cjs Misc: slug, timestamp, todos, scaffold, stats, websearch
Model Profiles lib/model-profiles.cjs Profile resolution table
UAT lib/uat.cjs Cross-phase UAT/verification audit
Profile Output lib/profile-output.cjs Developer profile formatting
Profile Pipeline lib/profile-pipeline.cjs Session analysis pipeline
Graphify lib/graphify.cjs Knowledge graph build/query/status/diff/snapshot (backs /gsd-graphify)
Learnings lib/learnings.cjs Extract learnings from phases/SUMMARY artifacts (backs /gsd-extract-learnings)
Audit lib/audit.cjs Phase/milestone audit queue handlers; audit-open helper
GSD2 Import lib/gsd2-import.cjs Reverse-migration importer from GSD-2 projects (backs /gsd-from-gsd2)
Intel lib/intel.cjs Queryable codebase intelligence index (backs /gsd-intel)

See also

Reference in New Issue View Git Blame Copy Permalink