Merge pull request #3123 from gsd-build/fix/3091-npx-install-gsd-sdk-symlink-never-create

fix: align SDK install/fallback guidance with query-capable CLI

.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.

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`.
 

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).

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`.
 

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:}
 

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"

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)'
     );
   });
 });

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(', ')}`);
+  });
+});