Architecture Deep Research - scan a repo, draft a PRD, run live deep research, and get a cited handoff for system-design decisions.
- GitHub stars
- 342
Install
/plugin install adr@beevibeRun it inside Claude Code after adding the marketplace with /plugin marketplace add beevibe-ai/beevibe.
Contents
Discovered from sourceCommands 6
/adr:decide — Architecture Deep Research
Use when the user is making an architecture decision and wants ADR to run the full pipeline. Trigger phrases: "pick a topology", "should we use Kafka or Postgres LISTEN", "what retrieval architecture", "decide auth provider", "architecture deep research".
The run takes 3–6 minutes. You MUST stream progress to the user as events land — silent waiting is bad UX. This command uses background bash + tail -F + the Monitor tool to surface each event in chat as it happens, instead of blocking on the MCP tool until completion.
Step 1 — Confirm the decision name
Ask one question (skip if the user already named it):
What's the architecture decision? (e.g. "event bus topology", "retrieval architecture", "auth provider")
Capture as <DECISION>. Derive <SLUG> by lowercasing and replacing non-alphanum with -. Derive <DOMAIN> from the repo's README / package.json — if you can't tell, ask.
ADR produces a research report on the decision space — whatever candidates the live evidence surfaces (architecture patterns, specific products, or a mix) get their own section in research-report.json and ADR.md. The reader decides.
Step 1.5 — Ask whether to include peer products
Most architects looking at a real decision want to see 3-5 similar products and how they handle the same aspect ("what does Linear use for vector storage?" beats reading abstract benchmarks). Ask:
Question: "Should ADR also research 3-5 similar / competitor products and how each one handles
<DECISION>?"Options:
- Yes — include peers (recommended) — Discover finds 3-5 comparable products. Deep-research adds one targeted task per peer hitting their GitHub repo, docs, and engineering blog for this specific decision aspect. Adds 30-60s + a few cents to the run.
- No — skip peers — Standard pipeline only.
Capture as <INCLUDE_PEERS> (boolean). If yes, you'll pass --include-peers on the deep-research invocation below.
Step 2 — Confirm the env is ready
npx -y --package=github:beevibe-ai/beevibe-cto adr-doctor
If NOT READY, invoke /adr:doctor and wait. Do not proceed with a broken env.
Step 3 — Prepare the output dir and event log
The deep-research command writes events.jsonl to --out. We pre-create it so tail -F can attach before the file would otherwise exist.
mkdir -p .adr-runs/<SLUG>
touch .adr-runs/<SLUG>/events.jsonl
Step 4 — Kick off deep-research in the background
Use the Bash tool with run_in_background: true. Capture the returned task id — you'll need it to know when the run finishes.
npx -y --package=github:beevibe-ai/beevibe-cto adr \
deep-research --discover-first \
--repo . \
--domain "<DOMAIN>" \
--decision "<DECISION>" \
--out .adr-runs/<SLUG>
When <INCLUDE_PEERS> is true, append --include-peers to the command (and optionally --max-peers <N> if the user asked for a different cap, default is 5).
Tell the user something like: "Kicked off — typical run is 3–6 minutes. I'll surface each stage as it happens."
Step 5 — Tail the event log in the background
Second Bash call, also run_in_background: true. Capture this task id too so you can stop the tail when the deep-research finishes.
tail -F .adr-runs/<SLUG>/events.jsonl
Each line that lands is a JSON object: {"ts":"...","type":"<event_type>", ...extra_fields}.
Step 6 — Stream events to the user via Monitor
Use the Monitor tool on the tail -F task id. Each new stdout line is a notification with one event. Render every event — most as a single line, some as a multi-line content block when the payload carries concrete content the user should see (URLs, claims, options, eliminated candidates, etc.). The point is for the chat to be a live research log, not a progress bar.
Single-line events (one chat line each)
| event_type | One-line message |
|---|---|
repo_scanned | ✓ Repo scan done — file_count files, manifest_count manifests, deploy_config_count deploy configs |
principles_extracted | ✓ Discovered pattern_count patterns + antipattern_count anti-patterns |
pdr_drafted | ✓ Drafted PRD — bytes bytes |
peers_extraction_failed | ⚠ Peer finder failed — proceeding without peers |
discover_completed | ✓ Discover stage complete |
run_started | 🚀 Deep-research started — <domain>: <decision> |
strategic_context_created | ✓ Strategic context: query_shapes.length entities, bounded_contexts.length query shapes |
decision_context_loaded_from_disk | ✓ Decision context loaded from existing decision-context.json (note_count notes) |
decision_context_extraction_failed | ⚠ Decision context extraction failed — proceeding without annotations |
research_plan_created | 🌐 Planned task_count research tasks (peer_task_count peer-targeted) |
research_batch_started | 🔎 Dispatching parallel research agents (max max_parallel) |
research_agent_started | 🔍 task: <title> |
research_round_started | round round searching: queries[0] |
research_search_completed | round round got result_count hits for query |
research_source_skipped | ↪ skipped <title> (reason) |
research_round_judged | round round judge: complete=<value> |
research_round_completed | round round ✓ (evidence_count evidence) |
research_agent_finished | ✓ task done (evidence_count evidence) |
evidence_collected | ✓ Evidence pool: total_items items, promoted_candidates_count promoted |
private_corpus_evidence_injected | 🧠 Injected synthetic_count items from discover; antipattern_axis_count antipattern axes |
candidate_relevance_filter_failed | ⚠ Relevance filter failed — keeping all candidates |
adaptive_research_cycle_started | 🔁 Adaptive cycle cycle: filling evidence gaps |
adaptive_research_cycle_completed | ✓ Adaptive cycle cycle complete (promoted_candidate_count promoted) |
adversarial_research_cycle_started | ⚔️ Adversarial cycle cycle: arguing against candidates |
adversarial_research_cycle_completed | ✓ Adversarial cycle cycle complete (empty_cells_after empty cells remain) |
synthesis_started | 🧩 Writing research report — candidates candidates, evidence_count evidence items |
critique_started | 🧐 Critique: evaluating report comprehensiveness |
resynthesis_started | 🔄 Re-writing report to address original_high_severity_count high-severity issues |
resynthesis_accepted | ✓ Re-synthesis accepted (original_high_severity_count → new_high_severity_count) |
resynthesis_rejected | ↪ Re-synthesis rejected — keeping original (reason) |
citation_audit_started | 🔗 Citation audit: verifying citations across evidence_count items |
citation_audit_batch_started | ⤓ batch <claim_context> (citation_count citations) |
citation_audit_batch_completed | ✓ batch <claim_context> — verified_count/citation_count verified |
evaluation_pack_started | 🧪 Building evaluation pack |
evaluation_pack_completed | ✓ Evaluation pack — test_case_count test cases, metric_count metrics |
claim_audit_started | 📝 Claim audit: scanning artifacts |
claim_audit_completed | 📝 Claim audit: total_claims_checked checked, uncited_material_claim_count uncited |
artifact_validation_warnings | ⚠ warning_count artifact(s) failed schema; wrote .invalid.json siblings (files) |
handoff_skipped | ↪ Handoff artifacts skipped — run adr handoff <out_dir> --option <name> after picking a candidate |
handoff_writing | 📝 Writing handoff artifacts (only when adr handoff ran) |
Multi-line content events (render as a small block in chat)
These carry concrete content the user wants to see. Render each as a 2-6 line block with the header on its own line, then the items indented. Do not collapse to a single line.
decision_context_extracted — header ✓ Extracted N context notes (K tags) then one bullet per notes[]:
✓ Extracted 3 context notes (3 tags)
Tags: phase:pre_pmf, deployment:self_hosted_single_vm, cost_sensitivity:high
• [deployment] Self-hosted is the primary deploy model
└ from: "self-hosted is the primary deploy model"
• [deployment] Should fit existing Docker Compose stack
└ from: "fits the existing Docker Compose"
• [cost] Budget-sensitive at early stage
└ from: "budget-sensitive at early stage"
These are annotations on the option space, not filters. They flow to synthesis as soft context and appear in the ADR.md header.
decision_context_gaps_detected — header ⚠ Detected N context gaps (run continues) then one bullet per gap. This is informational, not a blocker — the run proceeds and the follow-up question stage at the end will surface what to sharpen on the next run:
⚠ Detected 4 context gaps (run continues)
• What latency target do you need? (p95 / p99)
• How many tenants in production today vs in 12 months?
• Which compliance regimes apply? (SOC2 / HIPAA / GDPR / none)
• Self-hosted only, or is managed cloud acceptable?
follow_up_questions_proposed — header ✓ Proposed N follow-up questions then one bullet per follow_ups[]:
✓ Proposed 3 follow-up questions
• [deployment_model] (spread 0.84) Self-hosted or managed? The matrix splits cleanly on this axis.
└ adr deep-research --discover-first --repo . --domain "<DOMAIN>" --decision "self-hosted vector store" --out .adr-runs/<SLUG>-self-hosted
• [pricing_model] (spread 0.71) Per-vector or per-query pricing? Pinecone bills per dimension; pgvector is free.
└ adr deep-research --discover-first --repo . --domain "<DOMAIN>" --decision "vector store at >10M vectors budget envelope" --out .adr-runs/<SLUG>-budget
peers_found — header 🤝 Found N peer products then one bullet per peer (with evidence_strategy shown — architecture, adoption, or both):
🤝 Found 5 peer products
• Cal.com (★33k, TypeScript) [architecture] — Multi-tenant SaaS shipping its own auth + scheduling
• Onyx (★12k, Python) [architecture] — Self-hosted agent runtime with similar agent OS shape
• Obsidian (closed-source) [adoption] — Read via community signal (r/ObsidianMD, plugin ecosystem)
• Roam Research (closed-source) [adoption] — Read via community signal (migration write-ups)
• Notion (closed-source) [both] — SaaS at similar abstraction layer; mixed query set
peer_research_tasks_added — header 🎯 Added N peer-targeted research tasks then bullets:
🎯 Added 5 peer-targeted research tasks
• Cal.com → how does Cal.com handle vector store for agent memory? (cal.com/docs, github.com/cal-com/cal.com)
• Onyx → how does Onyx handle vector store for agent memory? (docs.onyx.app)
…
research_source_processed — the combined per-source beat. One header line for the fetch + preview, then one bullet per top claim. Replaces the previous 4 per-source events (fetching / fetched / claims_extracting / claims_extracted) so 30 sources fire 30 events instead of 120:
✓ "Architecture · Onyx Docs" (8.1KB, http_fetch_ok, 3 claims, score 0.82)
└ "Onyx uses Postgres with pgvector as the default vector store. The schema separates per-tenant indexes via..."
• [pgvector / supports] Onyx ships with pgvector as the default vector store across all deployments.
• [pgvector / supports] Schema separates per-tenant indexes via tenant_id partition columns.
• [self_hosted / supports] Default deployment is single-container Docker Compose with embedded Postgres.
candidate_relevance_filter_completed — header + bullet per dropped:
🎯 Dropped 2 off-topic candidates: nextjs, postgres_centric_storage
• nextjs — Framework, not a vector store
• postgres_centric_storage — Storage stack choice, not a vector store
comparison_matrix_built — header + top strong cells:
📊 Matrix: 5 candidates × 13 axes (35 empty, 18 strong, 6 weak)
• pgvector — strong on fits_existing_stack: "Postgres extension; runs inside the existing 5433 deployment without adding a new container [12]"
• Onyx → pgvector — strong on production_examples: "Onyx default deploy uses pgvector across all customers [4]"
• weaviate — weak on fits_existing_stack: "Requires its own container alongside Postgres [9]"
synthesis_completed — header + per-candidate summary:
✓ Report written — 2 candidates
Candidates:
• pgvector [thick] (strong on fits_existing_stack, cost_envelope, p95_latency)
└ Pick when: existing Postgres deployment, low-single-digit-M vectors
• weaviate [medium] (strong on hybrid_search; weak on fits_existing_stack)
└ Pick when: hybrid search is mandatory and Postgres is not in the stack
A run with candidate_count === 1 just means ADR found one candidate in this space — it's still the reader's call. A run with no candidates means the evidence pool didn't surface any (re-run with sharper context).
critique_completed — header + top issues:
🧐 Critique: 7 issues (0 high-severity, human review NOT recommended)
Summary: pgvector strong_axes are evidence-backed; one minor citation_mismatch on weaviate's failure_modes cell.
Top issues:
• [medium] citation_mismatch: citation [57] discusses OAuth2, not token_based_auth
citation_audit_completed — header + unsupported list (only when N > 0):
🔗 Citation audit: 29/30 verified, 1 unsupported
Unsupported:
• [21] for candidate:pgvector — "Cited paper discusses HNSW indexes in general, not pgvector specifically"
run_completed — final summary block (lives at the end of Step 7).
Pacing
Stream every event individually. Do NOT consolidate multiple events into one message. The only exception: when research_source_fetching fires for many URLs in the same round, render them consecutively on adjacent lines (still one chat message per event).
| handoff_skipped | ↪ Handoff artifacts skipped — adr handoff <out_dir> --option <name> after picking |
| run_completed | ✅ Run complete — research report written |
Unknown event types: print as <event_type> with no message body. Don't lose them.
Stream every event individually. Each event line in events.jsonl is meant to be a beat the user sees in chat — not a candidate for batching. Surface each event the moment it lands. The kernel's job is to emit beats at the granularity that makes sense for streaming UX; the slash command's job is to translate each one to a single chat line. Do NOT consolidate multiple events into one message even when they land in the same tick.
The only exception: when the same event_type fires very rapidly (e.g. research_source_fetching for 8 URLs in a single round), it's OK to render them on consecutive lines without skipping any.
Step 6.5 — Clarification is non-blocking
ADR no longer halts the run on thin context. If decision_context_gaps_detected fires, the run continues — burning the evidence budget on a thin PRD is the lesser failure mode compared to forcing the user through a clarification dialog before they've seen anything.
What you do as the slash command:
- Surface the gap event when it lands (multi-line render — see the table above) so the user knows what's missing.
- Don't kill the tail. Don't re-invoke. Let the run finish.
- After the run, the
follow_up_questions_proposedevent carries pre-filledadr deep-researchcommands targeting the matrix's highest-spread axes. Show them to the user as quick-pick next steps for a sharper run.
If the user wants to add context before the run completes, the right move is to cancel the current run, edit .adr-runs/<SLUG>/decision-context.json to add notes, and re-run with the same --out — adr will pick up the edited file as-is.
Step 7 — When the deep-research task finishes
You'll be notified when the background deep-research task completes (the one from Step 4, NOT the tail task). At that point:
- Stop the
tail -Ftask (let it die naturally — it has no more input — or kill it explicitly via Bash). - Open the rendered HTML report in the user's browser. This fires first so the user has the report visible while you're still reading it. The
adr opensubcommand rendersADR.md→ADR.html(mermaid diagrams as SVG, tables, dark/light mode CSS) and opens it via the OS default browser. Output is one line:Opened <path>/ADR.html in your browser.
adr open .adr-runs/<SLUG>
If adr open errors (rare — typically because ADR.md doesn't exist yet, which means the run crashed before synthesis), report it inline and continue with the markdown summary.
- Read
ADR.mdfirst. This is the founder-facing research report — executive summary, option space, per-candidate sections (what evidence shows/what evidence does not show/ pick / avoid / citations), cross-cutting tradeoffs, open questions, where to dig deeper, references. It's what the user actually wants to read.
cat .adr-runs/<SLUG>/ADR.md
- Then read
research-report.jsonif you need the structuredoptions[]for Step 8's summary.
cat .adr-runs/<SLUG>/research-report.json
- If
ADR.mddoesn't exist, the run did not reach the artifact stage. Inspect.adr-runs/<SLUG>/state.json(the kernel writes{"status": "crashed", "error": ...}on every failure path now) and the tail ofevents.jsonlto find out what died. Report clearly to the user. Salvageable run state:evidence.json,comparison-matrix.json, andcritique.jsonmay still be present and useful even when the run crashed. In this branch, skip step 2'sadr opencall — there's no report yet to render.
Step 8 — Summarize the result
Read research-report.json and state.json:
-
candidate_count > 0— the option space is mapped. Show:Candidates: <options[].name>, comma-separated Depth split: <thick count> thick, <medium> medium, <thin> thin Matrix: <candidates>×<axes>, <empty_cells> empty, <strong_cells> strong Citations: <verified_count>/<total_citations> verified Open Qs: <open_questions.length> Dig deeper: <follow_ups.length> research threads proposedThen offer: "Want me to walk through each candidate from
ADR.md, or look at the research threads to dig deeper?"When
candidate_count === 1, frame it as "ADR found one candidate in this space" — not "the answer." The dig-deeper section is how to widen the search if the lone candidate feels too thin. -
candidate_count === 0— no candidates surfaced. Show:Result: no candidates surfaced from the evidence pool Reason: read critique.json Next step: re-run with sharper context (see follow-up-questions.json), or run `adr supersede` once more evidence is available
If critique flagged recommend_human_review: true, append:
⚠ recommend_human_review = true — the critique flagged structural issues with the report.
Open .adr-runs/<SLUG>/ADR.md before acting.
Step 9 — Your job after the report
The report does not pick a candidate. That's the human's call. Read the per-candidate sections in ADR.md, weigh them against your team-side context (existing infrastructure, hiring plans, vendor relationships, budget), then:
- Walk through each candidate's tradeoffs from
ADR.md - Walk the comparison matrix cell by cell
- Look at
follow-up-questions.jsonand pick a sharper research thread to chase next - Once you've picked a candidate, run
adr handoff <out_dir> --option <name>to generate the implementation contract (agent-guardrails.md+execution-handoff.json). Pass--write-evaluation-packto also generatedomain-evaluation-pack.json.
Hard rules for the implement path
When the user has run adr handoff and is ready to implement, the agent's job:
- Read the chosen candidate's block.
execution-handoff.jsonis scoped to one candidate by--option. Honor THAT candidate'sstrong_axes,weak_axes,when_to_pick,when_not_to_pick, andcitations. - Respect
agent-guardrails.mdfor the chosen candidate. - Run against
domain-evaluation-pack.jsontest cases before declaring done (only if it was generated). - If something the cited evidence doesn't support comes up, surface the gap — don't paper over it, and don't silently swap to a different candidate.
Failure modes
- doctor reports missing keys: invoke
/adr:doctor. Do not run without them. - adr deep-research exits non-zero: the tail will stop emitting. Read
.adr-runs/<SLUG>/state.jsonfor the failure reason andevents.jsonlfor the last events. Show the user. recommend_human_review: true: do NOT proceed to implement automatically.- Run exceeds 10 minutes: most likely a rate-limited search provider. Inspect events, suggest switching providers via
/adr:doctor.
Why background bash + tail instead of the MCP tool
The MCP server's adr_deep_research tool is request/response — it blocks for 3–6 minutes and returns the handoff. Silent. We use bash + tail instead so events stream live. The MCP server remains available for hosts (Cursor, Codex) that don't have a chat surface to stream into.
/adr:discover — Repo scan and PRD draft
Use when the user wants the cheap, fast preview: "what does ADR think about my repo?", "draft a PRD I can edit", "what patterns are in this codebase?".
Step 1 — Confirm the decision name
Ask the user (skip if they already named it):
What architecture decision is the PRD for? (e.g. "event bus topology", "retrieval architecture")
Capture as <DECISION>.
Step 2 — Check the environment
npx -y --package=github:beevibe-ai/beevibe-cto adr-doctor
adr discover only needs an LLM provider (no web search). If that one is missing, invoke /adr:doctor to set it up.
Step 3 — Run discover via the MCP server
Use the adr_discover MCP tool:
{
"repo_path": ".",
"decision": "<DECISION>",
"out_dir": ".adr-runs/<slug>-discover"
}
Runs in 15–60 seconds and costs under a cent on gpt-4.1-mini.
Step 4 — Show the user the artifacts
The tool response gives you pattern_count, antipattern_count, and the path to pdr.draft.md. Read pdr.draft.md and show the user:
- The 3 most interesting patterns (with their file:line citations)
- The 2 most interesting anti-patterns (with their reasons)
- The Open questions section, verbatim — these are what the user must fill in before deep-research
Step 5 — Offer next steps
- Edit
pdr.draft.mdto fill in Open questions, then run/adr:decide(which will use the draft as input via--input-path) - Run
/adr:decidedirectly withdiscover_first: trueand let it skip the manual review step - Pipe the draft into a GitHub issue comment (for the bot workflow)
/adr:doctor — First-time setup
Audience: someone who may have never created an API key before. Do not paste URLs and walk away. Open each signup page in their browser, then guide them through the click path one step at a time. Wait for them to come back with each value before moving on.
Step 1 — Audit what's already there
npx -y --package=github:beevibe-ai/beevibe-cto adr-doctor
Read the output:
- If it ends with READY, congratulate the user and stop. They're done.
- If it ends with NOT READY, note which keys are missing and proceed to Step 2. Skip any category that's already set.
Step 2 — Walk through each missing key
For each missing key, do three things in this order:
- Explain in one sentence what it's for and what the user is about to do.
- Open the signup page in their browser via
open <url>(macOS) or print the URL with instructions to click (other OSes). - Walk them through the navigation, step by step. Wait for them to paste the value into chat before moving on.
Search provider (required)
Ask the user which provider they want before opening anything. Use AskUserQuestion with this exact question and options — do not pick for them:
Question: "Which search provider would you like ADR to use? It pulls live evidence from the web for every research run."
Options:
- Brave Search (recommended) — 2,000 free queries/month, no credit card required
- Tavily — 1,000 free requests/month, no credit card required
- Serper (Google) — 2,500 free queries on signup
- Self-hosted SearXNG — already running your own instance
Then dispatch by their choice. Each branch: open the signup page, walk through the click path, capture the key.
If they pick Brave Search
open https://api-dashboard.search.brave.com/register 2>/dev/null || echo "Open this URL in your browser: https://api-dashboard.search.brave.com/register"
- Sign in with Google or GitHub (top-right).
- Click Subscribe in the left sidebar, pick the Free plan.
- Click Add API key, name it "adr".
- Copy the key value (a long random string).
Paste it here when you have it.
Capture as BRAVE_SEARCH_API_KEY.
If they pick Tavily
open https://app.tavily.com/home 2>/dev/null || echo "Open this URL in your browser: https://app.tavily.com/home"
- Sign in (Google / GitHub / email).
- The dashboard shows your API key at the top — it starts with
tvly-.- Click the copy icon next to it.
Paste the key here.
Capture as TAVILY_API_KEY.
If they pick Serper
open https://serper.dev/api-key 2>/dev/null || echo "Open this URL in your browser: https://serper.dev/api-key"
- Sign in (Google / GitHub).
- Your API key is shown on the page — copy it.
Paste the key here.
Capture as SERPER_API_KEY.
If they pick Self-hosted SearXNG
Don't open a URL. Just ask:
Paste the base URL of your SearXNG instance (e.g.
https://search.example.com).
Capture as SEARXNG_URL.
LLM provider (required) → OpenAI
Say:
ADR uses an LLM to synthesize the research. I'll set up OpenAI. New accounts get $5 in free credits — enough for many ADR runs. After that you'll need to add a credit card. Opening the keys page now.
Then:
open https://platform.openai.com/api-keys 2>/dev/null || echo "Open this URL: https://platform.openai.com/api-keys"
Walk them through:
- Sign in (or create an account at https://platform.openai.com/signup if you don't have one).
- Click Create new secret key (top-right).
- Name it "adr" — leave permissions on "All".
- Click Create secret key and copy the value. It starts with
sk-. You can only see it once — copy it now.Paste the key here.
Capture as ADR_OPENAI_API_KEY.
If they don't want to create an OpenAI account, they can use any OpenAI-compatible provider (Azure, vLLM, llamafile, Ollama with OpenAI wrapper). Set ADR_OPENAI_BASE_URL to point at it. But for first-time users, just use OpenAI.
GitHub token (optional but strongly recommended)
Say:
Without a GitHub token, ADR is capped at 60 GitHub API calls per hour. Multi-repo research runs hit that fast. With a token, the cap is 5,000/hr. The token is free and takes 30 seconds. Want to set one up?
If yes:
open "https://github.com/settings/personal-access-tokens/new" 2>/dev/null || echo "Open this URL: https://github.com/settings/personal-access-tokens/new"
Walk them through:
- Token name: "adr"
- Expiration: 90 days (or "No expiration" if you don't want to renew)
- Repository access: "Public Repositories (read-only)" — that's enough.
- Permissions: leave defaults (Contents read, Metadata read).
- Click Generate token at the bottom. Copy the value — starts with
github_pat_.Paste the token here.
Capture as GITHUB_TOKEN. If they decline, skip.
Model override (optional — only if they ask)
Don't bring this up unless the user asks about it. Default gpt-4.1-mini is fine for most decisions. Smarter alternative: gpt-5 (slower, more expensive, better synthesis).
Step 3 — Write the keys in one bash call
npx -y --package=github:beevibe-ai/beevibe-cto adr-doctor set --json '{
"BRAVE_SEARCH_API_KEY": "<paste-from-step-2>",
"ADR_OPENAI_API_KEY": "<paste-from-step-2>",
"GITHUB_TOKEN": "<paste-from-step-2>"
}'
Only include keys the user actually provided. If they skipped GITHUB_TOKEN, omit it entirely from the JSON — don't pass "".
The set command writes to ~/.adr/config.json (mode 0600), refuses unknown keys, and re-audits at the end.
Step 4 — Confirm READY
The previous step's output already shows the post-write audit. It should end with READY.
If it still says NOT READY, identify what's still missing and loop back to Step 2 for those specific keys.
Closing message
Once READY, tell the user:
You're all set. Try
/adr:decideto make an architecture decision against the current repo, or/adr:discoverfor a quick scan-only preview.
Notes for Claude
- Be patient. A first-time user creating an OpenAI account from scratch can take 5+ minutes (signup → email verification → phone verification → page navigation). Don't rush them.
- Don't echo keys back. When the user pastes a key, acknowledge ("got it") and move on. Don't repeat the value.
- One key at a time. Don't ask for all three keys in one message. Walk through each one fully (open URL, give steps, wait for paste) before starting the next.
- If the user gets lost, offer to screenshot-walk them through it: "if you're stuck, tell me what you see and I'll guide you."
- Mask in your own messages. Refer to keys as "the Brave key you just gave me", not by value.
- Keys are persisted to
~/.adr/config.json. The user never needs to re-export them in a shell.
/adr:guard — Install write-time + commit-time hooks
Use when the user wants the bot to enforce their team's principles automatically, not just on demand.
Step 0 — Check principles exist
If .adr/principles.json doesn't exist:
Your team principles haven't been discovered yet. Run
/adr:principlesfirst — the hooks need somewhere to read the rules from.
Stop.
Step 1 — Install the hooks
adr guard install
This writes two files:
.claude/settings.local.json— adds a PreToolUse hook on Edit/Write/MultiEdit. Every time Claude Code is about to write to a file, the hook checks the team principles for that file's path and injects the relevant ones into the agent's context. No LLM call — pure file-based lookup..git/hooks/pre-commit— runsadr review --staged --top-n 5before each commit. Blocks the commit if any HIGH-severity violation is found; lets medium/low through as advisory.
Both installs are idempotent — running again is a no-op.
Step 2 — Show the user what's now in effect
The hooks are installed. From now on:
- At write time, every Edit/Write tool call shows me the team principles for that file's area. I'll surface conflicts if the change would violate one.
- At commit time,
git commitruns an automatic check. HIGH-severity violations block the commit. Bypass withgit commit --no-verifyif you must.
Step 3 — Offer the dry-run
Want to test it? Tell me to edit a file in this repo and I'll show you the principles that fire.
Notes for the bot
- The pre-write hook is silent when no principles match. That's intentional — write-time noise on every Edit kills the signal. Only fires when a discovered example shares a top-level dir with the edited file, or the lens is broadly applicable.
- Re-run
adr guard installto refresh. Principles can change (re-running/adr:principlesupdates them); the install command is idempotent so re-running is safe. - Pre-commit failures are recoverable. If the user hits a block they disagree with, they can either (a) fix the issue, (b) update the principle via
/adr:principles, or (c) bypass with--no-verifyfor an emergency commit.
/adr:principles — Discover the team's code-review principles
Use when the user wants the bot to learn their team's conventions so PR review can cite the team's own code as the reference.
Step 1 — Check the environment
npx -y --package=github:beevibe-ai/beevibe-cto adr-doctor
adr principles only needs an LLM provider (no web search). If that one is missing, invoke /adr:doctor.
Step 2 — Set expectations, then run
Before calling the tool, tell the user EXACTLY what's about to happen — the tool runs for 2-4 minutes with no other visible output, so without this the user just sees a spinner.
Print something like:
Running principles discovery on the repo. This takes ~2-4 minutes and runs in five steps:
- Scan the repo (files, manifests, docs) — instant
- Sample ~24 representative source files — instant
- Extract product intent + discover review lenses (parallel LLM, ~15s)
- Per-lens pattern extraction (parallel LLM, ~30s)
- Consolidate + cite-verify + write
.adr/principles.{md,json}(~30s)Cost: ~$0.15 on gpt-4.1-mini. You'll see the result when it's done.
THEN call the adr_principles MCP tool with non_interactive: true:
{
"repo_path": ".",
"non_interactive": true
}
The MCP server emits notifications/message for every step, and notifications/progress when the client opts in via _meta.progressToken. Some clients surface these in the spinner; others don't. Either way the upfront step list gives the user something to read.
The tool returns the lenses, the per-lens patterns, AND the product intent block (identity, architectural_intent, product_philosophy, non_goals). The full content lives in .adr/principles.{md,json} on disk.
Step 3 — Show the user what we found
Read .adr/principles.json to see the full structure. Then show the user — lead with the product portrait, NOT the lint rules:
- What this is — the
identityfield. One sentence on what the product actually is. - Architectural intent — the 3-6 foundational decisions from
architectural_intent. Each with itswhyand the files cited. - Product philosophy — the 3-6 recurring design principles from
product_philosophy. These are the team's voice — quote verbatim where pulled from CLAUDE.md / AGENTS.md. - Non-goals — what the team explicitly chose NOT to do. Often the most telling part.
- Code-level lenses + their principles — show top 2-3 strongest per lens, with team
file:linecitations.
Be concrete. "DO: state lives in /stores/*Store.ts, not component-local useState (lens: state-boundaries) — cited to web/src/stores/chatStore.ts:14". Not "DO: maintain clean architecture".
The order matters: the product portrait makes the user say "yes, this gets us" before they dive into the code rules. Reversing it makes the output read like a lint config.
Step 4 — Walk through ambiguities one at a time
For each ambiguity in .adr/principles.json (each lens may have its own ambiguities block in the per-lens extractions), show the user:
- The ambiguity description
- Both sides of the conflict, with
file:linecitations - Ask their preference in one short question, with 2-3 concrete options when possible
Do not dump all ambiguities at once. Walk them one at a time. The user is lazy and hates editing — make the choices feel like a conversation, not homework.
Capture each answer.
Step 5 — Re-run with the answers
Re-run adr_principles if any answers materially change the principle set. For most cases, you can update .adr/principles.json in place by appending the user's answers to the interview_log array and re-running the consolidator manually with the CLI:
npx adr principles init # interactive mode picks up the file
For Phase 1 MVP, simpler: skip the re-run. Just present the v0 principles + confirmed answers to the user and tell them they can re-run later if their conventions drift.
Step 6 — Confirm + suggest the next step
Your team has N principles across M lenses, written to
.adr/principles.md. Now PR review knows what to look for.Run
/adr:review <PR#>to check a PR against this list — comments will cite your team's own file:line.
Notes for the bot
- Do not invent principles. Only show the user principles the tool returned. If the LLM hallucinated something obviously wrong, flag it but do not delete it without confirmation.
- Lead with the team example. A principle without a team file:line citation is unfounded. Skip it.
- Plain language. "Stop putting state in components" not "delineate state boundaries via reactive store primitives".
- The interactive interview is the highest-value step. Skip it only if the user is in a hurry — and tell them they can re-run later.
/adr:review — Dynamic PR review against team principles
Use when the user wants the bot to PR-review a change against the team's own conventions, not generic style rules. Requires /adr:principles to have run at least once.
Step 0 — Check principles exist
If .adr/principles.json doesn't exist in the repo, tell the user:
Your team principles haven't been discovered yet. Run
/adr:principlesfirst — it scans the repo and learns what your team's conventions are, so PR review can cite your own code.
Stop. Do not proceed.
Step 1 — Figure out what to review
If the user typed /adr:review 42, that's PR #42. Otherwise ask one short question:
What do you want me to review?
- A PR — give me the number
- Your staged changes (
git diff --staged)- Your current branch vs main
Skip the question if the user already said.
Step 2 — Detect violations via the MCP server
Call adr_review with the appropriate source:
{ "pr_number": 42 }
or
{ "staged": true }
or
{ "branch": "main" }
The tool returns structured violations (each with principle_id, file, line, severity, message, suggested_fix) and the matching principles array (id, rule, rationale, examples_to_follow).
Runs in 30-90 seconds depending on diff size. Costs $0.01-$0.05 on gpt-4.1-mini.
Step 3 — If no violations: ship it
If violation_count is 0:
No principle violations in this change. Ship it.
Stop.
Step 4 — Walk through violations one at a time
For each violation in the returned list:
-
Show the user this block:
[N/total] <SEVERITY-COLORED> file.ts:LINE Team principle: <principle.rule> <principle.rationale> Why this hunk fails: <violation.message> Team example to follow: <principle.examples_to_follow[0]> Fix: <violation.suggested_fix> -
Ask one short question:
Post / edit / skip?
-
Capture the answer. If "edit", let them rewrite the comment text. Track which violations get accepted.
Do not batch them. Walk through one at a time, even if there are 10. The user is lazy — make it a conversation, not a triage queue. They can say "post all the rest" to short-circuit.
Step 5 — Post the accepted ones
Only ask this if there are accepted violations AND the source was a PR. (For local diffs there's nowhere to post.)
Ready to post N comments to PR #42?
If yes, get PR metadata with one gh call:
gh pr view <N> --json headRefOid,baseRepository,baseRepositoryOwner
Then for each accepted violation, post via gh api:
gh api --method POST \
"repos/<owner>/<repo>/pulls/<N>/comments" \
-f body="<rendered comment>" \
-f commit_id="<headRefOid>" \
-f path="<violation.file>" \
-F line=<violation.line> \
-f side=RIGHT
The rendered comment for each violation should look like:
Team principle: <principle.rule>
> <principle.rationale>
<violation.message>
**Team example to follow:** `<principle.examples_to_follow[0]>`
**Fix:** <violation.suggested_fix>
_From `adr review` · lens: `<principle.lens>` · principle: `<principle.id>`_
Step 6 — Summarize
Posted N of M comments to PR #42. Skipped K. The team's principles are evolving — re-run
/adr:principlesperiodically as your conventions shift.
Notes for the bot
- One at a time, not all at once. The walkthrough is the whole point — batch output is exactly what existing PR bots do, and it's bad.
- Cite the team's own code. Every comment must include the
examples_to_followreference. "Here's the rule, here's where we already do it right" is the formula. - Don't post style nitpicks. This is principles-based review, not lint. If the LLM surfaced something that's clearly cosmetic, drop it before showing the user.
- Severity colors: high = red, medium = yellow, low = gray. Honest signal helps the user triage at a glance.
- For local diffs (staged / branch), there's nothing to post — just show the violations and let the user fix locally.
MCP servers 1
Sponsors
Details
- Marketplace
- beevibe-ai/beevibe
- Source
- plugin
- Author
- Beevibe
- Category
- Agent Orchestration
