Threnody plan

Threnody planning mode

Unified planning entry point for normal orchestration (plan_task) and swarms (execute_swarm). Every path ends at the same confirmation gate (§4) — the difference between plan-only and plan-then-execute is only what the recommended option is, not whether the user gets asked.

Trigger phrases

Plan-only: "plan only", "dry run", "show waves", "preview the swarm", "don't execute yet", "what agents would you spawn" — recommend Cancel at the gate and stop there unless the user picks a run option.

Plan-then-execute: default when user asks to build/implement/refactor without plan-only qualifiers — recommend the matching run option at the gate.

Always plan first: multi-file, multi-concern, or parallel agent work

Host-native plans auto-fan out to one agent per file when intent implies a webapp/fullstack stack (heuristic_intent_templates). Use expand_host_plan after scaffold waves if more files appear.

For broad code review, prefer the token-cheap FAST_REVIEW: shape (one read-only reviewer per file plus synthesis). Use the deeper REVIEW: file × dimension swarm only when the user explicitly asks for deep review, security-critical audit, threat modeling, or a named specialist dimension.

Fast-start contract

Any plan path that emits agents must return a spawnable host_spawn_waves handoff quickly: target under 5 seconds to handoff and under 30 seconds to first host spawn. Keep optional LLM refinement, consensus, detailed receipts, and learning aggregation off the first-spawn path.

When executing a returned plan, spawn all agents in the same wave as one batch before waiting at the wave barrier. Never serialize agents inside a single wave.

Workflow

1. Classify

Call route_task(task=...) (MCP: Threnody).

2. Choose planning tool

Need	Tool
Standard multi-step work, no swarm persistence	decompose_task (preferred) or plan_task
Budget cap, swarm_id, topology, resume	execute_swarm (host-native default)
Frontend + backend + API in parallel	Same tools + contract-first prompt (see threnody-fullstack)

Swarm signals: large fanout, explicit budget/resume, topology choice, user says "swarm"

Task signals: refactor across files, fleet waves, no persistence requirement

3. Present wave plan

Use this template:

## Threnody plan

- **Tier:** {tier from route_task}
- **Mode:** {plan_task | execute_swarm}
- **Topology:** {dag | star | hierarchical | auto | linear} (swarm only)
- **Host execution:** host_native (default)

| Wave | Parallel | Agents | Tier | Summary |
|------|----------|--------|------|---------|
| 1 | no | 1 | medium | Define API contract |
| 2 | yes | 2 | medium | Backend + frontend |
| 3 | no | 1 | low | Integration smoke tests |

**Estimated cost:** {from swarm cost_estimate if present}

Include consumes / produces / depends_on when the plan exposes them.

4. Confirm before spawning — always

After the wave table, always call AskUserQuestion — in both the plan-only and the plan-then-execute branch. Never spawn straight off a plan.

Show first: the wave table, cost_estimate when present, and plan_summary.coverage.deferred when any file ended up with no owner.

Then one question, header Execute, four options:

Option	Meaning
Run as swarm	hand off host_spawn_waves via threnody-swarm (swarm_id, budget, resume)
Run as task	wave execution via threnody-task, no swarm persistence
Adjust scope	user describes the change in free text
Cancel	stop — spawn nothing

Order the options so the tool that actually produced the plan comes first and is labelled (Recommended): execute_swarm → Run as swarm first; decompose_task / plan_task → Run as task first.

On Adjust scope: re-call the same planning tool with the amended task, render the new wave table, and ask again. Never spawn during this loop.

On Cancel: stop. Do not call report_host_swarm_complete — nothing ran.

After the user picks a run option:

• Spawn host_spawn_waves via threnody-task or threnody-swarm — the orchestrator does not implement subtasks with direct edits.
• For every wave, start every same-wave agent first, then wait for that wave's results before advancing to dependent waves.
• Reporting: in batch mode (default, see learning_report_contract.report_mode) report once at terminal via report_host_swarm_complete — no per-worker-wave round-trip. In inline mode call report_host_wave after each wave. Use inspect_swarm to confirm status transitions.

Timing tradeoff (intentional): the question sits between handoff and first spawn. The <5s handoff target still holds; the <30s first-spawn target now includes human response time by design. Keep the pre-question rendering cheap — do not fetch receipts or run extra tools just to draw the table.

Full-stack prompt boilerplate

When planning frontend + backend + API work, append to the task:

Contract-first: wave 1 OpenAPI + shared types (produces api-contract);
wave 2 parallel frontend and backend (consumes api-contract);
wave 3 integration tests and wire-up. Use depends_on and topology dag.

See threnody-fullstack for details.

Token cost

• Prefer host-native plans (host_spawn_waves) — one planner call, host Task/Agent bills once.
• Avoid delegate swarm + star coordinator rounds unless expert — each round adds LLM synthesis cost.
• Alignment = contract artifacts + verify gates, not multi-agent voting consensus.
• Keep ordinary security-adjacent work at medium unless the task says deep/security-critical or the files expose concrete exploit primitives.

Execution handoff

Planned with	Execute via
decompose_task / plan_task	threnody-task
execute_swarm	threnody-swarm

Related skills

• Entry routing: threnody-routing
• Normal execution: threnody-task
• Swarm execution: threnody-swarm
• Full-stack parallel: threnody-fullstack
• Utility subtask monitoring: threnody-subtasks