From f3d6c0a88071e6cb50c5a41b084b8dd25b2adb4b Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Fri, 8 May 2026 22:18:43 -0400 Subject: [PATCH] docs(coordination): cycle-2 CLI tail kickoff prompts (PM + Dev A/B/C) Partitions Plan B's remaining phases (3-8) across three cycle-2 streams once cycle-1 Stream A and Stream B's bundled Phase 1+2 PR have merged. Stream A picks up Phase 3 (prompt_or_flag + builder compression), Stream B owns Phases 4/5/6 (after_manifest_change, ParamsFile, batched purge), Stream C owns Phases 7/8 (parser migration to relicario-core + WASM exports). Plan C (extension restructure) is not in cycle 2. Each kickoff bakes in cycle-1 lessons: prefer single-line relay body content, avoid the f-string footgun in Python inbox-monitor scripts, narration discipline (IN-PROGRESS updates at meaningful in-flight moments, not just phase boundaries). The PM prompt also captures cycle-1 outcomes (commits/PRs landed, the 17 pre-existing extension test failures pattern, DEV-B's option-(b) git_run choice) so the new PM picks up cold without relay history. Co-Authored-By: Claude Opus 4.7 --- .../2026-05-09-cli-tail-coordinator.md | 64 ++++++ .../2026-05-09-cli-tail-dev-a-prompt.md | 185 ++++++++++++++++ .../2026-05-09-cli-tail-dev-b-prompt.md | 196 +++++++++++++++++ .../2026-05-09-cli-tail-dev-c-prompt.md | 205 ++++++++++++++++++ .../2026-05-09-cli-tail-pm-prompt.md | 145 +++++++++++++ 5 files changed, 795 insertions(+) create mode 100644 docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md create mode 100644 docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md create mode 100644 docs/superpowers/coordination/2026-05-09-cli-tail-dev-b-prompt.md create mode 100644 docs/superpowers/coordination/2026-05-09-cli-tail-dev-c-prompt.md create mode 100644 docs/superpowers/coordination/2026-05-09-cli-tail-pm-prompt.md diff --git a/docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md b/docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md new file mode 100644 index 0000000..9abfa7d --- /dev/null +++ b/docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md @@ -0,0 +1,64 @@ +# CLI Tail — Cycle 2 Coordinator + +**Date:** 2026-05-09 +**Status:** Draft (launches once cycle-1 prerequisites land) +**Theme:** parallelize the post-split tail of Plan B (the CLI restructure) across three independent streams. Plan B's eight phases are already defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`; this coordinator only partitions the remaining phases across cycle-2 streams and records the cross-stream contracts. + +## What this is + +The cycle-1 four-agent run (`2026-05-04-arch-followup-*`) ships: + +- **Stream A** — Plan A (security + docs polish): `impl Drop for SessionHandle`, JS swallow removal, `recovery_qr.rs` docs, `start.sh` fourth-window. Independent of B and C. +- **Stream B** — Plan B Phases 1 + 2 only (mechanical `main.rs` split + `helpers::git_run` + 16-site sweep). Stops after Phase 2 per a 2026-05-09 user-driven RESCOPE directive. +- **Stream C** — Plan C (extension restructure). Did not launch in cycle 1 (DEV-C never acked); remains pending and is *not* picked up by cycle 2 (still its own multi-week effort, separate kickoff). + +The remaining six Plan B phases (3 through 8) are partitioned across three cycle-2 streams below. Each cycle-2 stream is independent of the other two once cycle-1 Stream B (Phase 1 + 2) has merged to `main`. + +## Pre-launch checklist (cycle 2 cannot open until all green) + +- [ ] Cycle-1 Stream A merged to `main` +- [ ] Cycle-1 Stream B PR (Phase 1 + 2 bundle) merged to `main` +- [ ] Working tree clean on `main`; `git pull` reflects both merges +- [ ] All cycle-1 worktrees torn down (`git worktree remove ../relicario.arch-followup-stream-a` and `*-stream-b`); cycle-1 branches deleted locally if requested +- [ ] Relay server still running on `localhost:7331` (check `ss -ltn 'sport = :7331'`) +- [ ] Cycle-2 kickoff prompts present in `docs/superpowers/coordination/2026-05-09-cli-tail-{pm,dev-a,dev-b,dev-c}-prompt.md` + +## Stream partition + +| Stream | Branch | Worktree | Plan B phases | Theme | +|---|---|---|---|---| +| A | `feature/cli-tail-stream-a-prompt-helpers` | `/home/alee/Sources/relicario.cli-tail-stream-a` | Phase 3 | `prompt_or_flag` + `build_*_item` compression | +| B | `feature/cli-tail-stream-b-session-manifest` | `/home/alee/Sources/relicario.cli-tail-stream-b` | Phases 4, 5, 6 | `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge | +| C | `feature/cli-tail-stream-c-core-wasm-seam` | `/home/alee/Sources/relicario.cli-tail-stream-c` | Phases 7, 8 | parser migration to `relicario-core` + base32 dedup + WASM exports | + +Phases reference the canonical definitions in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`. Devs do NOT redesign — they execute against that spec. + +## Cross-stream dependencies (cycle 2) + +- **Stream A and Stream B**: both touch `crates/relicario-cli/src/commands/*.rs` files but in disjoint ways. Stream A modifies `commands/add.rs` (the seven `build_*_item` builders). Stream B modifies `commands/init.rs` (`ParamsFile`), `commands/trash.rs` (batched purge), and seven manifest-mutation sites scattered across `commands/{add,edit,trash,attach,settings,import}.rs`. Conflict surface is `commands/add.rs` (A modifies builders; B modifies the `after_manifest_change` callsite). Whoever opens their PR second rebases. +- **Stream B internal sequencing**: Phase 6 (batched purge) depends on Phase 4 (`after_manifest_change` wrapper) — Phase 6's commit message logic uses the wrapper. Phase 5 (`ParamsFile`) is independent of 4 and 6 within Stream B; can ship first, last, or middle. +- **Stream C**: touches `crates/relicario-core/`, `crates/relicario-wasm/`, and `extension/src/wasm.d.ts` only. Zero overlap with Streams A and B. Internal sequencing: Phase 7 (parser migration to core) before Phase 8 (WASM exports + `wasm.d.ts` mirror). +- **No cross-stream interface contracts.** All three plans were finalized in cycle 1; the partition does not introduce new contracts. + +## Pre-merge checklist (per cycle-2 stream) + +Same as cycle 1, plus a narration check: + +- [ ] Stream's owned phases all complete per Plan B's "Done criteria" +- [ ] `cargo test --workspace` green on the stream's worktree +- [ ] `cargo clippy --workspace` silent +- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean (always, but Stream C in particular) +- [ ] No regression in CLI behaviour — existing `crates/relicario-cli/tests/*` tests pass without modification +- [ ] Narration discipline observed — STATUS UPDATEs include in-flight beats, not just phase boundaries +- [ ] PR description cross-references the corresponding Plan B phase numbers + +## Out of scope for cycle 2 + +- Plan C (extension restructure) — multi-week effort, scheduled separately when DEV-C bandwidth available +- The Plan B `helpers::git_run` itself (shipped in cycle 1 Stream B) +- The cycle-1 P3 nits explicitly out-of-scope in Plan B +- The eight "Open architectural decisions" from the synthesis + +## Tag + +No release tag for cycle 2. Same as the cycle-1 architecture-review followup train — these are structural-cleanup bundles, not versioned releases. Each stream merges via `gh pr merge --merge` (preserve history; no squash per project convention). diff --git a/docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md new file mode 100644 index 0000000..b73dba1 --- /dev/null +++ b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md @@ -0,0 +1,185 @@ +# Dev A Kickoff Prompt — CLI Tail (Cycle 2) Stream A + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Stream A of the CLI-tail cycle-2 release. + +Stream A is **Plan B Phase 3** — `prompt_or_flag` helper plus the seven `build_*_item` builder compression in the CLI. Single phase, S-M effort. The phase is defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` under "Phase 3 — `prompt_or_flag` and `build_*_item` compression". Cycle 1 already shipped the mechanical `main.rs` split (Phase 1) and the `helpers::git_run` sweep (Phase 2), so the file tree under `crates/relicario-cli/src/commands/` and `prompt.rs` is in place — your job is to add the helper to `prompt.rs` and refactor the seven builders in `commands/add.rs`. + +A PM in another terminal coordinates you with Dev-B (session/manifest discipline — Phases 4, 5, 6) and Dev-C (parser migration + WASM seam — Phases 7, 8). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario.cli-tail-stream-a -b feature/cli-tail-stream-a-prompt-helpers +cd ../relicario.cli-tail-stream-a +pwd # should print /home/alee/Sources/relicario.cli-tail-stream-a +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-a`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-a` so subagents don't accidentally commit to main. This is non-negotiable. + +Today: 2026-05-09. Project rules in `CLAUDE.md` apply. + +## 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-a"` +- `read_messages(for)` — drain your inbox; call with `for="dev-a"` 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-a")`. After emitting any status/question block: `post_message(from="dev-a", 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-a","to":"pm","kind":"status","body":"..."}' +python3 call.py read_messages '{"for":"dev-a"}' +``` + +**Cycle-1 lessons baked in (read once):** + +- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only. +- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 dev-a and dev-b both hit this; documenting once here. + +## Required reading (in order) + +1. `CLAUDE.md` — project rules +2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phase 3 only +3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (your scope is **Phase 3 only**; read the whole plan for context, but execute Phase 3) +4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only — your work is fully captured in Plan B) +5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's notes; the relevant section is the `build_*_item` discussion (line-level context for the seven builders the synthesis abbreviates) + +## Execution mode + +Use **subagent-driven-development** (per `CLAUDE.md` memory default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per sub-step, two-stage review. + +**Every subagent prompt MUST start with**: + +``` +cd /home/alee/Sources/relicario.cli-tail-stream-a +``` + +…before any other instruction. Non-negotiable per project memory. + +## Your scope and boundaries + +**In scope:** Plan B Phase 3 — adding `prompt_or_flag` (and `prompt_or_flag_optional`) to `crates/relicario-cli/src/prompt.rs`, then refactoring the seven `build_*_item` functions in `crates/relicario-cli/src/commands/add.rs` to use the helper. Per-type bodies should shrink by ~30%. + +**Out of scope:** +- Phases 4, 5, 6 (Dev-B owns) — `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge +- Phases 7, 8 (Dev-C owns) — parser migration to `relicario-core`, base32 dedup, WASM exports +- Anything outside Plan B's Phase 3 definition. If you trip over an out-of-scope issue, file a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- Do not change the CLI's external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification. +- 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 protocol + +You are one of four terminals. The user runs all four; the PM in another terminal coordinates you. + +**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: + +- When you dispatch a subagent (so the user sees what's running) +- When a subagent returns with a decision worth flagging (an unexpected finding, a trade-off taken, a surprise) +- When a sub-task completes (e.g. `prompt_or_flag` helper landed; first builder converted) +- When you change direction or hit something unexpected +- When you start a new sub-step + +The `Notes` field should narrate WHAT happened and WHY — not just "Phase 3 done". Three sentences max. Examples of useful: "subagent reported `build_login_item` already takes Result-wrapped fields, so the conversion is just chain-flattening"; "found one builder uses `prompt_secret`, kept it on raw `prompt_secret` since `prompt_or_flag` doesn't handle the no-echo case." Examples of NOT useful: "builder converted" with no context; "tests pass" with no count. + +Print every STATUS UPDATE locally before/after sending it so the user reads it in your own terminal. + +**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-a")` first, then post via `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")` and also print here. Format: + +``` +## STATUS UPDATE — DEV-A +Time: +Branch: feature/cli-tail-stream-a-prompt-helpers +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**When you need PM input mid-task**: post via `post_message(kind="question")`: + +``` +## QUESTION TO PM — DEV-A +Time: +Context: +Options: +Recommended: +Blocker: yes | no +``` + +**You'll receive**: `## DIRECTIVE TO DEV-A` blocks from the PM. + +## Authority within Phase 3 + +You don't need PM permission to: + +- Execute sub-steps per Plan B's Phase 3 +- Make implementation decisions consistent with Plan B +- Write tests, refactor your own code, fix bugs you introduce +- Push commits to your feature branch + +You **do** escalate when: + +- A scope question outside Plan B Phase 3 +- A test you can't make green after honest debugging +- A discovered bug not in Plan B +- Anything destructive (per `CLAUDE.md`) +- Before opening the PR for review + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +cd /home/alee/Sources/relicario.cli-tail-stream-a +cargo test --workspace +cargo clippy --workspace +cargo build -p relicario-wasm --target wasm32-unknown-unknown +``` + +All three must be green / clean. Then push and open the PR: + +```bash +git push -u origin feature/cli-tail-stream-a-prompt-helpers +gh pr create --base main --head feature/cli-tail-stream-a-prompt-helpers --title "refactor(cli): prompt_or_flag helper + build_*_item compression (Plan B Phase 3)" --body "$(cat <<'EOF' +## Summary +- Adds `prompt_or_flag` and `prompt_or_flag_optional` to `crates/relicario-cli/src/prompt.rs` +- Refactors the seven `build_*_item` functions in `crates/relicario-cli/src/commands/add.rs` to use the helper +- Per-type bodies shrink by ~30%; existing CLI integration tests pass without modification + +## Plan B Phase 3 +Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phase 3. +See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition. + +## Test plan +- [x] cargo test --workspace +- [x] cargo clippy --workspace +- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown +- [x] Existing crates/relicario-cli/tests/* pass without modification + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL. + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-a-prompt-helpers`), then start Phase 3 sub-step 1 (add `prompt_or_flag` to `prompt.rs`). diff --git a/docs/superpowers/coordination/2026-05-09-cli-tail-dev-b-prompt.md b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-b-prompt.md new file mode 100644 index 0000000..1417fd1 --- /dev/null +++ b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-b-prompt.md @@ -0,0 +1,196 @@ +# Dev B Kickoff Prompt — CLI Tail (Cycle 2) Stream B + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Stream B of the CLI-tail cycle-2 release. + +Stream B is **Plan B Phases 4, 5, 6** — session/manifest discipline. Three phases, S-M effort each, total mid-day to multi-day: + +- **Phase 4** — `Vault::after_manifest_change(&self, manifest: &Manifest)` wrapper that funnels the seven manifest-mutation sites in `commands/{add,edit,trash,attach,settings,import}.rs` through one `save_manifest + groups-cache write` path. Marks `save_manifest` as `pub(crate)` (or renames it `save_manifest_raw`) so callers must use the wrapper. +- **Phase 5** — Single canonical `ParamsFile` in `crates/relicario-cli/src/session.rs`, replacing the two-definition split between `commands/init.rs` (write side) and `session.rs:114` (read side). Adds `Serialize` + `Deserialize`, `for_new_vault` constructor, `into_kdf_params` inversion. On-disk JSON format must round-trip with current `params.json` files. +- **Phase 6** — Batched purge in `cmd_purge` and `cmd_trash_empty`. Renames `purge_item` to `purge_item_filesystem` (filesystem mutation only); the callers accumulate paths and run a single `git_run(...["rm", "-rf", "--ignore-unmatch", paths...])` plus `git_run(...["add", "manifest.enc"])` plus one `git_run(...["commit"])` per batch. A 50-item `trash empty` should fire 3 git invocations total, not 150. + +The phases are defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` under "Phase 4", "Phase 5", "Phase 6". Internal sequencing: Phase 4 before Phase 6 (Phase 6 uses `after_manifest_change`); Phase 5 is independent of 4 and 6. + +A PM in another terminal coordinates you with Dev-A (Plan B Phase 3) and Dev-C (Plan B Phases 7, 8). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario.cli-tail-stream-b -b feature/cli-tail-stream-b-session-manifest +cd ../relicario.cli-tail-stream-b +pwd # should print /home/alee/Sources/relicario.cli-tail-stream-b +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-b`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-b` so subagents don't accidentally commit to main. Non-negotiable. + +Today: 2026-05-09. Project rules in `CLAUDE.md` apply. + +## 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: + +```bash +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"}' +``` + +**Cycle-1 lessons baked in (read once):** + +- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only. +- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 dev-a and dev-b both hit this; documenting once here. + +## Required reading (in order) + +1. `CLAUDE.md` — project rules +2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phases 4, 5, 6 only +3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (read the whole plan; execute Phases 4, 5, 6) +4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only) +5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes; the relevant sections are `refresh_groups_cache` discipline, `ParamsFile` dedup, batched purge + +## Execution mode + +Use **subagent-driven-development**. Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases. + +**Every subagent prompt MUST start with**: + +``` +cd /home/alee/Sources/relicario.cli-tail-stream-b +``` + +…before any other instruction. + +## Your scope and boundaries + +**In scope:** Plan B Phases 4, 5, 6. + +**Out of scope:** +- Phase 3 (Dev-A owns) — `prompt_or_flag` + `build_*_item` compression +- Phases 7, 8 (Dev-C owns) — parser migration to `relicario-core`, base32 dedup, WASM exports +- Anything outside Plan B Phases 4-6. If you trip over an out-of-scope issue, file a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- Phase 5 must round-trip with existing on-disk `params.json` — write a fixture-string test that reads a known-current params.json and asserts the canonical struct parses it identically. On-disk format change would break existing vaults. +- Do not change CLI external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification. +- The `groups.cache` plaintext "failures silently swallowed" doc-comment from current `helpers.rs:90-93` must be preserved on the new `after_manifest_change` wrapper. Don't change the policy. +- 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. + +**Internal phase sequencing (within Stream B):** +- Phase 5 (`ParamsFile`) is independent — ship first to get it out of the way, OR last for diff-locality with the session-touching Phase 4. Either is fine; pick whichever reviews more cleanly. +- Phase 4 (`after_manifest_change`) before Phase 6 (`batched purge`). Phase 6's commit logic relies on the wrapper. + +## Coordination protocol + +You are one of four terminals. The PM coordinates you with Dev-A and Dev-C. + +**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: + +- When you dispatch a subagent +- When a subagent returns with a decision worth flagging (a found-but-unexpected coupling, a trade-off taken) +- When a sub-task completes (e.g. `after_manifest_change` wrapper landed; first manifest-mutation site converted; `ParamsFile` round-trip test green) +- When you change direction or hit something unexpected +- When you start a new phase + +The `Notes` field should narrate WHAT and WHY. Three sentences max. Examples of useful: "Phase 5 fixture test caught that `format_version` was previously emitted but never read; preserved the field but kept the read side tolerant"; "found one manifest-mutation site in `commands/import.rs` that did NOT call `refresh_groups_cache` historically (DEV-B notes flagged 7 sites; this is an 8th — surfacing as a question)." Print every STATUS UPDATE locally too. + +**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-b")`, then post and print using: + +``` +## STATUS UPDATE — DEV-B +Time: +Branch: feature/cli-tail-stream-b-session-manifest +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**For PM input mid-task**: + +``` +## QUESTION TO PM — DEV-B +Time: +Context: +Options: +Recommended: +Blocker: yes | no +``` + +## Authority within Phases 4-6 + +You don't need PM permission to: + +- Execute sub-steps per Plan B's Phases 4, 5, 6 +- Make implementation decisions consistent with Plan B +- Write tests, refactor your own code, fix bugs you introduce +- Push commits to your feature branch + +You **do** escalate when: + +- A scope question outside Plan B Phases 4-6 +- A test you can't make green after honest debugging +- A discovered bug not in Plan B +- Anything destructive (per `CLAUDE.md`) +- Before opening the PR for review +- If you find an unexpected manifest-mutation site beyond the seven DEV-B notes flagged (likely surfaces in Phase 4) + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +cd /home/alee/Sources/relicario.cli-tail-stream-b +cargo test --workspace +cargo clippy --workspace +cargo build -p relicario-wasm --target wasm32-unknown-unknown +``` + +All three must be green / clean. Then push and open the PR: + +```bash +git push -u origin feature/cli-tail-stream-b-session-manifest +gh pr create --base main --head feature/cli-tail-stream-b-session-manifest --title "refactor(cli): session/manifest discipline (Plan B Phases 4, 5, 6)" --body "$(cat <<'EOF' +## Summary +- Phase 4 — `Vault::after_manifest_change` wrapper funnels seven manifest-mutation sites; `save_manifest` made `pub(crate)` so callers can't bypass the wrapper +- Phase 5 — Single canonical `ParamsFile` in `session.rs` replaces the two-definition split; on-disk JSON round-trips with existing vaults (fixture-string test) +- Phase 6 — Batched purge: a 50-item `trash empty` now fires 3 git invocations instead of 150 + +## Plan B Phases 4-6 +Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 4, 5, 6. +See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition. + +## Test plan +- [x] cargo test --workspace +- [x] cargo clippy --workspace +- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown +- [x] params.json round-trip test against existing on-disk format +- [x] `trash empty` with N items produces 1 commit (regression invariant) +- [x] Existing crates/relicario-cli/tests/* pass without modification + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL. + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-b-session-manifest`), then start Phase 4 (or Phase 5 if you prefer to ship the independent piece first — call it out in the status update). diff --git a/docs/superpowers/coordination/2026-05-09-cli-tail-dev-c-prompt.md b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-c-prompt.md new file mode 100644 index 0000000..28436fe --- /dev/null +++ b/docs/superpowers/coordination/2026-05-09-cli-tail-dev-c-prompt.md @@ -0,0 +1,205 @@ +# Dev C Kickoff Prompt — CLI Tail (Cycle 2) Stream C + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Stream C of the CLI-tail cycle-2 release. + +Stream C is **Plan B Phases 7 and 8** — the parser migration to `relicario-core` plus the WASM seam. Two phases, M effort: + +- **Phase 7** — Migrate `parse_month_year`, `base32_decode_lenient`, `guess_mime` from `crates/relicario-cli/src/parse.rs` into `relicario-core` (`MonthYear::parse` on `time.rs`, new `pub(crate) mod base32` with `encode_rfc4648` / `decode_rfc4648_lenient`, new `mime::guess_for_extension`). Pair with DEV-A's P2 base32 dedup: extract the inline `base32_encode` from `crates/relicario-core/src/item.rs:255-275` and `decode_base32_totp` from `crates/relicario-core/src/import_lastpass.rs:202-220` into the new shared module. Steam's `STEAM_ALPHABET` at `item_types/totp.rs:13` stays untouched (with a neighbour comment). The CLI's `parse.rs` becomes a thin re-export shim — no callsite changes in cycle 2. +- **Phase 8** — `#[wasm_bindgen]` exports for the three migrated parsers (`parse_month_year`, `base32_decode_lenient`, `guess_mime`) plus the matching declarations in `extension/src/wasm.d.ts`. snake_case JS naming consistent with every existing export. Plan C (extension restructure) does NOT consume these this round — the seam ships in cycle 2; consumption is a future plan. + +Phase definitions are canonical in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 7 and 8. Internal sequencing: Phase 7 before Phase 8. + +A PM in another terminal coordinates you with Dev-A (Plan B Phase 3) and Dev-B (Plan B Phases 4, 5, 6). With the relay server running, you communicate via `post_message` / `read_messages` directly. + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario.cli-tail-stream-c -b feature/cli-tail-stream-c-core-wasm-seam +cd ../relicario.cli-tail-stream-c +pwd # should print /home/alee/Sources/relicario.cli-tail-stream-c +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-c`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-c` so subagents don't accidentally commit to main. Non-negotiable. + +Today: 2026-05-09. Project rules in `CLAUDE.md` apply. + +## 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-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 task: `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"}' +``` + +**Cycle-1 lessons baked in (read once):** + +- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only. +- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 DEV-A and DEV-B both hit this; documenting once here so cycle-2 DEV-C does not. + +## Required reading (in order) + +1. `CLAUDE.md` — project rules +2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phases 7 + 8 only +3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (read the whole plan; execute Phases 7 and 8) +4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only — your work is fully captured in Plan B) +5. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — DEV-A's notes; the relevant section is the P2 "three base32 implementations" finding (the dedup that pairs with your Phase 7) +6. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's notes; the relevant section is the parser-migration P2 (line-level context for `parse_month_year`, `base32_decode_lenient`, `guess_mime`) +7. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — read **only** the "Boundary notes for DEV-B" section (cross-boundary contracts — `wasm.d.ts` is hand-maintained; every change must mirror; BigInt typing care for `attachment_encrypt`-style paths, but your three new exports take only `&str` and return primitives so they avoid that class) + +## Execution mode + +Use **subagent-driven-development**. Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review. + +**Every subagent prompt MUST start with**: + +``` +cd /home/alee/Sources/relicario.cli-tail-stream-c +``` + +…before any other instruction. + +## Your scope and boundaries + +**In scope:** Plan B Phases 7 and 8 — parser migration to `relicario-core` (paired with DEV-A P2 base32 dedup), then WASM exports + `extension/src/wasm.d.ts` mirror. + +**Out of scope:** +- Phase 3 (Dev-A owns) — `prompt_or_flag` + builder compression +- Phases 4, 5, 6 (Dev-B owns) — session/manifest discipline +- Plan C (extension restructure) — consumption of your new WASM exports is explicitly deferred to a future plan; you ship the seam, you do NOT wire SW message handlers in the extension. +- Anything outside Plan B Phases 7-8. If you trip over an out-of-scope issue (e.g. a fourth base32 implementation surfaces; a parser the CLI uses that wasn't in Plan B's three), file a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- Steam's `STEAM_ALPHABET` at `crates/relicario-core/src/item_types/totp.rs:13` is intentionally non-RFC-4648; do NOT consolidate it into the new shared base32 module. Add a neighbour comment: `// not RFC 4648 — Steam Guard's de-ambiguated alphabet; see crate::base32 for the standard impl.` +- The CLI's `parse.rs` becomes a thin re-export shim — keep callsite imports unchanged in cycle 2 (no caller-side import churn). +- WASM JS naming stays snake_case for the three new exports — consistent with every existing `#[wasm_bindgen]` export. Do NOT introduce camelCase here; that decision is explicitly deferred per Plan B. +- `extension/src/wasm.d.ts` mirror lands in the same commit as the Rust `#[wasm_bindgen]` additions. Both sides updated together; no half-state. +- Do not change CLI external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification. +- 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. + +**Internal phase sequencing (within Stream C):** +- Phase 7 (parser migration to core + base32 dedup) before Phase 8 (WASM exports). Phase 8 imports from the new core paths; Phase 7 must compile clean first. + +## Coordination protocol + +You are one of four terminals. The PM coordinates you with Dev-A and Dev-B. + +**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: + +- When you dispatch a subagent +- When a subagent returns with a decision worth flagging (an unexpected coupling, an alternative API shape considered, a found-but-flagged out-of-scope issue) +- When a sub-task completes (e.g. base32 module landed; `MonthYear::parse` integrated; first WASM export wired) +- When you change direction or hit something unexpected +- When you start a new phase + +The `Notes` field should narrate WHAT and WHY. Three sentences max. Examples of useful: "subagent surfaced a fourth base32 callsite in `crates/relicario-core/src/manifest.rs:??`; not in DEV-A P2's flagged list — escalating as a question"; "kept `MonthYear::parse` returning `Result` rather than touching `MonthYear::new`'s `&'static str` per Plan B's recommendation; `new`-to-`RelicarioError` is DEV-A's separate P3"; "WASM exports compile clean; `wasm.d.ts` mirror passes `tsc --noEmit` in `extension/`." Print every STATUS UPDATE locally too. + +**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-c")` first, then post via `post_message` and print here. Format: + +``` +## STATUS UPDATE — DEV-C +Time: +Branch: feature/cli-tail-stream-c-core-wasm-seam +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**For PM input mid-task**: + +``` +## QUESTION TO PM — DEV-C +Time: +Context: +Options: +Recommended: +Blocker: yes | no +``` + +## Authority within Phases 7-8 + +You don't need PM permission to: + +- Execute sub-steps per Plan B's Phases 7 and 8 +- Make implementation decisions consistent with Plan B +- Write tests, refactor your own code, fix bugs you introduce +- Push commits to your feature branch + +You **do** escalate when: + +- A scope question outside Plan B Phases 7-8 +- A test you can't make green after honest debugging +- A discovered bug not in Plan B +- A fourth base32 implementation or a parser surfaces beyond DEV-A P2 + Plan B's three +- Anything destructive (per `CLAUDE.md`) +- Before opening the PR for review + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +cd /home/alee/Sources/relicario.cli-tail-stream-c +cargo test --workspace +cargo clippy --workspace +cargo build -p relicario-wasm --target wasm32-unknown-unknown +cd extension && npm run test # verify wasm.d.ts mirror compiles against TS callers +``` + +All four must be green / clean. Then push and open the PR: + +```bash +cd /home/alee/Sources/relicario.cli-tail-stream-c +git push -u origin feature/cli-tail-stream-c-core-wasm-seam +gh pr create --base main --head feature/cli-tail-stream-c-core-wasm-seam --title "refactor(core,wasm): migrate parsers + base32 dedup + WASM exports (Plan B Phases 7, 8)" --body "$(cat <<'EOF' +## Summary +- Phase 7 — `parse_month_year`, `base32_decode_lenient`, `guess_mime` migrated from CLI to `relicario-core` (`MonthYear::parse`, new `pub(crate) mod base32`, new `mime::guess_for_extension`); base32 dedup folds `crates/relicario-core/src/item.rs:255-275` and `import_lastpass.rs:202-220` into the new shared module (Steam alphabet untouched per neighbour comment) +- Phase 8 — `#[wasm_bindgen]` exports for the three migrated parsers; `extension/src/wasm.d.ts` mirror updated in the same commit; snake_case JS naming consistent with existing exports +- The CLI's `parse.rs` is a thin re-export shim; existing CLI callsites unchanged + +## Plan B Phases 7-8 +Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 7 and 8. +See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition. + +## Test plan +- [x] cargo test --workspace +- [x] cargo clippy --workspace +- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown +- [x] cd extension && npm run test (verifies wasm.d.ts compiles) +- [x] Existing crates/relicario-cli/tests/* pass without modification +- [x] Existing crates/relicario-core/tests/* pass without modification + +## Out of scope (deferred) +- Extension consumption of the new WASM exports — Plan C territory; no SW message handlers wired in this PR +- camelCase JS naming for the three new exports — explicitly snake_case per Plan B; the camelCase decision is its own future plan + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL. + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-c-core-wasm-seam`), then start Phase 7 sub-step 1 (create `crates/relicario-core/src/base32.rs` with the unified `encode_rfc4648` / `decode_rfc4648_lenient` shape). diff --git a/docs/superpowers/coordination/2026-05-09-cli-tail-pm-prompt.md b/docs/superpowers/coordination/2026-05-09-cli-tail-pm-prompt.md new file mode 100644 index 0000000..a8af657 --- /dev/null +++ b/docs/superpowers/coordination/2026-05-09-cli-tail-pm-prompt.md @@ -0,0 +1,145 @@ +# PM Kickoff Prompt — CLI Tail (Cycle 2) + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are the **project manager** for the CLI-tail cycle-2 release. Three senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all four terminals. + +This release has no version tag — it's the second cycle of the architecture-review structural-cleanup bundle. Cycle 1 shipped Plan A (security + docs polish) and Plan B Phases 1 + 2 (mechanical `main.rs` split + `git_run` helper). Cycle 2 partitions the remaining six Plan B phases (3 through 8) across three independent streams. Plan C (extension restructure) is *not* in cycle 2 — it stays pending until DEV-C bandwidth is available, on its own kickoff. + +## Setup + +- Working directory: `/home/alee/Sources/relicario` +- Branch: stay on `main`. Do not check out feature branches. +- Today: 2026-05-09. Project rules in `CLAUDE.md` apply (Spanish flourish in chat replies only, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking, default to subagent-driven execution, force-cd subagents into their worktree). + +**Pre-launch state assumed:** cycle-1 Stream A merged, cycle-1 Stream B PR (Phase 1 + 2) merged, working tree clean on `main`, relay server alive on `localhost:7331`. Verify with `git log --oneline -5` and `ss -ltn 'sport = :7331'` before sending opening directives. If either is not in place, surface to the user before proceeding. + +## Cycle 1 outcomes (read for context — your context starts cold) + +The cycle-1 four-agent run (`docs/superpowers/coordination/2026-05-04-arch-followup-*-prompt.md`) produced: + +- **Stream A (security + docs polish)** merged to `main`. Key commits: `1e858e1` impl Drop for SessionHandle, `03d0781` SW free() unswallow, `229e483` recovery_qr.rs documentation, `f8296fa` rustdoc warning fix on a private intra-doc link, `0c9387f` start.sh fourth-window. Plan A complete. +- **Stream B (CLI restructure Phases 1 + 2 only)** merged to `main` per a 2026-05-09 RESCOPE directive that halted Plan B at Phase 2 to enable cycle-2 parallelization. Key commits: `97c8f99` 15-site git_run sweep, `f3cdbed` git_run helper. `main.rs` shipped at 509 LOC (vs spec's ≤500); the 9-LOC overshoot is `#[arg(...)]` attribute density on 9 sub-enums and was accepted at merge — substance criterion (clap surface + dispatch + 2 shim families only) was met. DEV-B chose Plan B's option (b) for `git_run` (capture stderr + replay on failure) over option (a) (terminal-aware streaming). +- **Stream C (extension restructure)** did NOT launch in cycle 1 (cycle-1 DEV-C never acked). Plan C remains pending and is *not* part of cycle 2 — it is a multi-week effort scheduled separately on its own kickoff. +- **17 pre-existing extension test failures** on the kickoff baseline `bd3d53f` were documented in cycle-1 Stream A's PR. They sit in `extension/src/{service-worker,popup}/...` (devices/router/settings clusters) and pre-date the architecture review. Treat as the regression baseline: any cycle-2 red test outside this 17-failure cluster is a new regression and a stream's responsibility. + +## Lessons learned (bake into your coordination) + +Cycle 1 surfaced three operational gotchas worth pre-empting: + +- **Prefer single-line relay message bodies.** Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals in body content. Compose `body` fields as a single line with sentences separated by periods; use ` -- ` for stronger breaks. The relay itself accepts multi-line bodies, but the consuming dev's monitor may not. +- **Python f-string footgun in inbox-monitor scripts.** If a dev reports a `SyntaxError: unexpected character after line continuation character`, their polling script likely uses `print(f"... {m.get(\"from\")} ...")` — Python f-strings cannot contain backslash-escaped quotes inside brace expressions. Fix is single quotes: `m.get('from')`. +- **Narration policy is non-negotiable.** Cycle 1 added it mid-run; cycle 2 has it baked into every kickoff. Devs MUST emit `Status: IN-PROGRESS` updates at meaningful in-flight moments (subagent dispatch, surprise findings, sub-task complete, phase start), not just at phase boundaries. You MUST narrate to the user in plain prose between tool calls — when a STATUS UPDATE lands, summarize it for the user before deciding; when you send a directive, state the rationale; when you dispatch a subagent, say so. Enforce both. + +## Required reading (in order) + +1. `CLAUDE.md` — project rules +2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — **partition spec for this cycle. The canonical source for who owns what.** +3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (phase definitions). Cycle 2 executes Phases 3 through 8. +4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — original synthesis (read the P-tags Plan B addresses: P1.2, P1.3, P1.10, plus the four CLI P2s) +5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes (line-level context the synthesis abbreviates) + +You do NOT need to read Plans A or C in detail — they're out of cycle-2 scope. Skim the partition coordinator's "Cross-stream dependencies" section so you know what conflicts to watch for. + +## Stream overview (from coordinator) + +| Stream | Branch | Owner | Plan B phases | Theme | +|---|---|---|---|---| +| A | `feature/cli-tail-stream-a-prompt-helpers` | DEV-A | Phase 3 | `prompt_or_flag` + `build_*_item` compression | +| B | `feature/cli-tail-stream-b-session-manifest` | DEV-B | Phases 4, 5, 6 | `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge | +| C | `feature/cli-tail-stream-c-core-wasm-seam` | DEV-C | Phases 7, 8 | parser migration to core + base32 dedup + WASM exports | + +**No interface contracts between streams.** All three are independent once the cycle-1 PRs have merged. Conflict surface: `commands/add.rs` (A modifies builders; B modifies a manifest-mutation callsite). Whichever stream opens its PR second rebases. + +## Your authority + +- Approve or deny scope changes from devs +- Review and merge PRs from each stream's feature branch +- Edit `docs/`, `CLAUDE.md`, or other doc artifacts as needed; do not write feature code + +## Your boundaries + +- Don't write feature code yourself. Edits to docs / `CLAUDE.md` are fine. +- Don't deviate from Plan B's phase definitions without user approval. +- Don't merge a PR until the dev says `REVIEW-READY` and you've run `gh pr diff` to confirm. +- Don't tag — no tag planned for this cycle. +- Project rule: ask the user before any git-destructive op (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`). + +## 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; `from` is always `"pm"` for you +- `read_messages(for)` — drain your inbox; call with `for="pm"` before each action +- `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. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`. + +**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim: + +```bash +cd /home/alee/Sources/relicario/tools/relay +python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}' +python3 call.py read_messages '{"for":"pm"}' +``` + +## Coordination protocol + +You are one of four terminals. Use `post_message` / `read_messages` directly. Call `read_messages(for="pm")` before every action. + +**Narrate to the user in plain prose between tool calls.** The user's only window into the release is this terminal output. Don't emit DIRECTIVE blocks silently. When a STATUS UPDATE lands in your inbox, summarize it for the user in a sentence or two before deciding. When you send a directive, state the rationale briefly so the user sees the reasoning, not just the verdict. When you dispatch a subagent (e.g. for plan review or coherence pass), say so. One or two sentences per beat is plenty — the goal is for the user to read this terminal top-to-bottom and understand the release as a story. + +**You receive:** `## STATUS UPDATE — DEV-` or `## QUESTION TO PM — DEV-` blocks. + +**You emit:** a `## DIRECTIVE TO DEV-` block — post it via `post_message` and also print it here so the user can see it. Format: + +``` +## DIRECTIVE TO DEV- +Time: +Action: PROCEED | HOLD | RESCOPE | REVIEW-COMPLETE | MERGE-APPROVED +Notes: +Next: +``` + +When asked "status?" by the user, give a current rollup: + +``` +## RELEASE STATUS — CLI Tail (Cycle 2) +Devs: +PM: +Blockers: +Next milestone: +``` + +## Reviewing PRs + +When a dev posts `Action: REVIEW-READY` with a PR URL: + +1. `gh pr view ` to read description and CI status +2. `gh pr diff ` to read changes +3. Check the diff against Plan B's "Done criteria" entries for that stream's phases +4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash per project convention) +5. If red: post `Action: HOLD` with specific concerns + +Use `superpowers:requesting-code-review` if you want a deeper independent review from a fresh subagent before approving. + +## Pre-merge checklist (per stream) + +Before each `MERGE-APPROVED`: + +- [ ] Plan B's "Done criteria" for the stream's owned phases all checked +- [ ] `cargo test --workspace` green on the stream's worktree +- [ ] `cargo clippy --workspace` silent +- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean (always, Stream C especially) +- [ ] No regression in CLI behaviour — existing `crates/relicario-cli/tests/*` pass without modification +- [ ] Narration discipline observed in the PR's STATUS UPDATE history + +## First action + +1. Call `read_messages(for="pm")` to drain any early inbox messages. +2. Verify pre-launch state: `git log --oneline -5 main`, `git status`, `ss -ltn 'sport = :7331'`. If any check fails, surface to the user before proceeding. +3. Emit a `## RELEASE STATUS` block confirming context absorbed. +4. Wait for setup-acknowledge STATUS UPDATEs from all three devs (their kickoff prompts have them post one after creating their worktree). Once all three are in, post opening `PROCEED` directives confirming each stream's plan path and phase scope. +5. Standing watch: drain inbox before each action; respond to QUESTIONs and STATUS UPDATEs as they arrive.