wave-planner
npx machina-cli add skill smith-horn/product-builder-starter/wave-planner --openclawWave Planner
Transform project issues into execution-ready implementation plans with wave-based organization, specialist agent assignments, token estimates, and TDD workflow.
Execution
When triggered, immediately:
- Read
./agent-prompt.md - Spawn a single Task with
subagent_type: "general-purpose"passing the agent-prompt content as the prompt - Include in the prompt: the user's request, current working directory, and any arguments passed
- Wait for the agent to complete
- Present the agent's summary to the user
Do NOT execute the planning workflow in this session. The subagent handles everything including user interaction (AskUserQuestion), artifact generation, and Linear queries.
Execution Context Requirements
This skill spawns a general-purpose subagent that performs file write operations (implementation plans, ADRs, hive configs).
Foreground execution required: Yes. Background execution auto-denies unapproved Write/Edit tools, causing silent failures when creating artifacts.
Required tools: Read, Write, Edit, Bash, Grep, Glob, Task, AskUserQuestion, TodoWrite
Fallback: If Write/Edit tools are denied, the subagent returns the plan content as text output for the coordinator to write to disk.
Reference: Subagent Tool Permissions Research
Changelog
v2.0.0
- Refactor: Thin dispatcher pattern — full logic extracted to agent-prompt.md
- Skill runs in isolated subagent context, reducing post-compaction restoration from ~400 lines to ~50 lines
See agent-prompt.md for prior changelog entries.
Source
git clone https://github.com/smith-horn/product-builder-starter/blob/main/skills/wave-planner/SKILL.mdView on GitHub Overview
Transforms project issues into wave-based implementation plans with risk prediction, specialist agent assignments, token estimates, and a TDD workflow. It organizes work into waves, assigns domain experts per wave, and documents decisions via ADRs generated by a dedicated subagent.
How This Skill Works
On trigger, wave-planner reads ./agent-prompt.md and spawns a single subagent (subagent_type: 'general-purpose') with the agent-prompt content as the prompt. It passes the user request, current working directory, and any arguments, then waits for the subagent to finish and returns its summary to the user. The subagent handles artifact generation (e.g., implementation plans, ADRs, hive configs) and all planning tasks; this session does not execute the plan.
When to Use It
- Backlog item that needs a concrete, wave-based implementation plan.
- A complex feature where risk prediction and mitigation per wave are required.
- When you want specialist agents assigned to each wave for domain tasks.
- To embed token estimates and a TDD workflow into the plan.
- When artifacts like ADRs and hive configs should be generated by a subagent.
Quick Start
- Step 1: Trigger /wave-planner with your issue.
- Step 2: The planner reads agent-prompt.md and launches a general-purpose subagent to draft the plan.
- Step 3: Review the subagent's summary and artifacts; proceed to execution if approved.
Best Practices
- Define the initial backlog item clearly before triggering the planner.
- Specify wave objectives and measurable success criteria for each wave.
- Include explicit risk and mitigation notes per wave.
- Assign a dedicated specialist agent to each wave and document ownership.
- Review ADRs, hive configs, and tests produced by the subagent before execution.
Example Use Cases
- Plan a new payment feature broken into Waves 1–3 with tests and risk notes.
- Migrate a monolith to microservices using wave-based planning and ADRs.
- Redesign a dashboards UI with waves, token estimates, and per-wave owners.
- Build a data ingestion pipeline with stepwise waves and TDD coverage.
- Provision infrastructure changes with hive configs and ADRs generated by the subagent.
