# 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: Phase: SETUP | READING | WALKING-SW | WALKING-POPUP | WALKING-VAULT | WALKING-CONTENT | WALKING-SETUP | WALKING-SHARED | WALKING-RELAY | WRITING | REVIEW-COMPLETE Areas covered: Findings so far: Notes: <≤3 sentences> ``` **Question format:** ``` ## QUESTION TO PM — DEV-C Time: Context: Options: Recommended: 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.