Core Concepts
The structural foundations that make Waves work: how artifacts relate to each other, how work flows through waves, how decisions are classified, and the principles that guide everything.
Every Piece of Work Traces to the Blueprint
Information flows downward. Detail is never duplicated upward. The structure enforces coherence without bureaucracy.
The Golden Rule: Nothing exists in the project that is not supported in the product blueprint.
If a logbook cannot trace to the blueprint, either the blueprint needs updating (via Blueprint Refinement) or the work should not exist.
Sub-Zero → Wave 0 → Wave N
Waves replaces fixed sprints with organic delivery cycles. Each wave carries a product increment from validation to production — lasting as long as it needs. No timeboxes. No artificial ceremonies.
Sub-Zero: Before You Commit
Feasibility
"Can we build this? Should we?"
/waves:feasibility-analyzeThe AI acts as a business consultant: market analysis, competitors, buyer personas, Monte Carlo revenue projections, and Bayesian risk assessment. If the numbers don't add up, you pivot or discard before investing time. Real data, not opinions.
Wave 0: The Foundational Wave
This is the wave most teams skip — and it's the most important one. Business stakeholders often want to jump straight to "the feature that sells." But without horizontal foundations, every vertical feature is built on sand.
Foundation
"What did we learn?"
/waves:foundation-createCompacts thousands of feasibility simulations into an executive summary: validated problem with evidence, refined target users, revenue model with unit economics, financial benchmarks, SWOT analysis, capabilities re-classified by operational criticality, and a readiness gate.
Blueprint
"What are we building, and why?"
/waves:blueprint-createConsumes the foundation and produces complete product architecture: hypothesis, mission, vision, design principles that generate traceable product rules, capabilities with scope boundaries and acceptance criteria, user flows, system flows, success metrics with dual signal (success + failure), and tech stack.
Roadmap W0
"What infrastructure do we need before business features?"
/waves:roadmap-createPlans the horizontal infrastructure every product needs before building verticals: authentication, database, CI/CD, base architecture — the essential capabilities that aren't business features but without which no business feature works.
Logbooks W0
"How do we implement each piece?"
/waves:logbook-createEach task in the W0 roadmap gets its own logbook: objectives, completion guides referencing actual code, progress tracked across sessions. The agent implements continuously, preserving full context. Come back tomorrow and pick up exactly where you left off.
Wave 1, 2, 3…N: Business Waves
Once W0 laid the foundations, each business wave builds vertical features on that base. Waves can overlap if they work on independent areas. A wave ends when its roadmap is complete and everything is in production.
Roadmap WN
"What features go in this wave?"
/waves:roadmap-createTakes capabilities from the blueprint and organizes them into phases for this specific wave. Each roadmap is numbered: roadmap_w1.json, roadmap_w2.json, etc. What goes in this wave? What can wait? What blocks what?
Logbooks
"How do we implement each ticket?"
/waves:logbook-createSame logbook system as W0. For each ticket, the agent breaks work into objectives with completion guides, implements with automatic code auditing, and preserves context between sessions. Code passes review on the first try.
feasibility → foundation → blueprint → roadmap_w0 → logbooks → roadmap_w1 → logbooks
Start at any level. If you already have a product, jump straight to a business wave. The full pipeline is for building from scratch.
Decision Classification
Every other framework gives the AI agent full autonomy (dangerous) or no autonomy (wasteful). Waves introduces graduated autonomy: the agent classifies every decision it makes by impact level, and its behavior changes accordingly. This is the trust contract between you and your agent.
The classification is not something you configure or toggle. It is injected into every action the agent takes. The agent evaluates each decision against the 5 levels and acts accordingly — proceeding when it should, stopping when it must.
When in doubt, classify UP — never down.
This is the trust contract. The human retains authority over decisions that matter. The agent errs on the side of caution, never on the side of speed.
Validated with 18 benchmark scenarios across all 5 levels: 100% correct actions, conservative bias when uncertain (classifies UP, never down). The system is ready for real delegation.
8 Principles That Guide Every Wave
Organic over Ceremonial
Meetings happen when they're needed, not when the calendar says.
Data over Opinion
Feasibility uses Monte Carlo simulations, not gut feelings. Decisions are recorded with reasons.
Traceability over Documentation
Every piece of work traces to the blueprint. The structure enforces coherence without bureaucracy.
AI as Team Member
Agents are not tools — they have defined responsibilities within each role.
Variable over Fixed
A wave lasts as long as it needs. No artificial boundaries, no wasted ceremony.
Celebration over Forensics
Wave closures recognize achievement first, then note improvements constructively.
Blueprint as Living Document
The product evolves through controlled change, not frozen specs or uncontrolled drift.
Enforcement over Instruction
Rules that can be ignored will be ignored. Hooks enforce the framework with code, not prose.