Plan Mode

Plan mode is for complex tasks that need exploration and design before implementation. Write tools are blocked until you approve the plan.

When to Use

Use plan mode when:

• Building a new feature with multiple files
• Multiple approaches are possible and you want to choose
• The task affects existing architecture
• Requirements are unclear and need investigation
• You want to review the approach before any code is written

Skip plan mode for:

• Simple fixes (typos, small bugs)
• Tasks with clear, specific instructions
• Pure research questions

How It Works

1. Enter Plan Mode

I need to add authentication to the app. Enter plan mode.

Or use the slash command:

/plan

2. Explore & Design

Agent Nine will:

• Read relevant files to understand the codebase
• Search for patterns and conventions
• Analyze the architecture
• Write a plan to .agent-nine/plan.md

During this phase, write operations are blocked:

• ❌ Cannot edit files
• ❌ Cannot write files
• ❌ Cannot run commands
• ✅ Can read files
• ✅ Can search (glob, grep)
• ✅ Can browse the web

3. Review the Plan

The plan includes:

• Approach — High-level strategy
• Files to modify — Exact paths with descriptions
• Steps — Ordered implementation steps
• Verification — How to confirm it works

4. Approve & Implement

Agent Nine exits plan mode and starts implementing step by step. All tools are unblocked.

5. Verify

After implementation, run verification:

Verify the plan was executed correctly

This checks:

• Files mentioned in the plan exist
• Expected content is present
• Specified commands pass (typecheck, tests)

Plan File

Plans are saved to .agent-nine/plan.md in your project:

# Plan: Add JWT Authentication

_Created: 2026-04-15T10:30:00Z_

## Approach
Use jsonwebtoken library with refresh tokens...

## Files to modify
- `auth/jwt.ts` — New JWT utility
- `middleware/auth.ts` — Auth middleware
- `routes/login.ts` — Login endpoint

## Steps
1. Install jsonwebtoken dependency
2. Create JWT utility with sign/verify
3. Add auth middleware
4. Update login route
5. Add tests

## Verification
- `npm run typecheck` should pass
- `npm test` should pass
- Login endpoint returns JWT token

Tips

• Be specific about what you want to build
• Mention any constraints or preferences
• If the plan looks wrong, tell Agent Nine before approving
• Use /undo if implementation goes off track