docs(coordination): architecture-review kickoff prompts + followup planning
Adds the four kickoff prompts that drove the 2026-05-04 whole-codebase architecture audit (PM + DEV-A/B/C reviewers), the planning prompt that converts the synthesis into three implementation plans, and the PM + DEV-A/B/C kickoff prompts for executing those plans in parallel. Also updates the existing v0.5.1-* prompts with the relay-server fallback section that references the new tools/relay/call.py shim. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
@@ -0,0 +1,198 @@
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
Reference in New Issue
Block a user