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,165 @@
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
Reference in New Issue
Block a user