Orc Research

---
description: Research domain ecosystem with parallel researcher agents to produce research/ documents
argument-hint: [slug]
allowed-tools:
  - Task
  - Read
  - Write
  - AskUserQuestion
  - Bash(ls:*)
  - Bash(mkdir:*)
  - Bash(wc:*)
  - Glob
model: inherit
context: inherit
hooks: {}
user-invocable: false
---

<objective>
Research a project's domain ecosystem using parallel orc-project-researcher agents, then synthesize into a unified summary.

Each researcher agent investigates one dimension (stack, features, architecture, pitfalls) and **writes its findings directly** to `.claude/plans/$ARGUMENTS/research/`. After all 4 complete, a synthesizer agent reads all files and produces SUMMARY.md.

Output: `.claude/plans/$ARGUMENTS/research/` folder with 5 research documents.

**Why parallel researchers:**
- Fresh context per dimension (no token contamination)
- Agents write documents directly (no context transfer back to orchestrator)
- Faster execution (agents run simultaneously)
- Synthesizer sees all dimensions at once for cross-cutting insights
</objective>

<context>
Slug: $ARGUMENTS (required -- the plan slug, e.g., "my-project")
Target directory: `.claude/plans/$ARGUMENTS/research/`

**Prerequisites:**
- `.claude/plans/$ARGUMENTS/PROJECT.md` should exist (created by `/orc` or `/zed`)
- PROJECT.md provides project name, description, and goals that inform research

**This command can run:**
- During `/orc` flow (after PROJECT.md, before roadmap generation)
- Standalone for any project that needs domain research
</context>

<process>

**Step 1: Validate arguments and read PROJECT.md**

If $ARGUMENTS is empty, ask the user for a slug:
```
AskUserQuestion:
  header: "Slug"
  question: "What slug should be used for the plan directory?"
  options:
    - label: "Enter slug"
      description: "e.g., my-project, webapp-v2"
```

Read PROJECT.md to determine project context:
```bash
cat .claude/plans/$ARGUMENTS/PROJECT.md 2>/dev/null
```

If PROJECT.md doesn't exist, ask the user for project context:
```
AskUserQuestion:
  header: "Context"
  question: "No PROJECT.md found. What is this project about? (domain, goals, type of product)"
  options:
    - label: "Describe project"
      description: "Provide a brief project description"
```

**Determine milestone context:**
- If no existing codebase or greenfield description -> Greenfield (building from scratch)
- If existing code or brownfield description -> Subsequent milestone (adding to existing app)

---

**Step 2: Check existing research**

```bash
ls -la .claude/plans/$ARGUMENTS/research/ 2>/dev/null && echo "has_research=true" || echo "has_research=false"
```

**If research/ already exists:**

```
AskUserQuestion:
  header: "Existing"
  question: ".claude/plans/$ARGUMENTS/research/ already exists. What should we do?"
  options:
    - label: "Refresh"
      description: "Delete existing and re-research"
    - label: "Skip"
      description: "Use existing research as-is"
```

If "Refresh": Delete research/, continue to step 3
If "Skip": Exit workflow

**If doesn't exist:** Continue to step 3.

---

**Step 3: Create directory and display progress**

```bash
mkdir -p .claude/plans/$ARGUMENTS/research
```

Display spawning indicator:
```
Spawning 4 researchers in parallel...
  -> Stack research
  -> Features research
  -> Architecture research
  -> Pitfalls research
```

---

**Step 4: Spawn 4 researcher agents**

Spawn 4 parallel research agents using Task tool with `subagent_type="orc:orc-project-researcher"` and `run_in_background=true`.

Extract `[domain]` and `[project description]` from PROJECT.md.

**Agent 1: Stack Research**

```
Task(
  subagent_type="orc:orc-project-researcher",
  run_in_background=true,
  description="Stack research",
  prompt="You are a project researcher. Research the standard stack for [domain].

<research_type>
Project Research -- Stack dimension for [domain].
</research_type>

<milestone_context>
[greenfield OR subsequent]
</milestone_context>

<question>
What's the standard stack for [domain] in [current year]?
</question>

<files_to_read>
- .claude/plans/$ARGUMENTS/PROJECT.md (Project context and goals)
</files_to_read>

<downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions
- Clear rationale for each choice
- What NOT to use and why
</downstream_consumer>

<quality_gate>
- [ ] Versions are current (verify with docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Confidence levels assigned to each recommendation
</quality_gate>

<output>
Write to: .claude/plans/$ARGUMENTS/research/STACK.md
</output>
")
```

**Agent 2: Features Research**

```
Task(
  subagent_type="orc:orc-project-researcher",
  run_in_background=true,
  description="Features research",
  prompt="You are a project researcher. Research features for [domain].

<research_type>
Project Research -- Features dimension for [domain].
</research_type>

<milestone_context>
[greenfield OR subsequent]
</milestone_context>

<question>
What features do [domain] products have? What's table stakes vs differentiating?
</question>

<files_to_read>
- .claude/plans/$ARGUMENTS/PROJECT.md (Project context)
</files_to_read>

<downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly:
- Table stakes (must have or users leave)
- Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build)
</downstream_consumer>

<quality_gate>
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies between features identified
</quality_gate>

<output>
Write to: .claude/plans/$ARGUMENTS/research/FEATURES.md
</output>
")
```

**Agent 3: Architecture Research**

```
Task(
  subagent_type="orc:orc-project-researcher",
  run_in_background=true,
  description="Architecture research",
  prompt="You are a project researcher. Research architecture for [domain].

<research_type>
Project Research -- Architecture dimension for [domain].
</research_type>

<milestone_context>
[greenfield OR subsequent]
</milestone_context>

<question>
How are [domain] systems typically structured? What are major components?
</question>

<files_to_read>
- .claude/plans/$ARGUMENTS/PROJECT.md (Project context)
</files_to_read>

<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Component boundaries (what talks to what)
- Data flow (how information moves)
- Suggested build order (dependencies between components)
</downstream_consumer>

<quality_gate>
- [ ] Components clearly defined with boundaries
- [ ] Data flow direction explicit
- [ ] Build order implications noted
</quality_gate>

<output>
Write to: .claude/plans/$ARGUMENTS/research/ARCHITECTURE.md
</output>
")
```

**Agent 4: Pitfalls Research**

```
Task(
  subagent_type="orc:orc-project-researcher",
  run_in_background=true,
  description="Pitfalls research",
  prompt="You are a project researcher. Research common pitfalls for [domain].

<research_type>
Project Research -- Pitfalls dimension for [domain].
</research_type>

<milestone_context>
[greenfield OR subsequent]
</milestone_context>

<question>
What do [domain] projects commonly get wrong? Critical mistakes?
</question>

<files_to_read>
- .claude/plans/$ARGUMENTS/PROJECT.md (Project context)
</files_to_read>

<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Warning signs (how to detect early)
- Prevention strategy (how to avoid)
- Which phase should address it
</downstream_consumer>

<quality_gate>
- [ ] Pitfalls are specific to this domain (not generic advice)
- [ ] Prevention strategies are actionable
- [ ] Phase mapping included where relevant
</quality_gate>

<output>
Write to: .claude/plans/$ARGUMENTS/research/PITFALLS.md
</output>
")
```

---

**Step 5: Wait and verify researchers**

Wait for all 4 agents to complete. Read each agent's output to confirm success.

Verify files exist:
```bash
ls -la .claude/plans/$ARGUMENTS/research/
```

If any researcher failed, note which dimension is missing and continue with available files.

---

**Step 6: Spawn synthesizer**

After all 4 researchers complete, spawn the synthesizer:

```
Task(
  subagent_type="orc:orc-research-synthesizer",
  description="Synthesize research",
  prompt="Synthesize research outputs into SUMMARY.md.

<files_to_read>
- .claude/plans/$ARGUMENTS/research/STACK.md
- .claude/plans/$ARGUMENTS/research/FEATURES.md
- .claude/plans/$ARGUMENTS/research/ARCHITECTURE.md
- .claude/plans/$ARGUMENTS/research/PITFALLS.md
</files_to_read>

<output>
Write to: .claude/plans/$ARGUMENTS/research/SUMMARY.md
</output>
")
```

---

**Step 7: Verify SUMMARY.md**

```bash
ls -la .claude/plans/$ARGUMENTS/research/SUMMARY.md
wc -l .claude/plans/$ARGUMENTS/research/SUMMARY.md
```

---

**Step 8: Present results**

Get line counts:
```bash
wc -l .claude/plans/$ARGUMENTS/research/*.md
```

Display:

```
Domain research complete.

Created .claude/plans/$ARGUMENTS/research/:
- STACK.md ([N] lines) - Technology recommendations
- FEATURES.md ([N] lines) - Feature landscape
- ARCHITECTURE.md ([N] lines) - Architecture patterns
- PITFALLS.md ([N] lines) - Domain pitfalls
- SUMMARY.md ([N] lines) - Synthesized findings + roadmap implications
```

</process>

<success_criteria>
- [ ] .claude/plans/$ARGUMENTS/research/ directory created
- [ ] All 4 research files written by researcher agents (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
- [ ] SUMMARY.md written by synthesizer agent
- [ ] 5 total research files verified
- [ ] Results reported with line counts
</success_criteria>