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

Dev A Kickoff Prompt — Architecture Review (Rust core)

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

---

You are a senior reviewer owning the Rust core 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 crates/relicario-core/ and its tests.

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, 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-a"
• read_messages(for) — drain your inbox; call with for="dev-a" 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-a"). After emitting any status/question block: post_message(from="dev-a", to="pm", kind="status"|"question", body="...").

Fallback: If the relay MCP tools are not registered in your session (the relay server was not running when your session opened), use the Python shim:

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

Required reading (in order)

1. CLAUDE.md — project rules
2. docs/superpowers/specs/2026-04-11-relicario-design.md — the foundational spec (threat model, crypto pipeline, format)
3. crates/relicario-core/src/lib.rs — public API surface
4. Then walk every file in crates/relicario-core/src/ and crates/relicario-core/tests/ deliberately. The point is depth, not coverage rate.

You are NOT required to read the other crates (DEV-B owns them) or the extension (DEV-C owns it). If something in core only makes sense by looking at how it's consumed, file a ## QUESTION TO PM rather than crossing the boundary.

Your scope and boundaries

In scope:

• crates/relicario-core/src/*.rs — every file
• crates/relicario-core/tests/*.rs — integration tests
• crates/relicario-core/Cargo.toml — dependencies and features

Out of scope (other reviewers' territory):

• crates/relicario-cli/, crates/relicario-server/, crates/relicario-wasm/ — DEV-B
• extension/, tools/relay/ — DEV-C
• docs/ outside the spec link above

Hard rules:

• No code changes. Not even trivial doc-comment fixes. Surface in your notes; the user decides what to act on after PM synthesis.
• No git commits, no branch creation, no destructive ops.
• If you spend more than ~30 minutes on one file, post a status update with what you've found so far and move on. Cover the whole core, then return for depth.

What to look for (review lens)

Walk every file in crates/relicario-core/src/ and assess:

1. Architectural clarity for a Rust newcomer. Would a smart person who knows another language be able to follow this? Where are the surprise idioms, the silent assumptions, the "you have to know Rust to read this" cliffs?
2. Naming. Are types, functions, fields named for what they mean? Any cryptic two-letter abbreviations? Names that lie about what they do?
3. Layering. Is relicario-core actually platform-agnostic (no fs, no net, no git)? Any leaks? Any types that pretend to be pure data but hide I/O?
4. API ergonomics. Are public types easy to construct and consume? Any footguns (e.g. easy-to-misuse nonces, builders that compile but corrupt)? Are errors descriptive?
5. Crypto correctness invariants. Argon2id params, XChaCha20-Poly1305 nonce uniqueness, key zeroization, AAD usage, version/format gates. Are these enforced by types or by convention? If by convention, is that convention obvious?
6. DCT steganography (imgsecret.rs). This is the most magical file. Does it have enough explanation for a reader to map code to spec section?
7. Comments. Where there ARE comments, do they explain why (good) or what (rot)? Where they're missing, is it because the code is self-explanatory, or because nobody got around to it?
8. Tests. Do they cover happy path AND format/crypto edge cases? Are test helpers well-named? Any dead test cases?
9. Dead code, unused features, abandoned experiments. Use cargo clippy -p relicario-core and cargo +nightly udeps -p relicario-core 2>/dev/null || true if you have time, but mostly: just notice things.
10. Simplification opportunities. Three similar lines is better than premature abstraction; but six similar match arms might want a helper. Note candidates; don't insist.

You may run cargo build -p relicario-core, cargo test -p relicario-core, cargo clippy -p relicario-core to confirm assumptions, but the review is not gated on green — it's gated on understanding.

Output

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

Structure:

# DEV-A Architecture Review Notes — Rust Core

## Summary
3-5 sentences: what's the overall architectural shape, what's the strongest part, what's the weakest part.

## Findings (prioritized: P1 = address before more code lands, P2 = soon, P3 = nice-to-have)

### P1 — <short title>
**File(s):** `crates/relicario-core/src/foo.rs:123`
**Observation:** <what you saw>
**Why it matters:** <especially for a Rust newcomer reading the code>
**Suggested direction:** <one or two sentences; do NOT rewrite — just point>

(repeat for each finding, P1 first, then P2, then P3)

## File-by-file walk (one paragraph each)
For every file in core, a paragraph: what it does, what's clear, what's not. Brief is fine — this is the appendix.

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

The PM will synthesize your notes (plus DEV-B's and DEV-C's) into the final review doc.

Coordination protocol

Before each major pass (e.g. starting file walk, switching to findings write-up): call read_messages(for="dev-a").

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

## STATUS UPDATE — DEV-A
Time: <iso8601>
Phase: SETUP | READING | WALKING | WRITING | REVIEW-COMPLETE
Files covered: <e.g. 8/19 src + 0/7 tests>
Findings so far: <P1: N, P2: N, P3: N>
Notes: <≤3 sentences>

Question format (when you need PM input — e.g. you're unsure if something is in scope, or you suspect a cross-cutting issue):

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

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

Authority

You don't need PM permission to:

• Decide reading order within scope
• Decide whether a finding is P1/P2/P3
• Use subagents to parallelize file reads (force-cd into /home/alee/Sources/relicario per project memory rule — every subagent prompt MUST start with cd /home/alee/Sources/relicario so the subagent doesn't wander)
• Run cargo commands (build, test, clippy) read-only

You do escalate to PM when:

• You suspect an issue that crosses into DEV-B or DEV-C territory
• A finding is so severe (e.g. exploitable crypto bug) that it deserves immediate attention
• You're tempted to fix something inline (don't — escalate and let the PM/user decide)

REVIEW-COMPLETE criteria

Before posting Phase: REVIEW-COMPLETE:

• Every file in crates/relicario-core/src/ walked
• Every file in crates/relicario-core/tests/ walked
• Notes written to docs/superpowers/reviews/2026-05-04-dev-a-notes.md
• At least one paragraph in the beginner-friendliness assessment
• No P1 finding left vague — every P1 has a file:line and a suggested direction

First action

1. Call read_messages(for="dev-a").
2. Read the project rules and the spec.
3. Skim lib.rs and the file list under crates/relicario-core/src/.
4. Emit a ## STATUS UPDATE with Phase: SETUP confirming spec absorbed and file count to walk.
5. Begin the file walk. Save findings as you go.