eb365f7336
* docs(en): update FEATURES/USER-GUIDE/COMMANDS for v1.40.0 surface - FEATURES.md: append v1.40.0 section (#122 skill consolidation, #123 namespace meta-skills, #124 context-window guard, #125 phase-lifecycle status-line read-side); add to TOC. - USER-GUIDE.md: add slash-command form (hyphen vs colon) primer and namespace routing primer; replace deleted slash forms in walkthroughs (`/gsd-add-backlog`, `/gsd-plant-seed`, `/gsd-add-phase`, `/gsd-set-profile`, `/gsd-list-workspaces`, etc.) with consolidated forms (`/gsd-capture --backlog`, `/gsd-phase --insert`, `/gsd-config --profile`, `/gsd-workspace --list`, etc.); fix `/gsd-spike-wrap-up` and `/gsd-sketch-wrap-up` to flag form. - COMMANDS.md: clarify Command Syntax (Gemini = colon form, others = hyphen form); add Namespace Meta-Skills section with all six routers; add `--context` to /gsd-health flag table. Refs #3047 * docs(en): refresh INVENTORY/CLI-TOOLS/STATE-MD-LIFECYCLE for v1.40.0 - INVENTORY.md: workflow-row "Invoked by" column updated to point at consolidated commands (`/gsd-phase` family, `/gsd-workspace --list`, `/gsd-config --advanced/--integrations/--profile`, `/gsd-sketch --wrap-up`, `/gsd-spike --wrap-up`); CLI-modules row for `secrets.cjs` updated to `/gsd-config --integrations`. Command count and namespace meta-skills section already reflect 65 shipped (= 59 consolidated sub-skills + 6 ns-* routers). - CLI-TOOLS.md: add `validate context` row under Validation Commands with the 60 %/70 % threshold envelope used by `/gsd-health --context`. - STATE-MD-LIFECYCLE.md: flip status header from "proposed" to "shipped in v1.40.0" since `parseStateMd()` and `formatGsdState()` now read and render `active_phase`, `next_action`, `next_phases`, and `progress`. `docs/AGENTS.md` audited and verified clean — `gsd-code-fixer` row already lists the correct `/gsd-code-review --fix` spawner; no deleted-skill references found. `docs/INVENTORY-MANIFEST.json` audited and verified clean — already enumerates the 65 commands (including six ns-* routers) and contains no deleted slash forms. Refs #3047 * docs(en): cleanup ARCHITECTURE/CONFIGURATION for v1.40.0 - ARCHITECTURE.md: split Commands install-target list to call out the Gemini colon form (`/gsd:command-name`) vs hyphen form for every other runtime. Add a new subsection covering two-stage hierarchical routing via the six namespace meta-skills (#2792) and a paired note on the MCP token-budget interaction so readers see the two big per-turn cost levers in one place. - CONFIGURATION.md: rewrite three references to the deleted `/gsd-settings-advanced` and `/gsd-settings-integrations` slash forms to use the consolidated `/gsd-config --advanced` / `/gsd-config --integrations` invocations. Add a new "STATE.md Frontmatter (Phase Lifecycle)" section documenting the four optional fields (`active_phase`, `next_action`, `next_phases`, `progress`) read by the v1.40 status-line, with a pointer to STATE-MD-LIFECYCLE.md for the full reference. `docs/manual-update.md` audited and verified clean — already documents `/gsd-update --reapply` (the consolidated form), no reference to the deleted `/gsd-reapply-patches`. Refs #3047 * docs(i18n): mirror v1.40.0 slash-command rename into ja-JP/ko-KR/zh-CN/pt-BR Mechanical token-level renames only — every reference to a deleted micro-skill slash form is rewritten to the consolidated form on the matching parent skill. No prose was machine-translated; new prose sections (slash-form primer, namespace routing primer, v1.40 feature entries, STATE.md frontmatter) were left for human translator follow-up. Renames applied uniformly across all four trees: /gsd-add-todo, /gsd-add-note, /gsd-add-backlog, /gsd-plant-seed, /gsd-check-todos → /gsd-capture[ --note| --backlog|--seed|--list] /gsd-add-phase, /gsd-insert-phase, /gsd-remove-phase, /gsd-edit-phase → /gsd-phase[ --insert| --remove|--edit] /gsd-new-workspace, /gsd-list-workspaces, /gsd-remove-workspace → /gsd-workspace[ --new| --list|--remove] /gsd-settings-advanced, /gsd-settings-integrations, /gsd-set-profile → /gsd-config[ --advanced| --integrations|--profile] /gsd-sketch-wrap-up → /gsd-sketch --wrap-up /gsd-spike-wrap-up → /gsd-spike --wrap-up /gsd-reapply-patches → /gsd-update --reapply /gsd-code-review-fix → /gsd-code-review --fix /gsd-plan-milestone-gaps → /gsd-audit-milestone Refs #3047 * docs(changelog): regroup [Unreleased] under Feature/Enhancement/Fix Replace the existing Keep-a-Changelog \`Added\` / \`Changed\` / \`Performance\` / \`Removed\` / \`Fixed\` sub-headers in the [Unreleased] block with the issue/PR template taxonomy: Added → Feature Changed / Performance → Enhancement Removed → Enhancement Fixed → Fix Order within the release: Feature → Enhancement → Fix. Every bullet preserved verbatim — only headers and grouping changed; the awkward inline-versioned headers (\`### Added — 1.40.0-rc.1\`, \`### Changed — 1.40.0-rc.1\`, \`### Fixed — 1.40.0-rc.1\`) folded into the same buckets with the \`— 1.40.0-rc.1\` suffix dropped, since the [Unreleased] block IS 1.40.0-rc.1. The [1.39.2] hotfix block called out in #3047's spec does not yet exist in CHANGELOG.md (the previously released hotfix is [1.39.1]), so this commit only regroups [Unreleased]. Older release blocks ([1.39.1] and earlier) are frozen and untouched. Refs #3047 * docs(changeset): add fragment for v1.40.0 doc audit Refs #3047 * docs(en): strip leading / from deleted slash-command tokens in FEATURES REQ-CONSOLIDATE-03 and REQ-CONSOLIDATE-04 listed deleted commands by their `/gsd-foo` form for the historical record. The docs-parity tests in bug-3010, bug-3029-3034, and bug-3042-3044 use the regex `/\/gsd-[a-z0-9][a-z0-9-]*/g` to scan user-facing surfaces for any remaining mention of removed slash forms — they cannot tell prose about a deleted command from a live recommendation. Strip the leading slash from the bare-name references (preserve the historical text otherwise). Tests now require a `/` prefix to match, so `gsd-add-todo` reads identically to a human but no longer trips the parser. Verified locally: 65/65 tests pass across the three docs-parity suites that were red on CI run 25270072600. Refs #3047 * docs(en): fix CR feedback + drop literal /gsd:plan-phase from USER-GUIDE CI: tests/bug-2543-gsd-slash-namespace.test.cjs flagged docs/USER-GUIDE.md:35 for embedding the literal `/gsd:plan-phase` token in the parenthetical Gemini-form example. The test scans every .md under docs/ for `/gsd:<live-cmd>` because non-Gemini surfaces must not advertise the colon form. Replaced the literal example with a prose substitution rule. CR: docs/ARCHITECTURE.md:125 — the namespace meta-skills were listed by file-prefix (`gsd-ns-workflow`) but the invocable frontmatter `name:` is the bare form (`gsd-workflow`). Verified against the six `commands/gsd/ns-*.md` files. Replaced with the canonical names and noted the file/name disagreement in-line. CR: docs/COMMANDS.md:723 — `v1.40` aligned to canonical `v1.40.0`. CR: docs/FEATURES.md:2679 — REQ-CTX-GUARD-02 advertised the wrong invocation (`gsd-tools validate context`). The shipped handler is exposed via `gsd-sdk query validate.context` and requires explicit `--tokens-used <int>` + `--context-window <int>` flags (verified against sdk/src/query/validate.ts:849-882 and get-shit-done/bin/lib/validate-command-router.cjs:19-36). CR: docs/zh-CN/README.md:533 — added `inherit` to the profile-options parenthetical to match the canonical set (verified against model-profiles.cjs:29 `VALID_PROFILES = […MODEL_PROFILES['gsd-planner'], 'inherit']`). Verified locally: 74/74 tests pass across the four docs-parity suites that were red on CI runs 25270072600 and 25270182903. Refs #3047
510 lines
19 KiB
Markdown
510 lines
19 KiB
Markdown
# 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](#sdk-and-programmatic-access). For slash commands and user flows, see [Command Reference](COMMANDS.md).
|
|
|
|
---
|
|
|
|
## 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](../sdk/src/query/QUERY-HANDLERS.md)). |
|
|
|
|
|
|
**Usage (CJS):**
|
|
|
|
```bash
|
|
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](../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](../sdk/src/query/QUERY-HANDLERS.md)).
|
|
- Conventions: mutation event wiring, `GSDError` vs `{ data: { error } }`, locks, and stubs — [QUERY-HANDLERS.md](../sdk/src/query/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](../sdk/src/query/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](../sdk/src/query/QUERY-HANDLERS.md).
|
|
|
|
---
|
|
|
|
## State Commands
|
|
|
|
Manage `.planning/STATE.md` — the project's living memory.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# Check phase numbering, disk/roadmap sync
|
|
node gsd-tools.cjs validate consistency
|
|
|
|
# Check .planning/ integrity, optionally repair
|
|
node gsd-tools.cjs validate health [--repair]
|
|
|
|
# Probe context-window utilization for status-line / hook callers (v1.40.0)
|
|
node gsd-tools.cjs validate context
|
|
```
|
|
|
|
`validate context` emits a structured envelope with `utilization`, `status`
|
|
(`ok` / `warn` / `critical` at the 60 % / 70 % thresholds), and a
|
|
`suggestion` string. The same data backs `/gsd-health --context`.
|
|
|
|
---
|
|
|
|
## Template Commands
|
|
|
|
Template selection and filling.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
|
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
|
```
|
|
|
|
---
|
|
|
|
## Milestone Commands
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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 <query> [--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](COMMANDS.md#gsd-graphify)).
|
|
|
|
---
|
|
|
|
## Module Architecture
|
|
|
|
| Module | File | Exports |
|
|
|--------|------|---------|
|
|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities, compatibility re-exports |
|
|
| State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` |
|
|
| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
|
|
| Planning Workspace | `lib/planning-workspace.cjs` | Planning seam: `planningDir`, `planningPaths`, active workstream routing, `.planning/.lock` |
|
|
| 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`) |
|
|
|
|
---
|
|
|
|
## Reviewer CLI Routing
|
|
|
|
`review.models.<cli>` maps a reviewer flavor to a shell command invoked by the code-review workflow. Set via [`/gsd-settings-integrations`](COMMANDS.md#gsd-settings-integrations) or directly:
|
|
|
|
```bash
|
|
gsd-sdk query config-set review.models.codex "codex exec --model gpt-5"
|
|
gsd-sdk query config-set review.models.gemini "gemini -m gemini-2.5-pro"
|
|
gsd-sdk query config-set review.models.opencode "opencode run --model claude-sonnet-4"
|
|
gsd-sdk query config-set review.models.claude "" # clear — fall back to session model
|
|
```
|
|
|
|
Slugs are validated against `[a-zA-Z0-9_-]+`; empty or path-containing slugs are rejected. See [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) for the full field reference.
|
|
|
|
## Secret Handling
|
|
|
|
API keys configured via `/gsd-settings-integrations` (`brave_search`, `firecrawl`, `exa_search`) are written plaintext to `.planning/config.json` but are masked (`****<last-4>`) in every `config-set` / `config-get` output, confirmation table, and interactive prompt. See `get-shit-done/bin/lib/secrets.cjs` for the masking implementation. The `config.json` file itself is the security boundary — protect it with filesystem permissions and keep it out of git (`.planning/` is gitignored by default).
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md) — registry matrix, routing, golden parity, intentional CJS differences
|
|
- [Architecture](ARCHITECTURE.md) — where `gsd-sdk query` fits in orchestration
|
|
- [Command Reference](COMMANDS.md) — user-facing `/gsd-` commands
|