From f93a1777880759b2f0b566bbd1b9da83cfc16ab0 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 16:54:12 -0600 Subject: [PATCH] docs(14): create researcher agent phase plans Phase 14: Dedicated Researcher Agent - 3 plans in 2 waves - Wave 1: 14-01 (agent creation) - Wave 2: 14-02, 14-03 (parallel orchestrator refactoring) - Ready for execution Co-Authored-By: Claude Opus 4.5 --- .planning/ROADMAP.md | 11 +- .../14-01-PLAN.md | 207 ++++++++++++++++ .../14-02-PLAN.md | 233 ++++++++++++++++++ .../14-03-PLAN.md | 233 ++++++++++++++++++ 4 files changed, 683 insertions(+), 1 deletion(-) create mode 100644 .planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md create mode 100644 .planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md create mode 100644 .planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 387f62d69..8034610fb 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -233,7 +233,16 @@ Created gsd-debugger agent with scientific method, hypothesis testing, 7+ invest **Goal:** Create `gsd-researcher` agent with research methodology baked in, refactor research commands to spawn specialized agents **Depends on:** Phase 13 **Research:** Unlikely (applying same agent pattern to research workflows) -**Plans:** TBD +**Plans:** 3 plans + +Plans: +- [ ] 14-01: Create gsd-researcher agent - Consolidate research expertise (~800-1000 lines) +- [ ] 14-02: Refactor /gsd:research-phase - Thin orchestrator, deprecate workflow +- [ ] 14-03: Refactor /gsd:research-project - Parallel agent spawning, deprecate workflow + +**Wave structure:** +- Wave 1: 14-01 (foundation) +- Wave 2: 14-02, 14-03 (parallel - both depend only on 14-01) Components: - Create `agents/gsd-researcher.md` with research expertise diff --git a/.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md b/.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md new file mode 100644 index 000000000..fd10ab17a --- /dev/null +++ b/.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md @@ -0,0 +1,207 @@ +--- +phase: 14-dedicated-researcher-agent +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: [agents/gsd-researcher.md] +autonomous: true + +must_haves: + truths: + - "gsd-researcher agent file exists with complete research methodology" + - "Agent covers all 4 research modes: ecosystem, feasibility, implementation, comparison" + - "Agent includes tool strategy (when to use Context7 vs WebSearch vs WebFetch)" + - "Agent includes source hierarchy and verification requirements" + artifacts: + - path: "agents/gsd-researcher.md" + provides: "Complete research expertise in single agent file" + min_lines: 600 + contains: "research_modes" + key_links: + - from: "agents/gsd-researcher.md" + to: "research commands" + via: "spawned by orchestrator" + pattern: "spawned by.*research" +--- + + +Create gsd-researcher agent with all research expertise baked in. + +Purpose: Consolidate ~1,200 lines of research methodology (research-phase.md workflow, research-project.md workflow, research-pitfalls.md, research.md template) into a single agent file following the thin orchestrator pattern established in Phase 13. + +Output: `agents/gsd-researcher.md` (~800-1000 lines) containing complete research methodology that orchestrators can spawn. + + + +@~/.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 reference (Phase 13 agent): +@agents/gsd-debugger.md (first 150 lines for structure pattern) + + + + + + Task 1: Create gsd-researcher agent file + agents/gsd-researcher.md + +Create agents/gsd-researcher.md following the gsd-debugger pattern with these sections: + +**Frontmatter:** +```yaml +--- +name: gsd-researcher +description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /gsd:research-phase and /gsd:research-project orchestrators. +tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__* +color: cyan +--- +``` + +**Core sections to include:** + +1. `` - Research agent identity, what spawns it, core responsibilities + +2. `` - Research principles: + - Source hierarchy (Context7 > Official docs > WebSearch) + - Verification requirements (cross-reference, confidence levels) + - Treating Claude's training as hypothesis not fact + - Honest reporting of gaps and unknowns + +3. `` - Four research modes with clear triggers: + - `ecosystem` — Survey landscape (tools, approaches, prior art) + - `feasibility` — Can we do X? What are blockers? + - `implementation` — How specifically to implement X? + - `comparison` — Compare options A vs B vs C + +4. `` - When to use each research tool: + - Context7: First for any library/framework (authoritative, current) + - Official docs via WebFetch: When Context7 lacks coverage + - WebSearch: Ecosystem discovery, community patterns, pitfalls + - Verification protocol: WebSearch findings must be cross-verified + +5. `` - Source prioritization: + - HIGH confidence: Context7, official documentation + - MEDIUM confidence: WebSearch verified with official source + - LOW confidence: WebSearch only (flagged for validation) + +6. `` - From research-pitfalls.md: + - All known pitfalls (config scope, deprecated features, tool variations, negative claims, etc.) + - Red flags to watch for + - Quick reference checklist + +7. `` - Templates for research outputs: + - Phase research (RESEARCH.md structure) + - Project research (SUMMARY.md, STACK.md, etc.) + - Comparison matrices + - Feasibility assessments + +8. `` - How the agent operates: + - Receive research question/scope from orchestrator + - Identify research domains + - Execute research protocol + - Verify findings + - Write output file(s) + - Return structured result + +9. `` - Return format to orchestrator: + - Research complete with findings summary + - Confidence assessment + - Files created + - Open questions/gaps + +10. `` - When research is complete + +Target: 800-1000 lines (consolidation from ~1,200 source lines with 20-30% reduction while preserving all critical concepts) + + +Verify file exists and has required sections: +```bash +wc -l agents/gsd-researcher.md +grep -c "research_modes\|tool_strategy\|source_hierarchy\|verification_protocol\|output_formats" agents/gsd-researcher.md +``` +Expected: 600-1000 lines, 5+ section matches + + agents/gsd-researcher.md exists with all 10 required sections, 600-1000 lines + + + + Task 2: Verify agent completeness + agents/gsd-researcher.md + +Read the created agent file and verify: + +1. **All research modes documented:** + - ecosystem mode has clear scope and output + - feasibility mode has clear scope and output + - implementation mode has clear scope and output + - comparison mode has clear scope and output + +2. **Tool strategy is actionable:** + - Context7 usage is explicit (resolve-library-id, query-docs) + - WebFetch patterns for official docs + - WebSearch query templates with {current_year} + - Verification requirements are clear + +3. **Pitfalls are preserved:** + - All pitfalls from research-pitfalls.md included + - Red flags section present + - Quick reference checklist included + +4. **Output formats match templates:** + - RESEARCH.md structure matches research.md template + - Project research structure matches research-project templates + +5. **No critical concepts lost:** + - Source hierarchy preserved + - Confidence levels system preserved + - Cross-verification requirements preserved + +If any gaps found, edit to add missing content. + + +All 4 research modes documented: +```bash +grep -E "ecosystem|feasibility|implementation|comparison" agents/gsd-researcher.md | wc -l +``` +Expected: 4+ matches (mode definitions plus references) + + Agent contains all 4 research modes, complete tool strategy, all pitfalls, and output formats + + + + + +Before declaring plan complete: +- [ ] agents/gsd-researcher.md exists +- [ ] File is 600-1000 lines (consolidated from ~1,200) +- [ ] All 10 required sections present +- [ ] 4 research modes defined with triggers and outputs +- [ ] Tool strategy section is actionable +- [ ] Verification protocol includes all pitfalls +- [ ] Output formats match existing templates + + + +- All tasks completed +- Agent file follows gsd-debugger pattern +- Research methodology consolidated without concept loss +- Ready for orchestrator integration (Plan 14-02) + + + +After completion, create `.planning/phases/14-dedicated-researcher-agent/14-01-SUMMARY.md` + diff --git a/.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md b/.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md new file mode 100644 index 000000000..9a3e52c0e --- /dev/null +++ b/.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md @@ -0,0 +1,233 @@ +--- +phase: 14-dedicated-researcher-agent +plan: 02 +type: execute +wave: 2 +depends_on: ["14-01"] +files_modified: [commands/gsd/research-phase.md, get-shit-done/workflows/research-phase.md, get-shit-done/templates/research-subagent-prompt.md] +autonomous: true + +must_haves: + truths: + - "/gsd:research-phase spawns gsd-researcher agent" + - "Command is <200 lines (thin orchestrator)" + - "Workflow file has deprecation notice pointing to agent" + artifacts: + - path: "commands/gsd/research-phase.md" + provides: "Thin orchestrator that spawns researcher agent" + min_lines: 80 + contains: "gsd-researcher" + - path: "get-shit-done/workflows/research-phase.md" + provides: "Deprecation notice" + contains: "DEPRECATED" + key_links: + - from: "commands/gsd/research-phase.md" + to: "agents/gsd-researcher.md" + via: "Task tool spawn" + pattern: "subagent_type.*gsd-researcher" +--- + + +Refactor /gsd:research-phase to thin orchestrator that spawns gsd-researcher agent. + +Purpose: Apply the thin orchestrator pattern from Phase 13 — command handles argument parsing and context gathering, all research expertise lives in the agent. Reduces main context from ~450+ lines to ~150 lines. + +Output: Refactored command (~150 lines), deprecated workflow, simplified 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 + +Files to refactor: +@commands/gsd/research-phase.md +@get-shit-done/workflows/research-phase.md + +Pattern reference (Phase 13 thin orchestrator): +@commands/gsd/debug.md +@.planning/phases/13-debug-agent/13-02-SUMMARY.md + + + + + + Task 1: Refactor /gsd:research-phase to thin orchestrator + commands/gsd/research-phase.md + +Rewrite commands/gsd/research-phase.md as thin orchestrator following the debug.md pattern: + +**Keep in orchestrator (low context cost, user interaction):** +- Argument parsing (phase number) +- Validation (phase exists in roadmap) +- Checking for existing RESEARCH.md +- Gathering phase context (roadmap description, requirements) +- Spawning the researcher agent with context +- Presenting results to user +- Offering next steps + +**Delegate to agent (burns context during research):** +- All research methodology +- Tool strategy (Context7, WebSearch, etc.) +- Source verification +- Output generation + +**Structure:** +```markdown +--- +name: gsd:research-phase +description: Research how to implement a phase before planning +argument-hint: "[phase]" +allowed-tools: + - Read + - Bash + - Task +--- + + +Research how to implement a phase. Spawns gsd-researcher agent with phase context. + + + +1. Parse phase argument +2. Validate phase exists in roadmap +3. Check for existing RESEARCH.md +4. Gather phase context (description, requirements, constraints) +5. Spawn gsd-researcher agent with research question +6. Present results and offer next steps + + + +Task( + prompt="Research implementation approach for phase {phase}...", + subagent_type="gsd-researcher" +) + +``` + +Target: ~150 lines (down from ~84 lines command + ~450 lines workflow) + + +```bash +wc -l commands/gsd/research-phase.md +grep -c "gsd-researcher\|Task\|subagent_type" commands/gsd/research-phase.md +``` +Expected: <200 lines, 3+ spawning references + + commands/gsd/research-phase.md is thin orchestrator <200 lines, spawns gsd-researcher + + + + Task 2: Deprecate workflows/research-phase.md + get-shit-done/workflows/research-phase.md + +Replace workflows/research-phase.md with deprecation notice following Phase 13 pattern: + +```markdown +# Research Phase Workflow + +## ⚠️ DEPRECATED + +**This workflow has been consolidated into the gsd-researcher agent.** + +The research methodology, tool strategy, and verification protocols now live in: +- `agents/gsd-researcher.md` + +The `/gsd:research-phase` command spawns the gsd-researcher agent directly. + +**Migration:** No action needed — the command handles this automatically. + +--- + +*Deprecated: 2026-01-XX* +*Replaced by: agents/gsd-researcher.md* +``` + +Keep file (don't delete) for git history traceability. + + +```bash +head -20 get-shit-done/workflows/research-phase.md +``` +Should show DEPRECATED notice + + workflows/research-phase.md has deprecation notice pointing to agent + + + + Task 3: Create research-subagent-prompt.md template + get-shit-done/templates/research-subagent-prompt.md + +Create a simple context-passing template for spawning the researcher agent: + +```markdown +# Research Subagent Prompt Template + +Template for spawning gsd-researcher agent from orchestrators. + +## Template + +``` + +Research: {research_question} + +Mode: {research_mode} (ecosystem | feasibility | implementation | comparison) + + + +Phase: {phase_number} - {phase_name} +Description: {phase_description} + +Requirements: +{phase_requirements} + +Constraints: +{constraints_from_state} + + + +Write research findings to: {output_path} +Use RESEARCH.md template structure for phase research. + +``` + +**Note:** Research methodology, tool strategy, and verification protocols are baked into the gsd-researcher agent. This template only passes context. +``` + +Target: ~60 lines (context-only, agent has expertise) + + +```bash +wc -l get-shit-done/templates/research-subagent-prompt.md +``` +Expected: <100 lines + + research-subagent-prompt.md template created, context-only (~60 lines) + + + + + +Before declaring plan complete: +- [ ] commands/gsd/research-phase.md is <200 lines +- [ ] Command spawns gsd-researcher agent via Task tool +- [ ] workflows/research-phase.md has deprecation notice +- [ ] research-subagent-prompt.md template exists +- [ ] Template is context-only (no methodology duplication) + + + +- All tasks completed +- Thin orchestrator pattern applied +- Main context reduced from ~530 lines to ~150 lines +- Workflow deprecated with clear redirect + + + +After completion, create `.planning/phases/14-dedicated-researcher-agent/14-02-SUMMARY.md` + diff --git a/.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md b/.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md new file mode 100644 index 000000000..700313a73 --- /dev/null +++ b/.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md @@ -0,0 +1,233 @@ +--- +phase: 14-dedicated-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] +autonomous: true + +must_haves: + truths: + - "/gsd:research-project spawns parallel gsd-researcher agents" + - "Command is <200 lines (thin orchestrator)" + - "Workflow file has deprecation notice pointing to agent" + - "4 parallel agents for stack, features, architecture, pitfalls" + artifacts: + - path: "commands/gsd/research-project.md" + provides: "Thin orchestrator that spawns parallel researcher agents" + min_lines: 100 + contains: "gsd-researcher" + - path: "get-shit-done/workflows/research-project.md" + provides: "Deprecation notice" + contains: "DEPRECATED" + key_links: + - from: "commands/gsd/research-project.md" + to: "agents/gsd-researcher.md" + via: "Parallel Task tool spawns" + pattern: "subagent_type.*gsd-researcher" +--- + + +Refactor /gsd:research-project to spawn parallel gsd-researcher agents. + +Purpose: Apply thin orchestrator pattern — command handles project analysis and spawns 4 parallel researcher agents (stack, features, architecture, pitfalls). Each agent writes its own file, orchestrator synthesizes SUMMARY.md. + +Output: Refactored command (~180 lines), deprecated workflow. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +Files to refactor: +@commands/gsd/research-project.md +@get-shit-done/workflows/research-project.md + +Pattern reference: +@commands/gsd/debug.md (thin orchestrator pattern) +@.planning/phases/13-debug-agent/13-02-SUMMARY.md + + + + + + Task 1: Refactor /gsd:research-project to thin orchestrator + commands/gsd/research-project.md + +Rewrite commands/gsd/research-project.md as thin orchestrator: + +**Keep in orchestrator:** +- PROJECT.md validation +- Domain analysis from PROJECT.md +- Research question generation +- Spawning 4 parallel researcher agents +- Waiting for all agents to complete +- Synthesizing SUMMARY.md from agent outputs +- Offering next steps + +**Delegate to agents (each writes its own file):** +- Stack research → .planning/research/STACK.md +- Features research → .planning/research/FEATURES.md +- Architecture research → .planning/research/ARCHITECTURE.md +- Pitfalls research → .planning/research/PITFALLS.md + +**Structure:** +```markdown +--- +name: gsd:research-project +description: Research domain ecosystem before creating roadmap +allowed-tools: + - Read + - Write + - Bash + - Task +--- + + +Research domain ecosystem. Spawns 4 parallel gsd-researcher agents for comprehensive coverage. + + + +1. Validate PROJECT.md exists +2. Analyze project to determine domain +3. Generate research questions (stack, features, architecture, pitfalls) +4. Create .planning/research/ directory +5. Spawn 4 gsd-researcher agents in parallel (each writes its own file) +6. Wait for all to complete +7. Synthesize SUMMARY.md from agent outputs +8. Commit research +9. Offer next steps + + + +Spawn all 4 in parallel with single message containing multiple Task calls: + +Task(prompt="Research stack for {domain}...", subagent_type="gsd-researcher") +Task(prompt="Research features for {domain}...", subagent_type="gsd-researcher") +Task(prompt="Research architecture for {domain}...", subagent_type="gsd-researcher") +Task(prompt="Research pitfalls for {domain}...", subagent_type="gsd-researcher") + +``` + +Target: ~180 lines (down from ~138 lines command + ~430 lines workflow) + + +```bash +wc -l commands/gsd/research-project.md +grep -c "gsd-researcher\|Task\|parallel" commands/gsd/research-project.md +``` +Expected: <200 lines, 4+ spawning references + + commands/gsd/research-project.md is thin orchestrator <200 lines, spawns 4 parallel agents + + + + Task 2: Deprecate workflows/research-project.md + get-shit-done/workflows/research-project.md + +Replace workflows/research-project.md with deprecation notice: + +```markdown +# Research Project Workflow + +## ⚠️ DEPRECATED + +**This workflow has been consolidated into the gsd-researcher agent.** + +The research methodology for project research now lives in: +- `agents/gsd-researcher.md` + +The `/gsd:research-project` command spawns 4 parallel gsd-researcher agents: +- Stack agent → .planning/research/STACK.md +- Features agent → .planning/research/FEATURES.md +- Architecture agent → .planning/research/ARCHITECTURE.md +- Pitfalls agent → .planning/research/PITFALLS.md + +The orchestrator synthesizes SUMMARY.md after all agents complete. + +**Migration:** No action needed — the command handles this automatically. + +--- + +*Deprecated: 2026-01-XX* +*Replaced by: agents/gsd-researcher.md* +``` + +Keep file for git history. + + +```bash +head -25 get-shit-done/workflows/research-project.md +``` +Should show DEPRECATED notice + + workflows/research-project.md has deprecation notice pointing to agent + + + + Task 3: Deprecate research-pitfalls.md reference + get-shit-done/references/research-pitfalls.md + +Add deprecation notice to top of research-pitfalls.md (keeping content for reference): + +```markdown +# Research Pitfalls Reference + +## ⚠️ DEPRECATED + +**This reference has been consolidated into the gsd-researcher agent.** + +The verification protocols and pitfall patterns now live in: +- `agents/gsd-researcher.md` (section: ``) + +The content below is preserved for reference but is no longer the primary source. + +--- + +*Deprecated: 2026-01-XX* +*Replaced by: agents/gsd-researcher.md* + +--- + +[existing content follows] +``` + +Keep full content below the notice for reference. + + +```bash +head -20 get-shit-done/references/research-pitfalls.md +``` +Should show DEPRECATED notice with pointer to agent + + research-pitfalls.md has deprecation notice pointing to agent + + + + + +Before declaring plan complete: +- [ ] commands/gsd/research-project.md is <200 lines +- [ ] Command spawns 4 parallel gsd-researcher agents +- [ ] workflows/research-project.md has deprecation notice +- [ ] research-pitfalls.md has deprecation notice +- [ ] All deprecation notices point to agents/gsd-researcher.md + + + +- All tasks completed +- Parallel agent spawning pattern documented +- Main context reduced significantly +- All deprecated files point to new agent location + + + +After completion, create `.planning/phases/14-dedicated-researcher-agent/14-03-SUMMARY.md` +