Planning
Overview
Plan-first development methodology where 80%+ of time goes to planning before implementation begins. Planning tokens are cheaper than implementation tokens, and models reason better about a detailed plan that fits their context window than about a sprawling codebase.
When to use: Starting new projects, adding major features, breaking complex work into phases, resuming work after context clears, managing multi-session implementations, coordinating multiple agents on the same codebase.
When NOT to use: Quick bug fixes, one-file changes, exploratory prototyping where requirements are unknown, trivial refactors where the change is obvious.
Quick Reference
| Planning Phase |
Description |
| 1. Initial plan |
Write goals, intent, workflows, tech stack |
| 2. Iterative refinement |
4-5 rounds of review until suggestions plateau |
| 3. Multi-model blend |
Get competing plans, merge best-of-all-worlds |
| 4. Convert to tasks |
Self-contained tasks with dependency structure |
| 5. Polish tasks |
6+ rounds of cross-model review |
| Phase Type |
Scope |
Max Files |
Duration |
| Infrastructure |
Scaffolding, build config, deployment |
3-5 |
1-3 hours |
| Database |
Migrations, schema, seed data |
2-4 |
2-4 hours |
| API |
Routes, middleware, validation |
3-6 |
3-6 hours |
| UI |
Components, forms, state, styling |
4-8 |
4-8 hours |
| Integration |
Third-party services, webhooks |
2-4 |
3-5 hours |
| Testing |
E2E tests, integration tests |
varies |
3-6 hours |
| Pattern |
Purpose |
Key Points |
| When to plan vs build |
Decision tree by complexity signals |
Match planning depth to task complexity |
| Risk assessment |
Probability x impact matrix |
Focus on high-risk items first |
| Session Lifecycle |
Action |
| Start |
Read SESSION.md, check "Next Action", continue |
| Work |
Implement, verify, debug (repeat) |
| Checkpoint |
Git commit with structured format, update SESSION.md hash |
| Wrap |
Update SESSION.md, git checkpoint, set concrete "Next Action" |
| Resume |
Read SESSION.md + planning docs, continue from "Next Action" |
| Document |
When to Generate |
| Implementation phases |
Always -- core plan doc for every project |
| Session tracking |
Always -- navigation hub for progress |
| Database schema |
3+ tables |
| API endpoints |
5+ endpoints |
| Architecture overview |
Multiple services or complex system boundaries |
| Critical workflows |
Complex setup steps, order-sensitive workflows |
| Good Plan |
Great Plan |
| Describes what to build |
Explains WHY you are building it |
| Lists features |
Details user workflows and interactions |
| Mentions tech stack |
Justifies tech choices with tradeoffs |
| Has tasks |
Has tasks with dependencies and rationale |
| ~500 lines |
~3,500+ lines after refinement |
Common Mistakes
| Mistake |
Correct Pattern |
| Starting implementation before planning is complete |
Spend 80%+ of time on planning; finish all refinement rounds before writing code |
| Writing vague next actions like "continue API work" |
Be specific: "Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47" |
| Session tracking doc over 200 lines |
Collapse completed phases to summaries; reference planning docs for details |
| Creating phases with 10+ files |
Auto-split into sub-phases of 5-8 files that fit in one 2-4 hour session |
| Single-round plan review |
Iterate 4-5 rounds until suggestions plateau; use multi-model blending for fresh perspectives |
| Copying code into session docs |
Reference file paths and line numbers instead of pasting code |
| Duplicating planning doc content in session doc |
Link to sections with anchors; session doc is a navigation hub |
| No verification criteria on phases |
Every phase needs specific, testable exit criteria (status codes, user flows, constraints) |
| Skeleton-first coding before a plan exists |
One thorough plan beats incremental skeleton-first coding |
| Planning without prototyping unknown tech |
Build a spike first for unfamiliar frameworks, then create the plan |
| Over-planning simple tasks |
Match planning depth to complexity; skip for trivial work |
| Not validating assumptions early |
Run a spike for the riskiest assumption first |
Delegation
- Explore existing codebase for architecture decisions: Use
Explore agent to survey file structure, patterns, and dependencies before planning
- Execute phase implementation with verification: Use
Task agent to implement individual phases, run verification criteria, and create checkpoint commits
- Design architecture and decompose into phases: Use
Plan agent to create implementation phases with dependency ordering and gate criteria
References
- Planning process and iterative refinement
- Session management and context tracking
- Phase-based implementation planning
- Review workflows and multi-model blending
- Decision tracking and conditional documents
- Planning document templates
1---2name: plan-first-development3description: Planning methodology and session management for software projects. Covers markdown plan creation, iterative refinement, multi-model blending, phase-based implementation docs, and cross-session progress tracking. Use when starting new projects, adding major features, breaking large work into phases, resuming after context clears, or managing multi-phase implementations.4license: MIT5---6
7# Planning
8
9## Overview
10
11Plan-first development methodology where 80%+ of time goes to planning before implementation begins. Planning tokens are cheaper than implementation tokens, and models reason better about a detailed plan that fits their context window than about a sprawling codebase.
12
13**When to use:** Starting new projects, adding major features, breaking complex work into phases, resuming work after context clears, managing multi-session implementations, coordinating multiple agents on the same codebase.
14
15**When NOT to use:** Quick bug fixes, one-file changes, exploratory prototyping where requirements are unknown, trivial refactors where the change is obvious.
16
17## Quick Reference
18
19| Planning Phase | Description |
20| ----------------------- | ---------------------------------------------- |
21| 1. Initial plan | Write goals, intent, workflows, tech stack |
22| 2. Iterative refinement | 4-5 rounds of review until suggestions plateau |
23| 3. Multi-model blend | Get competing plans, merge best-of-all-worlds |
24| 4. Convert to tasks | Self-contained tasks with dependency structure |
25| 5. Polish tasks | 6+ rounds of cross-model review |
26
27| Phase Type | Scope | Max Files | Duration |
28| -------------- | ------------------------------------- | --------- | --------- |
29| Infrastructure | Scaffolding, build config, deployment | 3-5 | 1-3 hours |
30| Database | Migrations, schema, seed data | 2-4 | 2-4 hours |
31| API | Routes, middleware, validation | 3-6 | 3-6 hours |
32| UI | Components, forms, state, styling | 4-8 | 4-8 hours |
33| Integration | Third-party services, webhooks | 2-4 | 3-5 hours |
34| Testing | E2E tests, integration tests | varies | 3-6 hours |
35
36| Pattern | Purpose | Key Points |
37| --------------------- | ----------------------------------- | --------------------------------------- |
38| When to plan vs build | Decision tree by complexity signals | Match planning depth to task complexity |
39| Risk assessment | Probability x impact matrix | Focus on high-risk items first |
40
41| Session Lifecycle | Action |
42| ----------------- | ------------------------------------------------------------- |
43| Start | Read SESSION.md, check "Next Action", continue |
44| Work | Implement, verify, debug (repeat) |
45| Checkpoint | Git commit with structured format, update SESSION.md hash |
46| Wrap | Update SESSION.md, git checkpoint, set concrete "Next Action" |
47| Resume | Read SESSION.md + planning docs, continue from "Next Action" |
48
49| Document | When to Generate |
50| --------------------- | ---------------------------------------------- |
51| Implementation phases | Always -- core plan doc for every project |
52| Session tracking | Always -- navigation hub for progress |
53| Database schema | 3+ tables |
54| API endpoints | 5+ endpoints |
55| Architecture overview | Multiple services or complex system boundaries |
56| Critical workflows | Complex setup steps, order-sensitive workflows |
57
58| Good Plan | Great Plan |
59| ----------------------- | ----------------------------------------- |
60| Describes what to build | Explains WHY you are building it |
61| Lists features | Details user workflows and interactions |
62| Mentions tech stack | Justifies tech choices with tradeoffs |
63| Has tasks | Has tasks with dependencies and rationale |
64| ~500 lines | ~3,500+ lines after refinement |
65
66## Common Mistakes
67
68| Mistake | Correct Pattern |
69| --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
70| Starting implementation before planning is complete | Spend 80%+ of time on planning; finish all refinement rounds before writing code |
71| Writing vague next actions like "continue API work" | Be specific: "Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47" |
72| Session tracking doc over 200 lines | Collapse completed phases to summaries; reference planning docs for details |
73| Creating phases with 10+ files | Auto-split into sub-phases of 5-8 files that fit in one 2-4 hour session |
74| Single-round plan review | Iterate 4-5 rounds until suggestions plateau; use multi-model blending for fresh perspectives |
75| Copying code into session docs | Reference file paths and line numbers instead of pasting code |
76| Duplicating planning doc content in session doc | Link to sections with anchors; session doc is a navigation hub |
77| No verification criteria on phases | Every phase needs specific, testable exit criteria (status codes, user flows, constraints) |
78| Skeleton-first coding before a plan exists | One thorough plan beats incremental skeleton-first coding |
79| Planning without prototyping unknown tech | Build a spike first for unfamiliar frameworks, then create the plan |
80| Over-planning simple tasks | Match planning depth to complexity; skip for trivial work |
81| Not validating assumptions early | Run a spike for the riskiest assumption first |
82
83## Delegation
84
85- **Explore existing codebase for architecture decisions**: Use `Explore` agent to survey file structure, patterns, and dependencies before planning
86- **Execute phase implementation with verification**: Use `Task` agent to implement individual phases, run verification criteria, and create checkpoint commits
87- **Design architecture and decompose into phases**: Use `Plan` agent to create implementation phases with dependency ordering and gate criteria
88
89## References
90
91- [Planning process and iterative refinement](references/planning-process.md)
92- [Session management and context tracking](references/session-management.md)
93- [Phase-based implementation planning](references/phase-planning.md)
94- [Review workflows and multi-model blending](references/review-workflows.md)
95- [Decision tracking and conditional documents](references/decision-tracking.md)
96- [Planning document templates](references/document-templates.md)
oakoss