feat: Phase 2 caller migration — gsd-sdk query in workflows, agents, commands (#2179)
* feat: Phase 2 caller migration — gsd-sdk query in workflows (#2122) Cherry-picked orchestration rewrites from feat/sdk-foundation (#2008, 4018fee) onto current main, resolving conflicts to keep upstream worktree guards and post-merge test gate. SDK stub registry omitted (out of Phase 2 scope per #2122). Refs: #2122 #2008 Made-with: Cursor * docs: add gsd-sdk query migration blurb Made-with: Cursor * docs(workflows): extend Phase 2 gsd-sdk query caller migration - Swap node gsd-tools.cjs for gsd-sdk query in review, plan-phase, execute-plan, ship, extract_learnings, ai-integration-phase, eval-review, next, thread - Document graphify CJS-only in gsd-planner; dual-path in CLI-TOOLS and ARCHITECTURE - Update tests: workstreams gsd-sdk path, thread frontmatter.get, workspace init.*, CRLF-safe autonomous frontmatter parse - CHANGELOG: Phase 2 caller migration scope Made-with: Cursor * docs(phase2): USER-GUIDE + remaining gsd-sdk query call sites - USER-GUIDE: dual-path CLI section; state validate/sync use full CJS path - Commands: debug (config-get+tdd), quick (security note), intel Task prompt - Agent: gsd-debug-session-manager resolve-model via jq - Workflows: milestone-summary, forensics, next, complete-milestone/verify-work (audit-open CJS notes), discuss-phase, progress, verify-phase, add/insert/remove phase, transition, manager, quick workflow; remove-phase commit without --files - Test: quick-session-management accepts frontmatter.get - CHANGELOG: Phase 2 follow-up bullet Made-with: Cursor * docs(phase2): align gsd-sdk query examples in commands and agents - init.* query names; frontmatter.get uses positional field name - state.* handlers use positional args; commit uses positional paths - CJS-only notes for from-gsd2 and graphify; learnings.query wording - CHANGELOG: Phase 2 orchestration doc pass Made-with: Cursor * docs(phase2): normalize gsd-sdk query commit to positional file paths - Strip --files from commit examples in workflows, references, commands - Keep commit-to-subrepo ... --files (separate handler) - git-planning-commit.md: document positional args - Tests: new-project commit line, state.record-session, gates CRLF, roadmap.analyze - CHANGELOG [Unreleased] Made-with: Cursor * feat(sdk): gsd-sdk query parity with gsd-tools and PR 2179 registry fixes - Route query via longest-prefix match and dotted single-token expansion; fall back to runGsdToolsQuery (same argv as node gsd-tools.cjs) for full CLI coverage. - Parse gsd-sdk query permissively so gsd-tools flags (--json, --verify, etc.) are not rejected by strict parseArgs. - resolveGsdToolsPath: honor GSD_TOOLS_PATH; prefer bundled get-shit-done copy over project .claude installs; export runGsdToolsQuery from the SDK. - Fix gsd-tools audit-open (core.output; pass object for --json JSON). - Register summary-extract as alias of summary.extract; fix audit-fix workflow to call audit-uat instead of invalid init.audit-uat (PR review). Updates QUERY-HANDLERS.md and CHANGELOG [Unreleased]. Made-with: Cursor * fix(sdk): Phase 2 scope — Trek-e review (#2179, #2122) - Remove gsd-sdk query passthrough to gsd-tools.cjs; drop GSD_TOOLS_PATH - Consolidate argv routing in resolveQueryArgv(); update USAGE and QUERY-HANDLERS - Surface @file: read failures in GSDTools.parseOutput - execute-plan: defer Task Commit Protocol to gsd-executor - stale-colon-refs: skip .planning/ and root CLAUDE.md (gitignored overlays) - CHANGELOG [Unreleased]: maintainer review and routing notes Made-with: Cursor
This commit is contained in:
Rezolv
@@ -54,7 +54,7 @@ GSD is a **meta-prompting framework** that sits between the user and AI coding a
|
||||
│ │ │
|
||||
┌──────▼──────────────▼─────────────────▼──────────────┐
|
||||
│ CLI TOOLS LAYER │
|
||||
│ get-shit-done/bin/gsd-tools.cjs │
|
||||
│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │
|
||||
│ (State, config, phase, roadmap, verify, templates) │
|
||||
└──────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
@@ -76,7 +76,7 @@ Every agent spawned by an orchestrator gets a clean context window (up to 200K t
|
||||
### 2. Thin Orchestrators
|
||||
|
||||
Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:
|
||||
- Load context via `gsd-tools.cjs init <workflow>`
|
||||
- Load context via `gsd-sdk query init.<workflow>` (or legacy `gsd-tools.cjs init <workflow>`)
|
||||
- Spawn specialized agents with focused prompts
|
||||
- Collect results and route to the next step
|
||||
- Update state between steps
|
||||
@@ -118,7 +118,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description
|
||||
### Workflows (`get-shit-done/workflows/*.md`)
|
||||
|
||||
Orchestration logic that commands reference. Contains the step-by-step process including:
|
||||
- Context loading via `gsd-tools.cjs init`
|
||||
- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)
|
||||
- Agent spawn instructions with model resolution
|
||||
- Gate/checkpoint definitions
|
||||
- State update patterns
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
|
||||
`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:** 15 domain modules in `get-shit-done/bin/lib/`
|
||||
|
||||
|
||||
@@ -798,14 +798,20 @@ Each workspace gets:
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Programmatic CLI (`gsd-sdk query` vs `gsd-tools.cjs`)
|
||||
|
||||
For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md](CLI-TOOLS.md) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy **`node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs`** CLI remains supported for dual-mode operation.
|
||||
|
||||
**Not yet on `gsd-sdk query` (use CJS):** `state validate`, `state sync`, `audit-open`, `graphify`, `from-gsd2`, and any subcommand not listed in the registry.
|
||||
|
||||
### STATE.md Out of Sync
|
||||
|
||||
If STATE.md shows incorrect phase status or position, use the state consistency commands:
|
||||
If STATE.md shows incorrect phase status or position, use the state consistency commands (**CJS-only** until ported to the query layer):
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs state validate # Detect drift between STATE.md and filesystem
|
||||
node gsd-tools.cjs state sync --verify # Preview what sync would change
|
||||
node gsd-tools.cjs state sync # Reconstruct STATE.md from disk
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift between STATE.md and filesystem
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview what sync would change
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md from disk
|
||||
```
|
||||
|
||||
These commands are new in v1.32 and replace manual STATE.md editing.
|
||||
|
||||
22
docs/gsd-sdk-query-migration-blurb.md
Normal file
22
docs/gsd-sdk-query-migration-blurb.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# GSD SDK query migration (summary blurb)
|
||||
|
||||
Copy-paste friendly for Discord and GitHub comments.
|
||||
|
||||
---
|
||||
|
||||
**@gsd-build/sdk** replaces the untyped, monolithic `gsd-tools.cjs` subprocess with a typed, tested, registry-based query system and **`gsd-sdk query`**, giving GSD structured results, classified errors (`GSDQueryError`), and golden-verified parity with the old CLI. That gives the framework one stable contract instead of a fragile, very large CLI that every workflow had to spawn and parse by hand.
|
||||
|
||||
**What users can expect**
|
||||
|
||||
- Same GSD commands and workflows they already use.
|
||||
- Snappier runs (less Node startup on chained tool calls).
|
||||
- Fewer mysterious mid-workflow failures and safer upgrades, because behavior is covered by tests and a single stable contract.
|
||||
- Stronger predictability: outputs and failure modes are consistent and explicit.
|
||||
|
||||
**Cost and tokens**
|
||||
|
||||
The SDK does not automatically reduce LLM tokens per model call. Savings show up indirectly: fewer ambiguous tool results and fewer retry or recovery loops, which often lowers real-world session cost and wall time.
|
||||
|
||||
**Agents then vs now**
|
||||
|
||||
Agents always followed workflow instructions. What improved is the surface those steps run on. Before, workflows effectively said to shell out to `gsd-tools.cjs` and interpret stdout or JSON with brittle assumptions. Now they point at **`gsd-sdk query`** and typed handlers that return the shapes prompts expect, with clearer error reasons when something must stop or be fixed, so instruction following holds end to end with less thrash from bad parses or silent output drift.
|
||||
Reference in New Issue
Block a user