# Adr > Research architectural decisions and write ADRs with evidence - **Type:** Skill - **Install:** `agentstack add skill-qgolem-orc-adr` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [qGolem](https://github.com/qGolem) - **Source:** https://github.com/qGolem/orc/tree/main/skills/adr ## Install ```sh agentstack add skill-qgolem-orc-adr ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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)) ```markdown # 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](https://github.com/qGolem) - **Source:** [qGolem/orc](https://github.com/qGolem/orc) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-qgolem-orc-adr - Seller: https://agentstack.voostack.com/s/qgolem - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.