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