Mode 1: Planning Mode

Purpose: Analysis and planning without making changes.

Characteristics:

Read-only operations
Focus on understanding the codebase
Create plans and strategies
Identify affected components

Allowed Tools:

Read - Read files
Glob - Find files
Grep - Search content
Bash - Read-only commands (ls, cat, git status, git log)

Excluded Tools:

Write - No file creation
Edit - No file modification
Bash - No commands that modify state
NotebookEdit - No notebook changes

When to Use:

Starting work on unfamiliar tasks
Analyzing complex bugs
Planning architectural changes
Understanding dependencies before refactoring

Example Prompt:

You are operating in PLANNING MODE.

Your task is to analyze the codebase but NOT write any code.
Focus on:
- Understanding the current implementation
- Identifying affected components
- Creating a comprehensive plan
- Documenting your findings

Do NOT:
- Create new files
- Modify existing files
- Run commands that change state

Mode 2: Editing Mode

Purpose: Full implementation capability.

Characteristics:

Full write access
Implementation focus
Test-driven when appropriate
Follows established patterns

Allowed Tools:

All read tools
Write - Create files
Edit - Modify files
Bash - All safe commands (build, test, lint)
NotebookEdit - Modify notebooks

Excluded Tools:

Destructive bash commands (rm -rf, git reset --hard, etc.)

When to Use:

After planning is complete
When implementation path is clear
For well-defined tasks
During test-driven development

Example Prompt:

You are operating in EDITING MODE.

You have full capability to:
- Create new files
- Modify existing files
- Run build/test commands

Guidelines:
- Follow TDD: write test first, then implement
- Follow project conventions
- Run tests after changes
- Keep changes focused on the task

Mode 3: Interactive Mode

Purpose: User-guided development with frequent checkpoints.

Characteristics:

Pause for user approval before major changes
Explain options before proceeding
Smaller, incremental changes
More user involvement

Allowed Tools:

All tools available
Frequent use of AskUserQuestion

Behavior:

Explain what you're about to do before doing it
Present options when multiple approaches exist
Ask for confirmation before significant changes
Provide clear progress updates

When to Use:

Learning user preferences
High-risk changes
Unclear requirements
When user wants to stay involved

Example Prompt:

You are operating in INTERACTIVE MODE.

Before any significant action:
1. Explain what you plan to do
2. Present alternatives if they exist
3. Wait for user confirmation
4. Make the change
5. Report the result

Always keep the user informed and in control.

Mode 4: One-Shot Mode

Purpose: Single-task execution without follow-up.

Characteristics:

Optimized for quick, focused tasks
Minimal interaction
Complete task fully before stopping
No iterative refinement expected

Allowed Tools:

All tools as appropriate

Behavior:

Understand the complete task upfront
Execute fully
Provide comprehensive summary at end

When to Use:

Simple, well-defined tasks
Automation scripts
Batch operations
When user won't be monitoring

Example Prompt:

You are operating in ONE-SHOT MODE.

Complete the following task fully in a single execution:
- Analyze requirements
- Implement solution
- Validate/test
- Summarize changes

Do not expect follow-up interaction.

Mode Transitions

Planning -> Editing

Transition when:

Plan is complete
User has approved approach
All unknowns are resolved

## Mode Transition: Planning -> Editing

**Planning Summary**:

- Analyzed: [files/components]
- Plan: [brief description]
- Affected: [components list]

**Ready to implement**: [yes/no]
**Blockers**: [none / list blockers]

Transitioning to EDITING MODE.

Editing -> Planning

Transition when:

Unexpected complexity discovered
Scope expansion needed
Architectural questions arise

## Mode Transition: Editing -> Planning

**Reason**: Discovered unexpected dependency
**Need to analyze**: [what needs investigation]

Returning to PLANNING MODE for analysis.

Any -> Interactive

Transition when:

User requests involvement
High-risk decision point
Multiple valid approaches

## Mode Transition: -> Interactive

**Reason**: Multiple valid approaches identified
**Options**:

1. Approach A - [pros/cons]
2. Approach B - [pros/cons]

Entering INTERACTIVE MODE for user decision.

Integration with Task System

When using tasks, note the current mode:

TaskCreate({
  subject: 'Implement user validation',
  description: '...',
  metadata: { mode: 'editing' },
});

TaskUpdate({
  taskId: '1',
  metadata: { mode: 'planning', reason: 'Need architectural review' },
});

Self-Assessment Checklist

Before changing modes, verify:

Entering Planning Mode:

Task requires analysis
Don't have enough information to proceed
Complex decision points ahead

Entering Editing Mode:

Plan is complete
Approach is decided
User has approved (if required)

Entering Interactive Mode:

User involvement needed
Multiple options to present
High-risk or unclear situation

Agent Response:

This is a significant task. I'll start in PLANNING MODE.

## Planning Mode Analysis

### Current Understanding
Reading authentication-related files...
- auth.ts - Main authentication logic
- session.ts - Session management
- middleware/auth.ts - Auth middleware

### Observations
- Current: Custom JWT implementation
- Dependencies: 12 files import from auth.ts
- Tests: 24 tests in auth.test.ts

### Plan
1. Identify all auth touchpoints
2. Design new interface (minimal breaking changes)
3. Implement with backwards compatibility
4. Migrate consumers gradually

### Questions
Before proceeding to EDITING MODE:
1. Should I preserve the current API or is breaking change OK?
2. Target deadline/timeline?

Awaiting your input before transitioning modes.

</usage_example>

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern discovered -> .claude/context/memory/learnings.md
Issue encountered -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

operational-modes

Overview

Available Modes