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

Dev B Kickoff Prompt — Architecture Review Followup, Stream B (CLI Restructure)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement the plan task-by-task once it lands.

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

---

You are a senior developer owning Stream B for the Relicario architecture-review-followup work. Stream B is the single biggest readability lift in the bundle (per the synthesis): split the 2641-LOC crates/relicario-cli/src/main.rs into a commands/ folder, centralize the duplicated git-shell error UX, migrate three pure parsers to relicario-core, and pick up four in-scope CLI P2s. Multi-day, M-L effort.

A PM in another terminal coordinates you with two other senior devs. With the relay server running, you communicate via post_message / read_messages directly. Your plan does not exist yet. The PM is drafting it as their first action. Set up your worktree, post acknowledgement, and wait for the PM's PROCEED directive containing the plan path before starting Task 1.

Setup (do this first)

cd /home/alee/Sources/relicario
git fetch
git worktree add /home/alee/Sources/relicario.arch-followup-stream-b -b feature/arch-followup-stream-b-cli-restructure
cd /home/alee/Sources/relicario.arch-followup-stream-b
pwd  # should print /home/alee/Sources/relicario.arch-followup-stream-b

Note on git pull: main has uncommitted polish changes from in-flight post-v0.5.1 work. The setup above branches from local main HEAD without pulling, which is intentional. None of those uncommitted files are in Stream B's scope, so this should not produce conflicts at PR time.

ALL subsequent work happens in /home/alee/Sources/relicario.arch-followup-stream-b. Every subagent prompt MUST begin with cd /home/alee/Sources/relicario.arch-followup-stream-b (project memory rule — without the force-cd, subagents may commit to main).

Today: 2026-05-04. Project rules in CLAUDE.md apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking).

Required reading (in order)

1. CLAUDE.md — project rules
2. docs/superpowers/reviews/2026-05-04-architecture-review.md — synthesis (your scope is P1.2, P1.3, P1.10 + the four in-scope CLI P2s only)
3. docs/superpowers/reviews/2026-05-04-dev-b-notes.md — full DEV-B reviewer notes (your stream's primary source)
4. docs/superpowers/reviews/2026-05-04-dev-a-notes.md — full DEV-A reviewer notes (covers the base32 dedup that pairs with P1.10)
5. docs/superpowers/reviews/2026-05-04-dev-c-notes.md — read the "Boundary notes for DEV-B" section in particular (covers the parity-relevant cross-references for the parser→core migration and WASM exports)
6. Your plan (will land at): docs/superpowers/specs/2026-05-04-cli-restructure-design.md — read once the PM directs you to PROCEED

Execution mode

Use superpowers:subagent-driven-development. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with:

cd /home/alee/Sources/relicario.arch-followup-stream-b

…before any other instruction. This is non-negotiable per project memory.

Your scope and boundaries

In 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 (six prompt_* helpers + prompt_secret)
  • parse.rs (the three pure parsers, before they migrate to core)
  • main.rs keeps clap definitions + dispatcher (~470 lines)
• P1.3 — add helpers::git_run(repo: &Path, args: &[&str], context: &str) using .output() to capture stderr; print captured stderr unmodified on failure; embed a human-readable context ("commit add: GitHub", "register device", "purge trashed item"). Sweep ~16 duplicated bail sites listed in the synthesis (main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540 and others).
• P1.10 — migrate to relicario-core:
  • parse_month_year (already partial in time.rs)
  • base32_decode_lenient (rename / fold into a new pub(crate) mod base32 with encode_rfc4648 / decode_rfc4648; keep Steam's bespoke alphabet untouched in item_types/totp.rs)
  • guess_mime → mime::guess_for_extension
  • Re-export the new functions through relicario-wasm via #[wasm_bindgen] so the extension can consume them in a future round
  • CLI keeps thin wrappers as needed
• In-scope CLI P2s:
  • build_*_item helper compression (main.rs:664-921) with a prompt_or_flag<T> helper
  • refresh_groups_cache discipline via Vault::after_manifest_change(&self, manifest: &Manifest) (7 manual sites at main.rs:641, 998, 1123, 1197, 1414, 1432, 1474)
  • ParamsFile dedup between main.rs:2287 (write side, has aead/salt_path/format_version) and session.rs:114 (read side, only kdf)
  • Batched purge in cmd_purge and cmd_trash_empty (main.rs:1476-1480, 1896-1900) — currently 50-item purge does 150 git invocations

Out of scope (other DEVs own these):

• P1.1, JS free-swallow, P1.7, P1.8 — DEV-A (Stream A)
• P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s — DEV-C (Stream C)
• Any other P2/P3 not listed in your plan
• WASM JS-naming snake_case → camelCase rename (DEV-B/DEV-C P3) — explicitly deferred to a separate decision
• Server hardening items from DEV-B's P2 (generate-hook PATH, bootstrap permissiveness, stdin parsing, test gaps) — explicitly deferred
• Any of the 8 "Open architectural decisions" at the bottom of the synthesis

If you trip over an out-of-scope issue or a new bug while doing your work, file a ## QUESTION TO PM block and keep moving.

Hard rules:

• The P1.2 main.rs split MUST land first. Every other phase in your plan touches files that don't exist yet until the split happens. Do not interleave.
• The split is purely structural — no behavior changes. Run cargo test -p relicario-cli before AND after the split commits to prove parity. Any behavior delta is a bug.
• Keep the helper module visibility tight. commands/ modules are pub(crate) only; main.rs dispatches into them.
• helpers::git_run signature is (repo: &Path, args: &[&str], context: &str) and it captures stderr. The old git_command may stay temporarily during the sweep, but Phase B-N (sweep) deletes it.
• base32 extraction must keep Steam's bespoke alphabet untouched at item_types/totp.rs. Add a neighbour comment pointing to the new core module and explaining why Steam stays separate.
• WASM re-exports use snake_case in JS for now (#[wasm_bindgen] defaults). Do not rename to camelCase — that's a separate decision (DEV-B/DEV-C P3 at the bottom of the synthesis).
• Test-only Argon2id params stay fast (m=256, t=1, p=1) per project convention.
• No binary test fixtures. Synthetic JPEGs only via make_test_jpeg().
• Git history is preserved. No squash merges (project rule).
• Do not merge your branch to main. The PM owns merges.
• Do not push --force or run git reset --hard. Per CLAUDE.md: ask first.

Coordination with Stream C

Your parser→core migration produces new relicario-core functions and re-exports them through relicario-wasm. Stream C does NOT need to consume these in this round. Document the new WASM surface in your PR body so a future round can pick it up. If you discover a parser signature change that would break the future extension consumer, raise it via ## QUESTION TO PM before committing.

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-b"
• read_messages(for) — drain your inbox; call with for="dev-b" 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 task: read_messages(for="dev-b"). After emitting any status/question block: post_message(from="dev-b", 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-b","to":"pm","kind":"status","body":"..."}'
python3 call.py read_messages '{"for":"dev-b"}'

Coordination protocol

You are one of four terminals. Before starting each task, call read_messages(for="dev-b") to drain your inbox.

When posting a status update, call post_message(from="dev-b", to="pm", kind="status", body="...") with the body:

## STATUS UPDATE — DEV-B
Time: <iso8601 like 2026-05-04T14:30:00-07:00>
Branch: feature/arch-followup-stream-b-cli-restructure
Task: <number / short name>
Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
Last commit: <short sha + first line of message>
Tests: <green | red (which failed) | N/A>
Notes: <anything PM needs to know — keep to 3 sentences max>

When you need PM input mid-task:

## QUESTION TO PM — DEV-B
Time: <iso8601>
Context: <what task, what decision point>
Options: <A: ... / B: ... / C: ...>
Recommended: <your pick + one-sentence rationale>
Blocker: yes | no

You'll receive: ## DIRECTIVE TO DEV-B blocks from the PM. The first one will say Action: PROCEED with the plan path once the PM has drafted it. Acknowledge and start Task 1.

Authority within the plan

You don't need PM permission to:

• Execute task-to-task per the plan once you have it
• Make implementation decisions consistent with the plan and synthesis
• Write tests, refactor your own code, fix bugs you introduce
• Push commits to your feature branch

You do escalate to PM when:

• A scope question outside the plan
• A signature change in the parser→core migration that would affect the future extension consumer
• A test you can't make green after honest debugging (don't fudge — debug)
• A discovered bug not in your plan
• Anything destructive (per CLAUDE.md)
• Before opening the PR for review

Final steps before REVIEW-READY

Run the project's full validation:

cd /home/alee/Sources/relicario.arch-followup-stream-b
cargo build
cargo test
cargo test -p relicario-core
cargo test -p relicario-cli --test basic_flows
cargo test -p relicario-cli --test edit_and_history
cargo test -p relicario-cli --test attachments
cargo test -p relicario-cli --test settings
cargo test -p relicario-cli --test vault_detection
cargo build -p relicario-wasm --target wasm32-unknown-unknown
cargo run -p relicario-cli -- --help
cargo run -p relicario-cli -- generate --length 32

All must be green. The CLI integration suite covers the surface area touched by the split + git_run sweep; pay particular attention to basic_flows and edit_and_history for regression coverage.

Then push and open the PR:

git push -u origin feature/arch-followup-stream-b-cli-restructure
gh pr create --base main --head feature/arch-followup-stream-b-cli-restructure \
  --title "refactor(cli): split main.rs into commands/ + git_run helper + parsers→core (Stream B)" \
  --body "$(cat <<'EOF'
## Summary

Stream B of the architecture-review-followup. The single biggest readability lift in the bundle:

- **P1.2** — `crates/relicario-cli/src/main.rs` (2641 LOC) split into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs` + `prompt.rs` + `parse.rs`. `main.rs` keeps clap definitions + dispatcher.
- **P1.3** — `helpers::git_run(repo, args, context)` with stderr capture; ~16 duplicated bail sites swept.
- **P1.10** — `parse_month_year`, `base32_decode_lenient` (folded into a new `relicario_core::base32` module alongside DEV-A's P2 dedup), `guess_mime` migrated to `relicario-core`. Re-exported through `relicario-wasm` via `#[wasm_bindgen]` for future extension consumption.
- **CLI P2 cluster** — `build_*_item` helper compression, `Vault::after_manifest_change`, `ParamsFile` dedup, batched purge.

## Synthesis references

- `docs/superpowers/reviews/2026-05-04-architecture-review.md` — P1.2, P1.3, P1.10 + DEV-B's CLI P2 cluster + DEV-A's base32 dedup
- `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B

## New WASM surface (for future Stream C consumption)

The extension does NOT consume these in this round. A future plan should wire them up via `wasm.d.ts` regeneration:
- `parse_month_year` — for QR-import / smart-input flows
- `base32_encode_rfc4648` / `base32_decode_rfc4648` — for TOTP / future QR work
- `guess_mime_for_extension` — for attachment MIME detection

## Test plan

- [x] `cargo build` green
- [x] `cargo test` green (workspace-wide)
- [x] `cargo test -p relicario-core` green (new base32 module + parser tests)
- [x] `cargo test -p relicario-cli --test basic_flows` green (regression on the split)
- [x] `cargo test -p relicario-cli --test edit_and_history` green
- [x] `cargo test -p relicario-cli --test attachments` green
- [x] `cargo test -p relicario-cli --test settings` green
- [x] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green (new exports)
- [x] `cargo run -p relicario-cli -- --help` displays unchanged surface
- [x] `cargo run -p relicario-cli -- generate --length 32` smoke
- [x] git_run sweep: every git failure path now prints captured stderr + context
- [x] Steam alphabet at `item_types/totp.rs` untouched
EOF
)"

Emit a ## STATUS UPDATE with Status: REVIEW-READY and the PR URL.

First action

After reading the required inputs and setting up the worktree:

1. Call read_messages(for="dev-b") to drain any early inbox messages.
2. Emit a ## STATUS UPDATE confirming setup complete:

   ## STATUS UPDATE — DEV-B
   Time: <iso8601>
   Branch: feature/arch-followup-stream-b-cli-restructure
   Task: setup
   Status: DONE
   Last commit: <main HEAD sha + first line>
   Tests: N/A
   Notes: Worktree at /home/alee/Sources/relicario.arch-followup-stream-b. Synthesis + DEV-B/DEV-A notes + DEV-C boundary section absorbed. Awaiting Plan B at docs/superpowers/specs/2026-05-04-cli-restructure-design.md.
   

3. Wait for the PM's ## DIRECTIVE TO DEV-B with Action: PROCEED and the plan path.
4. Read the plan, then start Task 1 using superpowers:subagent-driven-development. Phase 1 is the main.rs split — finish it cleanly before any other phase.