From 120113c42bb94a86e557827033d5bda5464c24f1 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 4 May 2026 23:18:41 -0400 Subject: [PATCH 1/2] fix(sdk-guidance): point quick install hint and agent fallbacks to query-capable CLI --- agents/gsd-executor.md | 2 +- agents/gsd-plan-checker.md | 14 ++++---- agents/gsd-planner.md | 2 +- agents/gsd-roadmapper.md | 2 +- get-shit-done/workflows/quick.md | 4 +-- .../bug-2334-quick-gsd-sdk-preflight.test.cjs | 4 +-- ...dk-package-guidance-and-fallbacks.test.cjs | 32 +++++++++++++++++++ 7 files changed, 46 insertions(+), 14 deletions(-) create mode 100644 tests/bug-3091-sdk-package-guidance-and-fallbacks.test.cjs diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index c6c0837a3..227468ef5 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -74,7 +74,7 @@ Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `phase_dir Also load planning state (position, decisions, blockers) via the SDK — **use `node` to invoke the CLI** (not `npx`): ```bash -node ./node_modules/@gsd-build/sdk/dist/cli.js query state.load 2>/dev/null +gsd-sdk query state.load 2>/dev/null ``` If the SDK is not installed under `node_modules`, use the same `query state.load` argv with your local `gsd-sdk` CLI on `PATH`. diff --git a/agents/gsd-plan-checker.md b/agents/gsd-plan-checker.md index 0169ea827..2957e165f 100644 --- a/agents/gsd-plan-checker.md +++ b/agents/gsd-plan-checker.md @@ -655,11 +655,11 @@ Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`. Orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas. ```bash -node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-plans "$phase_number" +gsd-sdk query phase.list-plans "$phase_number" # Research / brief artifacts (deterministic listing) -node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-artifacts "$phase_number" --type research -node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.get-phase "$phase_number" -node ./node_modules/@gsd-build/sdk/dist/cli.js query phase.list-artifacts "$phase_number" --type summary +gsd-sdk query phase.list-artifacts "$phase_number" --type research +gsd-sdk query roadmap.get-phase "$phase_number" +gsd-sdk query phase.list-artifacts "$phase_number" --type summary ``` **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas. @@ -747,7 +747,7 @@ The `tasks` array in the result shows each task's completeness: **For manual validation of specificity** (`verify.plan-structure` checks structure, not content quality), use structured extraction instead of grepping raw XML: ```bash -node ./node_modules/@gsd-build/sdk/dist/cli.js query plan.task-structure "$PLAN_PATH" +gsd-sdk query plan.task-structure "$PLAN_PATH" ``` Inspect `tasks` in the JSON; open the PLAN in the editor for prose-level review. @@ -774,8 +774,8 @@ Missing: No mention of fetch/API call → Issue: Key link not planned ## Step 8: Assess Scope ```bash -node ./node_modules/@gsd-build/sdk/dist/cli.js query plan.task-structure "$PHASE_DIR/$PHASE-01-PLAN.md" -node ./node_modules/@gsd-build/sdk/dist/cli.js query frontmatter.get "$PHASE_DIR/$PHASE-01-PLAN.md" files_modified +gsd-sdk query plan.task-structure "$PHASE_DIR/$PHASE-01-PLAN.md" +gsd-sdk query frontmatter.get "$PHASE_DIR/$PHASE-01-PLAN.md" files_modified ``` Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required). diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 9a5a9a20d..6382cbae1 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -814,7 +814,7 @@ Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `c Also load planning state (position, decisions, blockers) via the SDK — **use `node` to invoke the CLI** (not `npx`): ```bash -node ./node_modules/@gsd-build/sdk/dist/cli.js query state.load 2>/dev/null +gsd-sdk query state.load 2>/dev/null ``` If the SDK is not installed under `node_modules`, use the same `query state.load` argv with your local `gsd-sdk` CLI on `PATH`. diff --git a/agents/gsd-roadmapper.md b/agents/gsd-roadmapper.md index c90667245..643ef35a0 100644 --- a/agents/gsd-roadmapper.md +++ b/agents/gsd-roadmapper.md @@ -560,7 +560,7 @@ When files are written and returning to orchestrator: ### Files Ready for Review -User can review actual files in the editor or via SDK queries (e.g. `node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.analyze` and `query state.load`) instead of ad-hoc shell `cat`. +User can review actual files in the editor or via SDK queries (e.g. `gsd-sdk query roadmap.analyze` and `gsd-sdk query state.load`) instead of ad-hoc shell `cat`. {If gaps found during creation:} diff --git a/get-shit-done/workflows/quick.md b/get-shit-done/workflows/quick.md index b03a5e09e..cbb0b5d00 100644 --- a/get-shit-done/workflows/quick.md +++ b/get-shit-done/workflows/quick.md @@ -128,8 +128,8 @@ If `$VALIDATE_MODE` only: if ! command -v gsd-sdk &>/dev/null; then echo "⚠ gsd-sdk not found in PATH — /gsd-quick requires it." echo "" - echo "Install the GSD SDK:" - echo " npm install -g @gsd-build/sdk" + echo "Install the query-capable GSD SDK CLI:" + echo " npm install -g get-shit-done-cc" echo "" echo "Or update GSD to get the latest packages:" echo " /gsd-update" diff --git a/tests/bug-2334-quick-gsd-sdk-preflight.test.cjs b/tests/bug-2334-quick-gsd-sdk-preflight.test.cjs index 401603cd7..fea80fd35 100644 --- a/tests/bug-2334-quick-gsd-sdk-preflight.test.cjs +++ b/tests/bug-2334-quick-gsd-sdk-preflight.test.cjs @@ -56,10 +56,10 @@ describe('bug #2334: quick workflow gsd-sdk pre-flight check', () => { const firstSdkCall = content.indexOf('gsd-sdk query init.quick', step2Start); const step2Section = content.slice(step2Start, firstSdkCall); - const hasInstallHint = step2Section.includes('@gsd-build/sdk') || step2Section.includes('gsd-update') || step2Section.includes('/gsd-update'); + const hasInstallHint = step2Section.includes('get-shit-done-cc') || step2Section.includes('gsd-update') || step2Section.includes('/gsd-update'); assert.ok( hasInstallHint, - 'Pre-flight error must include a hint on how to install gsd-sdk (npm install -g @gsd-build/sdk or /gsd-update)' + 'Pre-flight error must include a hint on how to install query-capable gsd-sdk (npm install -g get-shit-done-cc or /gsd-update)' ); }); }); diff --git a/tests/bug-3091-sdk-package-guidance-and-fallbacks.test.cjs b/tests/bug-3091-sdk-package-guidance-and-fallbacks.test.cjs new file mode 100644 index 000000000..2f62136e4 --- /dev/null +++ b/tests/bug-3091-sdk-package-guidance-and-fallbacks.test.cjs @@ -0,0 +1,32 @@ +'use strict'; + +const { test, describe } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const ROOT = path.join(__dirname, '..'); + +function read(rel) { + return fs.readFileSync(path.join(ROOT, rel), 'utf8'); +} + +describe('bug #3091: sdk install guidance and agent fallbacks use query-capable CLI', () => { + test('quick workflow install hint references get-shit-done-cc (not @gsd-build/sdk)', () => { + const content = read('get-shit-done/workflows/quick.md'); + assert.ok(content.includes('npm install -g get-shit-done-cc')); + assert.ok(!content.includes('npm install -g @gsd-build/sdk')); + }); + + test('agent docs no longer reference node_modules/@gsd-build/sdk/dist/cli.js query fallback', () => { + const files = [ + 'agents/gsd-planner.md', + 'agents/gsd-executor.md', + 'agents/gsd-plan-checker.md', + 'agents/gsd-roadmapper.md', + ]; + + const offenders = files.filter((f) => read(f).includes('@gsd-build/sdk/dist/cli.js query')); + assert.deepStrictEqual(offenders, [], `stale @gsd-build/sdk query fallback references: ${offenders.join(', ')}`); + }); +}); From e2b12bfad20d75c19b3f9603280810eb47019a25 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 4 May 2026 23:32:07 -0400 Subject: [PATCH 2/2] chore(changeset): add release fragment for PR #3123 --- .changeset/pr-3123-release-note.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/pr-3123-release-note.md diff --git a/.changeset/pr-3123-release-note.md b/.changeset/pr-3123-release-note.md new file mode 100644 index 000000000..b292a3f85 --- /dev/null +++ b/.changeset/pr-3123-release-note.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 3123 +--- +Fixes for issue #3123 were applied to keep command/workflow behavior and SDK parity aligned with current documented usage.