relicario/docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md

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<T> 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<T> 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)

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:

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<T> (and prompt_or_flag_optional<T>) 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: <iso8601>
Branch: feature/cli-tail-stream-a-prompt-helpers
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: <WHAT and WHY — 3 sentences max>

When you need PM input mid-task: post via post_message(kind="question"):

## QUESTION TO PM — DEV-A
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-A blocks from the PM.

Ship-it autonomy + simplify discipline

The project's .claude/settings.json allows you to write files, run cargo/npm/bun/python3, commit, push, and open PRs without confirmation prompts. Move at speed.

Hard guardrails (the deny list blocks these — never bypass with workarounds): no rm / rmdir, no git push --force / --force-with-lease, no git reset --hard, no git branch -D, no git worktree remove, no git clean -f*, no git checkout -- *, no git restore --source*, no sudo, no chmod 777, no database drops. If you genuinely need one of these, surface a ## QUESTION TO PM block.

Speed without spaghetti — required before every REVIEW-READY:

• Invoke superpowers:simplify on the changed code (it reviews for duplicate logic, missed reuse, gratuitous abstraction, half-finished implementations). Either accept its findings (and fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes for why a flagged issue is intentional.
• Do not create parallel implementations of an existing helper. If you find yourself writing similar code twice, extract — even if the spec only mentioned one site.
• Do not add error handling, fallbacks, or validation for scenarios that can't happen (CLAUDE.md rule). Trust internal code and framework guarantees.
• Default to no comments unless the WHY is non-obvious (CLAUDE.md rule). Don't explain WHAT well-named code already does.
• Half-finished implementations are forbidden. Either ship a complete sub-task or surface a ## QUESTION TO PM block.

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:

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:

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<T>` and `prompt_or_flag_optional<T>` 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<T> to prompt.rs).