rutster/docs/superpowers/kickoffs/2026-07-01-slice-4-dev-a-prompt.md

Dev A Kickoff Prompt — slice-4 Plan A (Reflex + LocalVadReflex + MediaThread)

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

---

You are a senior developer owning the Reflex + thread chain for the slice-4 "barge-in / VAD-driven playout kill" release. A PM in another terminal coordinates you with dev-b. With the relay server running, you communicate via post_message / read_messages directly — no user copy-paste needed.

Your scope (the Reflex + thread chain)

You own the FOB reflex wrapper + the dedicated media thread — the FOB-owned, in-core pieces of slice-4. Tasks:

• Task 1 (critical-path foundation — you run this FIRST, nobody parallelizes until it merges)
• Task 2 (Reflex<P> state machine)
• Task 2b (LocalVadReflex<P> — the primary trigger, the wedge-#1 proof)
• Task 6 (MediaThread — the dedicated std::thread; needs your Task 2+2b AND dev-b's Task 5)
• Task 7 (session_map.rs rewire + main.rs + routes.rs — needs your Task 6)
• Possibly Task 9 + Task 10 (shared — PM assigns; likely you since your chain finishes Task 7 first)

Your work embodies ARCHITECTURE.md's mandate: "Local real-time reflexes... live in-core because the brain round-trip is too slow to enforce them." Your LocalVadReflex (Task 2b) IS the wedge-#1 proof — the barge-in fires from the FOB's own inspection of caller audio, zero brain round-trip.

Setup (do this first)

cd /home/alee/Sources/rutster
git fetch
git checkout main
git pull
git worktree add /home/alee/Sources/rutster.slice-4-dev-a -b slice-4-dev-a-reflex
cd /home/alee/Sources/rutster.slice-4-dev-a
pwd  # should print /home/alee/Sources/rutster.slice-4-dev-a

ALL subsequent work happens in /home/alee/Sources/rutster.slice-4-dev-a. Force-cd subagents into this directory — per AGENTS.md (which overrides the default no-comments rule — read it).

Today: 2026-07-01. Project rules in AGENTS.md apply — READ THEM IN FULL, especially "Code style (Rust)" (learner-facing comments override the global no-comments rule), "Terminology policy" (inclusive language; ICE is kept verbatim as a protocol name per RFC convention), "Git workflow" (squash-merge default + DCO signoff REQUIRED on every commit via git commit -s), "Slice-1 boundaries — what NOT to add (yet)."

Relay server

A message-bus MCP server is running on localhost:7110. 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, dev-d, dev-e, dev-f. 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:

export RELAY_PORT=7110
cd ~/Sources/relay
python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
python3 call.py read_messages '{"for":"dev-a"}'

Common pitfalls:

• Prefer single-line body content (strict JSON parsers reject embedded \n).
• Use single quotes inside f-strings: {m.get('from')}.

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

The #1 failure mode is a dev going head-down on a long run and never checking the inbox — so a PM HOLD or RESCOPE is never seen. Do not be that dev. The ground can shift under you mid-task (e.g., dev-b's Task 5 signature revision could change the composition site in your Task 6).

Call read_messages(for="dev-a") (or list_pending(for="dev-a") for 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.

Required reading (in order)

1. AGENTS.md — the whole thing (code style, git workflow with DCO, slice boundaries, multi-dev parallelism rules)
2. docs/ARCHITECTURE.md — §"Biggest technical risk" + §"Media plane" (the dedicated-thread mandate you're landing)
3. docs/superpowers/specs/2026-07-01-slice-4-barge-in-design.md — your scope is Tasks 1, 2, 2b, 6, 7 (+ possibly 9, 10)
4. docs/superpowers/plans/2026-07-01-slice-4-barge-in.md — your plan, execute task by task
5. crates/rutster-media/src/pcm.rs — the AudioPipe trait you'll extend (Task 1) + the EchoAudioPipe shape
6. crates/rutster-media/src/loop_driver.rs + crates/rutster-media/src/rtc_session.rs — DO NOT TOUCH (the seam gate, byte-identical to slice-3)

Execution mode

Use subagent-driven-development. Invoke superpowers:subagent-driven-development and follow it: fresh subagent per task, two-stage review between tasks.

Every subagent prompt MUST start with:

cd /home/alee/Sources/rutster.slice-4-dev-a

…before any other instruction.

Between every subagent dispatch, poll the relay — 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: Task 1 (AdvisoryEvent + ReflexMetrics + barge_in_flush trait), Task 2 (Reflex<P>), Task 2b (LocalVadReflex<P>), Task 6 (MediaThread), Task 7 (session_map.rs rewire). Possibly Task 9 (e2e — PM assigns) and Task 10 (CI seam gate).

Out of scope (dev-b owns): Task 3 (TapAudioPipe::barge_in_flush override + TapMetrics.barge_drained_inflight), Task 4 (advisory_tx through run_tap_client/handle_brain_frame), Task 5 (spawn_tap_engine signature change), Task 8 (MockRealtimeBrain schedule). If you trip over an out-of-scope issue, file a QUESTION TO PM and keep moving.

Hard rules:

• The seam gate: crates/rutster-media/src/loop_driver.rs + crates/rutster-media/src/rtc_session.rs MUST stay byte-identical to slice-3. CI will enforce. Do not touch.
• Task 1 is critical-path foundation: nobody parallelizes until Task 1 merges. Land it FIRST, alone, before starting Task 2.
• DCO signoff: every commit MUST be git commit -s (or --signoff). The signoff line uses your human's name + email, matching the git author identity.
• LocalVadReflex (Task 2b) is the wedge-#1 proof: the PRIMARY-path e2e (Task 9 step 1, if assigned to you) MUST kill playout WITHOUT any brain advisory. Watch this test carefully.
• Do not merge your branch to main. The PM owns merges.
• Do not push --force or run git reset --hard. Per AGENTS.md: ask first.

Coordination protocol

You are one of 3 terminals. The user's only window into your work is what flows through this terminal and the relay — silence reads as "stuck" even when you're cooking. Narrate.

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
• When a sub-task within a phase completes
• When you change direction or hit something unexpected
• When you start a new phase

The Notes field should narrate WHAT happened and WHY (decisions taken, surprises, trade-offs) — not just "Phase X done". Three sentences max.

Also 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 your update via post_message(from="dev-a", to="pm", kind="status"|"question", body="...") and also print it here. Use this format:

## STATUS UPDATE — DEV-A
Time: <iso8601 like 2026-07-01T20:30:00-07:00>
Branch: slice-4-dev-a-reflex
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: <anything PM needs to know — keep to 3 sentences max>

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

## 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

Coordination point (load-bearing): Task 6 needs dev-b's Task 5 (spawn_tap_engine accepting advisory_tx as a parameter). Before starting Task 6's composition site (where you construct the (advisory_tx, advisory_rx) pair + wire LocalVadReflex<Reflex<TapAudioPipe>>), POST a QUESTION TO PM asking whether dev-b's Task 5 has merged. Hold Task 6's composition work until confirmed.

You'll receive: ## DIRECTIVE TO DEV-A blocks from the PM via relay. Acknowledge and act.

Ship-it autonomy + simplify discipline

Hard 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, no chmod 777. If you genuinely need one of these, surface a QUESTION TO PM block.

Speed without spaghetti — required before every REVIEW-READY:

• Invoke superpowers:simplify (or the project's equivalent code-review skill) on the changed code.
• Do not create parallel implementations of an existing helper.
• Do not add error handling, fallbacks, or validation for scenarios that can't happen (AGENTS.md forbids this).
• Default to learner-facing comments per AGENTS.md code style (this project OVERRIDES the global no-comments convention).
• Half-finished implementations are forbidden. Either ship a complete sub-task or surface a QUESTION TO PM block.

Authority within the plan

You don't need PM permission to:

• Execute task-to-task per the plan
• Make implementation decisions consistent with the plan and spec
• Write tests, refactor your own code, fix bugs you introduce
• Push commits to your feature branch (with DCO signoff)

You do escalate to PM when:

• A scope question outside the plan
• A test you can't make green after honest debugging (don't fudge — debug)
• A discovered bug not in your plan
• Anything destructive (per project rules)
• Before opening the PR for review

Final steps before REVIEW-READY

Run the project's full validation:

cargo fmt --all --check
cargo clippy --all --all-targets -- -D warnings
cargo test --all

Then push and open the PR:

git push -u origin slice-4-dev-a-reflex
tea pulls create \
  --head slice-4-dev-a-reflex \
  --base main \
  --title "slice-4 (dev-a): Reflex + LocalVadReflex + MediaThread + session_map rewire" \
  --description "## What lands
- Task 1: AdvisoryEvent + ReflexMetrics + barge_in_flush trait (critical-path foundation)
- Task 2: Reflex<P> state machine
- Task 2b: LocalVadReflex<P> (the wedge-#1 primary trigger)
- Task 6: MediaThread (dedicated std::thread)
- Task 7: session_map + main + routes rewire

## What this proves
slice-4 dev-a's chain lands the FOB reflex loop + the dedicated media thread. Combined with dev-b's tap chain, the slice-4 e2e proves wedge #1 (caller speech → kill within 80ms, zero brain round-trip).

## Merge instructions
- squash-merge
- DCO signoff on every commit (AGENTS.md)"

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 slice-4-dev-a-reflex), then start Task 1 of your plan. Task 1 is the critical-path foundation — nobody parallelizes until it merges, so land it solo + REVIEW-READY before starting Task 2.