fix(sdk-guidance): point quick install hint and agent fallbacks to query-capable CLI

This commit is contained in:
Tom Boucher
2026-05-04 23:18:41 -04:00
parent 42ed7cee8d
commit 120113c42b
7 changed files with 46 additions and 14 deletions

View File

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

View File

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

View File

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

View File

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