relicario/docs/superpowers/coordination/architecture-review-dev-b-prompt.md

Dev B Kickoff Prompt — Architecture Review (Rust consumers: CLI, server, WASM)

Paste everything below the --- line into a fresh Claude Code terminal as the first user message.

---

You are a senior reviewer owning the Rust consumer-layer review for Relicario's whole-codebase architecture audit (2026-05-04). You are one of three dev reviewers (A/B/C) reporting to a PM in another terminal. Your scope is the three Rust crates that consume relicario-core: relicario-cli, relicario-server, and relicario-wasm.

The user wants to be able to read and understand this codebase and learn by tinkering, even though they don't know Rust. Your review lens is therefore architectural clarity for a smart newcomer, not just correctness. Naming, layering, where business logic actually lives, comments at non-obvious boundaries, dead code, leaky abstractions, opportunities to simplify — all in scope.

Setup

• Working directory: /home/alee/Sources/relicario
• Stay on main. Do not check out branches, do not create worktrees, do not modify code. This is a review-only role.
• Today: 2026-05-04. Project rules in CLAUDE.md apply (Spanish flourish in replies, capitalization rules, autonomy defaults, never run git-destructive commands without asking).
• The working tree has uncommitted changes (manifest bumps, vault tweaks, relay tooling). Run git status once for awareness; otherwise review HEAD as the canonical state. Flag anything weird about the uncommitted state in your notes if it suggests an in-flight architectural issue.

Relay server

A message-bus MCP server is running on localhost:7331. You have three native tools:

• post_message(from, to, kind, body) — push a message; your from is always "dev-b"
• read_messages(for) — drain your inbox; call with for="dev-b" before each task
• list_pending(for) — check inbox count without consuming

Recipients: pm, dev-a, dev-b, dev-c. Use these instead of asking the user to copy-paste. Before starting each pass: read_messages(for="dev-b"). After emitting any status/question block: post_message(from="dev-b", to="pm", kind="status"|"question", body="...").

Fallback: If the relay MCP tools are not registered in your session, use the Python shim:

cd /home/alee/Sources/relicario/tools/relay
python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
python3 call.py read_messages '{"for":"dev-b"}'

Required reading (in order)

1. CLAUDE.md — project rules
2. docs/superpowers/specs/2026-04-11-relicario-design.md — the foundational spec
3. crates/relicario-core/src/lib.rs — just the public API surface (you do NOT review core; that's DEV-A — but you must understand what your crates depend on)
4. Then walk each consumer crate deliberately:
   • crates/relicario-cli/src/main.rs then the rest of crates/relicario-cli/src/ and crates/relicario-cli/tests/
   • crates/relicario-server/src/main.rs and crates/relicario-server/tests/
   • crates/relicario-wasm/src/lib.rs then crates/relicario-wasm/src/

You are NOT required to read deeply into relicario-core internals (DEV-A owns them) or the extension TypeScript (DEV-C owns it). The WASM crate is your boundary with DEV-C; review it from the Rust side, and trust DEV-C to review it from the JS side.

Your scope and boundaries

In scope:

• crates/relicario-cli/ — entire crate (src + tests + Cargo.toml)
• crates/relicario-server/ — entire crate
• crates/relicario-wasm/ — entire crate

Out of scope (other reviewers' territory):

• crates/relicario-core/ internals — DEV-A
• extension/, tools/relay/ — DEV-C
• docs/ outside the spec link above

Hard rules:

• No code changes. Not even trivial. Surface in notes.
• No git commits, no branch creation, no destructive ops.
• If you spot a core-internal issue while you're poking at it, file a ## QUESTION TO PM so DEV-A can be alerted; don't expand your own scope.

What to look for (review lens)

For each crate, assess:

relicario-cli (the user-facing binary)

1. Command surface. Does the clap structure match the spec's intended UX? Are subcommand names and flags discoverable? Any flags that exist but don't do what their name suggests?
2. Where business logic lives. relicario-core should be doing the work; the CLI should be glue (parse args → call core → format output). Any place where the CLI has logic that should be in core?
3. Session handling. session.rs holds UnlockedVault with the master key in Zeroizing. Are session lifetimes clear? Any path where the key outlives its window?
4. Filesystem and git. The CLI is the only place that touches fs and shells out to git. Is helpers.rs doing this cleanly? Any path-handling bugs? Any place where git_command is invoked with insufficient error mapping?
5. Tests. Integration tests under crates/relicario-cli/tests/ — do they test the CLI surface or just re-test core? Are fixtures synthetic (per project convention)? Any mocked filesystem leaks?
6. Error UX. When something goes wrong, does the user get a useful message, or does a RelicarioError get printed raw?

relicario-server (Git pre-receive hook)

1. Surface. Two subcommands (verify-commit, generate-hook). Is the contract with Git clear? Does generate-hook produce a hook that's actually correct?
2. Trust model. This is the only piece that runs server-side. Does it correctly enforce "the server only sees opaque ciphertext" — i.e. it never tries to decrypt, only verifies signatures/format?
3. Failure modes. What happens if a malformed commit lands? Are rejections actionable for the pushing client?

relicario-wasm (extension bridge)

1. JS surface. What does #[wasm_bindgen] actually expose? Is the API minimal and well-typed (SessionHandle opaque), or does it leak Rust internals?
2. Session handle pattern. SessionHandle → Zeroizing<[u8;32]> indirection. Is the lifetime story sound? What happens when JS drops the handle?
3. Error mapping. Rust errors → JS exceptions. Are messages useful on the JS side, or do they just say "internal error"?
4. Build target. Does cargo build -p relicario-wasm --target wasm32-unknown-unknown succeed clean? Any feature flags that look gnarly?
5. Boundary with DEV-C. What does the TS side need to know that isn't documented in the WASM crate? Note these for DEV-C cross-reference.

Cross-cutting (all three crates)

1. Naming. Same questions as DEV-A.
2. Comments. Same.
3. Layering. Does each crate import only what it should? Any place where a consumer crate is reaching past relicario-core's public API?
4. Dead code, abandoned features. Notice things.
5. Simplification. Where would a Rust newcomer trip? What's the single change that would help most?

You may run cargo build, cargo test -p relicario-cli, cargo test -p relicario-server, cargo build -p relicario-wasm --target wasm32-unknown-unknown, cargo clippy --workspace. The review is not gated on green; it's gated on understanding.

Output

Write your findings to docs/superpowers/reviews/2026-05-04-dev-b-notes.md. Create the reviews/ directory with mkdir -p if it doesn't exist.

Structure:

# DEV-B Architecture Review Notes — Rust Consumers (CLI, Server, WASM)

## Summary
3-5 sentences spanning all three crates: what's the shape of the consumer layer, where is it strongest, where is it weakest.

## Findings (prioritized: P1 / P2 / P3)

Group by crate, P1 first within each:

### relicario-cli
#### P1 — <short title>
**File(s):** `crates/relicario-cli/src/main.rs:456`
**Observation:** ...
**Why it matters:** ...
**Suggested direction:** ...

### relicario-server
...

### relicario-wasm
...

### Cross-cutting
Findings that span more than one crate (e.g. an error-handling pattern that's inconsistent across all three).

## File-by-file walk
One paragraph per file across all three crates. Appendix-grade detail.

## Boundary notes for DEV-C
What about the WASM JS surface should DEV-C double-check from the TypeScript side?

## Beginner-friendliness assessment
A paragraph: how readable are these crates for a competent dev who has never written Rust? What single change would help most?

Coordination protocol

Before each major pass: read_messages(for="dev-b").

Status update format (post via post_message(from="dev-b", to="pm", kind="status", body="..."), also print here):

## STATUS UPDATE — DEV-B
Time: <iso8601>
Phase: SETUP | READING | WALKING-CLI | WALKING-SERVER | WALKING-WASM | WRITING | REVIEW-COMPLETE
Crates covered: <e.g. cli ✓ / server ✓ / wasm ⏳>
Findings so far: <P1: N, P2: N, P3: N>
Notes: <≤3 sentences>

Question format:

## QUESTION TO PM — DEV-B
Time: <iso8601>
Context: <what crate, what concern>
Options: <A / B / C>
Recommended: <pick + one-sentence rationale>
Blocker: yes | no

You'll receive ## DIRECTIVE TO DEV-B blocks from the PM via relay. Acknowledge and act.

Authority

You don't need PM permission to:

• Decide reading order within scope
• Decide P1/P2/P3 prioritization
• Use subagents to parallelize crate reads (force-cd into /home/alee/Sources/relicario per project memory rule — every subagent prompt MUST start with cd /home/alee/Sources/relicario)
• Run cargo commands (build, test, clippy) read-only

You do escalate to PM when:

• An issue spans into DEV-A's core or DEV-C's TS territory
• A finding is severe enough to deserve immediate attention
• You're tempted to fix something inline (don't)

REVIEW-COMPLETE criteria

• Every src file in cli/server/wasm walked
• Every test file walked
• Notes written to docs/superpowers/reviews/2026-05-04-dev-b-notes.md
• Boundary-notes section for DEV-C populated
• Every P1 has a file:line and suggested direction

First action

1. Call read_messages(for="dev-b").
2. Read project rules and spec.
3. Skim relicario-core/src/lib.rs for the public API your crates depend on.
4. Emit a ## STATUS UPDATE with Phase: SETUP confirming setup, listing crates+file counts you'll walk.
5. Begin the walk: cli first, then server, then wasm. Save findings as you go.