diegosouzapw Wave Planner
Transform project issues into execution-ready implementation plans with wave-based organization, specialist agent assignments, token estimates, and TDD workflow integration.
Behavioral Classification
Type: Guided Decision
This skill asks for your input on key decisions, then executes based on your choices.
Decision Points:
- Which scope? (P0 only, P0+P1, All issues)
- Architecture decisions requiring clarification
- Create ADRs for decisions?
- Risk mitigation strategies
After decisions are made, artifact generation proceeds automatically.
Quick Start
# Explicit invocation
/wave-planner Phase 3 Live Data
# Or use natural language (proactive trigger)
"Plan the implementation for the security hardening project"
"Break down the API redesign into waves"
"Create an implementation plan for PROJ-100"
What This Skill Does
- Checks for existing artifacts (plans, configs, projects) - MANDATORY
- Discovers issues from your PM tool (Linear, GitHub, Jira)
- Surfaces architecture decisions requiring clarification
- Predicts blockers and fail cases, generates mitigations
- Organizes issues into waves based on shared context
- Estimates tokens using dynamic codebase analysis
- Assigns specialist agents via LLM inference
- Generates execution-ready artifacts (or updates existing)
Pre-Flight Checks (MANDATORY)
Before wave execution, verify the environment. See preflight.md for the full script.
Quick check:
| Check | Command | Expected |
|---|---|---|
| MCP Server | grep claude-flow .mcp.json |
Found |
| Docker | docker ps | grep <project-name> |
Running |
| Git-crypt | git-crypt status |
Unlocked |
| Linear | linear issues list --limit 1 |
Returns issues |
Artifact Discovery (MANDATORY)
ALWAYS check for existing artifacts before creating new ones. Skipping discovery causes duplicate plans, wasted effort, and confusion.
Discovery Checklist
# 1. Check for existing implementation plans
ls docs/execution/ | grep -i "<project-name>"
# 2. Check for existing hive-mind configs
ls .claude/hive-mind/ | grep -i "<project-name>"
# 3. Check Linear for existing project
npx tsx ~/.claude/skills/linear/scripts/linear-ops.ts list-initiatives | grep -i "<project-name>"
linear projects list | grep -i "<project-name>"
# 4. Check for related ADRs
ls docs/adr/ | grep -i "<topic>"
When Duplicates Are Found
| Scenario | Action |
|---|---|
| Plan exists, not started | Review and update existing |
| Plan exists, partially executed | Continue from current wave |
| Plan exists, completed | Archive and create new if scope changed |
| Config exists, not executed | Use existing config |
| Linear project exists | Reuse, don't create duplicate |
Planning Workflow
Phase 1: Discovery
The skill detects your PM tool and fetches project issues:
Found 12 issues in "Phase 3 Live Data":
- 2 P0-Critical
- 4 P1-High
- 6 P2-Medium
Which scope should we plan?
A) P0-Critical only (2 issues)
B) P0 + P1-High (6 issues)
C) All issues (12 issues)
Phase 2: Architecture Decisions
Decisions are surfaced one at a time to reduce cognitive load:
PROJ-101 requires an architecture decision:
**Where should security scan results be stored?**
A) Separate security_scans table
B) JSON column on skills table
C) Dedicated security schema (Recommended)
Should I create an ADR for this decision?
Phase 3: Risk Analysis
The skill analyzes issues for potential blockers and fail cases:
Identified Risks:
1. **External Dependency Risk** (PROJ-101)
- Issue: Feature relies on third-party API
- Mitigation: Add fallback or cache layer
2. **Breaking Change Risk** (PROJ-102)
- Issue: Schema changes may break existing clients
- Mitigation: Version schema, add migration script
Risk Categories: External Dependency, Breaking Change, Integration, Performance, Security
Phase 4: Wave Organization
Issues are grouped by shared code context to minimize agent context-switching:
Wave 1: Foundation (~81K tokens)
├── PROJ-101: Error handling
├── PROJ-102: Configuration setup
└── Agent: backend-developer
Wave 2: Feature Implementation (~95K tokens)
├── PROJ-103: Core feature
├── PROJ-104: API endpoints
└── Agent: backend-developer
Phase 5: Artifact Generation
| Artifact | Location |
|---|---|
| Implementation Plan | docs/execution/{project}-implementation-plan.md |
| ADRs | docs/adr/{number}-{slug}.md |
| Hive Configs | .claude/hive-mind/{project}-wave-{n}.yaml |
| PM Sub-Issues | Created for code review findings |
Execution
After planning, execute waves. See execution.md for full details.
Quick start:
# Execute Wave 1
./claude-flow swarm "Execute Wave 1" \
--config .claude/hive-mind/{project}-wave-1.yaml \
--strategy development \
--mode hierarchical
Wave Completion Checklist (from execution.md):
- Run code review:
docker exec <container-name> npm run audit:standards - Fix findings OR create Linear sub-issues
- Update Linear issue status to Done
- Commit with Co-Authored-By
- Create PR if wave is complete
Reference Documentation
For detailed information, see reference.md:
- Output artifact formats (implementation plan, hive configs, ADRs)
- Token estimation calculations and budgets
- Agent assignment logic and triggers
- TDD workflow (red-green-refactor)
- PM tool adapters
- Example planning session
Configuration
# ~/.claude/skills/wave-planner/config.yaml
wave-planner:
defaults:
max_waves: 6
max_issues_per_wave: 5
token_budget_per_wave: 150000
adapters:
preferred: auto
estimation:
confidence_threshold: medium
review_cycle_count: 2
artifacts:
create_adrs: true
create_hive_configs: true
create_sub_issues: true
Environment
# PM tool credentials (via adapter)
LINEAR_API_KEY=lin_api_xxx
GITHUB_TOKEN=ghp_xxx
Skill Composition
This skill orchestrates:
| Skill | Usage |
|---|---|
linear |
PM operations (fetch, update, create) |
hive-mind |
Generate execution configs |
governance |
Code review after commits |
If a required skill is unavailable, the skill will prompt for installation.
Troubleshooting
"Linear skill not available"
Install the Linear skill to ~/.claude/skills/linear/
"Cannot detect PM tool"
Specify explicitly:
/wave-planner --adapter linear "Project Name"
"Token estimate seems high"
Check confidence level. Low confidence estimates include padding for unknowns. Refine issue descriptions or break into smaller issues.
Related Skills
- linear - PM operations
- hive-mind - Swarm execution (local skill, available after installation)
- governance - Code review
Changelog
v1.4.0 (2026-01-23)
- Refactor: Decompose into sub-files for progressive disclosure
- Extract pre-flight checks to preflight.md
- Extract execution details to execution.md
- Extract reference documentation to reference.md
- Add Behavioral Classification section (ADR-025)
- Main SKILL.md reduced from 785 to ~350 lines
v1.3.0 (2026-01-23)
- New: Artifact Discovery phase (MANDATORY before creation)
- Check for existing implementation plans before creating
- Check for existing hive-mind configs before creating
- Check Linear for existing projects/issues
- Discovery workflow with options to review, update, or archive
v1.2.0 (2026-01-21)
- New: Pre-Flight Checks section
- New: Automated Code Review Trigger configuration
- Enhanced: Wave Completion Checklist with Linear enforcement
- Added "The Deferred Issue Rule" - no deferral without Linear ticket
v1.1.0 (2026-01-21)
- New: Risk Analysis phase
- Predict blockers and fail cases before wave organization
- Auto-generate mitigations for identified risks
- Risk register added to implementation plan output
v1.0.0 (2026-01-21)
- Initial release
- Linear adapter support
- Dynamic token estimation
- TDD workflow integration
- Hive mind config generation