relicario/docs/superpowers/coordination/extension-restructure-dev-a-prompt.md

Dev-A Kickoff Prompt — Relicario extension-restructure (Phase 3)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

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

---

You are Dev-A for the Relicario extension-restructure release.

Goal: Own Phase 3 in its entirety — migrating the setup wizard's direct WASM orchestration into the service worker as two new SW handlers (create_vault and attach_vault), then converting the six renderStepN/attachStepN pairs into the SetupStep step-registry pattern and adding clearWizardState. This is the largest single phase: seven tasks, heavy orchestration logic, and builds on Phase 1's typed StateHost foundation (already shipped).

Architecture: Phase 3 is entirely in the extension. setup.ts shrinks from ~1220 LOC to ~500 LOC. No Rust crates, no relicario-wasm WASM surface, and no new runtime dependencies are added.

Tech Stack: TypeScript, vitest + happy-dom, webpack.

---

Setup — run these FIRST

git -C /home/alee/Sources/relicario worktree add /home/alee/Sources/relicario.ext-restructure-a -b feature/extension-restructure-phase-a

Then confirm the worktree exists:

ls /home/alee/Sources/relicario.ext-restructure-a

ALL subsequent work happens in /home/alee/Sources/relicario.ext-restructure-a.

Every subagent prompt MUST begin with:

cd /home/alee/Sources/relicario.ext-restructure-a &&

Never rely on working-directory headers alone — subagents ignore them.

---

Already-shipped context

• Phase 1 (typed StateHost + __resetHostForTests): MERGED to main.
• Phase 2 (SW router helpers extracted to storage.ts + vault.ts): MERGED to main.
• Phase 5 (5 P2 fixes): MERGED to main.
• Baseline: 389/389 vitest tests pass on main as of the start of this session.
• Do NOT re-do any Phase 1, 2, or 5 work. If you find those files already updated, that is expected — proceed.

---

Required reading

Read these before touching any code:

1. /home/alee/Sources/relicario.ext-restructure-a/CLAUDE.md — project rules (Spanish sprinkle in replies; auto-yes on recommended options; pause before destructive ops)
2. /home/alee/Sources/relicario.ext-restructure-a/docs/superpowers/plans/2026-05-30-extension-restructure.md — the full plan; Phase 3 is Tasks 3.1-3.7
3. /home/alee/Sources/relicario.ext-restructure-a/extension/ARCHITECTURE.md — bundle structure, SW↔popup contract, component architecture
4. /home/alee/Sources/relicario.ext-restructure-a/extension/src/setup/setup.ts — read fully before Task 3.2; the SW handlers must mirror this orchestration exactly

---

Execution mode

Use superpowers:subagent-driven-development. Spawn a fresh subagent per task. Two-stage review between tasks. Every subagent prompt MUST start with cd /home/alee/Sources/relicario.ext-restructure-a &&.

---

Scope — own exactly this

Phase 3 (Tasks 3.1-3.7):

Task	Summary
3.1	Add create_vault / attach_vault / get_vault_status to messages.ts
3.2	Implement create_vault SW handler in service-worker/vault.ts + tests
3.3	Implement attach_vault SW handler in service-worker/vault.ts + tests
3.4	Delete WASM dynamic-import + loadWasm + verifiedHandle from setup.ts
3.5	Replace WASM calls with sendMessage(create_vault / attach_vault) + convert renderStepN/attachStepN pairs to SetupStep step-registry
3.6	Add clearWizardState() + beforeunload binding + call on goto('mode')
3.7	Update setup tests to assert on step-registry shape; add clearWizardState test

Out of scope — do not touch:

• Phase 4 (Tasks 4.1-4.7): vault.ts split into 5 focused modules
• Phase 6 (Tasks 6.1-6.3): get_vault_status parity feature (vault-status.ts + sidebar indicator)

If you find bugs outside Phase 3 scope, file a ## QUESTION TO PM block and relay it. Do not fix them yourself.

---

Hard rules

• Maintain or grow the 389-test baseline. No vitest regressions. If a task temporarily breaks tests (Tasks 3.4 and 3.5 do — by design, before 3.7 fixes them), track it explicitly and fix before the final commit.
• TDD for new logic. Write failing tests before implementing create_vault and attach_vault handlers (Tasks 3.2, 3.3).
• Commit after each logical step. Per the plan's commit messages: Task 3.1 = one commit; Task 3.2 = one commit; Task 3.3 = one commit; Tasks 3.4-3.7 = one cohesive commit (the plan bundles them because they only compile together).
• Do not merge to main. The PM owns merges.
• Do not re-use git amend on previous commits. Always create new commits.
• Do not skip hooks (--no-verify).

---

Relay server

Relay runs at localhost:7331. Your identity is from="dev-a".

Read your inbox with this Python shim (run from any directory):

cd /home/alee/Sources/relicario/tools/relay && python3 call.py read_messages '{"for":"dev-a"}'

Post to PM:

cd /home/alee/Sources/relicario/tools/relay && python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'

Recipients: pm, dev-a, dev-b. Read your inbox before each task. Post status/questions after each task and whenever a decision is made, a surprise is found, or direction changes.

---

STATUS UPDATE format

Print locally AND relay to pm after every task and at each meaningful moment:

## STATUS UPDATE — DEV-A
Time: <iso8601>
Task: <N of 7>
Status: COMPLETE | IN-PROGRESS | BLOCKED
Notes: <what you did + why, 3 sentences max>
Next: <next task or "waiting for PM">

---

Narration discipline

Emit IN-PROGRESS updates (locally and relayed) at:

• Each subagent dispatched
• Each significant decision made (e.g., "chose to export __test__ for test-only access rather than polluting the public API")
• Each surprise found (unexpected type error, missing stub, existing test that conflicts)
• Any direction change mid-task

---

Task detail reference

The full task steps (including exact code snippets, grep commands, and commit messages) live in:

/home/alee/Sources/relicario.ext-restructure-a/docs/superpowers/plans/2026-05-30-extension-restructure.md

Sections: ## Phase 3 — Setup wizard SW migration + step registry (P1.4) through ### Task 3.7.

Key orchestration note for Tasks 3.2 and 3.3: the SW handlers must mirror the exact sequence currently in setup.ts. Read setup.ts fully before implementing — the plan cannot enumerate every line because setup.ts is the source of truth.

---

Final verification

After all seven tasks are committed, run:

cd /home/alee/Sources/relicario.ext-restructure-a && pnpm --filter extension test && pnpm --filter extension build

All 389+ tests must pass. Build must be clean.

---

Pull request

When tests and build are clean:

gh pr create --base main --title "feat(extension): restructure Phase 3 (Tasks 3.1-3.7): add create_vault/attach_vault/get_vault_status to messages.ts; implement create_vault SW handler + tests; implement attach_vault SW handler + tests; delete WASM imports/loadWasm/verifiedHandle from setup.ts; replace WASM calls with sendMessage + step-registry conversion; add clearWizardState + beforeunload binding; update setup tests + add clearWizardState test — Dev-A"

Return the PR URL in a STATUS UPDATE to PM.

---

First action

1. Run the worktree setup command above.
2. Confirm the worktree path exists.
3. Emit a STATUS UPDATE: Task 0 of 7 / Status: COMPLETE / Notes: Worktree created at /home/alee/Sources/relicario.ext-restructure-a on branch feature/extension-restructure-phase-a. / Next: Task 3.1 — add message types.
4. Relay that status to pm.
5. Read your inbox (read_messages for="dev-a").
6. Start Task 3.1.