orc-research

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

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

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:

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

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

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>
")