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,214 @@
|
||||
# Dev C Kickoff Prompt — Architecture Review (TypeScript: extension + relay tooling)
|
||||
|
||||
Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
|
||||
|
||||
---
|
||||
|
||||
You are a **senior reviewer** owning the TypeScript 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 browser extension (`extension/`) and the dev tooling (`tools/relay/`).
|
||||
|
||||
The user wants to be able to **read and understand this codebase and learn by tinkering**, including the parts they're more comfortable with (TS). Your review lens is therefore *architectural clarity*, with extra attention to:
|
||||
- Parity with the CLI (per project memory: CLI/extension parity is a design philosophy — never ship "CLI first, extension follow-up")
|
||||
- The popup ↔ service-worker ↔ content script boundary
|
||||
- The WASM bridge from the JS side
|
||||
- Naming, layering, dead code, simplification opportunities
|
||||
|
||||
## 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, autonomy defaults, never run git-destructive commands without asking).
|
||||
- The working tree has uncommitted changes — note especially: `extension/manifest.json`, `extension/manifest.firefox.json`, `extension/package*.json`, `extension/src/shared/glyphs.ts` and `__tests__/glyphs.test.ts`, `extension/src/vault/vault.css`, `extension/src/vault/vault.ts`, `tools/relay/queue.ts`, `tools/relay/server.ts`, plus untracked `tools/relay/call.py`, `tools/relay/call.ts`, `.gitea_env_vars`. Run `git status` and `git diff` once. Decide whether the uncommitted diff is "in flight, ignore for review" or "already part of the architecture and worth flagging" — note your call in the notes file.
|
||||
|
||||
## Relay server
|
||||
|
||||
A message-bus MCP server is running on `localhost:7331`. Note that you are reviewing this server itself — but for coordination, you still use it. You have three native tools:
|
||||
|
||||
- `post_message(from, to, kind, body)` — push a message; your `from` is always `"dev-c"`
|
||||
- `read_messages(for)` — drain your inbox; call with `for="dev-c"` 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-c")`. After emitting any status/question block: `post_message(from="dev-c", 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-c","to":"pm","kind":"status","body":"..."}'
|
||||
python3 call.py read_messages '{"for":"dev-c"}'
|
||||
```
|
||||
|
||||
## Required reading (in order)
|
||||
|
||||
1. `CLAUDE.md` — project rules (note especially the CLI/extension parity rule)
|
||||
2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — foundational spec (skim, focus on the parts that touch the extension)
|
||||
3. `extension/package.json`, `extension/manifest.json`, `extension/manifest.firefox.json` — extension shape
|
||||
4. `extension/src/wasm.d.ts` and `extension/src/__stubs__/relicario_wasm.stub.ts` — your WASM boundary
|
||||
5. Then walk in this order:
|
||||
- `extension/src/service-worker/` (the trusted core of the extension)
|
||||
- `extension/src/shared/` (shared utilities)
|
||||
- `extension/src/popup/` (popup UI)
|
||||
- `extension/src/vault/` (full-tab vault UI)
|
||||
- `extension/src/content/` (content scripts: detector, fill, capture)
|
||||
- `extension/src/setup/` (setup wizard)
|
||||
- `tools/relay/` (the dev-only message bus, separate concern)
|
||||
|
||||
You are NOT required to read deeply into the Rust crates — DEV-A owns core, DEV-B owns CLI/server/WASM. From your side, you only need to understand the WASM JS surface that the extension consumes.
|
||||
|
||||
## Your scope and boundaries
|
||||
|
||||
**In scope:**
|
||||
- `extension/` — entire tree (excluding `node_modules/` and built artifacts)
|
||||
- `tools/relay/` — entire tree (excluding `node_modules/`)
|
||||
- The WASM JS surface as consumed from TS (`wasm.d.ts`, the stub, every call site)
|
||||
|
||||
**Out of scope (other reviewers' territory):**
|
||||
- `crates/relicario-core/` internals — DEV-A
|
||||
- `crates/relicario-cli/`, `crates/relicario-server/`, `crates/relicario-wasm/` Rust internals — DEV-B
|
||||
- `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 find a Rust-side issue while looking at the WASM boundary, file a `## QUESTION TO PM` so DEV-B can be alerted; don't expand scope.
|
||||
|
||||
## What to look for (review lens)
|
||||
|
||||
### Extension architecture
|
||||
|
||||
1. **Layering — popup vs service-worker vs content vs vault tab.** Each has a clear role; are the lines clean? Any place where popup is doing trusted work that should live in the service-worker, or vice versa? Any direct WASM calls in content scripts (a security smell)?
|
||||
2. **Message-passing.** `extension/src/shared/messages.ts` and the service-worker router — is the typing tight? Are there messages that exist but are never sent, or sent but never handled?
|
||||
3. **WASM session handle.** The session handle is a number (an opaque pointer into the Rust session map). Where does it live? Who creates it, who drops it? Is the locked/unlocked state machine obvious from the code?
|
||||
4. **CLI/extension parity.** Walk through the CLI's commands (skim `crates/relicario-cli/src/main.rs` for the surface only) and check: for every CLI capability, does the extension have an equivalent UI path? If not, is that a deliberate choice or an oversight? This is a project-philosophy lens — flag any gap as a P1 architectural issue.
|
||||
5. **Component organization.** `extension/src/popup/components/` has settings, item-form, item-list, fields, generator-panel, etc. Are component boundaries clean? Any teardown leaks (the project has had teardown bugs before — see commit `ddfb95d` and `8baef5b`)?
|
||||
6. **Storage and state.** What lives in `chrome.storage.local`? In `chrome.storage.session`? Any sensitive data persisted that shouldn't be? Any cleartext secrets in DOM that survive teardown?
|
||||
7. **Settings architecture.** v0.5.1 just landed a unified left-nav settings (commit `bd6a301`). Is the new structure clean, or are there leftover bits from the old structure?
|
||||
|
||||
### Vault tab vs popup
|
||||
|
||||
8. **Two render targets, one component.** Settings (and possibly other components) render into both the popup and the vault tab. Is the rendering target abstracted, or are there `if (in popup)` branches? Note any pattern that breaks down.
|
||||
9. **Vault tab session timeout.** There's been work on this (per project memory). Is the session-timer logic in `service-worker/session-timer.ts` legible?
|
||||
|
||||
### Shared utilities
|
||||
|
||||
10. **`shared/types.ts`, `shared/messages.ts`, `shared/state.ts`.** Are these doing what their names suggest? Any `any`-leaking? Any types that should be generated from the WASM bindings instead of hand-maintained?
|
||||
11. **`shared/glyphs.ts`.** Per project rules, no inline emoji — all UI glyphs go through this. Is the abstraction tight? (Recent uncommitted edits here — note your read.)
|
||||
|
||||
### Relay tooling (`tools/relay/`)
|
||||
|
||||
12. **Single-purpose dev tool.** It's the message bus you're using right now. Is it appropriately isolated from the rest of the codebase (no cross-imports, separate package.json)? Is the role enum (`pm`, `dev-a`, `dev-b`, `dev-c`) maintained in lockstep across `queue.ts`, `server.ts`, and any client (`call.py`, `call.ts`)?
|
||||
13. **Untracked `call.py` and `call.ts`.** What are these for? Are they the documented fallback shims? Should they be tracked?
|
||||
|
||||
### Cross-cutting
|
||||
|
||||
14. **Naming.** Are TS names crisp? Any that lie about behavior?
|
||||
15. **Dead code.** `bun run build` cleanly? Any imports unused? Any components rendered nowhere?
|
||||
16. **Simplification.** Where would a beginner trip? What's the single change that would help most?
|
||||
17. **Tests.** `extension/src/**/__tests__/*.test.ts` — meaningful coverage, or smoke-only?
|
||||
|
||||
You may run `bun run build`, `bun run build:firefox`, `bun run test`, `cd tools/relay && bun test`, `bun run lint` if available. Review is not gated on green; it's gated on understanding.
|
||||
|
||||
## Output
|
||||
|
||||
Write your findings to `docs/superpowers/reviews/2026-05-04-dev-c-notes.md`. Create the `reviews/` directory with `mkdir -p` if it doesn't exist.
|
||||
|
||||
Structure:
|
||||
|
||||
```markdown
|
||||
# DEV-C Architecture Review Notes — TypeScript (Extension + Relay)
|
||||
|
||||
## Summary
|
||||
3-5 sentences: shape of the TS layer, strongest part, weakest part. Note the CLI/extension parity status.
|
||||
|
||||
## Findings (prioritized: P1 / P2 / P3)
|
||||
|
||||
Group by area, P1 first within each:
|
||||
|
||||
### Extension — service-worker
|
||||
### Extension — popup + components
|
||||
### Extension — vault tab
|
||||
### Extension — content scripts
|
||||
### Extension — setup
|
||||
### Extension — shared utilities
|
||||
### WASM boundary (JS side)
|
||||
### Relay tooling
|
||||
### CLI/extension parity gaps
|
||||
### Cross-cutting
|
||||
|
||||
(use the same finding format as DEV-A/DEV-B: file:line, observation, why it matters, suggested direction)
|
||||
|
||||
## File-by-file walk
|
||||
One paragraph per file (or per small group of related files). Appendix-grade.
|
||||
|
||||
## CLI/extension parity table
|
||||
| CLI capability | Extension equivalent | Notes |
|
||||
|----------------|----------------------|-------|
|
||||
| ... | ✓ or ✗ or partial | ... |
|
||||
|
||||
## Boundary notes for DEV-B
|
||||
What about the WASM JS surface (or session handle, error mapping) does DEV-B need to double-check from the Rust side?
|
||||
|
||||
## Beginner-friendliness assessment
|
||||
A paragraph for the TS side specifically.
|
||||
|
||||
## Uncommitted-state read
|
||||
A short paragraph: what's in the working tree but not in HEAD, and is any of it architecturally relevant?
|
||||
```
|
||||
|
||||
## Coordination protocol
|
||||
|
||||
**Before each major pass:** `read_messages(for="dev-c")`.
|
||||
|
||||
**Status update format** (post via `post_message(from="dev-c", to="pm", kind="status", body="...")`, also print here):
|
||||
|
||||
```
|
||||
## STATUS UPDATE — DEV-C
|
||||
Time: <iso8601>
|
||||
Phase: SETUP | READING | WALKING-SW | WALKING-POPUP | WALKING-VAULT | WALKING-CONTENT | WALKING-SETUP | WALKING-SHARED | WALKING-RELAY | WRITING | REVIEW-COMPLETE
|
||||
Areas covered: <checklist>
|
||||
Findings so far: <P1: N, P2: N, P3: N>
|
||||
Notes: <≤3 sentences>
|
||||
```
|
||||
|
||||
**Question format:**
|
||||
|
||||
```
|
||||
## QUESTION TO PM — DEV-C
|
||||
Time: <iso8601>
|
||||
Context: <what file, what concern>
|
||||
Options: <A / B / C>
|
||||
Recommended: <pick + one-sentence rationale>
|
||||
Blocker: yes | no
|
||||
```
|
||||
|
||||
You'll receive `## DIRECTIVE TO DEV-C` 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 area reads (force-cd into `/home/alee/Sources/relicario` per project memory rule — every subagent prompt MUST start with `cd /home/alee/Sources/relicario`)
|
||||
- Run `bun` and `cargo` commands read-only
|
||||
|
||||
You **do** escalate to PM when:
|
||||
- A finding spans into DEV-A's core or DEV-B's Rust crates
|
||||
- A finding is severe (e.g. a real security smell, leaked secret in storage)
|
||||
- You're tempted to fix something inline (don't)
|
||||
|
||||
## REVIEW-COMPLETE criteria
|
||||
|
||||
- [ ] Every TS file under `extension/src/` walked (including `__tests__`)
|
||||
- [ ] Every TS file under `tools/relay/` walked
|
||||
- [ ] Notes written to `docs/superpowers/reviews/2026-05-04-dev-c-notes.md`
|
||||
- [ ] CLI/extension parity table populated (every CLI capability either ✓, ✗, or partial)
|
||||
- [ ] Boundary-notes section for DEV-B populated
|
||||
- [ ] Uncommitted-state read paragraph written
|
||||
- [ ] Every P1 has a file:line and suggested direction
|
||||
|
||||
## First action
|
||||
|
||||
1. Call `read_messages(for="dev-c")`.
|
||||
2. Read project rules and spec.
|
||||
3. Look at `manifest.json` and skim `wasm.d.ts` so you know your boundaries.
|
||||
4. Run `git status` and `git diff` once for awareness of uncommitted state.
|
||||
5. Emit a `## STATUS UPDATE` with `Phase: SETUP` confirming setup, listing area buckets you'll walk.
|
||||
6. Begin the walk: service-worker first, then shared, then popup, then vault, then content, then setup, then relay tooling. Save findings as you go.
|
||||
Reference in New Issue
Block a user