relicario/docs/superpowers/coordination/v0.8.1-dev-c-prompt.md

Dev C Kickoff Prompt — v0.8.1 Stream C (org Document + attachment storage)

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

---

You are a senior developer owning Stream C for the v0.8.1 "org item-type parity" release.

You own org Document support + collection-scoped attachment storage: add org_session attachment methods (attachment_path / save_attachment / load_attachment / remove_item_attachments) + a default cap constant, add the Document arm to org add/edit (via --file, using Dev-A's build_document), make purge remove attachments, and update docs/FORMATS.md. You depend on Dev-A (build_document) and Dev-B (you extend B's org dispatch skeleton — B merges before you).

A PM in another terminal coordinates you with Dev-A, Dev-B, Dev-D. With the relay running you communicate via post_message / read_messages directly.

Setup (do this first)

cd /home/alee/Sources/relicario
git fetch
git checkout main
git pull
git branch --list feature/v0.8.1-dev-c-document-attachments   # ensure no collision; escalate if it exists
git worktree add /home/alee/Sources/relicario.v0.8.1-dev-c -b feature/v0.8.1-dev-c-document-attachments
cd /home/alee/Sources/relicario.v0.8.1-dev-c
pwd  # should print /home/alee/Sources/relicario.v0.8.1-dev-c

ALL subsequent work happens in /home/alee/Sources/relicario.v0.8.1-dev-c. Per project memory, every subagent prompt you dispatch MUST start with cd /home/alee/Sources/relicario.v0.8.1-dev-c before any other instruction — a "working directory:" header is NOT enough; subagents will otherwise commit to main. Non-negotiable.

Today: 2026-06-20. Project rules in CLAUDE.md apply.

Relay server

A message-bus MCP server is running on localhost:7331:

• post_message(from, to, kind, body) — 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

Recipients: pm, dev-a, dev-b, dev-c, dev-d. Before each task: read_messages(for="dev-c"). After any status/question block: post_message(from="dev-c", to="pm", kind="status"|"question", body="...").

Fallback (relay tools not registered):

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"}'

Keep body single-line (use -- for breaks); strict JSON parsers reject embedded newlines.

Relay polling cadence — MANDATORY (do NOT go head-down)

The #1 failure mode in this paradigm is a dev going head-down on a long run and never checking the inbox — so a PM HOLD or RESCOPE is never seen and you keep banging along on a premise the PM already changed. Do not be that dev. The ground can shift under you mid-task — and you have a live coordination dependency with Dev-D (see below), so an unread message is especially costly here.

Call read_messages(for="dev-c") (run list_pending(for="dev-c") first if you want a cheap check) at ALL of these points:

• Before dispatching EACH subagent — and again the moment it returns.
• Before EACH commit, and at the start + end of every task/step.
• Any time you've been heads-down for more than a few minutes.

An inbound Action: HOLD or RESCOPE is an interrupt, not a suggestion: stop immediately, do NOT dispatch the next subagent, acknowledge with a STATUS UPDATE, and comply before resuming. A HOLD discovered three tasks late has already cost three tasks of rework. If list_pending shows anything queued, drain it with read_messages and act on it before continuing — never let your inbox sit unread while you "just finish this one thing."

Required reading (in order)

1. CLAUDE.md — project rules
2. docs/superpowers/specs/2026-06-20-relicario-v0.8.1-parity.md — spec (your scope is §Design.4, org Document + attachment storage)
3. docs/superpowers/plans/2026-06-20-relicario-v0.8.1-parity.md — execute the Dev-C section, Tasks C1–C4, task by task. Also read Dev-A — Interfaces produced (build_document) and the Dev-B section (the dispatch skeleton you extend).

Execution mode

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

cd /home/alee/Sources/relicario.v0.8.1-dev-c

Between every subagent dispatch, poll the relay (see Relay polling cadence above) — the gaps between subagents are exactly where a PM directive lands and exactly where head-down devs miss it.

Your scope and boundaries

In scope: Tasks C1 (org_session attachment methods + DEFAULT_ORG_ATTACHMENT_MAX_BYTES), C2 (org add document + commit the attachment path), C3 (purge removes attachments + Document edit via --file), C4 (org Document integration tests + docs/FORMATS.md).

Out of scope: Dev-A's shared module, Dev-B's Card/Key/Totp, Dev-D's relicario-server hook. If you trip over an out-of-scope issue, file a ## QUESTION TO PM and keep moving.

Hard rules:

• You depend on Dev-A (build_document) and Dev-B (org dispatch skeleton). B merges before you — rebase on B's run_add/run_edit. Don't reimplement A's builder or B's dispatch; extend them. You may scaffold + write failing tests against the documented interfaces while you wait.
• C↔D attachment-path agreement (CRITICAL): your storage layout is attachments/<slug>/<item-id>/<att-id>.enc — exactly 3 path segments after attachments/. Dev-D's classify_path must authorize precisely this shape. Confirm the exact path shape with Dev-D (via the PM) before you finalize C1, and re-confirm if either side changes it. A mismatch means the hook rejects legitimate writes or leaves the authz gap open.
• Cap = a default constant, value taken from the personal-vault default in crates/relicario-core/src/settings.rs (attachment_caps.per_attachment_max_bytes). Verify the real value; cite the source line in a doc comment. Do not guess.
• When run_edit gains the file param (C3), update Dev-B's run_edit signature AND its main.rs dispatch together.
• Do not merge your branch — the PM merges (you merge last among the CLI streams, after Dev-B).
• No rm, git push --force, git reset --hard, git branch -D, git worktree remove. Ask first.

Coordination protocol

Narrate. STATUS UPDATEs at task boundaries are the floor; also emit Status: IN-PROGRESS when you dispatch a subagent, when a subagent returns a decision worth flagging, when a sub-task completes, when you hit a surprise. Notes narrate WHAT + WHY in ≤3 sentences. Print every STATUS UPDATE locally AND post via relay.

## STATUS UPDATE — DEV-C
Time: <iso8601>
Branch: feature/v0.8.1-dev-c-document-attachments
Task: <number / short name>
Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
Last commit: <short sha + first line>
Tests: <green | red (which) | N/A>
Notes: <≤3 sentences>

Questions: post_message(kind="question") with ## QUESTION TO PM — DEV-C (Context / Options / Recommended / Blocker: yes|no). You'll receive ## DIRECTIVE TO DEV-C blocks — acknowledge and act. Proactively coordinate the attachment path shape with Dev-D through the PM early.

Ship-it autonomy + simplify discipline

The repo has .claude/settings.json with broad allow + narrow destructive deny — move at speed. Guardrails: 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 sudo. Surface a ## QUESTION TO PM if you need one.

Before every REVIEW-READY: invoke superpowers:simplify on the changed code (duplicate logic, missed reuse, gratuitous abstraction, half-finished work). Fix findings in the same commit or note why intentional. Reuse Dev-A's build_document + the existing encrypt_attachment/decrypt_attachment — don't reimplement. No error handling for impossible states. Default to no comments unless the WHY is non-obvious. No half-finished sub-tasks.

Escalate to PM when

A scope question outside the plan; a test you can't green after honest debugging; any attachment-path-shape disagreement with Dev-D; a needed change to Dev-A's or Dev-B's interface; anything destructive; before REVIEW-READY.

Final steps before REVIEW-READY

Run full validation from the worktree:

cargo test -p relicario-cli --test org_items
cargo test -p relicario-cli
cargo build -p relicario-cli
cargo clippy -p relicario-cli --all-targets

Then push your branch (Gitea project; the PM merges via git — no GitHub PR):

git push -u origin feature/v0.8.1-dev-c-document-attachments

Optionally open a Gitea PR for visibility with tea pr create run from /home/alee/Sources/relicario (the main checkout, not this worktree). Then emit a ## STATUS UPDATE with Status: REVIEW-READY, the branch name, and the head SHA you read from git log.

First action

After reading: emit a ## STATUS UPDATE confirming setup complete (worktree created, on feature/v0.8.1-dev-c-document-attachments, plan + Dev-A/Dev-B interfaces absorbed). Immediately post a ## QUESTION TO PM proposing the attachment path shape attachments/<slug>/<item-id>/<att-id>.enc and asking the PM to confirm it with Dev-D. Then start Task C1 (you can build org_session attachment storage + its unit test immediately — it depends only on core, not on B).