feat(02-01): research-project command, workflow, and template
- Created /gsd:research-project slash command for pre-roadmap domain research - Built batched subagent workflow (3-4 max parallel, 2 batches) - Defined project-research template for ecosystem/architecture/pitfalls/standards 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
147
commands/gsd/research-project.md
Normal file
147
commands/gsd/research-project.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
description: Research domain ecosystem before creating roadmap
|
||||
allowed-tools:
|
||||
- Task
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<!--
|
||||
DESIGN NOTE: Pre-Roadmap Research
|
||||
|
||||
This command runs AFTER new-project and BEFORE create-roadmap.
|
||||
It spawns batched subagents to research domain ecosystems in parallel.
|
||||
Subagents write directly to .planning/research/ to preserve main context.
|
||||
|
||||
Flow: new-project → research-project (optional) → create-roadmap
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Research domain ecosystem via batched subagents before roadmap creation.
|
||||
|
||||
Spawns 3-4 subagents in parallel to research:
|
||||
- Ecosystem (libraries, frameworks, tools)
|
||||
- Architecture (patterns, project structure)
|
||||
- Pitfalls (common mistakes, what NOT to do)
|
||||
- Standards (best practices, conventions)
|
||||
|
||||
Each subagent writes directly to `.planning/research/` preserving main context.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/research-project.md
|
||||
@~/.claude/get-shit-done/templates/project-research.md
|
||||
@~/.claude/get-shit-done/references/research-subagent-prompts.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Load project vision:**
|
||||
@.planning/PROJECT.md
|
||||
|
||||
**Check for existing research:**
|
||||
!`ls .planning/research/ 2>/dev/null || echo "NO_RESEARCH_DIR"`
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
Check prerequisites:
|
||||
|
||||
```bash
|
||||
# Verify .planning/ exists
|
||||
[ -d .planning ] || { echo "No .planning/ directory. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Verify PROJECT.md exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Check for existing research
|
||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
||||
```
|
||||
|
||||
If RESEARCH_EXISTS:
|
||||
```
|
||||
Research already exists at .planning/research/
|
||||
|
||||
What would you like to do?
|
||||
1. View existing research
|
||||
2. Re-run research (overwrites existing)
|
||||
3. Skip to create-roadmap
|
||||
```
|
||||
|
||||
Wait for user decision.
|
||||
</step>
|
||||
|
||||
<step name="detect_domain">
|
||||
Parse PROJECT.md to identify the domain and research scope.
|
||||
|
||||
Look for:
|
||||
- Technologies mentioned (Three.js, WebGL, audio, etc.)
|
||||
- Problem domain (3D, games, real-time, etc.)
|
||||
- Technical constraints that suggest specific ecosystems
|
||||
|
||||
If domain unclear, use AskUserQuestion:
|
||||
- header: "Domain"
|
||||
- question: "What domain should we research?"
|
||||
- options:
|
||||
- "3D/Graphics" - Three.js, WebGL, shaders
|
||||
- "Games/Interactive" - Physics, collision, procedural
|
||||
- "Audio/Music" - Web Audio, synthesis, DSP
|
||||
- (other relevant options based on PROJECT.md)
|
||||
</step>
|
||||
|
||||
<step name="research">
|
||||
Follow research-project.md workflow:
|
||||
|
||||
1. Create `.planning/research/` directory
|
||||
2. Spawn first batch of subagents (ecosystem + architecture)
|
||||
3. Wait for completion
|
||||
4. Spawn second batch (pitfalls + standards)
|
||||
5. Wait for completion
|
||||
6. Verify all outputs exist
|
||||
</step>
|
||||
|
||||
<step name="summarize">
|
||||
After all subagents complete:
|
||||
|
||||
```
|
||||
Research complete:
|
||||
- .planning/research/ecosystem.md
|
||||
- .planning/research/architecture.md
|
||||
- .planning/research/pitfalls.md
|
||||
- .planning/research/standards.md
|
||||
|
||||
Key findings:
|
||||
- [Top ecosystem recommendation]
|
||||
- [Key architecture pattern]
|
||||
- [Critical pitfall to avoid]
|
||||
|
||||
What's next?
|
||||
1. Create roadmap (/gsd:create-roadmap) - Incorporates research
|
||||
2. Review research files
|
||||
3. Done for now
|
||||
```
|
||||
|
||||
If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- `.planning/research/ecosystem.md`
|
||||
- `.planning/research/architecture.md`
|
||||
- `.planning/research/pitfalls.md`
|
||||
- `.planning/research/standards.md`
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md exists (prerequisite checked)
|
||||
- [ ] Domain detected or user clarified
|
||||
- [ ] Subagents spawned in batches of 3-4 max
|
||||
- [ ] All subagents wrote files directly to .planning/research/
|
||||
- [ ] All 4 research files exist
|
||||
- [ ] User knows next steps (create-roadmap)
|
||||
</success_criteria>
|
||||
181
get-shit-done/templates/project-research.md
Normal file
181
get-shit-done/templates/project-research.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Project Research Template
|
||||
|
||||
Template for `.planning/research/{category}.md` - project-level domain research written by subagents.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# {Category}: {Domain}
|
||||
|
||||
**Category:** {ecosystem | architecture | pitfalls | standards}
|
||||
**Domain:** {domain from PROJECT.md}
|
||||
**Researched:** {date}
|
||||
**Confidence:** {high | medium | low}
|
||||
|
||||
## Research Summary
|
||||
|
||||
{2-3 sentence overview of what was found and why it matters for this project}
|
||||
|
||||
## Findings
|
||||
|
||||
### {Finding 1 Title}
|
||||
|
||||
{What was discovered}
|
||||
|
||||
**Source:** {URL or documentation reference}
|
||||
**Confidence:** {high | medium | low}
|
||||
**Relevance:** {Why this matters for the project}
|
||||
|
||||
### {Finding 2 Title}
|
||||
|
||||
{What was discovered}
|
||||
|
||||
**Source:** {URL or documentation reference}
|
||||
**Confidence:** {high | medium | low}
|
||||
**Relevance:** {Why this matters for the project}
|
||||
|
||||
{... additional findings ...}
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Use
|
||||
|
||||
- **{Library/Pattern/Tool}** - {One line why}
|
||||
- **{Library/Pattern/Tool}** - {One line why}
|
||||
|
||||
### Avoid
|
||||
|
||||
- **{Thing to avoid}** - {One line why}
|
||||
- **{Thing to avoid}** - {One line why}
|
||||
|
||||
### Defer Decision
|
||||
|
||||
- **{Topic}** - {Why more info needed}
|
||||
|
||||
## Sources
|
||||
|
||||
| Source | Type | Confidence | Last Verified |
|
||||
|--------|------|------------|---------------|
|
||||
| {URL or reference} | {official docs / blog / github / forum} | {high/medium/low} | {date} |
|
||||
| {URL or reference} | {type} | {confidence} | {date} |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- {Question that couldn't be resolved}
|
||||
- {Question that needs more context}
|
||||
- {Question for roadmap planning to consider}
|
||||
|
||||
---
|
||||
*Generated by research-project subagent*
|
||||
*Category: {category}*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<category_guides>
|
||||
|
||||
## Category-Specific Guidance
|
||||
|
||||
### ecosystem.md
|
||||
|
||||
**Purpose:** Map the library/framework landscape for this domain
|
||||
|
||||
**Key questions to answer:**
|
||||
- What are the go-to libraries for this problem?
|
||||
- Which frameworks are actively maintained?
|
||||
- What's the "standard stack" experts use?
|
||||
- What NOT to hand-roll (existing solutions exist)?
|
||||
|
||||
**Structure emphasis:**
|
||||
- Compare 2-4 main options
|
||||
- Clear "use X when..." guidance
|
||||
- Version currency (is it maintained?)
|
||||
- Integration considerations
|
||||
|
||||
### architecture.md
|
||||
|
||||
**Purpose:** Document standard project structure and patterns
|
||||
|
||||
**Key questions to answer:**
|
||||
- How do experts organize code for this domain?
|
||||
- What patterns prevent common problems?
|
||||
- What component boundaries make sense?
|
||||
- How does data flow in typical implementations?
|
||||
|
||||
**Structure emphasis:**
|
||||
- Directory structure recommendations
|
||||
- Component organization patterns
|
||||
- State management approaches
|
||||
- Integration patterns with related systems
|
||||
|
||||
### pitfalls.md
|
||||
|
||||
**Purpose:** Catalog what NOT to do and why
|
||||
|
||||
**Key questions to answer:**
|
||||
- What mistakes do beginners commonly make?
|
||||
- What causes performance problems?
|
||||
- What architectural choices cause regret?
|
||||
- What seems like a good idea but isn't?
|
||||
|
||||
**Structure emphasis:**
|
||||
- Clear problem → consequence → solution
|
||||
- Real examples of failures
|
||||
- Detection (how to know if you're doing this)
|
||||
- Prevention (how to avoid)
|
||||
|
||||
### standards.md
|
||||
|
||||
**Purpose:** Document best practices and quality expectations
|
||||
|
||||
**Key questions to answer:**
|
||||
- What does "production quality" mean for this domain?
|
||||
- What testing approaches work?
|
||||
- What performance benchmarks matter?
|
||||
- What accessibility/security considerations apply?
|
||||
|
||||
**Structure emphasis:**
|
||||
- Measurable quality criteria
|
||||
- Testing strategies that work
|
||||
- Performance targets
|
||||
- Common standards/conventions
|
||||
|
||||
</category_guides>
|
||||
|
||||
<difference_from_phase_research>
|
||||
## How This Differs from Phase-Level Research
|
||||
|
||||
**project-research.md (this template):**
|
||||
- Written BEFORE roadmap exists
|
||||
- Informs phase structure and scope
|
||||
- Ecosystem-level landscape view
|
||||
- Answers "what tools/patterns should we use?"
|
||||
|
||||
**research.md (phase-level):**
|
||||
- Written AFTER roadmap exists
|
||||
- Informs specific phase implementation
|
||||
- Implementation-level detail
|
||||
- Answers "how do we implement this phase?"
|
||||
|
||||
Project research is strategic (shapes the roadmap).
|
||||
Phase research is tactical (shapes the implementation).
|
||||
</difference_from_phase_research>
|
||||
|
||||
<quality_bar>
|
||||
## Quality Expectations
|
||||
|
||||
A well-written research file:
|
||||
- Has specific, actionable recommendations (not "it depends")
|
||||
- Cites sources with confidence levels
|
||||
- Distinguishes verified facts from educated guesses
|
||||
- Surfaces open questions honestly
|
||||
- Can be read in 2-3 minutes and inform a decision
|
||||
|
||||
**Avoid:**
|
||||
- Generic advice that applies to anything
|
||||
- Recommendations without reasoning
|
||||
- Outdated information (pre-2024 unless fundamental)
|
||||
- Confidence without verification
|
||||
</quality_bar>
|
||||
173
get-shit-done/workflows/research-project.md
Normal file
173
get-shit-done/workflows/research-project.md
Normal file
@@ -0,0 +1,173 @@
|
||||
<purpose>
|
||||
Orchestrate batched subagent research for domain ecosystems before roadmap creation.
|
||||
|
||||
Subagents write directly to `.planning/research/` to preserve main context.
|
||||
Maximum 4 parallel subagents, recommended batch size 3.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="setup">
|
||||
Create research directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
Parse PROJECT.md to extract:
|
||||
- Domain keywords (technology mentions, problem space)
|
||||
- Constraints that affect ecosystem choices
|
||||
- Any mentioned preferences or requirements
|
||||
</step>
|
||||
|
||||
<step name="define_research_categories">
|
||||
Standard research categories:
|
||||
|
||||
1. **ecosystem.md** - Libraries, frameworks, tools for this domain
|
||||
2. **architecture.md** - Patterns, project structure, component organization
|
||||
3. **pitfalls.md** - Common mistakes, what NOT to do, performance traps
|
||||
4. **standards.md** - Best practices, conventions, quality expectations
|
||||
|
||||
Each subagent researches ONE category and writes directly to `.planning/research/{category}.md`
|
||||
</step>
|
||||
|
||||
<step name="batch_execution">
|
||||
## Batched Subagent Spawning
|
||||
|
||||
**Batch 1: Foundation research** (spawn in parallel)
|
||||
|
||||
Spawn using Task tool with `subagent_type="general-purpose"`:
|
||||
|
||||
```
|
||||
Subagent 1: ecosystem.md
|
||||
Subagent 2: architecture.md
|
||||
```
|
||||
|
||||
**Wait for Batch 1 completion.**
|
||||
|
||||
**Batch 2: Risk & quality research** (spawn in parallel)
|
||||
|
||||
```
|
||||
Subagent 3: pitfalls.md
|
||||
Subagent 4: standards.md
|
||||
```
|
||||
|
||||
**Wait for Batch 2 completion.**
|
||||
|
||||
**Subagent prompt structure:**
|
||||
|
||||
Use prompts from `~/.claude/get-shit-done/references/research-subagent-prompts.md`
|
||||
|
||||
Each subagent receives:
|
||||
- Domain context from PROJECT.md
|
||||
- Category assignment (ecosystem, architecture, etc.)
|
||||
- Output format from templates/project-research.md
|
||||
- Instruction to write directly to `.planning/research/{category}.md`
|
||||
</step>
|
||||
|
||||
<step name="verify_outputs">
|
||||
After all batches complete:
|
||||
|
||||
```bash
|
||||
# Check all files exist
|
||||
ls -la .planning/research/
|
||||
|
||||
# Verify each file has content
|
||||
for f in ecosystem architecture pitfalls standards; do
|
||||
[ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING"
|
||||
done
|
||||
```
|
||||
|
||||
**If any file missing:**
|
||||
- Log which subagent failed
|
||||
- Optionally retry that specific subagent
|
||||
- Continue with available research (partial is better than none)
|
||||
</step>
|
||||
|
||||
<step name="aggregate">
|
||||
Read key findings from each research file for summary:
|
||||
|
||||
```bash
|
||||
# Extract first few lines of each for summary
|
||||
for f in .planning/research/*.md; do
|
||||
echo "=== $(basename $f) ==="
|
||||
head -20 "$f"
|
||||
echo ""
|
||||
done
|
||||
```
|
||||
|
||||
Extract for user summary:
|
||||
- Top library/framework recommendation from ecosystem.md
|
||||
- Primary architecture pattern from architecture.md
|
||||
- Most critical pitfall from pitfalls.md
|
||||
- Key quality standard from standards.md
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<batching_rules>
|
||||
## Batching Configuration
|
||||
|
||||
**Maximum parallel subagents:** 4 (API safety limit)
|
||||
**Recommended batch size:** 3 (reliable)
|
||||
|
||||
**Batch ordering rationale:**
|
||||
- Batch 1 (ecosystem + architecture): Foundation knowledge that informs everything
|
||||
- Batch 2 (pitfalls + standards): Risk and quality that build on foundation
|
||||
|
||||
**Between batches:**
|
||||
- Verify all subagents in batch completed
|
||||
- Check for failures, note for retry if needed
|
||||
- Proceed to next batch
|
||||
</batching_rules>
|
||||
|
||||
<subagent_template>
|
||||
## Task Tool Invocation Pattern
|
||||
|
||||
For each subagent, use:
|
||||
|
||||
```
|
||||
Task tool parameters:
|
||||
- subagent_type: "general-purpose"
|
||||
- description: "Research {category} for {domain}"
|
||||
- prompt: [filled template from research-subagent-prompts.md]
|
||||
```
|
||||
|
||||
**Prompt template (simplified):**
|
||||
|
||||
```
|
||||
Research and write {category}.md for {domain} domain.
|
||||
|
||||
## Context
|
||||
{Paste relevant sections from PROJECT.md}
|
||||
|
||||
## Your Assignment
|
||||
File: .planning/research/{category}.md
|
||||
Category: {category}
|
||||
Purpose: {category-specific purpose}
|
||||
|
||||
## Research Requirements
|
||||
Use WebSearch to find current information. Verify:
|
||||
- Libraries are actively maintained (commits in last 12 months)
|
||||
- Patterns are current best practice (not deprecated)
|
||||
- Examples are from 2024-2025 sources where possible
|
||||
|
||||
## Output
|
||||
Write directly to .planning/research/{category}.md using the template structure:
|
||||
- research_summary
|
||||
- findings (specific discoveries with sources)
|
||||
- recommendations (actionable guidance)
|
||||
- sources (where info came from, confidence level)
|
||||
- open_questions (what couldn't be resolved)
|
||||
|
||||
Quality bar: Someone reading this should be able to make informed decisions about the roadmap.
|
||||
```
|
||||
</subagent_template>
|
||||
|
||||
<success_criteria>
|
||||
Research workflow complete when:
|
||||
- [ ] All 4 research files exist in .planning/research/
|
||||
- [ ] Each file has substantive content (not empty/error)
|
||||
- [ ] Key findings extracted for summary
|
||||
- [ ] Main agent context preserved (minimal usage)
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user