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

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:

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:

# 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.