@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/agents/gsd-advisor-researcher.md

@@ -19,6 +19,8 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md
 </documentation_lookup>

package/agents/gsd-ai-researcher.md

@@ -72,7 +72,7 @@ Update AI-SPEC.md at `ai_spec_path`:
 
 **Section 3 — Framework Quick Reference:** real installation command, actual imports, working entry point pattern for `system_type`, abstractions table (3-5 rows), pitfall list with why-it's-a-pitfall notes, folder structure, Sources subsection with URLs.
 
-**Section 4 — Implementation Guidance:** specific model (e.g., `claude-sonnet-4-6`, `gpt-4o`) with params, core pattern as code snippet with inline comments, tool use config, state management approach, context window strategy.
+**Section 4 — Implementation Guidance:** specific model (e.g., `claude-sonnet-5`, `gpt-4o`) with params, core pattern as code snippet with inline comments, tool use config, state management approach, context window strategy.
 </step>
 
 <step name="write_section_4b">

package/agents/gsd-assumptions-analyzer.md

@@ -20,6 +20,8 @@ Spawned by `discuss-phase-assumptions` via `Task()`. You do NOT present output d
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 <input>
 Agent receives via prompt:
 

package/agents/gsd-code-fixer.md

@@ -24,6 +24,8 @@ Before fixing code, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions during fixes.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-code-reviewer.md

@@ -40,6 +40,8 @@ Before reviewing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions during review.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during review

package/agents/gsd-codebase-mapper.md

@@ -29,6 +29,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-debugger.md

@@ -40,6 +40,8 @@ Your job: Find the root cause through hypothesis testing, maintain debug file st
 - Load `rules/*.md` as needed during **investigation and fix**.
 - Follow skill rules relevant to the bug being investigated and the fix being applied.
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 <philosophy>
 
 @~/.claude/gsd-core/references/debugger-philosophy.md

package/agents/gsd-doc-writer.md

@@ -34,6 +34,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-eval-auditor.md

@@ -39,6 +39,8 @@ Read `~/.claude/gsd-core/references/ai-evals.md` before auditing. This is your s
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-executor.md

@@ -64,6 +64,8 @@ Before executing, discover project context:
 - Load `rules/*.md` as needed during **implementation**.
 - Follow skill rules relevant to the task you are about to commit.
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 **CLAUDE.md enforcement:** If `./CLAUDE.md` exists, treat its directives as hard constraints during execution. Before committing each task, verify that code changes do not violate CLAUDE.md rules (forbidden patterns, required conventions, mandated tools). If a task action would contradict a CLAUDE.md directive, apply the CLAUDE.md rule — it takes precedence over plan instructions. Document any CLAUDE.md-driven adjustments as deviations (Rule 2: auto-add missing critical functionality).
 </project_context>
 
@@ -689,7 +691,7 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 </self_check>
 
 <state_updates>
-After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (positional args; see `sdk/src/query/QUERY-HANDLERS.md`):
+After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (named flags; see `sdk/src/query/QUERY-HANDLERS.md`):
 
 ```bash
 # Advance plan counter (handles edge cases automatically)
@@ -700,16 +702,17 @@ gsd_run query state.update-progress
 
 # Record execution metrics (phase, plan, duration, tasks, files)
 gsd_run query state.record-metric \
-  "${PHASE}" "${PLAN}" "${DURATION}" "${TASK_COUNT}" "${FILE_COUNT}"
+  --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
+  --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
 
 # Add decisions (extract from SUMMARY.md key-decisions)
 for decision in "${DECISIONS[@]}"; do
-  gsd_run query state.add-decision "${decision}"
+  gsd_run query state.add-decision --summary "${decision}"
 done
 
-# Update session info (timestamp, stopped-at, resume-file)
+# Update session info (stopped-at, resume-file; timestamp set automatically)
 gsd_run query state.record-session \
-  "" "Completed ${PHASE}-${PLAN}-PLAN.md" "None"
+  --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" --resume-file "None"
 ```
 
 ```bash
@@ -736,7 +739,7 @@ gsd_run query requirements.mark-complete ${REQ_IDS}
 
 **For blockers found during execution:**
 ```bash
-gsd_run query state.add-blocker "Blocker description"
+gsd_run query state.add-blocker --text "Blocker description"
 ```
 </state_updates>
 

package/agents/gsd-integration-checker.md

@@ -35,6 +35,8 @@ Every expected cross-phase connection must resolve to WIRED (verified end-to-end
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-nyquist-auditor.md

@@ -51,6 +51,8 @@ Read ALL files from `<required_reading>`. Extract:
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-phase-researcher.md

@@ -50,6 +50,8 @@ Before researching, discover project context:
 - Load `rules/*.md` as needed during **research**.
 - Research output should account for project skill patterns and conventions.
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 **CLAUDE.md enforcement:** If `./CLAUDE.md` exists, extract all actionable directives (required tools, forbidden patterns, coding conventions, testing rules, security requirements). Include a `## Project Constraints (from CLAUDE.md)` section in RESEARCH.md listing these directives so the planner can verify compliance. Treat CLAUDE.md directives with the same authority as locked decisions from CONTEXT.md — research should not recommend approaches that contradict them.
 </project_context>
 

package/agents/gsd-plan-checker.md

@@ -54,6 +54,8 @@ Before verifying, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification

package/agents/gsd-planner.md

@@ -46,6 +46,8 @@ Before planning, discover project context:
 **Project skills:** @~/.claude/gsd-core/references/project-skills-discovery.md
 - Load `rules/*.md` as needed during **planning**.
 - Ensure plans account for project skill patterns and conventions.
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 </project_context>
 
 <context_fidelity>

package/agents/gsd-project-researcher.md

@@ -34,6 +34,8 @@ Your files feed the roadmap:
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md
 </documentation_lookup>

package/agents/gsd-research-synthesizer.md

@@ -34,6 +34,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+
 <downstream_consumer>
 Your SUMMARY.md is consumed by the gsd-roadmapper agent which uses it to:
 

package/agents/gsd-roadmapper.md

@@ -26,6 +26,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-security-auditor.md

@@ -51,6 +51,8 @@ Read ALL files from `<required_reading>`. Extract:
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-ui-auditor.md

@@ -49,6 +49,8 @@ Before auditing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill
 3. Do NOT load full `AGENTS.md` files (100KB+ context cost)

package/agents/gsd-ui-checker.md

@@ -30,6 +30,8 @@ Before verifying, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification

package/agents/gsd-ui-researcher.md

@@ -39,6 +39,8 @@ Before researching, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research

package/agents/gsd-verifier.md

@@ -52,14 +52,16 @@ Before verifying, discover project context:
 **Project skills:** @~/.claude/gsd-core/references/project-skills-discovery.md
 - Load `rules/*.md` as needed during **verification**.
 - Apply skill rules when scanning for anti-patterns and verifying quality.
+
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
 </project_context>
 
 <core_principle>
 **Task completion ≠ Goal achievement**
 
-A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved.
+A "create chat component" task can be complete with a placeholder file — task done, goal "working chat interface" missed.
 
-Goal-backward verification starts from the outcome and works backwards:
+Start from the outcome and work backwards:
 
 1. What must be TRUE for the goal to be achieved?
 2. What must EXIST for those truths to hold?
@@ -197,6 +199,7 @@ For each truth:
    - A pre-existing test exercises the transition/invariant and passes (confirm via Step 7b's single-named-test path) → ✓ VERIFIED.
    - No such test exists, or it can't run without a server/state mutation → ⚠️ PRESENT_BEHAVIOR_UNVERIFIED. Emit a human-verification item (Step 8) and do not count it toward the verified score (Step 9).
    - An accepted override (Step 3b) carries the truth as PASSED (override), exactly as it does for a FAILED truth.
+5b. **Non-inferable (`backstop`) truths:** a `verification: backstop` truth (via `truthVerification()`) abstains unless confirmed by explicit evidence — mark `insufficient_spec` -> a human-verification item -> `human_needed`. See `references/honest-verifier.md`.
 6. Determine truth status
 
 ## Step 3b: Check Verification Overrides

package/bin/gsd-mcp-server.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * gsd-mcp-server — companion MCP server bin entry (ADR-1239 Phase C-2 / #1681).
+ *
+ * Lives at top-level bin/ (alongside install.js) — it is a PACKAGE bin the host
+ * spawns via `npx gsd-mcp-server` (or the global bin), NOT a per-runtime
+ * artifact copied into a host's config dir. (Placing it under gsd-core/bin/
+ * would leak it into every runtime install + break golden parity.)
+ *
+ * A stdio JSON-RPC 2.0 server exposing GSD interface points 1 (command) + 5
+ * (state IO) so any MCP-consuming host (Claude/Codex/OpenCode/VS Code/Gemini/
+ * Cursor/Cline/Hermes) can drive GSD with no bespoke plugin. Delegates to the
+ * tested server module (gsd-core/bin/lib/mcp-server.cjs runServer). Reads
+ * line-delimited JSON-RPC from stdin, writes one response + newline per
+ * request, exits cleanly when stdin closes.
+ *
+ * The protocol logic (handleMessage) + the injectable-stream loop (runServer)
+ * are unit-tested in tests/gsd-mcp-server.test.cjs; the process lifecycle
+ * (spawn → JSON-RPC → clean exit) in tests/gsd-mcp-server-bin.test.cjs.
+ */
+const { runServer } = require('../gsd-core/bin/lib/mcp-server.cjs');
+
+runServer({
+  input: process.stdin,
+  output: process.stdout,
+  ctx: { cwd: process.cwd() },
+}).catch((err) => {
+  process.stderr.write(String((err && err.message) || err) + '\n');
+  process.exit(1);
+});