From d20d2844331a91bffddd9fd0a82551e5418ee68a Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 16:40:51 -0600 Subject: [PATCH] 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 --- .../phases/14-researcher-agent/14-01-PLAN.md | 197 ++++++++++++++++ .../phases/14-researcher-agent/14-02-PLAN.md | 205 +++++++++++++++++ .../phases/14-researcher-agent/14-03-PLAN.md | 213 ++++++++++++++++++ 3 files changed, 615 insertions(+) create mode 100644 .planning/phases/14-researcher-agent/14-01-PLAN.md create mode 100644 .planning/phases/14-researcher-agent/14-02-PLAN.md create mode 100644 .planning/phases/14-researcher-agent/14-03-PLAN.md diff --git a/.planning/phases/14-researcher-agent/14-01-PLAN.md b/.planning/phases/14-researcher-agent/14-01-PLAN.md new file mode 100644 index 000000000..8685c78ed --- /dev/null +++ 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: "" + key_links: + - from: "gsd-researcher.md" + to: "RESEARCH.md output" + via: "research_protocol and output_formats sections" + pattern: "RESEARCH\\.md" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Create gsd-researcher agent + agents/gsd-researcher.md + +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. + + +- 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 + + gsd-researcher.md created with complete research methodology, all modes, verification patterns + + + + Task 2: Verify agent completeness + agents/gsd-researcher.md + +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. + + All verification points checked, agent is complete and self-contained + Agent verified complete with all methodology, modes, and verification patterns + + + + + +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 + + + + +- 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 + + + +After completion, create `.planning/phases/14-researcher-agent/14-01-SUMMARY.md` + diff --git a/.planning/phases/14-researcher-agent/14-02-PLAN.md b/.planning/phases/14-researcher-agent/14-02-PLAN.md new file mode 100644 index 000000000..efb109c49 --- /dev/null +++ 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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Create research-subagent-prompt template + get-shit-done/templates/research-subagent-prompt.md + +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. + + File exists at get-shit-done/templates/research-subagent-prompt.md + Subagent prompt template created, references gsd-researcher agent + + + + Task 2: Refactor research-phase command to thin orchestrator + commands/gsd/research-phase.md + +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. + + +- 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 + + /gsd:research-phase refactored to thin orchestrator that spawns gsd-researcher + + + + Task 3: Deprecate workflows/research-phase.md + get-shit-done/workflows/research-phase.md + +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. + + File contains deprecation notice pointing to gsd-researcher agent + workflows/research-phase.md deprecated with redirect to agent + + + + + +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 + + + + +- /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 + + + +After completion, create `.planning/phases/14-researcher-agent/14-02-SUMMARY.md` + diff --git a/.planning/phases/14-researcher-agent/14-03-PLAN.md b/.planning/phases/14-researcher-agent/14-03-PLAN.md new file mode 100644 index 000000000..1690a42c1 --- /dev/null +++ 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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Refactor research-project command to thin orchestrator + commands/gsd/research-project.md + +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). + + +- 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 + + /gsd:research-project refactored to parallel orchestrator + + + + Task 2: Deprecate workflows/research-project.md + get-shit-done/workflows/research-project.md + +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. +``` + + File contains deprecation notice pointing to gsd-researcher agent + workflows/research-project.md deprecated with redirect to agent + + + + Task 3: Deprecate references/research-pitfalls.md + get-shit-done/references/research-pitfalls.md + +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:** `` + +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. +``` + + File contains deprecation notice pointing to gsd-researcher agent verification_patterns section + references/research-pitfalls.md deprecated with redirect to agent + + + + + +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 + + + + +- /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 + + + +After completion, create `.planning/phases/14-researcher-agent/14-03-SUMMARY.md` +