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)

```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<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.

## 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<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`).