principles

/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:

1. Scan the repo (files, manifests, docs) — instant
2. Sample ~24 representative source files — instant
3. Extract product intent + discover review lenses (parallel LLM, ~15s)
4. Per-lens pattern extraction (parallel LLM, ~30s)
5. 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:

1. What this is — the identity field. One sentence on what the product actually is.
2. Architectural intent — the 3-6 foundational decisions from architectural_intent. Each with its why and the files cited.
3. 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.
4. Non-goals — what the team explicitly chose NOT to do. Often the most telling part.
5. Code-level lenses + their principles — show top 2-3 strongest per lens, with team file:line citations.