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 (tracked in beads issues). 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 clear beads issues 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, create Epic + issues, start work |
"let's plan this idea: X" |
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
- Research: See _RESEARCH/JWT_AUTH.md
## 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 reversibleResearch First
Plans often reference research documents. If you're planning something unfamiliar, run "let's research X" first to gather context, then incorporate findings into your plan.
Implementation Phase
When you say "let's implement X", Farmwork:
- Loads the plan from _PLANS/
- Creates a beads Epic for the overall feature
- Creates individual beads issues for each step
- Works through issues systematically
- Updates issue status as work progresses
This issue-first approach ensures every piece of work is tracked, providing full visibility into progress and a historical record of what was done.
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 beads issues and git history preserve what was done. If you need to reference the approach later, check the commit messages or issue descriptions.