Back to Post
Planning Before Coding: The Agent Workflow That Prevents Rewrites
1 / 1

TL;DR:

📖 Quick Start

The Problem: Coding Without Planning

You: “Add user authentication to the app”

Agent: Immediately starts editing files

30 minutes later:

What went wrong? The agent jumped straight to implementation without:

The fix: Plan first, code second.

The Planning Workflow

flowchart LR
    Todo[📝 todo/<br/>new-feature.md] --> Review{Oracle<br/>Review}
    Review -->|Simplify| Todo
    Review -->|Approved| Progress[🚧 in-progress/<br/>new-feature.md]
    Progress --> Code[Agent<br/>Implements]
    Code --> Update[Update<br/>Progress]
    Update --> Done{Success<br/>Criteria?}
    Done -->|No| Code
    Done -->|Yes| Complete[✅ completed/<br/>new-feature.md]

Step 1: Create a Plan

Before any code changes, create a plan file:

.agents/plans/todo/add-user-auth.md

What belongs in a plan:

Example plan structure:

# Add User Authentication

## Goal
Implement JWT-based authentication for API endpoints.

## Current State
- No auth system exists
- API endpoints are public
- User model exists in database

## Scope
**In scope:**
- JWT token generation/validation
- Login endpoint
- Protected route middleware
- Basic tests

**Out of scope (for now):**
- OAuth providers
- Password reset flow
- Email verification
- Rate limiting

## Steps
1. Research existing auth patterns in codebase
2. Add JWT library dependency
3. Create auth middleware
4. Implement login endpoint
5. Protect existing routes
6. Add tests
7. Update API documentation

## Success Criteria
- [ ] User can login with username/password
- [ ] Protected endpoints return 401 without token
- [ ] Protected endpoints work with valid token
- [ ] Tests pass
- [ ] Build succeeds

## Implementation Notes
- Use existing User model, don't create new tables
- Store JWT secret in environment variables
- Token expiry: 24 hours
- Test with curl before writing integration tests

Step 2: Consult the Oracle

Before starting work, ask Oracle to review the plan:

🔨 Try It Now: Oracle Plan Review

Task: Get Oracle feedback before coding

Prompt:

Oracle: review the plan in .agents/plans/todo/[your-feature].md

Focus on:
1. Is the scope minimal or over-engineered?
2. Are there simpler approaches I'm missing?
3. What should be deferred to later?
4. Are the steps in the right order?

Suggest a simplified version with core functionality only.

Verification:

Expected outcome: Plan is 30-50% simpler, focused on core value, ready to execute.

Oracle catches:

Oracle suggests:

Step 3: Move to In-Progress

Once plan is solid:

mv .agents/plans/todo/add-user-auth.md .agents/plans/in-progress/

This signals:

Step 4: Execute with Plan Context

Start a fresh thread with plan attached:

🔨 Try It Now: Mission Repeat-Back

Task: Ensure agent understands the plan before coding

Prompt:

Read the plan in @.agents/plans/in-progress/[feature].md

Before writing any code, repeat back to me:
1. The core goal in one sentence
2. The first 3 steps you'll take
3. What success looks like
4. What's explicitly out of scope

Then proceed with implementation.

Verification:

Expected outcome: No wasted work on wrong approach, plan stays in sync with reality.

Agent behavior changes:

Step 5: Keep Plan Updated

As work progresses, agent updates the plan:

## Steps
1. ✅ Research existing auth patterns in codebase
   - Found SessionManager pattern in /auth
   - Can reuse token validation helpers
2. ✅ Add JWT library dependency
   - Added jsonwebtoken@9.0.2
3. 🚧 Create auth middleware
   - In progress, using existing pattern
4. ⏸️ Implement login endpoint
...

Benefits:

Step 6: Move to Completed

When all success criteria are met:

mv .agents/plans/in-progress/add-user-auth.md .agents/plans/completed/

Update plan with results:

## Results
- Completed in 2 hours
- All tests passing
- Zero TypeScript errors
- API endpoints protected
- Documentation updated

## Learnings
- Reusing SessionManager saved 1 hour
- Middleware pattern was clearer than decorators
- Testing with curl caught token expiry bug early

## Follow-up Tasks
- Add OAuth providers (new plan)
- Implement password reset (new plan)
- Add rate limiting (new plan)

Why This Works

1. Prevents Thrash

Without plan:

Agent tries approach A → fails
Agent tries approach B → fails
Agent tries approach C → partially works
Agent rewrites everything → breaks other things

With plan:

Oracle reviews → suggests proven approach
Agent follows plan → works first time

2. Controls Scope

Plans make scope explicit. When agent suggests “while we’re here, let’s also add…”—the plan says “out of scope.”

3. Creates Checkpoints

Each step is a checkpoint. If something breaks, you know exactly where:

1. ✅ Add dependency
2. ✅ Create middleware
3. ❌ Implement login endpoint ← broke here

4. Enables Parallelization

Clear plans enable multiple agents:

Agent 1: .agents/plans/in-progress/add-auth.md
Agent 2: .agents/plans/in-progress/add-logging.md
Agent 3: .agents/plans/in-progress/fix-tests.md

Independent plans = no conflicts.

5. Builds Institutional Memory

Completed plans document:

Future work references past plans.

When to Skip Planning

Skip the plan for:

Always plan for:

Rule of thumb: If you can’t describe success in one sentence, write a plan.

Common Planning Mistakes

Mistake 1: Too Much Detail

Bad:

Step 1: Import jwt library on line 3 of auth.ts
Step 2: Create function validateToken with parameters...

Good:

Step 1: Create auth middleware using jwt library
Step 2: Add token validation helper

Plans guide direction, not dictate every keystroke.

Mistake 2: No Success Criteria

Bad:

## Steps
1. Add authentication
2. Add tests

Good:

## Success Criteria
- [ ] User can login with username/password
- [ ] Invalid credentials return 401
- [ ] Protected endpoints require valid token
- [ ] npm test passes
- [ ] npm run build succeeds

Success criteria tell you when to stop.

Mistake 3: Skipping Oracle Review

You write a plan, skip Oracle review, agent codes for an hour, then Oracle points out a 5-minute alternative.

Always: Oracle reviews plans before coding starts.

Mistake 4: Not Updating Plans

Plan becomes stale, agent improvises, chaos returns.

Fix: Agent updates plan after each major step.

Planning Templates

Feature Template

# [Feature Name]

## Goal
[What and why]

## Current State
[What exists]

## Scope
**In scope:**
- [Thing 1]
- [Thing 2]

**Out of scope:**
- [Thing 3]
- [Thing 4]

## Steps
1. [Step 1]
2. [Step 2]

## Success Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Implementation Notes
[Key principles, pitfalls, testing]

Bug Fix Template

# Fix: [Bug Description]

## Problem
[What's broken]

## Root Cause
[Why it's broken]

## Solution Approach
[How to fix]

## Steps
1. [Step 1]
2. [Step 2]

## Verification
- [ ] [Test case 1]
- [ ] [Test case 2]
- [ ] [Regression tests pass]

Refactor Template

# Refactor: [What]

## Current State
[How it works now]

## Problems
- [Problem 1]
- [Problem 2]

## Target State
[How it should work]

## Migration Strategy
[How to get there safely]

## Success Criteria
- [ ] [Functionality unchanged]
- [ ] [Tests pass]
- [ ] [Performance improved]

The Planning Habit

Your workflow becomes:

  1. User requests feature
  2. Create plan in .agents/plans/todo/
  3. Oracle reviews and simplifies
  4. Move to .agents/plans/in-progress/
  5. Agent implements with plan context
  6. Agent updates plan with progress
  7. Verify success criteria
  8. Move to .agents/plans/completed/
  9. Update plan with results

Time investment:

Quality improvement:

Real Example: This Blog

Without planning:

With planning:

# Add Blog Posts About Agent Workflows

## Goal
Publish 4 posts about agent best practices

## Steps
1. Create post files with frontmatter
2. Set draft: false
3. Test build locally
4. Verify posts appear on /posts page
5. Commit and push

## Success Criteria
- [ ] npm run build succeeds
- [ ] All 4 posts visible at http://localhost:4321/posts
- [ ] Frontmatter valid
- [ ] Published to production

Result: Done in 15 minutes, zero issues.

Key Takeaways

What’s Next

You’ve completed the practice path! Now apply these patterns to your daily work.

Practice Path:

  1. What is an Agent
  2. First Win in 15 Minutes
  3. Workflows That Stick
  4. Power Patterns
  5. You are here: Planning Workflow

Related:

Standalone:

Challenge: Try it on your next feature. Create a plan, get Oracle review, then code. You’ll never go back.