The Planning Model

What is the Planning Model?

The planning model is how floww organizes work into progressively narrower scopes: milestones contain phases, phases contain plans, plans are grouped into waves, and each plan contains tasks. This hierarchy exists because AI executes best with focused, bounded context. A milestone captures a vision. A task captures a single action with clear verification criteria. The hierarchy bridges the gap between the two.

The model is not theoretical. Every concept maps to files on disk that both the desktop client and flowwCLI (the terminal companion) read and write.

The Hierarchy

Milestone — A shipped version of the product. “v2.0 Workflowws” is a milestone. It contains all the phases needed to reach that goal. Milestones are named after what ships, not what happens internally.

Phase — A cohesive domain of work within a milestone. “Wiki Content Expansion” is a phase. It has requirements, may depend on other phases, and produces measurable outcomes. A phase is the largest unit that a team (human or AI) can reason about as a single thing.

Plan — An executable unit for Claude. Each plan targets roughly 50% of a context window so the AI can complete it in a single session without losing coherence. Plans contain 2-4 tasks, specify exact files, and include verification criteria. Multiple plans within a phase can run in parallel if they share no dependencies.

Wave — A group of plans with no dependencies between them. Wave 1 runs first. Wave 2 starts only after every plan in Wave 1 completes. Waves maximize parallelism while respecting ordering constraints. Within a wave, independent plans can run simultaneously.

Task — A single focused action. Each task specifies the files it touches, the action to take, how to verify the result, and what “done” means. Tasks are atomic — they either complete fully or do not count as done. Each task produces its own commit.

Phase Lifecycle

Every phase progresses through five stages, each producing artifacts that persist across sessions, across context windows, and across agents:

1. Discuss — Gather requirements and constraints from the user. Produces CONTEXT.md — the user’s vision, locked decisions, and areas where Claude has discretion.
2. Research — Investigate the codebase and technical landscape. Produces RESEARCH.md — verified patterns, dependencies, common pitfalls, and implementation recommendations.
3. Plan — Break the phase into executable plans. Produces PLAN.md files — one per plan, each with tasks, verification criteria, and file lists.
4. Execute — Run plans with Claude. Produces SUMMARY.md files — one per plan, documenting what was built, decisions made, and deviations from the plan.
5. Verify — Confirm the phase delivered on its requirements. The artifacts ARE the communication layer — a new Claude session can pick up exactly where the last one left off by reading the files.

The lifecycle is designed for continuity. No planning happens in conversation memory alone. Everything is written to disk so that context compaction, session boundaries, and agent handoffs do not lose information.

Why This Structure

The planning model solves a specific problem: AI context windows are finite, but real projects are not. A desktop application might need fifty changes across twenty files to ship a feature. No single Claude session can hold all of that and execute well. The hierarchy decomposes the work until each piece fits comfortably within AI capabilities, then reassembles the results through stamps (context-aware snapshots) and summary artifacts.

This is not a methodology imposed from the outside. It emerged from building floww itself — every phase of floww’s development was planned and executed through this model, with each iteration refining the structure.

Why It Works This Way

The hierarchy is not bureaucracy — it is a compression strategy. A milestone is too large for Claude to execute directly. A phase is still too large. A plan is just right: the scope fits within a single context window, the verification criteria are measurable, and the output is a committed artifact. The hierarchy exists to progressively narrow scope from human-scale vision to Claude-scale action. Each level strips away irrelevant context and focuses attention. The artifacts at each level — CONTEXT.md, RESEARCH.md, PLAN.md — are not documentation; they are the communication protocol between human intent and AI execution. When a session ends, the next agent picks up the artifacts and continues without loss.

In Practice