Planning
Plan-first development methodology that creates reviewed implementation plans before any code is written, ensuring alignment and reducing wasted effort.
Definition
Planning in Farmwork is a formal phase where implementation details are worked out before any code is written. Plans live in _PLANS/ as markdown documents and are deleted after successful implementation.
The planning phase bridges the gap between ideas (in GARDEN.md) and implementation. It's where abstract concepts become concrete, reviewable specifications.
Philosophy
Core Principle
Measure twice, cut once. The cost of planning is minimal compared to the cost of implementing the wrong thing. Plans are cheap to revise; code is expensive to rewrite.
In agricultural terms, you don't plant crops without knowing your soil, climate, and market. Farmwork's planning system ensures you understand what you're building, why you're building it, and how it fits into the existing landscape.
Benefits of Plan-First
- Catches design flaws before they become code
- Creates reviewable artifacts for team alignment
- Generates a clear todo list from approved plans
- Reduces context-switching during implementation
- Provides natural checkpoints for scope validation
Workflow
Trigger Phrases
| Phrase | Action |
|---|---|
"make a plan for X" |
Create new plan in _PLANS/X.md |
"let's implement X" |
Load plan, break it into todos, start work |
/plan-idea |
Graduate idea from GARDEN to _PLANS/ |
Plan Structure
Plans use SCREAMING_SNAKE_CASE.md filenames to distinguish them from other documentation. A well-formed plan includes:
# Add User Authentication
## Goal
Implement JWT-based authentication with secure
session management.
## Context
- Current state: No auth, all routes public
- Desired state: Protected routes, role-based access
## Implementation Steps
1. [ ] Add auth dependencies (jsonwebtoken, bcrypt)
2. [ ] Create User model with password hashing
3. [ ] Implement login/register endpoints
4. [ ] Add JWT middleware for route protection
5. [ ] Update existing routes with auth guards
## Technical Decisions
- JWT in httpOnly cookies (not localStorage)
- 15-minute access tokens, 7-day refresh tokens
- Argon2 for password hashing
## Testing Strategy
- Unit tests for auth utilities
- Integration tests for auth flow
- E2E tests for protected routes
## Rollback Plan
- Feature flag to disable auth
- Database migration reversibleUnderstand Before Planning
If you're planning something unfamiliar, take time to read the relevant code and docs first, then incorporate what you learn directly into the plan's Context section.
Implementation Phase
When you say "let's implement X", Farmwork:
- Loads the plan from _PLANS/
- Breaks the implementation steps into a todo list
- Works through the todos systematically
- Updates the plan's checkboxes as work progresses
This plan-first approach ensures every piece of work is tracked, providing full visibility into progress before anything is deleted.
Lifecycle
Unlike most Farmwork documents, plans are temporary. They exist only during the planning and implementation phases:
- Created: When you say "make a plan for..."
- Reviewed: You read, suggest changes, iterate
- Executed: When you say "let's implement..."
- Deleted: After successful implementation
Plans Don't Persist
Once implementation is complete, the plan is deleted. The git history preserves what was done. If you need to reference the approach later, check the commit messages.