@rafinery/cli 0.2.2 → 0.4.0

package/blueprint/.claude/commands/rafa.md

@@ -1,10 +1,75 @@
 ---
-description: rafa — init · scan · improve · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|push|leverage|migrate|update|help> [--brain-only]
+version: 1.3.0
+description: rafa — the repo's engineering SOP. Use whenever the dev wants to plan a feature or change, build/execute against the active plan, improve code health, or ground work in the repo's brain — intent counts, the dev does NOT need to type /rafa. Also explicit: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]. Admin verbs (init/scan/push/migrate/update) run ONLY when explicitly invoked.
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
 Argument: `$ARGUMENTS`
 
+## Intent routing — implicit by default, explicit as override
+
+Work verbs dispatch on **prompt intent**; the dev never needs to remember a command.
+Admin verbs are expensive or side-effectful and run **only when explicitly typed**.
+
+| Prompt shape | Route |
+|---|---|
+| "let's add / build / implement / refactor X" (no active plan) | `## plan` — weight by blast radius: lite vs full (see plan.md § plan-lite) |
+| same, with an active plan covering it | `## build` |
+| "why / how / where does X …" (a question) | recall-and-answer: MCP `search_knowledge` → cited answer. No choreography. |
+| "list plans / what plans are there" | `list_plans` — NAMES ONLY (id · title · status · progress); never dump bodies |
+| "load / open / work on plan X" | `get_plan(X)` → materialize parent + children (bodies) into `.rafa/plans/<X>/` + set `active.md` → resume per `## build` |
+| "improve / clean up / what's rotting" | `## improve` |
+| explicit `/rafa <admin verb>` — init · scan · push · migrate · update | that verb, and ONLY then |
+
+**Announce-and-proceed, never ask-permission:** state the route in one line — *"this
+looks plan-shaped — following the plan SOP (say 'skip' to bypass)"* — then go. "skip"
+always wins, immediately and without argument. Never narrate other devs' activity
+unless explicitly asked (serve knowledge, not gossip). Misroutes the dev corrects are
+signal — prefer under-routing (answer plainly) over dragging a question through
+choreography.
+
+**Scope discipline (owner rule):** deliver exactly what the message asked — fix what
+they're expecting, nothing else. No unsolicited extras beyond bloom's single opt-in
+nudge. Fix-shaped prompts: recall the failure domain's knowledge → fix the asked
+thing → verify → stop.
+
+## Offers — ask at the boundary, never nag
+
+Three interaction modes by the weight of the action:
+1. **Just do** (session-local, reversible): recall · drafting · local journaling ·
+   status updates. Announce-and-proceed.
+2. **Ask once per session, then remember**: recurring cadences — *"keep plans
+   updated + pushed as I work (progress, notes, staged insights)?"* at build start.
+   One answer covers the session.
+3. **Offer at the boundary** (creates a durable artifact, leaves the machine, or
+   spends real money): a short, well-timed question at a NATURAL boundary —
+   - intent is getting big mid-conversation → *"want me to turn this into a plan?"*
+   - work/task complete → *"push the brain so the platform (and your team) see it?"*
+   - plan drafted but the dev drifted → *"push this plan to the platform?"*
+   - session start, local ahead of platform → *"brain is N commits behind — push?"*
+   - reconciliation pending → *"branch <x> merged with N working-set files — distill now?"*
+   - adjudication pending → *"1 file diverged at the <x>→<y> fold — pick a copy?"*
+
+Offer etiquette (hard rules): boundaries only, never mid-flow · once per moment — a
+"no" is remembered for the session and never re-argued · an unanswered offer never
+blocks; keep working, the offer stands · admin verbs stay explicit — an ACCEPTED
+offer is the explicit invocation.
+
+**Bootstrap digest — one question, however much is pending.** Session start may
+accumulate many offers (staleness push, N distills, needs-adjudication flags, a
+nudge). NEVER ask them serially — batch into ONE itemized digest: *"3 things
+pending: brain push · 2 merged branches to distill · 1 file needs adjudication —
+want any now, or later?"*
+Dismissible as a unit; offer fatigue trains reflexive yes, which corrodes every
+consent rung above it.
+
+**The frame is CONSENT (owner, 2026-07-10).** Four rungs, each action needs exactly
+one: (1) **implied** — the message itself consents to what it asks, and only that ·
+(2) **session** — asked once, remembered, revocable mid-session ("stop pushing") ·
+(3) **boundary** — the offer; acceptance is the consent · (4) **standing** — durable
+opt-ins recorded in config (insights capture per dev). And one thing consent can
+never waive: nothing person-scoped leaves the user brain, ever.
+
 You orchestrate three context-isolated *leaf* subagents — **atlas** (scan/fix), **prism**
 (validate), **bloom** (improve) — and shuttle artifacts between them via the filesystem.
 Subagents never spawn each other (Claude Code forbids nesting), so the loop lives here, in the
@@ -20,11 +85,11 @@ codebase in *its* window — you hold only summaries + the on-disk artifacts (`.
 The default runs the whole pipeline. `--brain-only` stops after the brain is validated (skips
 improve + push — a cheap knowledge refresh).
 
-1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per `.rafa/capabilities/scan.md`:
+1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per `.claude/skills/rafa-scan/SKILL.md`:
    comprehensive, breadth-before-depth, cited notes → `.rafa/brain/{rules,playbooks}/` +
-   `coverage.md`. Run `node .rafa/bin/verify-citations.mjs` until it **exits 0**. Return a
+   `coverage.md`. Run `npx @rafinery/cli verify-citations` until it **exits 0**. Return a
    coverage summary only — not the raw reads."*
-2. **Gate 1 — checker (trust-but-verify)**: re-run `node .rafa/bin/verify-citations.mjs`
+2. **Gate 1 — checker (trust-but-verify)**: re-run `npx @rafinery/cli verify-citations`
    yourself. Must **exit 0** (if not, re-spawn atlas to fix). It writes `citation-check.md`.
 3. **Gate 2 — prism**: spawn the `prism` subagent **context-isolated** — pass ONLY:
    *"Validate the scan in `.rafa/brain/` against the repo per your SOP; write
@@ -37,7 +102,7 @@ improve + push — a cheap knowledge refresh).
 6. **Improve** *(skip if `--brain-only`)* — run the **improve pass** (below): spawn `bloom` →
    `.rafa/improve/`. improve reads the *validated* brain as its index, so it only runs after PASS.
 7. **Push** — present the full summary (brain verdict/score + top improvements). **On the dev's
-   explicit approval**, push the brain: `node .rafa/bin/rafa-push.mjs` — commits `.rafa/` and
+   explicit approval**, push the brain: `npx @rafinery/cli push` — commits `.rafa/` and
    pushes to the brain remote using the dev's own git auth, stamped `brain-for: <code sha>`.
    Never push without approval.
 
@@ -52,8 +117,94 @@ cite-check them (`--root=.rafa/improve --dirs=improvements`, drop unresolved), r
 `ledger.md` + debt trend."* When it returns, read `ledger.md` and **surface only the top few
 high-leverage P0/P1s — don't nag; the dev triages.**
 
+## `plan <intent>` — brain-grounded, prism-validated decomposition
+Per [the rafa-plan skill](../skills/rafa-plan/SKILL.md). The trio at plan time —
+atlas drafts, bloom pulls, prism validates the plan itself:
+1. **Staleness check** — if this repo is platform-connected, compare the MCP envelope's
+   `brainForSha` to the local brain stamp; if the platform is behind, surface "run `rafa push`"
+   (never proceed silently, never block).
+2. **Spawn `atlas`** context-isolated: *"Draft a plan for `<intent>` per
+   `.claude/skills/rafa-plan/SKILL.md`: RECALL the brain slice for the touched domains (coverage →
+   search → rules/playbooks, honor non-exemplars), name the blast radius, decompose into
+   contract §7 files — one parent + child-owned tasks, globally-unique prefixed ids, each child
+   body carrying a `## Done-check`. Return the draft file contents."*
+3. **Spawn `bloom`**: *"List open improvements in the blast radius `<domains>`; return the
+   top-leverage few as optional child tasks."* Fold them in, marked optional.
+4. **Spawn `prism`** context-isolated: *"Validate this DRAFT plan against the brain + code per
+   `.claude/skills/rafa-plan/SKILL.md`: every task grounded (not hallucinated), every child has a
+   `## Done-check`. REJECT with reasons or PASS."* Fix-and-revalidate until PASS (max 3; then
+   surface and stop).
+5. **Approval gate** (ExitPlanMode / the dev). On approval: write `plans/<plan>/*.md`, set
+   `active.md` = `# <plan-id>`, run `npx @rafinery/cli compile` to exit 0, then in a
+   connected repo **`push_plan` + `set_active_plan` immediately — approval IS the push
+   trigger for plans** (the dedicated plans channel; plans never ride the brain manifest;
+   no second prompt — the dev just approved this exact content). The plan renders on the
+   platform and becomes resumable from any session/machine/teammate within moments:
+   *"list plans"* = names only · *"load plan X"* materializes it back into `.rafa/plans/`.
+
+## `build` — execute the active plan, trio-choreographed
+Per [the rafa-build skill](../skills/rafa-build/SKILL.md). Resume from `active.md`
+(or the platform's `get_active_plan` when connected — "load plan X" materializes it) —
+never re-derive context.
+Per task: **atlas** recalls + implements → **prism** validates against the child's
+`## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects) → **bloom**
+sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`; one opt-in
+nudge max) → update the child file's `status` + `## Log` → at CHECKPOINTS (task done ·
+cadence under session consent): `push_plan`/`update_plan_status` (plans channel) +
+`rafa checkpoint` (working set) so the platform reflects live progress. Terminal
+statuses when honest: `superseded` (replaced by a newer plan) · `abandoned` (dropped).
+If execution invalidates/creates brain knowledge, route per §capture (working set on a
+branch; full `## scan` on main — never hand-edit main's brain around the gate). When all
+children are done: prism-style final verify, set `active.md` = `# No active plan`,
+final `push_plan` + `set_active_plan` (clear).
+
+## capture — during ANY work (plan/build/answering), consent-gated
+Two destinations, one rule — route by what the observation is ABOUT:
+- **About the code** (a fact/gotcha/how-to discovered while working) → the
+  branch **working set**: author or edit the brain-shaped FILE under
+  `.rafa/brain/{rules,playbooks}/` (files are the working medium; hydrate the
+  existing note first via `rafa hydrate <rule|playbook> <id>` when refining
+  one). Candidate-grade — no gate at capture; it enters the org brain only at
+  merge-to-main distillation. Announce per file as it happens (*"capturing:
+  <path>"* — a "no" drops it). Sync at **checkpoints** (`rafa checkpoint`):
+  task done · plan approved · explicit ask · cadence under session consent ·
+  git push/pull of the code branch — **never session-end**. A checkpoint
+  CONFLICT (a teammate's newer copy) is decided HERE, in this session — read
+  the `.theirs.md` copy, merge/adopt/keep, re-checkpoint. **Third-party
+  rule:** a statement attributable to someone not in this session ("Carol
+  says…") is NEVER captured verbatim — paraphrase to an ownerless code fact,
+  or drop it. **No person-scoped content in the working set, ever** — a note
+  that names a person is rewritten person-free or routed/dropped. **No
+  secrets** — names are contracts, values are secrets (the platform also
+  screens; don't rely on it).
+- **About the dev** (a repeated correction, a stated preference/constraint) →
+  offer first (*"want me to remember that?"*), then `put_dev_insight` — the
+  dev's PRIVATE user brain, cross-repo. Never logged to repo activity, never
+  narrated to anyone (consent floor: nothing person-scoped leaves it).
+
+## `insights` — bootstrap/refresh the dev's user brain (compass)
+**Spawn `compass`** context-isolated per
+[the rafa-insights skill](../skills/rafa-insights/SKILL.md):
+bootstrap from the dev's native `/insights` report (distilled with judgment,
+never parsed) and/or refine from recent observations — every candidate OFFERED,
+banked only on yes (`put_dev_insight`). Legibility on request: list, correct,
+delete — the dev's brain, the dev's record. Capture during normal work does NOT
+require this command (rafa.md §capture routes it); this is the deliberate pass.
+
+## `distill [<branch>]` — reconcile a merged branch's working set into the org brain
+Per [the rafa-distill skill](../skills/rafa-distill/SKILL.md). The SESSION
+fallback of the rigor gradient — orgs with `rafa ci-setup` run this headlessly
+in their own CI on merge; offer it only when CI hasn't (or isn't wired).
+Normally OFFER-driven: at bootstrap, if `get_working_set` shows active files
+for a branch whose code reached main → *"branch <x> merged with N working-set
+files — distill now?"* Trio roles: conductor collects + surfaces adjudication
+flags to the dev · prism validates each file against MERGED MAIN (cited) ·
+atlas authors survivors into org-brain files → compile → push ·
+`resolve_working_file` (distilled/refuted with the cited reason — refutations
+reported to their author).
+
 ## `push` — (re-)push the brain to the brain remote
-`node .rafa/bin/rafa-push.mjs` — commit `.rafa/` and push to `origin` (the brain repo) with the
+`npx @rafinery/cli push` — commit `.rafa/` and push to `origin` (the brain repo) with the
 dev's own git auth. Use after a scan, or to re-sync a brain that changed.
 
 ## `leverage` — tune the dev's toolbox (rafa's 3rd mission; intelligence + exact edits)
@@ -62,7 +213,7 @@ Detection is cheap and deterministic; **acting needs intelligence — that's why
 1. **Inspect** the committed toolbox: `.claude/settings.json`, `.mcp.json`, `.claude/skills/`,
    `.claude/commands/`, and the stack (`package.json` / dirs). (`rafa leverage` gives the fast
    deterministic signal; here you reason over the real files.)
-2. **Reason** per [`.rafa/capabilities/leverage.md`](../../.rafa/capabilities/leverage.md): what's
+2. **Reason** per [the rafa-leverage skill](../skills/rafa-leverage/SKILL.md): what's
    missing / misconfigured / unused — permission gaps, an MCP the stack needs but isn't wired, a
    repeatable flow worth capturing as a skill, the best-fit *existing* skill for THIS repo. P1→P3.
 3. **Act — on the dev's approval, edit exactly.** Merge the precise permission entries, write the
@@ -73,11 +224,11 @@ Detection is cheap and deterministic; **acting needs intelligence — that's why
 Two channels. **Mechanical** changes (field rename, path move) run deterministically via the
 terminal `rafa migrate`. **Semantic** changes — a plan's *shape* changed and each file must be
 understood to be rewritten correctly — need intelligence, and that's this command.
-1. Read the target schema in [`.rafa/contract.md`](../../.rafa/contract.md) (§6/§7 for plans) and
+1. Read the target schema in [`.claude/rafa/contract.md`](../rafa/contract.md) (§6/§7 for plans) and
    the `from` versions in `rafa.json`.
 2. For each affected file under `.rafa/plans/` (and any other structured dir), **rewrite it to
    conform** — preserve meaning, remap fields, fill new required fields sensibly.
-3. Run `node .rafa/bin/rafa-compile.mjs` until it **exits 0** (validate-and-correct loop), surface
+3. Run `npx @rafinery/cli compile` until it **exits 0** (validate-and-correct loop), surface
    the diff for approval, then offer `rafa push` if this is a connected repo.
 
 ## `update` — the BRAIN-side of an upgrade (the CLI already did the blueprint side)
@@ -89,13 +240,13 @@ understood to be rewritten correctly — need intelligence, and that's this comm
   or re-run the CLI.
 1. **Find the gap.** The brain/plans conform to a *data* version; the blueprint just moved to a
    newer one. Compare `.rafa/manifest.json`'s `schemaVersion` (and `rafa.json`'s `contract`/`plans`)
-   to the current `.rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
+   to the current `.claude/rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
    update hasn't run yet, tell the dev to run `npx @rafinery/cli@latest update` first, then return.)
 2. **Migrate the brain side:**
    - **Contract bumped → the brain is a stale cache:** re-scan (`## scan`) to regenerate it, or for
      a targeted change, intelligently rewrite the affected notes to the new schema and re-validate.
    - **Plans shape changed:** rewrite each plan per `## migrate` (preserve meaning), compile to exit 0.
-3. **Record + summarize.** Run `node .rafa/bin/rafa-compile.mjs` to exit 0, then advance the data
+3. **Record + summarize.** Run `npx @rafinery/cli compile` to exit 0, then advance the data
    version in `rafa.json` (`contract`/`plans` → the versions you migrated to). Summarize what changed;
    on the dev's approval, `rafa push` if this is a connected repo.
 Never hand-edit around a migration or discard tuned files.
@@ -103,6 +254,26 @@ Never hand-edit around a migration or discard tuned files.
 ## `help` (also: no argument, or an unrecognized command)
 Print this reference verbatim and stop.
 
+**End to end — from zero to a queryable, working brain:**
+
+1. **Platform** — sign in → add a GitHub token → add brain repo + code repo → connect →
+   *Generate setup command* (15-min URL carrying a one-time MCP agent key).
+2. **Install** — in the code repo: `npx @rafinery/cli init '<setup-url>'` — vendors the
+   blueprint (agents · /rafa · skills · contract), records the brain remote in the
+   committed `rafa.json` (teammates: clone → `npx rafa pull` just works), registers the
+   knowledge MCP in `.mcp.json` (secret-free) + puts the key in
+   `.claude/settings.local.json` (gitignored).
+3. **Scan** — restart Claude Code → `/rafa scan` (atlas maps → prism validates → bloom
+   ledgers) → `rafa push` → webhook → the platform ingests the manifest.
+4. **See it** — platform repo pages: Overview · Brain · Improvements · Plans; *Agent
+   access* mints keys for more MCP clients (Slack, incident.io, CI).
+5. **Work** — `/rafa plan "<intent>"` (prism-validated, brain-grounded) → `/rafa build`
+   (atlas executes, prism gates each Done-check, bloom sweeps); every push syncs
+   progress so any session/teammate resumes exactly where work stopped.
+6. **Query** — any MCP client with a key reads the brain at `<platform>/api/mcp`:
+   `get_brain_status` · `search_knowledge` · `get_rule/playbook/improvement` ·
+   `get_plan` · `get_active_plan`. Read-only, cited, per-repo scoped.
+
 **rafa has two surfaces.** `/rafa <cmd>` runs the intelligent, in-editor passes; the terminal
 `rafa` CLI (run via `npx @rafinery/cli@latest <cmd>`) does the deterministic plumbing. Several
 names exist on both — the CLI does the mechanical half, `/rafa` the intelligent half.
@@ -113,7 +284,11 @@ names exist on both — the CLI does the mechanical half, `/rafa` the intelligen
 | `/rafa init` | First run: ensure structure, then run the full scan pass. |
 | `/rafa scan [--brain-only]` | The full pass: know → verify → improve → push. `--brain-only` stops after the brain is validated (a cheap knowledge refresh). |
 | `/rafa improve` | The improvement pass — bloom writes a cited, prioritized (P0–P3) ledger. |
+| `/rafa plan <intent>` | Trio planning: atlas drafts (brain-grounded, contract §7 files, Done-checks), bloom pulls blast-radius improvements, prism validates the plan — then approval, compile, push. |
+| `/rafa build` | Execute the active plan: per task atlas implements → prism gates `done` on the Done-check → bloom sweeps the ledger; compile + push progress as you go. |
 | `/rafa push` | (Re-)push the brain to the brain remote (your git auth). |
+| `/rafa distill [<branch>]` | Reconcile a merged branch's staged notes into the org brain (prism-validated vs merged main, compile-gated). Normally offer-driven at session start. |
+| `/rafa insights` | compass bootstraps/refreshes your private user brain from your native usage report + recent sessions — every insight offered before it's banked. |
 | `/rafa leverage` | Tune your toolbox: reason over config and, on approval, apply fixes exactly — merge settings, wire an MCP, scaffold a skill. |
 | `/rafa migrate` | Semantic migration — rewrite plans to a new schema preserving meaning, then compile-gate. |
 | `/rafa update` | The brain-side of an upgrade: after the CLI syncs the blueprint, run the migrations that need intelligence (re-scan a stale brain / rewrite plans). |
@@ -121,10 +296,12 @@ names exist on both — the CLI does the mechanical half, `/rafa` the intelligen
 **`rafa` — in the terminal (`npx @rafinery/cli@latest <cmd>`; deterministic):**
 | Command | What it does |
 |---|---|
-| `init [<setup-url>]` | Vendor the blueprint into the repo (+ wire the brain remote from a platform setup URL). |
+| `init [<setup-url>]` | Vendor the blueprint into the repo (agents, this command, the rafa skills, the contract) + wire the platform from a setup URL. `.rafa/` itself stays lazy. |
 | `update [--overwrite\|--keep]` | Blueprint-side of an upgrade: re-sync the blueprint (asks before overwriting files you tuned), run mechanical migrations, and report what the brain needs next. |
 | `compile` | Run the contract gate → `.rafa/manifest.json`. |
-| `push` | Compile, then push `.rafa/` to the brain remote. |
+| `verify-citations` | Deterministic citation checker (B1 resolution · B2 completeness · policy). |
+| `push` | Compile, then push `.rafa/` to the brain remote (a main-branch act; stamps the contract copy). |
+| `pull [--full] [--force]` | Make this clone brain-ready — bootstraps the lazy `.rafa/` from committed `rafa.json`; `--full` mirrors the whole brain repo locally. Never re-scan for existing knowledge. |
 | `leverage` | Detect toolbox gaps (deterministic) and print prioritized tips — the detector for `/rafa leverage`. |
 | `migrate` | Run the mechanical (deterministic) migrations. |