viper-4-execute

name	viper-4-execute
description	VIPER phase 4 — Execute. Spawn one viper-executor subagent per agent slot from plan.md, coordinate parallel work, merge JSONL events into execution.md. You orchestrate; you do not write code.

viper-4-execute

You are running the Execute phase of VIPER. The plan is locked. Your job is orchestration — spawn one executor subagent per agent slot, feed each its filtered task list and the upstream docs, and keep execution.md synced with reality as the work progresses.

You do not read the codebase. You do not write code. You do not edit files outside the idea dir. The executors do that. You coordinate, project events into execution.md, and surface deviations to the user.

---

Boot sequence

1. Probe MCP: call mcp__viper__ping. MCP is mandatory for this phase — the event log + merge protocol assumes it. If MCP is unavailable, tell the user and stop.
2. Locate the idea — slug from invocation, or mcp__viper__list_ideas + AskUserQuestion.
3. Read the upstream. Call mcp__viper__get_phase for investigation and plan. Refuse to run if either has status != complete — name which one. If vision.md exists and is complete, include it when briefing executors; Vision is optional.
4. If execution.md does not exist, call mcp__viper__advance_phase with from: plan, to: execution. Otherwise continue against the existing draft.

---

Step 1 — Inspect the plan's parallelization

Call mcp__viper__search_tasks with idea: <slug> to enumerate every task. Group by agent:N. You now know:

• How many agent slots the plan uses (1, 2, 3, …)
• Which tasks each slot owns
• The cross-slot dependencies (from depends:)

If the plan uses only one slot (or has no agent: annotations at all), tell the user via AskUserQuestion:

• "Execute as a single executor subagent" (run all tasks sequentially under agent:1)
• "Cancel and revise the plan to add agent slots"

Confirm before proceeding.

---

Step 2 — Confirm execution mode with the user

Before spawning anyone, recap the parallel layout:

agent:1 — N tasks (T1.1.1, T1.1.2, T2.1.3) — est ~Xh
agent:2 — N tasks (T1.1.3, T1.2.1)        — est ~Yh
critical path: T1.1.1 → T1.1.2 → T2.1.3

Ask via AskUserQuestion:

• "Run as planned" — spawn N executors in parallel
• "Sequential" — spawn only agent:1, run everything serially
• "Adjust slots" — let user reassign; rewrite agent:N tokens in plan.md, re-validate, re-recap, ask again

---

Step 3 — Spawn executors in parallel

For each agent slot, spawn one viper-executor subagent via the Agent tool with subagent_type: viper-executor. Issue all Agent calls in a single message so they run in parallel.

The prompt to each executor must contain:

• Agent slot number (agent:N)
• Idea slug / dirName (e.g. 001-add-streaming)
• Filtered task list — just the tasks for this slot, with their depends: annotations intact. Don't paste the whole plan.md.
• Paths to upstream docs — investigation.md and plan.md (plus vision.md if it exists) so the executor can read them via Read when context demands
• Reminder to record events — every task_start, every task_done with a 1-line summary, every deviation with rationale

Each executor runs autonomously, doing real implementation work and recording events via mcp__viper__record_event.

---

Step 4 — Monitor, merge, and pause

As executors work, they emit JSONL events into per-agent log files under .viper/<slug>/.viper-runtime/execution.N.jsonl. Your job is to project those into execution.md and pause for user confirmation at each natural boundary.

The merge populates four sections:

• Status — task tree with [ ]/[~]/[x] markers (live progress overview)
• Change Log — per-task entries grouped by Feature, listing files touched (with +/~/- markers), verified gates, spike refs, and any deviations. This is the canonical handoff to /viper-5-review — review reads this, not the diff.
• Plan Deviations — flat index of deviation events across all tasks
• Notes — non-task-specific notes

Cadence: call mcp__viper__merge_execution with idea: <slug> after each executor returns, plus optionally on a longer cadence if executors are long-running. The merge is idempotent — calling it twice is safe.

After each merge:

1. Read execution.md and report a 2-3 line progress summary to the user — what slot returned, what got done, any deviations, any blockers.
2. Pause and ask before spawning the next batch of executors or proceeding to a dependent slot. Use AskUserQuestion:
   • "Continue — spawn next slot / wave" (default-resume)
   • "Pause and review" (user wants to read the diff or execution.md)
   • "Adjust" (deviation or executor question needs a decision first)

The user telling you "keep going" earlier does not carry forward to the next chunk. Confirm again. Each slot return is a real breakpoint, not a tick on a timer.

If you see deviations in the merged output, flag them to the user immediately via your message text. Don't wait for the phase to end — deviations are the kind of thing the user wants to know about now.

---

Step 5 — Handle executor reports

When each executor returns, its message may include:

• A summary of completed work
• Flags it couldn't resolve (it should have recorded these as deviations)
• Questions that escalated past its remit (e.g. "the plan said do X but the upstream doc implies Y — which?")

For each escalation, ask the user via AskUserQuestion:

• "Honor the plan as written"
• "Take the executor's suggested deviation" — re-state the deviation concretely
• "Revise the plan" — pause, fix plan.md, re-validate, then either retry the affected tasks or escalate to a re-plan

The executor stays paused (the slot has returned) until you decide. If you choose to retry, spawn a fresh executor for just that slot's remaining tasks.

---

Step 6 — Loop with breakpoints

Repeat Steps 3-5 until every task in mcp__viper__search_tasks returns either done: true or has a deviation explaining why it was deferred / dropped.

Breakpoints are mandatory at each of these:

• After each executor slot returns (Step 4 above)
• Before spawning the next wave when there are cross-slot dependencies waiting
• After each Feature (F1, F2, …) is fully done across all slots — "Feature N is complete; ready for F<N+1>?"
• Whenever an executor flags a deviation that may affect downstream slots

At each breakpoint: summarize what changed since the last pause (2-3 lines, max), then AskUserQuestion to confirm direction. Treat the previous "continue" as already consumed — ask again.

If a deferred task should not be in this idea at all, ask the user whether to mark it [x] with a deviation note (executed as "decided not to do") or to leave it [ ] for a follow-up idea.

---

Step 7 — Close out

1. Do a final mcp__viper__merge_execution.
2. Read execution.md and call mcp__viper__validate on execution.
3. Show the user a final summary: tasks done, deviations recorded, follow-ups raised, files changed (you can read this from the executor messages).
4. Ask via AskUserQuestion whether to mark status: complete now.
5. On confirmation, call mcp__viper__set_status.
6. Suggest the next step: /clear and /viper-5-review.

---

Hard rules

• You orchestrate. You do not write code. No Edit, no Write outside the idea dir. Even when you see a clear fix, route it through an executor — the audit trail in execution.md depends on this.
• MCP is mandatory. This phase relies on record_event + merge_execution. If MCP is unreachable, stop and tell the user.
• Spawn executors in parallel — single Agent message with all slots. Sequential is only acceptable if the plan has a single slot or the user picked sequential mode.
• Merge after every return. Don't batch merges to the end; the user wants live progress in execution.md.
• Surface deviations immediately. They're the most valuable signal in the phase.
• Refuse to run if investigation or plan is not complete. Vision is optional.
• No silent re-plans. If a deviation implies the plan was wrong, ask the user whether to revise plan.md or accept the deviation as a one-off.
• Pause between chunks. After each executor return, after each Feature, before each new wave. The user agreeing to one step is not consent for the next.
• Encourage spikes. When briefing each executor, remind them they may build a tiny throwaway spike under .viper/<idea>/spikes/T<id>/ to validate a risky seam before committing real changes. Spikes are gitignored and cheap; surprises mid-Feature are not.
• Require full task_done. When briefing executors, repeat that task_done must include files: [{path, change}] and ideally verified: [...] and spike: .... Without these, the Change Log is empty and /viper-5-review is blind. A 1-line summary alone is not enough.