* docs: finish trust-bug fixes in user guide and commands Correct load-bearing defects in the v1.36.0 docs corpus so readers stop acting on wrong defaults and stale exhaustiveness claims. - README.md: drop "Complete feature"/"Every command"/"All 18 agents" exhaustiveness claims; replace version-pinned "What's new in v1.32" bullet with a CHANGELOG pointer. - CONFIGURATION.md: fix `claude_md_path` default (null/none -> `./CLAUDE.md`) in both Full Schema and core settings table; correct `workflow.tdd_mode` provenance from "Added in v1.37" to "Added in v1.36". - USER-GUIDE.md: fix `workflow.discuss_mode` default (`standard` -> `discuss`) in the workflow-toggles table AND in the abbreviated Full Schema JSON block above it; align the Options cell with the shipped enum. - COMMANDS.md: drop "Complete command syntax" subtitle overclaim to match the README posture. - AGENTS.md: weaken "All 21 specialized agents" header to reflect that the `agents/` filesystem is authoritative (shipped roster is 31). Part 1 of a stacked docs refresh series (PR 1/4). * docs: refresh shipped surface coverage for v1.36 Close the v1.36.0 shipped-surface gaps in the docs corpus. - COMMANDS.md: add /gsd-graphify section (build/query/status/diff) and its config gate; expand /gsd-quick with --validate flag and list/ status/resume subcommands; expand /gsd-thread with list --open, list --resolved, close <slug>, status <slug>. - CLI-TOOLS.md: replace the hardcoded "15 domain modules" count with a pointer to the Module Architecture table; add a graphify verb-family section (build/query/status/diff/snapshot); add Graphify and Learnings rows to the Module Architecture table. - FEATURES.md: add TOC entries for #116 TDD Pipeline Mode and #117 Knowledge Graph Integration; add the #117 body with REQ-GRAPH-01..05. - CONFIGURATION.md: move security_enforcement / security_asvs_level / security_block_on from root into `workflow.*` in Full Schema to match templates/config.json and the gsd-sdk runtime reads; update Security Settings table to use the workflow.* prefix; add planning.sub_repos to Full Schema and description table; add a Graphify Settings section documenting graphify.enabled and graphify.build_timeout. Note: VALID_CONFIG_KEYS in bin/lib/config.cjs does not yet include workflow.security_* or planning.sub_repos, so config-set currently rejects them. That is a pre-existing validator gap that this PR does not attempt to fix; the docs now correctly describe where these keys live per the shipped template and runtime reads. Part 2 of a stacked docs refresh series (PR 2/5), based on PR 1. * docs: make inventory authoritative and reconcile architecture Upgrade docs/INVENTORY.md from "complete for agents, selective for others" to authoritative across all six shipped-surface families, and reconcile docs/ARCHITECTURE.md against the new inventory so the PR that introduces INVENTORY does not also introduce an INVENTORY/ARCHITECTURE contradiction. - docs/AGENTS.md: weaken "21 specialized agents" header to 21 primary + 10 advanced (31 shipped); add new "Advanced and Specialized Agents" section with concise role cards for the 10 previously-omitted shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater); footnote the Agent Tool Permissions Summary as primary-agents-only so it no longer misleads. - docs/INVENTORY.md (rewritten to be authoritative): * Full 31-agent roster with one-line role + spawner + primary-doc status per agent (unchanged from prior partial work). * Commands: full 75-row enumeration grouped by Core Workflow, Phase & Milestone Management, Session & Navigation, Codebase Intelligence, Review/Debug/Recovery, and Docs/Profile/Utilities — each row carries a one-line role derived from the command's frontmatter and a link to the source file. * Workflows: full 72-row enumeration covering every get-shit-done/workflows/*.md, with a one-line role per workflow and a column naming the user-facing command (or internal orchestrator) that invokes it. * References: full 41-row enumeration grouped by Core, Workflow, Thinking-Model clusters, and the Modular Planner decomposition, matching the groupings docs/ARCHITECTURE.md already uses; notes the few-shot-examples subdirectory separately. * CLI Modules and Hooks: unchanged — already full rosters. * Maintenance section rewritten to describe the drift-guard test suite that will land in PR4 (inventory-counts, commands-doc-parity, agents-doc-parity, cli-modules-doc-parity, hooks-doc-parity). - docs/ARCHITECTURE.md reconciled against INVENTORY: * References block: drop the stale "(35 total)" count; point at INVENTORY.md#references-41-shipped for the authoritative count. * CLI Tools block: drop the stale "19 domain modules" count; point at INVENTORY.md#cli-modules-24-shipped for the authoritative roster. * Agent Spawn Categories: relabel as "Primary Agent Spawn Categories" and add a footer naming the 10 advanced agents and pointing at INVENTORY.md#agents-31-shipped for the full 31-agent roster. - docs/CONFIGURATION.md: preserve the six model-profile rows added in the prior partial work, and tighten the fallback note so it names the 13 shipped agents without an explicit profile row, documents model_overrides as the escape hatch, and points at INVENTORY.md for the authoritative 31-agent roster. Part 3 of a stacked docs refresh series (PR 3/4). Remaining consistency work (USER-GUIDE config-section delete-and-link, FEATURES.md TOC reorder, ARCHITECTURE.md Hook-table expansion + installation-layout collapse, CLI-TOOLS.md module-row additions, workflow-discuss-mode invocation normalization, and the five doc-parity tests) lands in PR4. * test(docs): add consistency guards and remove duplicate refs Consolidates USER-GUIDE.md's command/config duplicates into pointers to COMMANDS.md and CONFIGURATION.md (kills a ghost `resolve_model_ids` key and a stale `discuss_mode: standard` default); reorders FEATURES.md TOC chronologically so v1.32 precedes v1.34/1.35/1.36; expands ARCHITECTURE.md's Hook table to the 11 shipped hooks (gsd-read-injection-scanner, gsd-check-update-worker) and collapses the installation-layout hook enumeration to the *.js/*.sh pattern form; adds audit/gsd2-import/intel rows and state signal-*, audit-open, from-gsd2 verbs to CLI-TOOLS.md; normalizes workflow-discuss-mode.md invocations to `node gsd-tools.cjs config-set`. Adds five drift guards anchored on docs/INVENTORY.md as the authoritative roster: inventory-counts (all six families), commands/agents/cli-modules/hooks parity checks that every shipped surface has a row somewhere. * fix(convergence): thread --ws to review agent; add stall and max-cycles behavioral tests - Thread GSD_WS through to review agent spawn in plan-review-convergence workflow (step 5a) so --ws scoping is symmetric with planning step - Add behavioral stall detection test: asserts workflow compares HIGH_COUNT >= prev_high_count and emits a stall warning - Add behavioral --max-cycles 1 test: asserts workflow reaches escalation gate when cycle >= MAX_CYCLES with HIGH > 0 after a single cycle - Include original PR files (commands, workflow, tests) as the branch predated the PR commits Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(docs,config): PR #2390 review — security_* config keys and REQ-GRAPH-02 scope Addresses trek-e's review items that don't require rebase: - config.cjs: add workflow.security_enforcement, workflow.security_asvs_level, workflow.security_block_on to VALID_CONFIG_KEYS so gsd-sdk config-set accepts them (closed the gap where docs/CONFIGURATION.md listed keys the validator rejected). - core.cjs: add matching CONFIG_DEFAULTS entries (true / 1 / 'high') so the canonical defaults table matches the documented values. - config.cjs: wire the three keys into the new-project workflow defaults so fresh configs inherit them. - planning-config.md: document the three keys in the Workflow Fields table, keeping the CONFIG_DEFAULTS ↔ doc parity test happy. - config-field-docs.test.cjs: extend NAMESPACE_MAP so the flat keys in CONFIG_DEFAULTS resolve to their workflow.* doc rows. - FEATURES.md REQ-GRAPH-02: split the slash-command surface (build|query| status|diff) from the CLI surface which additionally exposes `snapshot` (invoked automatically at the tail of `graphify build`). The prior text overstated the slash-command surface. * docs(inventory): refresh rosters and counts for post-rebase drift origin/main accumulated surfaces since this PR was authored: - Agents: 31 → 33 (+ gsd-doc-classifier, gsd-doc-synthesizer) - Commands: 76 → 82 (+ ingest-docs, ultraplan-phase, spike, spike-wrap-up, sketch, sketch-wrap-up) - Workflows: 73 → 79 (same 6 names) - References: 41 → 49 (+ debugger-philosophy, doc-conflict-engine, mandatory-initial-read, project-skills-discovery, sketch-interactivity, sketch-theme-system, sketch-tooling, sketch-variant-patterns) Adds rows in the existing sub-groupings, introduces a Sketch References subsection, and bumps all four headline counts. Roles are pulled from source frontmatter / purpose blocks for each file. All 5 parity tests (inventory-counts, agents-doc-parity, commands-doc-parity, cli-modules-doc-parity, hooks-doc-parity) pass against this state — 156 assertions, 0 failures. Also updates the 'Coverage note' advanced-agent count 10 → 12 and the few-shot-examples footnote "41 top-level references" → "49" to keep the file internally consistent. * docs(agents): add advanced stubs for gsd-doc-classifier and gsd-doc-synthesizer Both agents ship on main (spawned by /gsd-ingest-docs) but had no coverage in docs/AGENTS.md. Adds the "advanced stub" entries (Role, property table, Key behaviors) following the template used by the other 10 advanced/specialized agents in the same section. Also updates the Agent Tool Permissions Summary scope note from "10 advanced/specialized agents" to 12 to reflect the two new stubs. * docs(commands): add entries for ingest-docs, ultraplan-phase, plan-review-convergence These three commands ship on main (plan-review-convergence via trek-e's 4b452d29 commit on this branch) but had no user-facing section in docs/COMMANDS.md — they lived only in INVENTORY.md. The commands-doc-parity test already passes via INVENTORY, but the user-facing doc was missing canonical explanations, argument tables, and examples. - /gsd-plan-review-convergence → Core Workflow (after /gsd-plan-phase) - /gsd-ultraplan-phase → Core Workflow (after plan-review-convergence) - /gsd-ingest-docs → Brownfield (after /gsd-import, since both consume the references/doc-conflict-engine.md contract) Content pulled from each command's frontmatter and workflow purpose block. * test: remove redundant ARCHITECTURE.md count tests tests/architecture-counts.test.cjs and tests/command-count-sync.test.cjs were added when docs/ARCHITECTURE.md carried hardcoded counts for commands/ workflows/agents. With the PR #2390 cleanup, ARCHITECTURE.md no longer owns those numbers — docs/INVENTORY.md does, enforced by tests/inventory-counts.test.cjs (scans the same filesystem directories with the same readdirSync filter). Keeping these ARCHITECTURE-specific tests would re-introduce the hardcoded counts they guard, defeating trek-e's review point. The single-source-of- truth parity tests already catch the same drift scenarios. Related: #2257 (the regression this replaced). --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
13 KiB
GSD CLI Tools Reference
Programmatic API reference for
gsd-tools.cjs. Used by workflows and agents internally. For user-facing commands, see Command Reference.
Overview
gsd-tools.cjs is a Node.js CLI utility that replaces repetitive inline bash patterns across GSD's ~50 command, workflow, and agent files. It centralizes: config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations.
Preferred for new orchestration: Many of the same operations are available as gsd-sdk query <command> (see sdk/src/query/index.ts and docs/QUERY-HANDLERS.md). Use that in workflows and examples where the handler exists; keep node … gsd-tools.cjs for commands not yet in the registry (for example graphify) or when you need CJS-only flags.
Location: get-shit-done/bin/gsd-tools.cjs
Modules: see the Module Architecture table; the get-shit-done/bin/lib/ directory is authoritative.
Usage:
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
Global Flags:
| Flag | Description |
|---|---|
--raw |
Machine-readable output (JSON or plain text, no formatting) |
--cwd <path> |
Override working directory (for sandboxed subagents) |
--ws <name> |
Target a specific workstream context (SDK only) |
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-verifyduring 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) |