Adr

Orc ADR

Research phase before implementation. Runs 4 parallel agents to find best practices, KOLs, and production code.

• [ ] Step 1: Parse input and determine mode
• [ ] Step 2: Extract or formulate research questions
• [ ] Step 2b: Direction signoff (user approves questions)
• [ ] Step 3: Launch 4 parallel research agents
• [ ] Step 4: Synthesize findings into ADR(s)
• [ ] Step 4b: User review gate (approve/revise/skip each ADR)
• [ ] Step 5: Write approved ADRs and return paths

Ground implementation decisions in real-world evidence. Find how production systems solve similar problems, who the key experts are, and what patterns work.

Your role:

• Formulate research questions from the topic or phase PLAN.md
• Get user signoff on research direction before launching agents
• Launch parallel research agents with focused queries
• Synthesize findings into actionable ADRs
• Get user approval before writing each ADR
• Return ADR paths for implementation reference

Not your role:

• Implementing code (that's orc-swarm)
• Making final decisions (ADRs are proposals for user review)
• Deep diving on tangents (stay focused on phase scope)

Avoid:

• Generic searches ("best practices TypeScript")
• Ignoring contradictory findings
• Creating ADRs without evidence
• Launching more than 4 agents (context limits)

Pattern

orc-adr (standalone skill, inherit)
    │
    ├── [parallel] Web Search Agent (general-purpose)
    ├── [parallel] Twitter/X Agent (general-purpose)
    ├── [parallel] GitHub Agent (general-purpose)
    └── [parallel] Docs Agent (general-purpose)
    │
    └── Synthesize → ADR(s)

Input

If $ARGUMENTS provided: Use as $TOPIC directly. If the topic looks like it references a plan phase (mentions a slug that exists in .claude/plans/), also load PLAN.md and STATE.md for richer context. Don't enforce a format — just work with what the user gives you.

If not provided: AskUserQuestion: "What architectural decision should I research?"

Process

Step 1: Parse Input and Load Context

Try to load useful context without being strict about what must exist:

1. Check for plan context: If .claude/plans/ exists and $TOPIC references a recognizable slug/phase, read PLAN.md and STATE.md for additional context
2. Check for existing ADRs: ls docs/adr/ to check for existing ADRs on the same topic (dedup)
3. Topic-only is fine: If none of the above applies, the topic string alone is enough to research

Extract (from whatever is available):

• Key technical decisions needed
• Technologies involved
• Phase name and goal (if plan context loaded)

Step 2: Extract or Formulate Research Questions

From whatever context is available (PLAN.md content, or just the topic string), identify 2-4 research questions. Look for:

• Architecture decisions (how to structure X?)
• Library choices (which library for Y?)
• Pattern selections (what pattern for Z?)
• Integration approaches (how to connect A and B?)

Format questions as:

Q1: How do production systems handle [specific problem]?
Q2: What's the recommended approach for [technical challenge]?
Q3: Who are the key experts on [topic] and what do they recommend?
Q4: What are real examples of [feature] in open source?

Step 2b: Direction Signoff

AskUserQuestion presenting the extracted questions and agent roster:

I've formulated these research questions for "$TOPIC":

$QUESTIONS

I'll research these with 4 parallel agents:
1. Web Search — articles, blogs, tutorials
2. Twitter/X — KOLs, trending opinions
3. GitHub — production code examples
4. Official Docs — specs, guides, constraints

Approve or Revise?

• Approve → proceed to Step 3
• Revise → user adjusts questions → re-present until approved

Step 3: Launch Parallel Research Agents

Launch 4 Task agents in parallel, each with a specific research focus:

Agent 1: Web Search (general articles, blogs, tutorials)

Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search the web for best practices on these questions.
Focus on:
- Recent articles (2024-2025)
- Technical blog posts from respected sources
- Conference talks or tutorials

Use WebSearch with queries like:
- "[topic] best practices 2025"
- "[technology] production architecture"
- "[problem] real world solution"

Return:
- 3-5 key insights with sources
- Any consensus or controversy
- Recommended approaches with rationale

Agent 2: Twitter/X (KOLs, trending opinions)

Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search Twitter/X for key opinion leaders on this topic.
Focus on:
- Influential developers who work on [technology]
- Recent discussions about [problem]
- Hot takes and contrarian views

Use WebSearch with queries like:
- "site:twitter.com [expert name] [topic]"
- "site:x.com [technology] best practice"
- "[KOL name] opinion [topic]"

Return:
- Key experts and their positions
- Trending approaches or debates
- Any warnings or anti-patterns mentioned

Agent 3: GitHub (production code examples)

Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search GitHub for production implementations related to these questions.
Focus on:
- Popular repos (>100 stars) using similar patterns
- How real codebases structure [component]
- Common libraries and their usage patterns

Use WebSearch with queries like:
- "site:github.com [technology] [pattern]"
- "[library] example implementation"
- "[project type] open source [feature]"

Return:
- 2-3 exemplary repos with links
- Code patterns observed
- Libraries/dependencies commonly used
- File structure patterns

Agent 4: Official Docs & Specs

Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search official documentation for the technologies involved.
Focus on:
- Official recommended patterns
- Migration guides or best practices sections
- Known limitations or gotchas

Use WebFetch for official docs:
- Framework documentation
- Library API references
- Official guides/tutorials

Return:
- Official recommendations
- Documented patterns
- Warnings or constraints
- Version-specific considerations

Step 4: Synthesize into ADR(s)

Wait for all 4 agents to complete. Synthesize findings into 1-3 ADRs.

ADR structure: (use [templates/ADR.md](templates/ADR.md))

# ADR-XXX: [Decision Title]

## Status
Proposed

## Context
[Problem we're solving, derived from PLAN.md]

## Research Findings

### Web Sources
- [insight 1] — [source]
- [insight 2] — [source]

### Expert Opinions (Twitter/X)
- [@expert1]: "[quote or position]"
- [@expert2]: "[contrasting view if any]"

### Production Examples (GitHub)
- [repo1](link): [how they solved it]
- [repo2](link): [alternative approach]

### Official Guidance
- [recommendation from docs]
- [constraints or warnings]

## Decision
[Recommended approach based on evidence]

## Consequences

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [tradeoff 1]
- [tradeoff 2]

### Trade-offs
- [key tradeoff and why we accept it]

## References
- [link 1]
- [link 2]

Naming convention (Dewey Decimal / MIT course style):

• Directory: docs/adr/ (run mkdir -p docs/adr on first use)
• Discover subject number: ls docs/adr/ to find existing categories, or assign new one
• Categories: 1=infrastructure, 2=data, 3=auth, 4=api, 5=frontend, etc.
• Find next sequence: ls docs/adr/ADR{subject}.* to find next NNN
• Format: docs/adr/ADR{subject}.{NNN}-{kebab-case-title}.md
• Examples: ADR3.001-session-management.md, ADR5.002-component-library.md

Step 4b: User Review Gate

For each synthesized ADR, AskUserQuestion presenting the full ADR content:

Here's the proposed ADR:

$ADR_CONTENT

Write, Revise, or Skip?

• Write → approve this ADR for writing to disk
• Revise → ask what to change, apply edits, re-present until approved
• Skip → don't write this ADR, move to next

Step 5: Write Approved ADRs and Return Paths

Only write ADRs approved ("Write") in Step 4b.

If all ADRs skipped:

RESEARCH COMPLETE — no ADRs written
Questions researched: $questions-count

Key findings:
- [finding 1]
- [finding 2]
- [finding 3]

Otherwise, report completion with comma-separated paths (no spaces):

RESEARCH COMPLETE
Questions researched: $questions-count

ADRs: docs/adr/ADR{subject}.{NNN}-title.md,docs/adr/ADR{subject}.{NNN}-title.md

Key findings:
- [finding 1]
- [finding 2]
- [finding 3]

Ready for implementation.

Critical: The ADRs: line must be comma-separated with NO SPACES between paths. This allows orc-swarm to parse it as a single token.

File Ownership

| File | Access | Purpose | |------|--------|---------| | PLAN.md | Read only (orc mode only) | Extract research questions when plan context available | | STATE.md | Read only (orc mode only) | Understand codebase context when plan context available | | docs/adr/ADR*.md | Write | Create new ADRs (only after user approval) |

Research Query Templates

For AI/LLM Integration

• "LLM agent architecture production 2025"
• "AI character simulation state management"
• "Claude API structured output patterns"

For Web UI

• "real-time web updates websocket vs SSE 2025"
• "React canvas game rendering patterns"
• "speech bubble UI component design"

For Backend

• "node.js tick loop game server patterns"
• "express real-time simulation architecture"
• "in-memory state management patterns"

Completion Criteria

• [ ] Research questions formulated and user-approved (Step 2b)
• [ ] 4 parallel agents launched and completed
• [ ] Findings synthesized (no contradictions ignored)
• [ ] Each ADR presented for user review (Step 4b)
• [ ] Only approved ADRs written to disk
• [ ] ADR paths returned (or "no ADRs written" if all skipped)

Skip Conditions

You may skip research if:

• PLAN.md explicitly says "no research needed"
• ADRs already exist covering the phase topic
• User passes --skip-research flag

In skip case, return:

RESEARCH SKIPPED
Reason: [reason]
Existing ADRs: [list if any]

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.