golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(#656): Research module — content-addressed cache + provider seam + registry-API legitimacy (#664)

Browse Source 
* feat(#656): add Research Store module (content-addressed cache, TTL staleness)

Content-addressed research cache behind a clock seam: researchKey (sha256, deterministic), putResearch/getResearch ({hit,stale}, never throws), ttlForSource (curated HIGH 30d / MED 7d / web LOW 1d), two-tier resolveStorePath (curated -> ~/.gsd/research-cache, web/synthesis -> project .planning/research/.cache). 28 behavioral + property tests; boundary coverage at ttl-1/ttl/ttl+1.

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#656): add Research Provider module (waterfall + confidence + plan)

Single source of truth for the Balanced provider waterfall (docs Context7->Ref->Jina, web Exa+Tavily, fallback Perplexity/Brave, Firecrawl scrape-only). classifyConfidence stamps HIGH|MEDIUM|LOW by provider (never throws). providerAvailability maps config flags to usable providers. planResearch checks the Research Store (injected seam) and returns cache-hits + a per-question fetch plan, falling through the waterfall to the always-available websearch terminal. 22 behavioral + property tests.

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#656): add Package Legitimacy module (registry-API verdicts, slopcheck optional)

Replaces the pip-install-or-degrade slopcheck prose gate with code: classifyPackage (pure, never throws) computes OK|SUS|SLOP from tunable thresholds (minAgeDays 30, minWeeklyDownloads 1000, requireRepo). checkPackages queries injectable npm/PyPI/crates registry adapters (real https with 5s timeout, degraded-not-thrown on failure); slopcheck is one optional adapter that can only escalate severity, never degrade to [ASSUMED]. 34 behavioral + property tests; boundary coverage on age and downloads (limit-1/limit/limit+1).

Known follow-up: real npm adapter must add api.npmjs.org last-week downloads fetch (currently null -> unknown-downloads). Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#656): detect Tavily/Ref/Perplexity/Jina provider keys; complete npm downloads adapter

config: add tavily_search/ref_search/perplexity/jina availability flags (env var or ~/.gsd/<x>_api_key), mirroring brave_search/exa_search/firecrawl, so the Research Provider waterfall can gate them. package-legitimacy: real npm adapter now fetches api.npmjs.org last-week downloads (bounded, degraded-not-thrown) so weeklyDownloads is populated. +12 config tests; 34 legitimacy tests unchanged.

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#656): expose Research seam via gsd-tools query (research-plan, research-store, package-legitimacy)

Routes the L2-hybrid surface so agents reach it as CLI: 'query research-store get/put' (cache, HOME-sandboxable), 'query research-plan --input' (cache-hits + fetch plan from planResearch), 'query package-legitimacy check --ecosystem' (async registry verdicts). Commands skip .planning root resolution and appear in top-level usage. 5 behavioral runGsdTools tests; command-contract unchanged (335).

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(#656): document Research module (CONTEXT predicates, ADR-0656, architecture, changeset)

Adds GSD-RESEARCH.* + DEFECT.RESEARCH-PROVIDER-PROSE-DRIFT predicates to CONTEXT.md, ADR-0656 recording the L2-hybrid seam decision, a docs/ARCHITECTURE.md Research Module subsection, and an Added changeset fragment (pr:0, backfill on PR). Notes the #657 deferrals (agent collapse + install.js MCP mapping).

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#656): sync inventory for research modules

Regenerate INVENTORY-MANIFEST.json and bump docs/INVENTORY.md CLI Modules count 82->85 with rows for research-store/research-provider/package-legitimacy (DEFECT.INVENTORY-DRIFT).

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#656): eslint-ignore generated research .cjs artifacts (ADR-457)

research-store/research-provider/package-legitimacy .cjs are tsc-generated from src/*.cts, so they belong in the ESLint ignore block (lint the .cts source, not the emitted .cjs). Fixes tests/551-eslint-bin-lib-coverage.

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#656): backfill changeset pr number to #664

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#656): satisfy eslint lint-tests gate

Fix 20 eslint errors in the new research files: use helpers.cleanup() instead of raw fs.rmSync() in tests (local/no-raw-rmsync-in-tests, Windows-EBUSY retry budget); drop redundant '| string' union members and unnecessary type assertions; deterministic object normalization in researchKey (no-base-to-string). Logic unchanged; 6180 tests still green.

Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): harden package legitimacy per review (W1/W2/I3/I4)

W1: httpsGet now reads statusCode; npm/PyPI/crates map 404 -> exists:false -> SLOP (registry-existence is the #1 slopsquatting defense; previously only npm caught it). Transport made injectable (_setHttpGet) for hermetic 404 tests. W2: suspicious-postinstall is now terminal SLOP independent of the optional slopcheck adapter, and the regex drops the bare https?:// arm (over-fired on esbuild/sharp/node-gyp) for shell-exec/download-exec signatures only. I3: checkPackages now threads version to registry.lookup and adapters verify that specific version exists. I4: moreServerVerdict -> moreSevereVerdict. +11 regression tests (all RED-first); 45 total green.

Addresses review by @davesienkowski on #664. Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): research-store tier coherence + freshness + version TTL (W4/I1/I2/I4)

I1: tier now derives from source (curated -> user ~/.gsd, else -> project .planning), not kind, so put-tier and get-tier can't diverge; kind is a key component only. W4: getResearch searches both tiers and returns the freshest (non-stale preferred), never letting a stale curated entry shadow a fresh web one; blank version caps TTL at 1 day (no 30d on version-blind keys). I2: atomic platformWriteSync instead of raw fs.writeFileSync on the shared global path. I4: dropped the dead ttlForSource arm. CLI get now searches both tiers. +5 RED-first regression tests; 38 green.

Addresses review by @davesienkowski on #664. Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): expose classifyConfidence as a CLI route, killing dead code (W3)

Adds 'gsd-tools query classify-confidence --provider X [--verified]' so research agents get the confidence tier FROM CODE (provider waterfall + verification lever) instead of asserting it in prose. classifyConfidence previously had no runtime caller. HIGH means 'trusted provider'; --verified raises web results to MEDIUM (verification semantics documented in ADR-0656). +4 behavioral tests.

Addresses review by @davesienkowski on #664 (W3). Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): close Codex adversarial-review findings (path-traversal, version-age, malformed-cache)

HIGH: research key must be 64-hex sha256 (isValidResearchKey) + resolved-path containment check in put/get + CLI validation -> blocks '../../x' arbitrary-file-write. HIGH: package legitimacy now derives publishedAt from the REQUESTED version (npm time[version], PyPI releases[version] upload_time, crates versions[].created_at) so a new malicious version of an old package can't inherit old age and evade 'too-new'. MEDIUM: getResearch validates entry shape (finite fetched_at + positive ttl + required fields) -> malformed cache entry is a miss, not fresh-forever. +regression tests (RED-first); 111 green.

Codex adversarial review (required pre-PR gate). Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): close code-review correctness findings

(1) package-legitimacy CLI now rejects unknown --flags instead of silently consuming the following package as a flag value; only --ecosystem takes a value. (2) crates recent_downloads (90-day) normalized to a weekly figure before the minWeeklyDownloads threshold (was ~13x too lenient). (3) research-plan --input validates parsed JSON is an object with an Array questions before destructuring -> clean usage error instead of an uncaught TypeError on null/bad input. (4) research-store put rejects a flag value that is itself a --flag (no more storing '--source' as content). (5) planResearch skips questions whose text is not a non-empty string instead of emitting question:undefined. +13 RED-first regression tests; 143 green.

Code-review gate. Issue #656. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(#657): extract researcher documentation_lookup to shared @-reference

6 researcher agents carried a near-duplicate <documentation_lookup> block; consolidate into gsd-core/references/research-documentation-lookup.md (@-included). Unifies the ctx7 CLI fallback to the safer 'command -v ctx7' guard (drops silent 'npx --yes ctx7@latest' execution in 5 agents). Behavior-preserving dedup; inventory 63->64 references. Phase A of the agent collapse.

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(#657): extract researcher philosophy + verification-protocol to shared @-references

philosophy and the pitfalls+pre-submission-checklist common-core were near-duplicated in project/phase researchers; consolidate into gsd-core/references/research-{philosophy,verification-protocol}.md (@-included). phase-researcher keeps its 3 extra checklist items inline. Pre-submission domains checklist made agent-agnostic so project-researcher doesn't lose features/architecture coverage. Write-contract intentionally left inline (bug-214 tests assert it verbatim). Inventory 64->66 refs. Behavior-preserving. Phase A.

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#657): wire gsd-phase-researcher to the Research seam (Phase B / S1)

The phase researcher now CALLS the code seam instead of carrying inline mechanics: provider waterfall -> 'gsd-tools query research-plan' (+ research-store put to cache digests); confidence-tier prose -> 'gsd-tools query classify-confidence'; slopcheck pip-install protocol -> 'gsd-tools query package-legitimacy check'. This makes the Research module a real runtime consumer (validates the seam end-to-end, addresses reviewer S1) and removes the duplicated waterfall/confidence/slopcheck prose. RESEARCH.md output contract, commit step, structured returns, and Phase-A @-includes unchanged. package-legitimacy-gate.test.cjs rewritten prose-grep -> behavioral (asserts the seam invocation).

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#657): wire gsd-project-researcher to the seam + add tavily/ref/jina MCP tools (Phase C.1)

project-researcher now calls gsd-tools query research-plan / classify-confidence (+ research-store put) instead of the inline provider waterfall + confidence-tier prose (mirrors the phase-researcher rewire; no package-legitimacy — phase-only). Output contract (STACK/FEATURES/ARCHITECTURE/PITFALLS/SUMMARY.md + sections, no-commit, structured returns, Phase-A @-includes) unchanged. Adds mcp__tavily/ref/jina__* to the project/phase/ui researcher tools frontmatter (Balanced provider set) so install.js MCP mapping (C.2) has a consumer.

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(#657): cover tavily/ref/jina MCP install handling + frontmatter parity guard (Phase C.2)

Investigation: exa/firecrawl have no explicit per-runtime tool-mapping — every mcp__<server>__* except context7 rides the generic passthrough (Copilot lowercases; OpenCode/Cursor/Windsurf/Augment keep as-is; Gemini auto-discovers). tavily/ref/jina are handled identically, no install path broken. Added 12 copilot-install passthrough tests + a mcp-tool-inheritance parity guard (tavily co-declared with exa, jina with firecrawl, ref present across the 3 web researchers) so the MCP set can't drift. No io.github registry ids invented (none sourceable in-repo); documented as a follow-up. 488 tests green.

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#657): profiles as source of truth for researcher agents + drift-guard (Phase C.3)

scripts/research-profiles.cjs declares each of the 7 researcher agents' identity + contract (name, description, color, tools, required @-includes, required gsd-tools seam calls, output-contract markers). scripts/gen-research-agents.cjs --check validates every committed agent against its profile; --write regenerates ONLY the frontmatter from profiles (body untouched) and is a verified no-op against the current agents (zero diff = fidelity). tests/research-agent-profiles.test.cjs is the DEFECT.GENERATIVE-FIX drift guard. Design note: profiles govern the generatable/contract surface rather than destructively regenerating the disparate operational prose bodies (those were deduped via @-includes in Phase A). scripts/ is not inventoried (no inventory change).

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#657): complete agent provider-dispatch + parity guard; align legitimacy field; validate profiles

Adversarial-review findings: (HIGH) the seam-wired agents' Step-C dispatch only mapped 6 providers, so a planResearch result of jina/ref/perplexity/brave (reachable via the waterfall fallbacks) had no handling -> agent stall; completed both agents' dispatch to all 9 PROVIDER_WATERFALL ids + a catch-all, and added a parity test asserting agent dispatch stays in sync with research-provider PROVIDER_WATERFALL (DEFECT.GENERATIVE-FIX). (MEDIUM) phase-researcher package-legitimacy JSON example used 'package' but the module returns 'name' -> aligned. (LOW) gen-research-agents checkAgent now returns a clear failure for a malformed profile instead of throwing. +parity/validation tests (RED-first).

Issue #657. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#656): make classifyConfidence verification-evidence-driven (W3)

Confidence conflated provider authority with claim verification — context7/ref
stamped HIGH purely by provider identity, and the only verification lever was a
self-set --verified flag. Split into two axes: provider authority (static) +
verification evidence (code-computed). HIGH now requires ground-truth
corroboration (legitimacyVerdict OK), independent of provider; authority alone
caps at MEDIUM; SLOP caps at LOW; the self-reported --verified is demoted to a
MEDIUM-only web lever. HIGH = corroborated-against-authoritative-source, not a
correctness guarantee. Adds --legitimacy-verdict to the classify-confidence CLI;
updates CONTEXT.md predicate + ADR-0656 (tier set unchanged, ADR-consistent).

Addresses davesienkowski's W3 review on #664.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#656): bind classify-confidence verdict to code, closing CLI self-grading

Adversarial review found the new --legitimacy-verdict flag was caller-supplied,
so an agent could self-assert OK->HIGH without any real legitimacy check —
reintroducing the exact self-grading hole W3 closes. Remove the free flag; the
CLI now computes the verdict via checkPackages only when --package/--ecosystem
is given (code-computed, not agent-asserted). Update the stale CLI test
(context7 alone -> MEDIUM) and extend the property test to vary legitimacyVerdict.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-05 17:58:48 -04:00
committed by GitHub
parent b44e16a47a
commit 11afca2968
37 changed files with 4979 additions and 439 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
agents/gsd-advisor-researcher.md
View File

@@ -18,26 +18,7 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
npx --yes ctx7@latest library <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<input>

21
agents/gsd-ai-researcher.md
View File

@@ -17,26 +17,7 @@ Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation g
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
npx --yes ctx7@latest library <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<required_reading>

21
agents/gsd-domain-researcher.md
View File

@@ -17,26 +17,7 @@ Research the business domain — not the technical framework. Write Section 1b o
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
npx --yes ctx7@latest library <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<required_reading>

265
agents/gsd-phase-researcher.md
View File

@@ -1,7 +1,7 @@
---
name: gsd-phase-researcher
description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
color: cyan
# hooks:
# PostToolUse:
@@ -30,41 +30,13 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <
- `[CITED: docs.example.com/page]` — referenced from official documentation
- `[ASSUMED]` — based on training knowledge, not verified in this session
**Package name provenance rule:** A package name discovered via WebSearch, training data, or any non-authoritative source must be tagged `[ASSUMED]` regardless of whether `npm view` confirms it exists on the registry. Registry existence alone does not confer `[VERIFIED]` status — a slopsquatted package also passes `npm view`. Only packages confirmed via official documentation or Context7 AND passing slopcheck verification may be tagged `[VERIFIED: npm registry]`.
**Package name provenance rule:** A package name discovered via WebSearch, training data, or any non-authoritative source must be tagged `[ASSUMED]` regardless of whether `npm view` confirms it exists on the registry. Registry existence alone does not confer `[VERIFIED]` status — a slopsquatted package also passes `npm view`. Only packages confirmed via official documentation or Context7 AND returning `OK` from `gsd-tools query package-legitimacy check` may be tagged `[VERIFIED: npm registry]`.
Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist.
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
if command -v ctx7 &>/dev/null; then
ctx7 library <name> "<query>"
else
echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
fi
```
Step 2 — Fetch documentation:
```bash
if command -v ctx7 &>/dev/null; then
ctx7 docs <libraryId> "<query>"
else
echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
fi
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output. Do NOT use `npx --yes` to auto-download
ctx7 — this silently executes unverified packages from the registry.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<project_context>
@@ -109,153 +81,106 @@ Your RESEARCH.md is consumed by `gsd-planner`:
</downstream_consumer>
<philosophy>
## Claude's Training as Hypothesis
Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
**The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
**The discipline:**
1. **Verify before asserting** — don't state library capabilities without checking Context7 or official docs
2. **Date your knowledge** — "As of my training" is a warning flag
3. **Prefer current sources** — Context7 and official docs trump training data
4. **Flag uncertainty** — LOW confidence when only training data supports a claim
## Honest Reporting
Research value comes from accuracy, not completeness theater.
**Report honestly:**
- "I couldn't find X" is valuable (now we know to investigate differently)
- "This is LOW confidence" is valuable (flags for validation)
- "Sources contradict" is valuable (surfaces real ambiguity)
**Avoid:** Padding findings, stating unverified claims as facts, hiding uncertainty behind confident language.
## Research is Investigation, Not Confirmation
**Bad research:** Start with hypothesis, find evidence to support it
**Good research:** Gather evidence, form conclusions from evidence
When researching "best library for X": find what the ecosystem actually uses, document tradeoffs honestly, let evidence drive recommendation.
@~/.claude/gsd-core/references/research-philosophy.md
</philosophy>
<tool_strategy>
## Tool Priority
## Research Plan via Code Seam
| Priority | Tool | Use For | Trust Level |
|----------|------|---------|-------------|
| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
The agent decides **what** to research (the questions). The seam decides **which provider** to use and manages caching.
**Context7 flow:**
1. `mcp__context7__resolve-library-id` with libraryName
2. `mcp__context7__query-docs` with resolved ID + specific query
### Step A — Build a research-plan input file
**WebSearch tips:** Use multiple query variations. Cross-verify with authoritative sources. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
Construct a JSON file at a temp path (e.g. `/tmp/research-plan-input.json`):
## Enhanced Web Search (Brave API)
```json
{
"ecosystem": "<npm|pypi|crates|...>",
"config": { "exa_search": true/false, "brave_search": true/false, "firecrawl": true/false, "tavily_search": true/false },
"questions": [
{ "text": "How does X work?", "kind": "docs", "library": "x", "version": "1.2.3" },
{ "text": "Best practices for Y?", "kind": "web" }
]
}
```
Check `brave_search` from init context. If `true`, use Brave Search for higher quality results:
`config` comes from the init context (availability flags). `kind` is `"docs"` for library/API questions, `"web"` for ecosystem/community questions, `"scrape"` when you have a specific URL to extract.
### Step B — Obtain the fetch plan
```bash
gsd-tools query websearch "your query" --limit 10
gsd-tools query research-plan --input /tmp/research-plan-input.json
```
**Options:**
- `--limit N` — Number of results (default: 10)
- `--freshness day|week|month` — Restrict to recent content
Returns `{ "items": [ { "question": "...", "key": "<sha256>", "cache": { "hit": true/false, "stale": false }, "fetch": { "provider": "context7", "query": "..." } } ] }`.
If `brave_search: false` (or not set), use built-in WebSearch tool instead.
- `cache.hit && !cache.stale` → reuse the cached digest; no fetch needed.
- `cache.hit && cache.stale` → fetch anyway to refresh; the old entry is returned as a fallback.
- no `cache` field → cache miss; must fetch.
Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
### Step C — Execute the indicated fetch
### Exa Semantic Search (MCP)
For each item where `fetch` is present, invoke the MCP tool matching `fetch.provider`:
Check `exa_search` from init context. If `true`, use Exa for semantic, research-heavy queries:
| provider id | MCP tool / built-in |
|-------------|---------------------|
| `context7` | `mcp__context7__resolve-library-id` then `mcp__context7__query-docs` |
| `ref` | `mcp__ref__*` (use the appropriate ref MCP tool for the query) |
| `jina` | `mcp__jina__*` (use the appropriate jina MCP tool for the query) |
| `exa` | `mcp__exa__web_search_exa` with `fetch.query` |
| `tavily` | `mcp__tavily__search` with `fetch.query` |
| `perplexity` | `mcp__perplexity__*` (use the appropriate perplexity MCP tool for the query) |
| `brave` | `gsd-tools query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
| `firecrawl` | `mcp__firecrawl__scrape` with url (scrape kind) or `mcp__firecrawl__search` |
| `websearch` | built-in `WebSearch` tool |
| `webfetch` | built-in `WebFetch` tool |
```
mcp__exa__web_search_exa with query: "your semantic query"
For any other provider id `X` not listed above: use `mcp__X__*` if available, else fall back to `WebSearch`.
**WebSearch tip:** Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
### Step D — Cache each digest
After digesting a source, persist it so future runs can reuse it:
```bash
gsd-tools query research-store put <key> \
--content "<one-paragraph digest>" \
--source <curated|web> \
--provider <provider-id> \
--confidence <HIGH|MEDIUM|LOW> \
--kind <docs|web>
```
**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries. Returns semantically relevant results.
If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
### Firecrawl Deep Scraping (MCP)
Check `firecrawl` from init context. If `true`, use Firecrawl to extract structured content from URLs:
```
mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
```
**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs. Use after finding a URL from Exa, WebSearch, or known docs. Returns clean markdown.
If `firecrawl: false` (or not set), fall back to WebFetch.
## Verification Protocol
**Verify every WebSearch finding:**
```
For each WebSearch finding:
1. Can I verify with Context7? → YES: HIGH confidence
2. Can I verify with official docs? → YES: MEDIUM confidence
3. Do multiple sources agree? → YES: Increase one level
4. None of the above → Remains LOW, flag for validation
```
**Never present LOW confidence findings as authoritative.**
`key` comes from the `research-plan` item. `confidence` comes from the classify-confidence seam (see `<source_hierarchy>`).
</tool_strategy>
<source_hierarchy>
| Level | Sources | Use |
|-------|---------|-----|
| HIGH | Context7, official docs, official releases | State as fact |
| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution |
| LOW | WebSearch only, single source, unverified | Flag as needing validation |
Obtain the confidence tier from code — do not hard-code tiers in your reasoning:
Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHub > Brave/WebSearch (verified) > WebSearch (unverified)
```bash
gsd-tools query classify-confidence --provider <provider-id>
# for cross-checked findings, add --verified:
gsd-tools query classify-confidence --provider <provider-id> --verified
```
Returns `HIGH`, `MEDIUM`, or `LOW`. Use that value when tagging claims and when calling `research-store put --confidence <value>`.
Keep using the provenance tags in RESEARCH.md:
- `[VERIFIED: source]` — confirmed via tool AND from an authoritative source (HIGH confidence)
- `[CITED: url]` — referenced from official documentation (MEDIUM confidence)
- `[ASSUMED]` — training knowledge, not verified this session (LOW confidence)
**Never present LOW confidence findings as authoritative.**
</source_hierarchy>
<verification_protocol>
@~/.claude/gsd-core/references/research-verification-protocol.md
## Known Pitfalls
### Configuration Scope Blindness
**Trap:** Assuming global configuration means no project-scoping exists
**Prevention:** Verify ALL configuration scopes (global, project, local, workspace)
### Deprecated Features
**Trap:** Finding old documentation and concluding feature doesn't exist
**Prevention:** Check current official docs, review changelog, verify version numbers and dates
### Negative Claims Without Evidence
**Trap:** Making definitive "X is not possible" statements without official verification
**Prevention:** For any negative claim — is it verified by official docs? Have you checked recent updates? Are you confusing "didn't find it" with "doesn't exist"?
### Single Source Reliance
**Trap:** Relying on a single source for critical claims
**Prevention:** Require multiple sources: official docs (primary), release notes (currency), additional source (verification)
## Pre-Submission Checklist
- [ ] All domains investigated (stack, patterns, pitfalls)
- [ ] Negative claims verified with official docs
- [ ] Multiple sources cross-referenced for critical claims
- [ ] URLs provided for authoritative sources
- [ ] Publication dates checked (prefer recent/current)
- [ ] Confidence levels assigned honestly
- [ ] "What might I have missed?" review completed
- [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank)
- [ ] Security domain included (or `security_enforcement: false` confirmed)
- [ ] ASVS categories verified against phase tech stack
@@ -269,30 +194,30 @@ Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHu
Every phase that installs external packages **must** run the following verification before
emitting the `## Package Legitimacy Audit` section in RESEARCH.md.
### Step 1 — Install slopcheck (best-effort)
### Step 1 — Run legitimacy check via seam
```bash
pip install slopcheck --break-system-packages 2>/dev/null || pip install slopcheck 2>/dev/null || true
gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkg1> <pkg2> ...
```
### Step 2 — Run legitimacy check
Returns a JSON array of per-package verdicts:
```bash
if command -v slopcheck &>/dev/null; then
slopcheck install <pkg1> <pkg2> ... --json
else
echo "slopcheck not available — marking all packages [ASSUMED]"
fi
```json
[
{ "name": "pkg1", "verdict": "OK", "signals": { ... }, "reasons": [] },
{ "name": "pkg2", "verdict": "SUS", "signals": { ... }, "reasons": ["low downloads"] },
{ "name": "pkg3", "verdict": "SLOP", "signals": { ... }, "reasons": ["not found on registry"] }
]
```
**Interpreting results:**
- `[SLOP]` — hallucinated or dangerously new package. **Remove entirely** from all RESEARCH.md recommendations. List in audit table under `Disposition: REMOVED`.
- `[SUS]` — suspicious (new, low-downloads, or no source repo). **Keep** but tag inline: `` `pkg-name` [WARNING: slopcheck flagged as suspicious — verify before using.] ``
- `[OK]` — clean. Proceed normally.
**Interpreting verdicts:**
- `SLOP` — hallucinated or dangerously new package. **Remove entirely** from all RESEARCH.md recommendations. List in audit table under `Disposition: REMOVED`.
- `SUS` — suspicious (new, low-downloads, or no source repo). **Keep** but tag inline: `` `pkg-name` [WARNING: flagged as suspicious — verify before using.] `` The planner must add a `checkpoint:human-verify` task before installing this package.
- `OK` — clean. Proceed normally.
**Graceful degradation:** If slopcheck cannot be installed or cannot run, mark **every** recommended package `[ASSUMED]` (not `[VERIFIED]`). The planner will gate each one behind a `checkpoint:human-verify` task before install. This is strictly safer than the current baseline — never a hard failure.
Packages discovered via WebSearch or training data and not yet verified must be tagged `[ASSUMED]` regardless of registry existence (a slopsquatted package also passes registry lookup).
### Step 3 — Ecosystem-specific registry verification
### Step 2 — Ecosystem-specific registry verification
Run the appropriate command for the phase's primary language:
@@ -310,14 +235,14 @@ cargo search <pkg>
Cross-ecosystem confusion (a Python package name that exists on npm but not PyPI) is a
documented hallucination vector (~9% rate). Always verify on the correct ecosystem registry.
### Step 4 — Check for suspicious postinstall scripts (Node.js phases)
### Step 3 — Check for suspicious postinstall scripts (Node.js phases)
```bash
npm view <pkg> scripts.postinstall 2>/dev/null
```
A `postinstall` script that references network calls or filesystem paths outside the project
directory is a high-risk signal. Flag such packages `[SUS]` even if slopcheck rates them `[OK]`.
directory is a high-risk signal. Flag such packages `[SUS]` even if the seam rates them `[OK]`.
</package_legitimacy_protocol>
@@ -380,16 +305,16 @@ Document the verified version and publish date. Training data versions may be mo
> **Required** whenever this phase installs external packages. Run the Package Legitimacy Gate protocol before completing this section.
| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
|---------|----------|-----|-----------|-------------|-----------|-------------|
| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
|---------|----------|-----|-----------|-------------|---------|-------------|
| [name] | npm/PyPI/crates | [e.g., 8 yrs] | [e.g., 50M/wk] | [github.com/org/repo or "none"] | [OK] | Approved |
| [name] | npm | [e.g., 3 days] | [e.g., 0] | none | [SLOP] | REMOVED |
| [name] | npm | [e.g., 2 mo] | [e.g., 800/wk] | [github.com/…] | [SUS] | Flagged — planner must add checkpoint |
**Packages removed due to slopcheck [SLOP] verdict:** [list, or "none"]
**Packages removed due to [SLOP] verdict:** [list, or "none"]
**Packages flagged as suspicious [SUS]:** [list — planner inserts checkpoint:human-verify before each install]
*If slopcheck was unavailable at research time, all packages above are tagged `[ASSUMED]` and the planner must gate each install behind a `checkpoint:human-verify` task.*
*Packages discovered via WebSearch or training data that have not been verified against an authoritative source are tagged `[ASSUMED]` and the planner must gate each install behind a `checkpoint:human-verify` task.*
## Architecture Patterns
@@ -778,7 +703,7 @@ docker info 2>/dev/null | head -3
## Step 3: Execute Research Protocol
For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd-tools query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd-tools query classify-confidence --provider <id>` to obtain the tier).
## Step 4: Validation Architecture Research (if nyquist_validation enabled)
@@ -925,7 +850,7 @@ Research is complete when:
- [ ] Common pitfalls catalogued
- [ ] Environment availability audited (or skipped with reason)
- [ ] Code examples provided
- [ ] Source hierarchy followed (Context7 → Official → WebSearch)
- [ ] Source hierarchy followed (research-plan seam determines provider order; classify-confidence seam determines tiers)
- [ ] All findings have confidence levels
- [ ] RESEARCH.md created in correct format
- [ ] RESEARCH.md committed to git

227
agents/gsd-project-researcher.md
View File

@@ -1,7 +1,7 @@
---
name: gsd-project-researcher
description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
color: cyan
# hooks:
# PostToolUse:
@@ -33,53 +33,11 @@ Your files feed the roadmap:
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
npx --yes ctx7@latest library <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<philosophy>
## Training Data = Hypothesis
Claude's training is 6-18 months stale. Knowledge may be outdated, incomplete, or wrong.
**Discipline:**
1. **Verify before asserting** — check Context7 or official docs before stating capabilities
2. **Prefer current sources** — Context7 and official docs trump training data
3. **Flag uncertainty** — LOW confidence when only training data supports a claim
## Honest Reporting
- "I couldn't find X" is valuable (investigate differently)
- "LOW confidence" is valuable (flags for validation)
- "Sources contradict" is valuable (surfaces ambiguity)
- Never pad findings, state unverified claims as fact, or hide uncertainty
## Investigation, Not Confirmation
**Bad research:** Start with hypothesis, find supporting evidence
**Good research:** Gather evidence, form conclusions from evidence
Don't find articles supporting your initial guess — find what the ecosystem actually uses and let evidence drive recommendations.
@~/.claude/gsd-core/references/research-philosophy.md
</philosophy>
<research_modes>
@@ -94,132 +52,95 @@ Don't find articles supporting your initial guess — find what the ecosystem ac
<tool_strategy>
## Tool Priority Order
## Research Plan via Code Seam
### 1. Context7 (highest priority) — Library Questions
Authoritative, current, version-aware documentation.
The agent decides **what** to research (the questions). The seam decides **which provider** to use and manages caching.
```
1. mcp__context7__resolve-library-id with libraryName: "[library]"
2. mcp__context7__query-docs with libraryId: [resolved ID], query: "[question]"
### Step A — Build a research-plan input file
Construct a JSON file at a temp path (e.g. `/tmp/research-plan-input.json`):
```json
{
"ecosystem": "<npm|pypi|crates|...>",
"config": { "exa_search": true/false, "brave_search": true/false, "firecrawl": true/false, "tavily_search": true/false },
"questions": [
{ "text": "How does X work?", "kind": "docs", "library": "x", "version": "1.2.3" },
{ "text": "Best practices for Y?", "kind": "web" }
]
}
```
Resolve first (don't guess IDs). Use specific queries. Trust over training data.
`config` comes from the init context (availability flags). `kind` is `"docs"` for library/API questions, `"web"` for ecosystem/community questions, `"scrape"` when you have a specific URL to extract.
### 2. Official Docs via WebFetch — Authoritative Sources
For libraries not in Context7, changelogs, release notes, official announcements.
Use exact URLs (not search result pages). Check publication dates. Prefer /docs/ over marketing.
### 3. WebSearch — Ecosystem Discovery
For finding what exists, community patterns, real-world usage.
**Query templates:**
```
Ecosystem: "[tech] best practices", "[tech] recommended libraries"
Patterns: "how to build [type] with [tech]", "[tech] architecture patterns"
Problems: "[tech] common mistakes", "[tech] gotchas"
```
Use multiple query variations. Mark WebSearch-only findings as LOW confidence. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
### Enhanced Web Search (Brave API)
Check `brave_search` from orchestrator context. If `true`, use Brave Search for higher quality results:
### Step B — Obtain the fetch plan
```bash
gsd-tools query websearch "your query" --limit 10
gsd-tools query research-plan --input /tmp/research-plan-input.json
```
**Options:**
- `--limit N` — Number of results (default: 10)
- `--freshness day|week|month` — Restrict to recent content
Returns `{ "items": [ { "question": "...", "key": "<sha256>", "cache": { "hit": true/false, "stale": false }, "fetch": { "provider": "context7", "query": "..." } } ] }`.
If `brave_search: false` (or not set), use built-in WebSearch tool instead.
- `cache.hit && !cache.stale` → reuse the cached digest; no fetch needed.
- `cache.hit && cache.stale` → fetch anyway to refresh; the old entry is returned as a fallback.
- no `cache` field → cache miss; must fetch.
Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
### Step C — Execute the indicated fetch
### Exa Semantic Search (MCP)
For each item where `fetch` is present, invoke the MCP tool matching `fetch.provider`:
Check `exa_search` from orchestrator context. If `true`, use Exa for research-heavy, semantic queries:
| provider id | MCP tool / built-in |
|-------------|---------------------|
| `context7` | `mcp__context7__resolve-library-id` then `mcp__context7__query-docs` |
| `ref` | `mcp__ref__*` (use the appropriate ref MCP tool for the query) |
| `jina` | `mcp__jina__*` (use the appropriate jina MCP tool for the query) |
| `exa` | `mcp__exa__web_search_exa` with `fetch.query` |
| `tavily` | `mcp__tavily__search` with `fetch.query` |
| `perplexity` | `mcp__perplexity__*` (use the appropriate perplexity MCP tool for the query) |
| `brave` | `gsd-tools query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
| `firecrawl` | `mcp__firecrawl__scrape` with url (scrape kind) or `mcp__firecrawl__search` |
| `websearch` | built-in `WebSearch` tool |
| `webfetch` | built-in `WebFetch` tool |
```
mcp__exa__web_search_exa with query: "your semantic query"
For any other provider id `X` not listed above: use `mcp__X__*` if available, else fall back to `WebSearch`.
**WebSearch tip:** Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
### Step D — Cache each digest
After digesting a source, persist it so future runs can reuse it:
```bash
gsd-tools query research-store put <key> \
--content "<one-paragraph digest>" \
--source <curated|web> \
--provider <provider-id> \
--confidence <HIGH|MEDIUM|LOW> \
--kind <docs|web>
```
**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries, ecosystem exploration. Returns semantically relevant results rather than keyword matches.
If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
### Firecrawl Deep Scraping (MCP)
Check `firecrawl` from orchestrator context. If `true`, use Firecrawl to extract structured content from discovered URLs:
```
mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
```
**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs, comparison articles. Use after finding a relevant URL from Exa, WebSearch, or known docs. Returns clean markdown instead of raw HTML.
If `firecrawl: false` (or not set), fall back to WebFetch.
## Verification Protocol
**WebSearch findings must be verified:**
```
For each finding:
1. Verify with Context7? YES → HIGH confidence
2. Verify with official docs? YES → MEDIUM confidence
3. Multiple sources agree? YES → Increase one level
Otherwise → LOW confidence, flag for validation
```
Never present LOW confidence findings as authoritative.
## Confidence Levels
| Level | Sources | Use |
|-------|---------|-----|
| HIGH | Context7, official documentation, official releases | State as fact |
| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution |
| LOW | WebSearch only, single source, unverified | Flag as needing validation |
**Source priority:** Context7 → Exa (verified) → Firecrawl (official docs) → Official GitHub → Brave/WebSearch (verified) → WebSearch (unverified)
`key` comes from the `research-plan` item. `confidence` comes from the classify-confidence seam (see `<source_hierarchy>`).
</tool_strategy>
<source_hierarchy>
Obtain the confidence tier from code — do not hard-code tiers in your reasoning:
```bash
gsd-tools query classify-confidence --provider <provider-id>
# for cross-checked findings, add --verified:
gsd-tools query classify-confidence --provider <provider-id> --verified
```
Returns `HIGH`, `MEDIUM`, or `LOW`. Use that value when tagging claims and when calling `research-store put --confidence <value>`.
**Never present LOW confidence findings as authoritative.**
</source_hierarchy>
<verification_protocol>
## Research Pitfalls
### Configuration Scope Blindness
**Trap:** Assuming global config means no project-scoping exists
**Prevention:** Verify ALL scopes (global, project, local, workspace)
### Deprecated Features
**Trap:** Old docs → concluding feature doesn't exist
**Prevention:** Check current docs, changelog, version numbers
### Negative Claims Without Evidence
**Trap:** Definitive "X is not possible" without official verification
**Prevention:** Is this in official docs? Checked recent updates? "Didn't find" ≠ "doesn't exist"
### Single Source Reliance
**Trap:** One source for critical claims
**Prevention:** Require official docs + release notes + additional source
## Pre-Submission Checklist
- [ ] All domains investigated (stack, features, architecture, pitfalls)
- [ ] Negative claims verified with official docs
- [ ] Multiple sources for critical claims
- [ ] URLs provided for authoritative sources
- [ ] Publication dates checked (prefer recent/current)
- [ ] Confidence levels assigned honestly
- [ ] "What might I have missed?" review completed
@~/.claude/gsd-core/references/research-verification-protocol.md
</verification_protocol>
<output_formats>
@@ -564,7 +485,7 @@ Orchestrator provides: project name/description, research mode, project context,
## Step 3: Execute Research
For each domain: Context7 → Official Docs → WebSearch → Verify. Document with confidence levels.
For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd-tools query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd-tools query classify-confidence --provider <id>` to obtain the tier).
## Step 4: Quality Check
@@ -678,7 +599,7 @@ Research is complete when:
- [ ] Feature landscape mapped (table stakes, differentiators, anti-features)
- [ ] Architecture patterns documented
- [ ] Domain pitfalls catalogued
- [ ] Source hierarchy followed (Context7 → Official → WebSearch)
- [ ] Source hierarchy followed (research-plan seam determines provider order; classify-confidence seam determines tiers)
- [ ] All findings have confidence levels
- [ ] Output files created in `.planning/research/`
- [ ] SUMMARY.md includes roadmap implications

23
agents/gsd-ui-researcher.md
View File

@@ -1,7 +1,7 @@
---
name: gsd-ui-researcher
description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
color: "#E879F9"
# hooks:
# PostToolUse:
@@ -28,26 +28,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
</role>
<documentation_lookup>
When you need library or framework documentation, check in this order:
1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
- Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
- Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
Step 1 — Resolve library ID:
```bash
npx --yes ctx7@latest library <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
@~/.claude/gsd-core/references/research-documentation-lookup.md
</documentation_lookup>
<project_context>