relicario/docs/superpowers/coordination/architecture-review-followup-planning-prompt.md

Planning Kickoff Prompt — Architecture-Review Follow-up

Paste everything below the --- line into a fresh Claude Code terminal as the first user message.

---

You are an architect drafting three implementation plans that follow up on the whole-codebase architecture review committed to main on 2026-05-04 (061facd docs(reviews): whole-codebase architecture audit 2026-05-04). Three reviewers (DEV-A: Rust core; DEV-B: Rust consumers; DEV-C: TypeScript) walked the codebase; the PM synthesized 10 P1s plus a long P2/P3 tail. Your job is to convert those findings into three discrete, well-scoped plans that the user (or future agents) can execute.

This is planning-only work. Do not modify the codebase being planned. Do not commit. Do not ship anything. Each plan is a markdown file in docs/superpowers/specs/ and that is the only output.

Setup

• Working directory: /home/alee/Sources/relicario
• Stay on main. Do not create branches or worktrees.
• 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 from in-flight v0.5.x work (manifests, vault.ts/css, glyphs, relay tooling, Cargo.toml version bumps). Treat them as "in flight, ignore" — do not include them in any plan.

Required reading (in order)

1. CLAUDE.md — project rules (Spanish flourish, capitalization, autonomy)
2. docs/superpowers/specs/2026-04-11-relicario-design.md — foundational design spec (threat model, crypto pipeline, format)
3. docs/superpowers/reviews/2026-05-04-architecture-review.md — PM synthesis. This is the canonical source. Every plan below must trace its scope back to specific findings here.
4. docs/superpowers/reviews/2026-05-04-dev-a-notes.md — DEV-A's full notes (Rust core)
5. docs/superpowers/reviews/2026-05-04-dev-b-notes.md — DEV-B's full notes (CLI/server/WASM), especially the "Boundary notes for DEV-C" section
6. docs/superpowers/reviews/2026-05-04-dev-c-notes.md — DEV-C's full notes (extension + relay), especially the "Boundary notes for DEV-B" section

Also skim two existing plan docs to match the format and tone:

• docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md
• docs/superpowers/specs/2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md

What to produce

Three plan files, all under docs/superpowers/specs/:

Plan A — Security & docs polish PR

Filename: docs/superpowers/specs/2026-05-04-security-polish-design.md Scope (drawn from synthesis): P1.1 (SessionHandle impl Drop + Rust wasm-bindgen-test + extension .free() callsite audit), the partner JS-side fix at service-worker/session.ts:26 (remove the try { current.free() } swallow), P1.7 (recovery_qr.rs documentation to match crypto.rs/backup.rs density), and the launcher fix DEV-C suspected at tools/relay/start.sh:80 (4-window dev-c support; queue.test.ts assertion already fixed in 061facd). Goal: one short PR, all-S-effort items, ships in under a day. This is the security-flavored quick win that goes first; nothing in B or C should depend on it.

Plan B — CLI restructure

Filename: docs/superpowers/specs/2026-05-04-cli-restructure-design.md Scope: P1.2 (split crates/relicario-cli/src/main.rs 2641 LOC into commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs + prompt.rs + parse.rs, leaving main.rs as clap definitions + dispatcher), P1.3 (helpers::git_run(repo, args, context) with stderr capture; sweep the ~16 duplicated bail sites), P1.10 (migrate parse_month_year, base32_decode_lenient, guess_mime to relicario-core and re-export through relicario-wasm for the extension; pair with the core base32 dedup from DEV-A's P2), plus the in-scope CLI P2s (build_*_item helper compression, refresh_groups_cache discipline via Vault::after_manifest_change, ParamsFile dedup between main.rs:2287 and session.rs:114, batched purge in cmd_purge/cmd_trash_empty). Sequencing matters here: the main.rs split must land first because every other P2 in this plan touches files that don't exist yet until the split happens. Goal: M-L effort, multi-day plan; "single biggest readability lift" per the synthesis.

Plan C — Extension restructure

Filename: docs/superpowers/specs/2026-05-04-extension-restructure-design.md Scope: P1.4 (extension/src/setup/setup.ts 1220 LOC: add create_vault and attach_vault SW messages; rewrite setup as a UI that posts those messages with gathered config + image bytes; convert the 6-step procedural wizard into a step-registry pattern { id, render, attach }[]; add clearWizardState() on beforeunload), P1.5 (split extension/src/vault/vault.ts 1027 LOC into vault-shell.ts / vault-sidebar.ts / vault-list.ts / vault-drawer.ts / vault-form-wrapper.ts; lift the vault_locked RPC intercept into shared/state.ts so popup and vault use one channel; reset state.drawerOpen on non-list renderPane), P1.6 (concrete StateHost interface in shared/state.ts with state: PopupState, navigate, popOutToTab, isInTab, openVaultTab; generic getState/setState over keyof PopupState; double-registration guard + __resetHostForTests helper), P1.9 (extract duplicated SW router helpers — loadDeviceSettings/loadBlacklist/saveBlacklist to service-worker/storage.ts; itemToManifestEntry to service-worker/vault.ts), plus the in-scope extension P2s (inactivity-timer reset on content-callable messages; state.gitHost clear on session expiry; teardown helper extraction; Promise.allSettled in devices/trash; mutation-observer debounce in content/detector.ts; vault-tab status indicator from get_vault_status for the relicario status parity gap). Sequencing: P1.6 (state.ts typing) is a precondition for P1.4 and P1.5 because lifting vault_locked and adding setup-via-SW both push through that surface. Goal: largest plan, multi-day to multi-week.

What's explicitly NOT in these three plans

• The full P2/P3 tail outside what's listed above. The synthesis doc is canonical; if a P2 isn't named in one of the three scopes above, it doesn't go in. Future plans can pick those up.
• WASM JS-naming snake_case → camelCase (DEV-B/DEV-C P3) — defer to a separate decision, not these plans.
• The 8 "Open architectural decisions" at the bottom of the synthesis — those are user-judgement calls, not implementation tasks.
• Anything that requires touching the in-flight uncommitted v0.5.x work (manifests, glyphs, vault.css, relay tooling beyond start.sh).

Plan format (match the existing specs)

Each plan file should have, at minimum:

# <Title> — Design

**Date:** 2026-05-04
**Status:** Proposed
**Source:** docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.X, P1.Y, ...)
**Effort estimate:** S | M | L

## Summary
2-4 sentences: what this plan accomplishes and why it matters for the user's stated goal ("make this app's architecture logical and readable for someone who doesn't know Rust but wants to learn by tinkering").

## Findings addressed
Bullet list, each entry citing the synthesis P-tag, the reviewer who found it, and the file:line.

## Approach
The architectural shape of the work — what gets extracted, what gets created, what gets renamed. Include directory trees / module diagrams if it helps a reader follow the layout change.

## Implementation phases
Numbered phases. Each phase:
- **Goal:** one-sentence outcome
- **Changes:** specific files touched, new files created, with paths
- **Tests:** what gets added or moved (synthetic fixtures only — no binary blobs, per project convention)
- **Effort:** S/M/L for the phase
- **Depends on:** other phases, or "none"

## Risks and mitigations
What can break, especially across the CLI/extension parity boundary. Cite specific findings.

## Out of scope
Explicit list of adjacent things this plan does NOT touch.

## Done criteria
Checklist a reviewer can use to confirm the plan shipped.

Mirror the tone and depth of 2026-05-02-v0.5.0-polish-harden-design.md and 2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md. Use the same heading conventions.

Execution approach

Use subagents. Per the user's standing preference (CLAUDE.md memory: "Default to subagent-driven execution — for any multi-task plan use subagent-driven mode without asking"), drafting these plans is parallel work. Spawn three Plan subagents in parallel (single message, three tool calls), one per plan file. Each subagent reads the same shared inputs (synthesis + relevant notes file(s)), then writes only its assigned plan file. Plan B and Plan C subagents should each receive the relevant cross-boundary section of the other reviewer's notes ("Boundary notes for DEV-C" goes to Plan C's drafter; "Boundary notes for DEV-B" goes to Plan B's drafter) so the parity boundary is respected.

After the three subagents return, do a coherence pass yourself:

• Confirm Plan A doesn't depend on B or C
• Confirm Plan B's parse_month_year/base32 migration to core is reachable from Plan C's WASM consumers (or note explicitly that Plan C will pick up the WASM exports in a later phase)
• Confirm Plan C's setup-via-SW migration cites the same create_vault/attach_vault message names everywhere

Each subagent prompt must start with cd /home/alee/Sources/relicario (project memory rule — without the force-cd, subagents may write to the wrong tree).

Hard constraints

• Read-only on the codebase being planned. No cargo, bun, or any other write commands beyond writing the three plan files.
• No commits. The user commits when ready.
• No git operations. Don't even git status unless you have a specific reason.
• Three files, no fewer, no more. If a finding doesn't fit any of the three scopes above, leave it out — future plans handle it.
• Spanish flourish in replies (1-2 phrases per reply with [translation] brackets), per CLAUDE.md. Do not put Spanish into the plan files themselves — those are project artifacts.

Done criteria

Before posting your final summary:

• All three plan files exist under docs/superpowers/specs/ with the exact filenames specified above
• Each plan cites at least one specific P1 from the synthesis in its "Findings addressed" section
• Each plan has phases, each phase has effort, each phase names specific files
• Plan A is independent (no dependencies on B or C)
• Plan B and Plan C call out the parity-relevant cross-references explicitly
• You did NOT modify any code, run any test, or commit anything
• You ask the user whether to commit the three plan files (do not commit unprompted)

First action

1. Read the synthesis (docs/superpowers/reviews/2026-05-04-architecture-review.md) end-to-end. Internalize the 10 P1s and the cross-cutting themes.
2. Skim the three per-reviewer notes files for the file:line context the synthesis abbreviates.
3. Skim the two existing plan docs above to absorb the format.
4. Tell the user what you absorbed in 3-5 sentences.
5. Spawn three Plan subagents in parallel with the scopes specified above.
6. Do the coherence pass.
7. Ask the user whether to commit the three plan files.