---

name: research-project description: Research domain ecosystem before creating roadmap allowed-tools:

• Read
• Write
• Bash
• Glob
• Grep
• Task
• WebFetch
• WebSearch
• mcp__context7__*

---

Answers the questions that inform quality roadmaps:

• What's the standard stack for this type of product?
• What features do users expect?
• How are these systems typically structured?
• What do projects in this domain commonly get wrong?

Run after /ag4:new-project, before /ag4:define-requirements.

Output: .planning/research/ folder with ecosystem knowledge.

<execution_context> @/.claude/ag4one/references/principles.md @/.claude/ag4one/workflows/research-project.md @/.claude/ag4one/templates/research-project/SUMMARY.md @/.claude/ag4one/templates/research-project/STACK.md @/.claude/ag4one/templates/research-project/FEATURES.md @/.claude/ag4one/templates/research-project/ARCHITECTURE.md @~/.claude/ag4one/templates/research-project/PITFALLS.md </execution_context>

Check if roadmap already exists

[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md already exists. Research is typically done before roadmap creation."

Check if research already exists

[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"

Copy</step>

<step name="check_existing">
**If RESEARCH_EXISTS:**

Use AskUserQuestion:
- header: "Research exists"
- question: "Research folder already exists. What would you like to do?"
- options:
  - "View existing" — Show current research summary
  - "Replace" — Run fresh research (will overwrite)
  - "Cancel" — Keep existing research

If "View existing": Read and display `.planning/research/SUMMARY.md`, then exit
If "Cancel": Exit
If "Replace": Continue with workflow
</step>

<step name="execute_research">
Follow the research-project.md workflow:
- Analyze PROJECT.md to determine domain
- Identify research questions based on domain
- Spawn parallel research agents
- Aggregate results into `.planning/research/`
- Create SUMMARY.md with roadmap implications
</step>

<step name="done">

Research complete:

• Summary: .planning/research/SUMMARY.md
• Stack: .planning/research/STACK.md
• Features: .planning/research/FEATURES.md
• Architecture: .planning/research/ARCHITECTURE.md
• Pitfalls: .planning/research/PITFALLS.md

---

▶ Next Up

Define requirements — scope your v1 from research findings

/ag4:define-requirements

/clear first → fresh context window

Flow: research-project → define-requirements → create-roadmap

---

Copy</step>

</process>

<when_to_use>
**Use research-project for:**
- Greenfield projects in established domains (community, e-commerce, SaaS)
- When "what features should exist" is partially unknown
- Complex integrations requiring ecosystem knowledge
- Domains where best practices matter (auth, payments, real-time)
- Any project where you'd Google "how to build a [X]" before starting

**Skip research-project for:**
- Well-defined specs ("build exactly this API")
- Simple tools/utilities with clear scope
- Adding features to existing codebases (use research-phase instead)
- Domains you've built in many times before
</when_to_use>

<success_criteria>
- [ ] PROJECT.md validated
- [ ] Domain identified from project description
- [ ] Research questions determined and approved
- [ ] Parallel research agents spawned
- [ ] All research documents created in .planning/research/
- [ ] SUMMARY.md includes roadmap implications
- [ ] Research committed to git
- [ ] User knows next step (define-requirements)
</success_criteria>