docs(14): create researcher agent phase plans

Phase 14: Dedicated Researcher Agent - 3 plans in 2 waves - Wave 1: 14-01 (gsd-researcher agent creation) - Wave 2: 14-02, 14-03 (orchestrator refactoring, parallel) - Ready for execution
2026-01-15 16:40:51 -06:00
parent 0a19b2e04d
commit d20d284433
3 changed files with 615 additions and 0 deletions
--- a/.planning/phases/14-researcher-agent/14-01-PLAN.md
+++ b/.planning/phases/14-researcher-agent/14-01-PLAN.md
@@ -0,0 +1,197 @@
+---
+phase: 14-researcher-agent
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: [agents/gsd-researcher.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "Agent has research methodology for Context7, WebSearch, WebFetch"
+    - "Agent understands source hierarchy (Context7 > official docs > WebSearch)"
+    - "Agent can operate in multiple research modes (ecosystem, feasibility, implementation, comparison)"
+    - "Agent produces structured RESEARCH.md output"
+  artifacts:
+    - path: "agents/gsd-researcher.md"
+      provides: "Complete research expertise"
+      min_lines: 700
+      contains: "<research_methodology>"
+  key_links:
+    - from: "gsd-researcher.md"
+      to: "RESEARCH.md output"
+      via: "research_protocol and output_formats sections"
+      pattern: "RESEARCH\\.md"
+---
+
+<objective>
+Create gsd-researcher agent with complete research methodology baked in.
+
+Purpose: Consolidate ~1,600 lines of research expertise (workflows, references, templates) into a dedicated agent that can be spawned by research commands.
+Output: `agents/gsd-researcher.md` with research methodology, source hierarchy, verification patterns, and multiple research modes.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Source material to consolidate:
+@get-shit-done/workflows/research-phase.md
+@get-shit-done/workflows/research-project.md
+@get-shit-done/references/research-pitfalls.md
+@get-shit-done/templates/research.md
+
+# Pattern to follow:
+@agents/gsd-debugger.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create gsd-researcher agent</name>
+  <files>agents/gsd-researcher.md</files>
+  <action>
+Create `agents/gsd-researcher.md` following the gsd-debugger pattern. Consolidate research expertise from source files (~1,600 lines) into ~700-900 lines.
+
+**Agent structure (required sections):**
+
+1. **Frontmatter:**
+   - name: gsd-researcher
+   - description: Researches domains using Context7, WebSearch, and official docs. Spawned by /gsd:research-phase and /gsd:research-project.
+   - tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, mcp__context7__*
+
+2. **role:** What the agent does, when spawned, core responsibilities
+
+3. **philosophy:**
+   - Research vs intuition (Claude's training is 6-18 months stale)
+   - Source hierarchy (Context7 > official docs > WebSearch)
+   - Evidence quality (verified vs unverified)
+   - Confidence levels (HIGH/MEDIUM/LOW)
+
+4. **research_methodology:**
+   - Context7 protocol (resolve-library-id → query-docs)
+   - WebFetch protocol (official docs, exact URLs)
+   - WebSearch protocol (discovery queries with {current_year})
+   - Cross-verification (mandatory for WebSearch findings)
+
+5. **research_modes:**
+   - **ecosystem:** Survey landscape (tools, approaches, prior art, standard stack)
+   - **feasibility:** Can we do X? What are blockers? What's the effort?
+   - **implementation:** How specifically to implement X? Patterns, libraries, code examples
+   - **comparison:** Compare options A vs B vs C with tradeoffs
+
+6. **verification_patterns:**
+   - Pitfalls checklist (from research-pitfalls.md)
+   - Source quality assessment
+   - Negative claim verification ("X is not possible" needs official source)
+   - Enumeration completeness (all known options investigated)
+
+7. **output_formats:**
+   - RESEARCH.md structure (from templates/research.md - condensed)
+   - STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md (for research-project)
+   - Confidence markup and source citations
+
+8. **execution_flow:**
+   - Mode detection from prompt
+   - Context loading (phase description, requirements, PROJECT.md)
+   - Domain identification
+   - Research execution (by mode)
+   - Quality check (pitfalls checklist)
+   - Output creation
+   - Structured return
+
+9. **structured_returns:**
+   - RESEARCH COMPLETE (standard success)
+   - RESEARCH INCONCLUSIVE (gaps documented)
+
+10. **success_criteria:** Checklist for complete research
+
+**Content consolidation targets:**
+- research-phase.md (~457 lines) → extract methodology, source protocol, output structure
+- research-project.md (~426 lines) → extract parallel research patterns, project domain analysis
+- research-pitfalls.md (~215 lines) → extract verification checklist, red flags
+- templates/research.md (~529 lines) → extract output structure (condensed)
+
+**Target length:** 700-900 lines (from ~1,600 source lines = ~50% reduction)
+
+The agent should be self-contained - spawning it with mode and context should produce quality research output.
+  </action>
+  <verify>
+- File exists at agents/gsd-researcher.md
+- Contains all 10 required sections
+- Line count is 700-900 lines
+- References Context7 MCP tools
+- Includes research modes (ecosystem, feasibility, implementation, comparison)
+- Includes pitfalls checklist
+  </verify>
+  <done>gsd-researcher.md created with complete research methodology, all modes, verification patterns</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Verify agent completeness</name>
+  <files>agents/gsd-researcher.md</files>
+  <action>
+Read the created agent file and verify:
+
+1. **All sections present:**
+   - [ ] Frontmatter with tools
+   - [ ] role section
+   - [ ] philosophy section
+   - [ ] research_methodology section
+   - [ ] research_modes section (all 4 modes)
+   - [ ] verification_patterns section
+   - [ ] output_formats section
+   - [ ] execution_flow section
+   - [ ] structured_returns section
+   - [ ] success_criteria section
+
+2. **Key content verified:**
+   - [ ] Context7 protocol documented (resolve-library-id → query-docs)
+   - [ ] Source hierarchy documented (Context7 > official > WebSearch)
+   - [ ] All 4 research modes documented (ecosystem, feasibility, implementation, comparison)
+   - [ ] Pitfalls checklist included
+   - [ ] RESEARCH.md output structure defined
+   - [ ] Confidence levels explained
+
+3. **No orphaned concepts:**
+   - [ ] Nothing references external workflow files for core methodology
+   - [ ] Agent is self-contained
+
+If any gaps found, update the agent file.
+  </action>
+  <verify>All verification points checked, agent is complete and self-contained</verify>
+  <done>Agent verified complete with all methodology, modes, and verification patterns</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] agents/gsd-researcher.md exists
+- [ ] File is 700-900 lines (consolidated from ~1,600)
+- [ ] All 10 required sections present
+- [ ] All 4 research modes documented
+- [ ] Context7 protocol included
+- [ ] Pitfalls checklist integrated
+- [ ] Agent follows gsd-debugger structural pattern
+</verification>
+
+<success_criteria>
+
+- gsd-researcher.md created with complete research methodology
+- All source expertise consolidated (research-phase, research-project, research-pitfalls, templates/research)
+- Agent is self-contained (no required external methodology files)
+- Follows established agent pattern (like gsd-debugger)
+- Ready for command integration in 14-02 and 14-03
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-researcher-agent/14-01-SUMMARY.md`
+</output>
--- a/.planning/phases/14-researcher-agent/14-02-PLAN.md
+++ b/.planning/phases/14-researcher-agent/14-02-PLAN.md
@@ -0,0 +1,205 @@
+---
+phase: 14-researcher-agent
+plan: 02
+type: execute
+wave: 2
+depends_on: ["14-01"]
+files_modified: [commands/gsd/research-phase.md, get-shit-done/templates/research-subagent-prompt.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "/gsd:research-phase spawns gsd-researcher agent"
+    - "Agent receives phase context and produces RESEARCH.md"
+    - "Command is thin orchestrator (<200 lines)"
+  artifacts:
+    - path: "commands/gsd/research-phase.md"
+      provides: "Thin orchestrator for phase research"
+      min_lines: 80
+      contains: "gsd-researcher"
+    - path: "get-shit-done/templates/research-subagent-prompt.md"
+      provides: "Subagent prompt template"
+      min_lines: 30
+  key_links:
+    - from: "research-phase.md command"
+      to: "gsd-researcher agent"
+      via: "Task tool spawn"
+      pattern: "subagent_type.*gsd-researcher"
+---
+
+<objective>
+Refactor /gsd:research-phase to thin orchestrator that spawns gsd-researcher agent.
+
+Purpose: Reduce main context load from ~500+ lines (command + workflow) to ~150 lines. Agent carries the research expertise.
+Output: Thin orchestrator command + subagent prompt template.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Current implementation to refactor:
+@commands/gsd/research-phase.md
+@get-shit-done/workflows/research-phase.md
+
+# Agent we're delegating to:
+@agents/gsd-researcher.md
+
+# Pattern to follow (from Phase 13):
+@commands/gsd/debug.md
+@get-shit-done/templates/debug-subagent-prompt.md
+
+# Prior summary for context:
+@.planning/phases/14-researcher-agent/14-01-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create research-subagent-prompt template</name>
+  <files>get-shit-done/templates/research-subagent-prompt.md</files>
+  <action>
+Create `get-shit-done/templates/research-subagent-prompt.md` following the debug-subagent-prompt.md pattern.
+
+**Template structure:**
+```markdown
+# Research Agent Prompt
+
+You are a GSD researcher spawned by the orchestrator.
+
+**Your agent expertise:**
+@~/.claude/agents/gsd-researcher.md
+
+**Research context:**
+{PHASE_CONTEXT}
+
+**Research mode:** {MODE}
+
+**Research scope:**
+{SCOPE}
+
+**Output location:** {OUTPUT_PATH}
+
+Execute research following your baked-in methodology. Return structured result when complete.
+```
+
+The template should be context-only (~50-80 lines). The agent file has all the methodology.
+  </action>
+  <verify>File exists at get-shit-done/templates/research-subagent-prompt.md</verify>
+  <done>Subagent prompt template created, references gsd-researcher agent</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Refactor research-phase command to thin orchestrator</name>
+  <files>commands/gsd/research-phase.md</files>
+  <action>
+Rewrite `commands/gsd/research-phase.md` as a thin orchestrator (~120-150 lines).
+
+**Orchestrator responsibilities (keep in command):**
+1. Validate phase argument
+2. Check for existing RESEARCH.md (offer to update/skip)
+3. Load phase context (ROADMAP, requirements, CONTEXT.md if exists)
+4. Spawn gsd-researcher agent with mode and context
+5. Handle agent return (RESEARCH COMPLETE or RESEARCH INCONCLUSIVE)
+6. Commit RESEARCH.md to git
+7. Offer next steps
+
+**Delegate to agent (via gsd-researcher):**
+- Research methodology
+- Source hierarchy (Context7 > official > WebSearch)
+- Domain identification
+- Research execution
+- Verification checklist
+- RESEARCH.md content creation
+
+**Command structure:**
+
+```yaml
+---
+name: gsd:research-phase
+description: Research how to implement a phase before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+```
+
+**Process:**
+1. validate_phase - Check phase exists in roadmap
+2. check_existing - Offer to update/view/skip if RESEARCH.md exists
+3. load_context - Read ROADMAP, requirements, CONTEXT.md
+4. spawn_researcher - Use Task tool with subagent_type: "gsd-researcher"
+5. handle_result - Process agent return
+6. git_commit - Commit RESEARCH.md
+7. offer_next - Suggest /gsd:plan-phase
+
+**Key change:** Remove all research methodology from command. Keep only orchestration logic.
+  </action>
+  <verify>
+- Command file is 120-150 lines
+- Spawns gsd-researcher agent
+- No research methodology in command (delegated to agent)
+- Has validate, check_existing, load_context, spawn_researcher, handle_result, git_commit steps
+  </verify>
+  <done>/gsd:research-phase refactored to thin orchestrator that spawns gsd-researcher</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Deprecate workflows/research-phase.md</name>
+  <files>get-shit-done/workflows/research-phase.md</files>
+  <action>
+Replace `get-shit-done/workflows/research-phase.md` with deprecation notice (following Phase 13 pattern).
+
+**Content:**
+```markdown
+# DEPRECATED
+
+This workflow has been replaced by the gsd-researcher agent.
+
+**New location:** `~/.claude/agents/gsd-researcher.md`
+
+The `/gsd:research-phase` command now spawns the gsd-researcher agent directly. All research methodology is baked into the agent.
+
+**Migration:** No action needed. Commands automatically use the new agent.
+```
+
+Keep the file (don't delete) for git history traceability.
+  </action>
+  <verify>File contains deprecation notice pointing to gsd-researcher agent</verify>
+  <done>workflows/research-phase.md deprecated with redirect to agent</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] get-shit-done/templates/research-subagent-prompt.md exists
+- [ ] commands/gsd/research-phase.md refactored (120-150 lines)
+- [ ] Command spawns gsd-researcher agent
+- [ ] No research methodology in command
+- [ ] workflows/research-phase.md deprecated with redirect
+</verification>
+
+<success_criteria>
+
+- /gsd:research-phase is now a thin orchestrator
+- Command spawns gsd-researcher agent for research
+- Main context load reduced from ~500+ to ~150 lines
+- Workflow file deprecated (not deleted) with agent pointer
+- Pattern established for research-project refactoring
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-researcher-agent/14-02-SUMMARY.md`
+</output>
--- a/.planning/phases/14-researcher-agent/14-03-PLAN.md
+++ b/.planning/phases/14-researcher-agent/14-03-PLAN.md
@@ -0,0 +1,213 @@
+---
+phase: 14-researcher-agent
+plan: 03
+type: execute
+wave: 2
+depends_on: ["14-01"]
+files_modified: [commands/gsd/research-project.md, get-shit-done/workflows/research-project.md, get-shit-done/references/research-pitfalls.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "/gsd:research-project spawns parallel gsd-researcher agents"
+    - "Each agent handles one research domain (stack, features, architecture, pitfalls)"
+    - "Command is thin orchestrator (<200 lines)"
+    - "Deprecated files redirect to agent"
+  artifacts:
+    - path: "commands/gsd/research-project.md"
+      provides: "Thin orchestrator for project research"
+      min_lines: 100
+      contains: "gsd-researcher"
+    - path: "get-shit-done/workflows/research-project.md"
+      provides: "Deprecation notice"
+      contains: "DEPRECATED"
+    - path: "get-shit-done/references/research-pitfalls.md"
+      provides: "Deprecation notice"
+      contains: "DEPRECATED"
+  key_links:
+    - from: "research-project.md command"
+      to: "gsd-researcher agents (parallel)"
+      via: "Multiple Task tool spawns"
+      pattern: "subagent_type.*gsd-researcher"
+---
+
+<objective>
+Refactor /gsd:research-project to thin orchestrator that spawns parallel gsd-researcher agents + deprecate remaining files.
+
+Purpose: Reduce main context load, enable parallel research for project domains.
+Output: Thin orchestrator command + deprecated workflow and reference files.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Current implementation to refactor:
+@commands/gsd/research-project.md
+@get-shit-done/workflows/research-project.md
+@get-shit-done/references/research-pitfalls.md
+
+# Agent we're delegating to:
+@agents/gsd-researcher.md
+
+# Template from 14-02:
+@get-shit-done/templates/research-subagent-prompt.md
+
+# Prior summaries:
+@.planning/phases/14-researcher-agent/14-01-SUMMARY.md
+@.planning/phases/14-researcher-agent/14-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Refactor research-project command to thin orchestrator</name>
+  <files>commands/gsd/research-project.md</files>
+  <action>
+Rewrite `commands/gsd/research-project.md` as a thin orchestrator (~150-180 lines).
+
+**Orchestrator responsibilities (keep in command):**
+1. Validate PROJECT.md exists
+2. Check for existing .planning/research/ (offer to view/replace/cancel)
+3. Analyze PROJECT.md to determine domain
+4. Generate research questions for each dimension
+5. Spawn 4 parallel gsd-researcher agents (stack, features, architecture, pitfalls)
+6. Wait for all agents to complete
+7. Create SUMMARY.md (synthesize agent outputs)
+8. Commit research to git
+9. Offer next steps (/gsd:define-requirements)
+
+**Delegate to agents (via gsd-researcher):**
+- Research methodology
+- Source hierarchy
+- Domain-specific research execution
+- Verification checklist
+- Individual file content (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
+
+**Command structure:**
+
+```yaml
+---
+name: gsd:research-project
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+```
+
+**Process:**
+1. validate - Check PROJECT.md exists
+2. check_existing - Handle existing research folder
+3. analyze_project - Extract domain, stack hints, core value
+4. determine_questions - Generate 4 research questions
+5. setup_directory - Create .planning/research/
+6. spawn_researchers - Spawn 4 gsd-researcher agents in parallel:
+   - Stack agent (mode: implementation, question: stack question)
+   - Features agent (mode: ecosystem, question: features question)
+   - Architecture agent (mode: implementation, question: architecture question)
+   - Pitfalls agent (mode: feasibility, question: pitfalls question)
+7. write_summary - Synthesize agent outputs into SUMMARY.md
+8. git_commit - Commit all research files
+9. present_results - Show summary, offer /gsd:define-requirements
+
+**Parallel spawn pattern:**
+```
+# Spawn all 4 in parallel (single message with multiple Task calls)
+Task(subagent_type: "gsd-researcher", prompt: stack context)
+Task(subagent_type: "gsd-researcher", prompt: features context)
+Task(subagent_type: "gsd-researcher", prompt: architecture context)
+Task(subagent_type: "gsd-researcher", prompt: pitfalls context)
+```
+
+Each agent writes its own output file (.planning/research/{DOMAIN}.md).
+  </action>
+  <verify>
+- Command file is 150-180 lines
+- Spawns 4 parallel gsd-researcher agents
+- No research methodology in command (delegated to agents)
+- Has validate, analyze, spawn_researchers, write_summary, git_commit steps
+  </verify>
+  <done>/gsd:research-project refactored to parallel orchestrator</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Deprecate workflows/research-project.md</name>
+  <files>get-shit-done/workflows/research-project.md</files>
+  <action>
+Replace `get-shit-done/workflows/research-project.md` with deprecation notice.
+
+**Content:**
+```markdown
+# DEPRECATED
+
+This workflow has been replaced by the gsd-researcher agent.
+
+**New location:** `~/.claude/agents/gsd-researcher.md`
+
+The `/gsd:research-project` command now spawns parallel gsd-researcher agents directly. Each agent handles one research domain (stack, features, architecture, pitfalls).
+
+**Migration:** No action needed. Commands automatically use the new agents.
+```
+  </action>
+  <verify>File contains deprecation notice pointing to gsd-researcher agent</verify>
+  <done>workflows/research-project.md deprecated with redirect to agent</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Deprecate references/research-pitfalls.md</name>
+  <files>get-shit-done/references/research-pitfalls.md</files>
+  <action>
+Replace `get-shit-done/references/research-pitfalls.md` with deprecation notice.
+
+**Content:**
+```markdown
+# DEPRECATED
+
+This reference has been consolidated into the gsd-researcher agent.
+
+**New location:** `~/.claude/agents/gsd-researcher.md`
+**Section:** `<verification_patterns>`
+
+All pitfall detection, verification checklists, and red flags are now baked into the gsd-researcher agent.
+
+**Migration:** No action needed. Research agents automatically apply verification patterns.
+```
+  </action>
+  <verify>File contains deprecation notice pointing to gsd-researcher agent verification_patterns section</verify>
+  <done>references/research-pitfalls.md deprecated with redirect to agent</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] commands/gsd/research-project.md refactored (150-180 lines)
+- [ ] Command spawns 4 parallel gsd-researcher agents
+- [ ] No research methodology in command
+- [ ] workflows/research-project.md deprecated with redirect
+- [ ] references/research-pitfalls.md deprecated with redirect
+</verification>
+
+<success_criteria>
+
+- /gsd:research-project is now a thin parallel orchestrator
+- Command spawns 4 gsd-researcher agents in parallel
+- Main context load significantly reduced
+- Workflow and reference files deprecated with agent pointers
+- Phase 14 complete - all research expertise consolidated in gsd-researcher
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-researcher-agent/14-03-SUMMARY.md`
+</output>