Docs menu
Docs
AI CTO
Crystal
Packages
Project

AI CTO Guide

From zero to your team's PR review automated. Six commands; about twenty minutes the first time. After that, the bot does the work — and the rules keep up with how your team actually codes.

Beevibe AI CTO ships as the beevibe-cto package — a separate OSS repo from the Beevibe workspace. It works on any codebase; you do not need Beevibe-the-workspace installed.

1. Install

Three ways in. Pick whichever fits your workflow — they share the same kernel and produce the same artifacts.

Claude Code plugin (recommended)

claude plugin marketplace add beevibe-ai/beevibe-cto
claude plugin install adr

Six slash commands become available in any Claude Code session: /adr:doctor, /adr:decide, /adr:discover, /adr:principles, /adr:review, /adr:guard. Start with /adr:doctor the first time — it walks you through one-time API key setup and saves it to ~/.adr/config.json.

CLI (terminal, CI, GitHub Actions)

npm install -g github:beevibe-ai/beevibe-cto
adr-doctor

MCP server (Cursor, Codex, any MCP host)

npm install -g github:beevibe-ai/beevibe-cto
adr-doctor setup

Then add to your host's MCP config (e.g. .claude/mcp.json):

{ "mcpServers": { "adr": { "command": "adr-mcp" } } }

Five tools become available: adr_discover, adr_deep_research, adr_read_handoff, adr_principles, adr_review.

API keys. You need at least one LLM key (ADR_OPENAI_API_KEY or OPENAI_API_KEY). A dedicated search key (Tavily, Brave, Serper) is optional — without one, ADR falls back to OpenAI's hosted web_search. For posting PR comments, also gh auth login (GitHub) or glab auth login (GitLab) or BB_TOKEN env var (Bitbucket).

2. Discover your team's principles

One-time setup per repo. The bot reads your README + ARCHITECTURE + CLAUDE.md + prior ADRs to name what your product actually is, then samples real source code to find the review angles a senior engineer would catch in a PR. Walks you through an interview to confirm.

cd your-repo
adr principles init

What happens, in order — each step streams to stdout so you see it work:

  1. Scan. Reads your repo structure, manifests, all docs (README, ARCHITECTURE, CLAUDE.md, prior ADRs), and samples ~24 representative source files. No LLM call yet.
  2. Product intent + lens discovery (parallel LLM). One call asks "what IS this product, what foundational decisions does the team stand on, what philosophy recurs across the code, what did they explicitly choose NOT to do?". Another asks "what review angles is this team's code organized around?".
  3. Per-lens extraction (parallel LLM). One call per lens. Finds positive patterns + antipatterns + ambiguities with file:line citations.
  4. Interview. The bot asks 4–8 short questions about ambiguities. Example: "I see Zustand stores in /stores AND useState in /components/ChatHeader.tsx:42 — is local state OK for derived UI, or should everything go through the store?" Type your answer, ENTER to skip.
  5. Consolidate + cite-or-die. Any citation pointing at a file that doesn't exist on disk is dropped — the bot never recommends ghost paths.

Time: ~2–4 minutes. Cost: ~$0.15 on gpt-4.1-mini.

Three files land in .adr/:

Commit the principles file. It belongs in git like a .eslintrc — the team owns it, the team reviews changes to it. adr principles refresh preserves your product intent (it rarely changes month-to-month); pass --reset-intent to force re-deriving after a major product pivot.

3. (Optional) Make a real decision with deep research

The flagship command. Run before committing to an architecture decision — vector store, event bus, auth pattern, retrieval topology, anything system-design.

adr decide --discover-first --include-peers --open \
  --repo . \
  --domain "your product domain" \
  --decision "vector store for agent memory" \
  --out .adr-runs/vector-store

Produces a research report at .adr-runs/vector-store/ADR.md with N candidates, each cited, plus Mermaid diagrams. --open renders it as HTML and opens in your browser.

Time: 3–6 min. Cost: $0.10–$0.30. See a real example report →

Skip this step if you're here for the PR-review loop. ADR principles + review + guard work without ever running adr decide.

4. Check a PR against the principles

Now your team's rules are written. Time to check a change against them.

From the terminal

adr review 42                       # GitHub PR #42
adr review --staged                  # your pre-commit local diff
adr review --branch main             # current branch vs main
adr review --diff change.patch       # arbitrary unified diff

Interactive walkthrough — the bot shows each violation one at a time:

[1/3] [HIGH] web/src/components/ChatHeader.tsx:42
  State lives in /stores/*Store.ts, not component-local useState
  Cross-component selections belong in the store.
  Line 42 adds useState for selectedAgentId. Cross-component selections live in chatStore.
  team example: web/src/stores/chatStore.ts:14
  fix: Move selectedAgentId to chatStore and expose via useSelectedAgent().

  > _

Per violation: ENTER to accept (keep for posting), e to edit the message, s to skip, q to stop. If --post is set on a PR, accepted comments post as inline GitHub / GitLab / Bitbucket comments, each citing your team's file:line as the example to follow.

For CI (non-interactive)

adr review 42 --non-interactive --post --batch
# --batch posts all comments as one PR-review event instead of N separate comments
# --event REQUEST_CHANGES blocks merge until violations are addressed (default: COMMENT)

In a Claude Code session

Run /adr:review 42. Claude walks you through each violation in chat — same accept / edit / skip flow but conversational. Accepted comments post via gh from Claude's tool use.

5. Wire write-time + commit-time hooks

Review at PR time is good. Preventing the violation in the first place is better.

adr guard install

Two hooks land, both idempotent (re-running is safe):

WhereWhat it does
.claude/settings.local.json Claude Code PreToolUse hook — fires on every Edit / Write / MultiEdit. Looks up principles relevant to the file being edited (no LLM call on the hot path) and injects them into the agent's context. The agent sees the team's conventions before generating code.
.git/hooks/pre-commit Runs adr review --staged --top-n 5 on every git commit. HIGH-severity violations block the commit. Medium / low are advisory. Bypass with git commit --no-verify if you must.

Reverse it cleanly:

adr guard uninstall

6. Keep the principles from rotting

Static linting rots. Configs get written once, drift from team practice, end up as noise nobody trusts. ADR's principles are built to evolve. Four commands keep them current:

adr principles refresh

adr principles refresh

Re-scans, re-extracts, but reads the prior interview log so it only asks about new ambiguities. Ideal outcome: 0 new questions, principles stay stable. Run quarterly, or after a big refactor.

adr principles incremental

adr principles incremental

Cheaper version of refresh. Looks at git log since the last refresh, re-extracts only over changed files, reuses prior lenses. Catches "team adopted a new convention in /packages/ three months ago and nobody updated the rules." Wire as a post-merge git hook or nightly CI.

adr principles refine --id <principle-id>

adr principles refine --id schema-validate-before-write

When adr review stats show a principle is wrong (high skip rate) or its message is wrong (high edit rate), refine re-runs discovery scoped to that one principle. Faster + more targeted than a full refresh.

adr drift

adr drift --max-files 100

Different from review: review checks a diff (incoming change), drift checks the whole codebase at HEAD. Answers "how far has the code drifted from the principles we discovered six months ago?". Run after a refactor sprint or a long pause. ~$0.50–$2 per run.

Plus the automatic stuff. Every adr review runs a cite-rot check (flags principles whose citations point at files that no longer exist) and persists accept / edit / skip stats per rule. After 5+ data points, principles users keep skipping auto-demote to confidence: low; ones users keep confirming auto-promote to high. No config, no flags — the rules learn from how your team actually uses them.

Suppression — // adr-ignore:

If a violation is intentional, mark the line. The bot stops repeating itself.

// adr-ignore: schema-validate-before-write
fs.writeFileSync(path, JSON.stringify(payload));  // raw write, on purpose

Works in any source language with comments — JS/TS (//), Python / Ruby / shell (#), CSS (/* */), HTML / Markdown (<!-- -->). Multiple principles per comment: // adr-ignore: rule-a, rule-b. Wildcard // adr-ignore: * suppresses all principles on that line — use sparingly.

Troubleshooting

"principles.json not found"

You haven't run adr principles init yet in this repo. review, guard, and drift all need the principles file as input.

"gh CLI not found" or "glab CLI not found"

adr review <PR#> with posting needs the host's CLI authenticated. Install gh (cli.github.com) or glab (gitlab.com/gitlab-org/cli) and run their auth login step.

Stale citations after a refactor

The next adr review emits a warning like "2 of 11 principles have stale citations." Run adr principles refresh (or incremental for speed) to update them.

Bot keeps flagging something the team accepted

Add // adr-ignore: <principle-id> on the line, or skip the violation 5+ times in adr review — after enough skips it auto-demotes to confidence: low. Or run adr principles refine --id <principle-id> to fix the rule itself.

I want to remove the hooks

adr guard uninstall reverses install cleanly. Both files survive any other hooks you had configured.

Next