golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(#194): remove sdk programmatic docs and bridge guidance

Browse Source
This commit is contained in:
Tom Boucher
2026-05-25 11:57:24 -04:00
parent a7eb4bd51e
commit e8fc50034d
5 changed files with 24 additions and 424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/CLI-TOOLS.md
View File

@@ -1,6 +1,6 @@
# 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 `@opengsd/gsd-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).
> Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (Node CLI). For slash commands and user flows, see [Command Reference](COMMANDS.md).
---
@@ -13,7 +13,7 @@
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **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)). |
| **Status** | Primary runtime command surface for orchestration, workflows, and automation. |
**Usage (CJS):**
@@ -29,47 +29,9 @@ node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
| -------------- | ---------------------------------------------------------------------------- |
| `--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) |
| `--ws <name>` | Workstream context for `.planning/workstreams/<name>` paths |
---
## 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 — `@opengsd/gsd-sdk` (`GSDTools`, `createRegistry`)**
- `GSDTools` now routes through the **SDK Runtime Bridge Module** (`sdk/src/query-runtime-bridge.ts`). Native registry dispatch is preferred; subprocess fallback is explicit policy (`allowFallbackToSubprocess`) and can be disabled for strict SDK-only execution.
- `strictSdk` mode fails fast when a command has no native adapter, making SDK publish/readiness checks deterministic.
- Structured bridge observability is available via `onDispatchEvent` (dispatch mode, fallback reason, duration, outcome, error kind).
- For direct typed dispatch without `GSDTools`, 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:** `state.json` and `state.load` are both registered query handlers with parity coverage. You can invoke them through `gsd-sdk query …` and through the SDK Runtime Bridge (`GSDTools` → `sdk/src/query-runtime-bridge.ts`), honoring `allowFallbackToSubprocess` / `strictSdk` and emitting `onDispatchEvent` observability. For direct typed dispatch, use `createRegistry()` from `sdk/src/query/index.ts`. 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
@@ -340,7 +302,7 @@ 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)
# Workstream-scoped init (`--ws` flag)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
@@ -438,7 +400,7 @@ 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 …`.
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)).
```bash
# Build or rebuild the knowledge graph
@@ -494,10 +456,10 @@ User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gs
`review.models.<cli>` maps a reviewer flavor to a shell command invoked by the code-review workflow. Set via [`/gsd-config --integrations`](COMMANDS.md#gsd-config) 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
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 "" # 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.
@@ -510,6 +472,5 @@ API keys configured via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_searc
## 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
- [Architecture](ARCHITECTURE.md) — orchestration and runtime layering
- [Command Reference](COMMANDS.md) — user-facing `/gsd-` commands