Agent Modes

You: "Add a user profile page with editable fields for name, email, and bio"

Agent: [Code Mode - Default]
"I'll create a user profile feature. Let me:
1. Create UserProfile component
2. Add form with validation
3. Connect to user API
4. Add update functionality
5. Include loading and error states
6. Generate tests"

[Creates multiple files, implements feature]

You: "This UserService class has too many responsibilities.
     Break it into smaller, focused services."

Agent: [Code Mode]
"I'll refactor UserService into:
- UserAuthService (authentication)
- UserProfileService (profile management)
- UserPreferencesService (settings)
- UserService (coordination)

Should I proceed?"

You: "Add input validation to all form components"

Agent: [Code Mode - High Confidence]
"Found 8 form components. Adding validation using your
established pattern (Yup schemas + custom error messages).

Working autonomously..."
[Adds validation to all forms, generates tests]
"Complete! All forms now have validation."

You: "@mode debug
     The app crashes when users upload files larger than 5MB"

Agent: [Debug Mode Activated]
"Investigating file upload crash. Let me check:

1. File upload handler
2. Memory limits
3. Server configuration
4. Error logs

Reading relevant files..."

[After analysis]
"Found the issue! Root cause analysis:

Primary Cause (90% confidence):
- No file size validation before upload
- Server default limit is 1MB (express default)
- Large files cause memory overflow

Contributing Factors:
- Missing error handling in upload route
- No user feedback during upload

Recommended fixes:
1. Add file size check on client (prevent upload)
2. Configure express fileSize limit
3. Add progress indicator
4. Improve error messages

Should I implement these fixes?"

You: "@mode debug
     Users are seeing negative prices in their shopping cart"

Agent: [Debug Mode]
"Investigating negative price issue.

Hypothesis Generation:
1. Discount calculation error (75% confidence)
2. Currency conversion issue (15% confidence)
3. Database corruption (5% confidence)
4. Race condition in cart updates (5% confidence)

Let me examine the discount calculation logic..."

[Reads files, traces data flow]

"Found it! In calculateDiscount():
- Discount percentage applied twice
- First in CartService.addItem()
- Again in CartService.calculateTotal()

This causes discounts over 50% to result in negative prices.

Example:
Item: $100, Discount: 60%
First application: $100 - $60 = $40
Second application: $40 - $60 = -$20

Fix: Remove duplicate discount application.
Location: src/services/CartService.ts:line 145

Should I apply the fix and add tests to prevent regression?"

You: "@mode debug
     Tests are failing after my changes to the auth system"

Agent: [Debug Mode]
"Analyzing test failures...

Failed Tests: 12 of 15 auth tests
Pattern detected: All failures related to token validation

Root Cause:
Your changes updated JWT token structure but tests
are using old token format.

Affected test files:
- auth.test.ts (8 tests)
- middleware.test.ts (4 tests)

Need to update:
1. Test token generation helpers
2. Mock JWT payloads
3. Token expiration expectations

I can fix all test mocks to match new format.
Proceed?"

"Users are getting a 500 error when they login"
[Agent automatically enters Debug Mode]

@mode debug
[Describes problem]

You: "@mode architect
     Help me design a notification system for our app"

Agent: [Architect Mode]
"Let me help design a notification system.

First, some questions:
1. What types of notifications? (Email, push, in-app, SMS?)
2. Scale expectations? (Users, notifications per day?)
3. Delivery requirements? (Real-time, scheduled, batched?)
4. Existing infrastructure? (Message queue, email service?)

[After your answers]

"Proposed Architecture:

## System Overview

```mermaid
graph TB
    A[App Events] --> B[Notification Service]
    B --> C{Notification Type}
    C -->|Email| D[Email Queue]
    C -->|Push| E[Push Queue]
    C -->|In-App| F[WebSocket Server]
    D --> G[Email Provider]
    E --> H[FCM/APNS]
    F --> I[Connected Clients]

erDiagram
    User ||--o{ NotificationPreference : has
    User ||--o{ Notification : receives
    Notification ||--|| NotificationTemplate : uses

    User {
        uuid id
        string email
        string phoneNumber
    }

    NotificationPreference {
        uuid id
        uuid userId
        string channel
        boolean enabled
        json settings
    }

    Notification {
        uuid id
        uuid userId
        string type
        string status
        timestamp sentAt
        json data
    }

**Database Design:**

erDiagram
    User ||--o{ Post : writes
    User ||--o{ Comment : writes
    Post ||--o{ Comment : has
    Post }o--o{ Tag : tagged_with
    Post }o--o{ Category : belongs_to
    Post ||--o{ PostRevision : has_revisions

    User {
        uuid id PK
        string email UK
        string username UK
        string passwordHash
        enum role
        timestamp createdAt
    }

    Post {
        uuid id PK
        uuid authorId FK
        string title
        string slug UK
        text content
        enum status
        timestamp publishedAt
        timestamp createdAt
        timestamp updatedAt
    }

    Comment {
        uuid id PK
        uuid postId FK
        uuid authorId FK
        uuid parentId FK
        text content
        timestamp createdAt
    }

    Tag {
        uuid id PK
        string name UK
        string slug UK
    }

    Category {
        uuid id PK
        string name UK
        string slug UK
        uuid parentId FK
    }

-- Performance critical indexes
CREATE INDEX idx_posts_author ON posts(authorId);
CREATE INDEX idx_posts_status_published ON posts(status, publishedAt);
CREATE INDEX idx_comments_post ON comments(postId);
CREATE INDEX idx_comments_author ON comments(authorId);

**System Planning:**

graph LR
    A[Load Balancer] --> B[API Server 1]
    A --> C[API Server 2]
    A --> D[API Server 3]
    B --> E[Database Primary]
    C --> E
    D --> E
    E --> F[Read Replica 1]
    E --> G[Read Replica 2]
    H[CDN] --> I[Static Assets]

### Architect Mode Features

**Visual Diagrams:**
- System architecture diagrams
- Database schemas (ERD)
- Sequence diagrams
- Component relationships

**Planning:**
- Phased implementation plans
- Risk assessment
- Trade-off analysis
- Technology recommendations

**Documentation:**
- Design decisions
- Architectural patterns
- Best practices
- Migration strategies

### Tips for Architect Mode

- Describe requirements clearly
- Mention scale/performance needs
- Discuss existing constraints
- Ask for multiple options
- Request diagrams for complex systems

---

## Ask Mode

**Purpose:** Getting explanations, learning, and understanding code.

### When to Use

- Understanding unfamiliar code
- Learning new concepts
- Researching approaches
- Getting documentation
- Exploring alternatives

### What It Does Well

✅ Explains code clearly
✅ Researches solutions
✅ Provides examples
✅ Links to documentation
✅ Compares alternatives

### Example Interactions

**Understanding Code:**

import { useAuth } from '@/hooks/useAuth';

function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuth();

  if (!isAuthenticated) {
    return <LoginForm onLogin={login} />;
  }

  return (
    <div>
      <h1>Welcome, {user.name}!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

const { user, isAuthenticated, isLoading, login } = useAuth();

if (isLoading) {
  return <Spinner />;
}

**Learning Concepts:**

const expensiveValue = useMemo(() => {
  return complexCalculation(data);
}, [data]);

const handleClick = useCallback(() => {
  doSomething(value);
}, [value]);

// Filtering large array
const filteredUsers = useMemo(() =>
  users.filter(u => u.age > 18),
  [users]
);

// Callback for child component
const handleDelete = useCallback((id) => {
  deleteUser(id);
}, [deleteUser]);

return <UserList onDelete={handleDelete} />;

// ❌ Unnecessary - too simple
const sum = useMemo(() => a + b, [a, b]);

// ✅ Good - expensive operation
const primes = useMemo(() =>
  findPrimes(largeNumber),
  [largeNumber]
);

**Researching Solutions:**

const multer = require('multer');
const upload = multer({ dest: 'uploads/' });

app.post('/upload', upload.single('file'), (req, res) => {
  console.log(req.file); // uploaded file info
  res.send('File uploaded');
});

const formidable = require('formidable');

app.post('/upload', (req, res) => {
  const form = formidable({ uploadDir: './uploads' });
  form.parse(req, (err, fields, files) => {
    // handle upload
  });
});

const multer = require('multer');

// Configure storage
const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, 'uploads/')
  },
  filename: function (req, file, cb) {
    cb(null, Date.now() + '-' + file.originalname)
  }
});

// Configure upload
const upload = multer({
  storage: storage,
  limits: {
    fileSize: 5 * 1024 * 1024 // 5MB
  },
  fileFilter: function (req, file, cb) {
    // Only allow images
    if (!file.mimetype.startsWith('image/')) {
      return cb(new Error('Only images allowed'));
    }
    cb(null, true);
  }
});

// Use in route
app.post('/upload', upload.single('avatar'), (req, res) => {
  res.json({
    success: true,
    file: req.file
  });
});

### Ask Mode Features

**Clear Explanations:**
- Step-by-step breakdowns
- Visual examples
- Comparisons
- Best practices

**Research Capabilities:**
- Web search
- Documentation lookup
- GitHub examples
- Stack Overflow solutions

**Learning-Focused:**
- No file modifications
- Read-only mode
- Safe to ask anything
- Encourages exploration

### Tips for Ask Mode

- Ask specific questions
- Provide context about your project
- Request examples
- Ask for comparisons ("X vs Y")
- Don't hesitate to ask follow-ups

---

## Orchestrator Mode

**Purpose:** Coordinating complex workflows that involve multiple modes.

### When to Use

- Complex projects requiring multiple approaches
- Tasks that need planning + execution
- Multi-phase implementations
- Cross-cutting concerns

### What It Does Differently

**Regular Modes:**
- Focus on specific task type
- Single approach
- Direct execution

**Orchestrator Mode:**
- Coordinates multiple modes
- Strategic planning
- Delegates to appropriate modes
- Synthesizes results

### Example Interactions

**Complex Migration:**

**Full-Stack Feature:**

### Orchestrator Mode Features

**Strategic Coordination:**
- Breaks down complex projects
- Delegates to specialized modes
- Maintains context across modes
- Synthesizes results

**Progress Tracking:**
- Shows current phase
- Mode being used
- Completion percentage
- Next steps

**Adaptive Planning:**
- Adjusts plan based on findings
- Handles unexpected issues
- Reprioritizes as needed

### Tips for Orchestrator Mode

- Use for genuinely complex projects
- Trust the agent to coordinate
- Review plans before full execution
- Provide feedback between phases

---

## Switching Between Modes

### Automatic Mode Switching

The agent often switches modes automatically based on your request:

### Manual Mode Switching

Force a specific mode:

### Mid-Conversation Switching

---

## Mode Comparison

### By Speed

**Fastest:** Code Mode (high confidence tasks)
**Fast:** Ask Mode (read-only)
**Medium:** Debug Mode (investigation takes time)
**Slower:** Architect Mode (thorough planning)
**Slowest:** Orchestrator Mode (coordinates multiple phases)

### By Autonomy

**Most Autonomous:** Code Mode (with learned patterns)
**Moderate:** Debug Mode (needs to investigate)
**Less Autonomous:** Architect Mode (needs decisions)
**Interactive:** Ask Mode (question/answer)
**Coordinating:** Orchestrator Mode (manages other modes)

### By File Modifications

**Heavy Modifications:** Code Mode, Orchestrator Mode
**Targeted Modifications:** Debug Mode
**No Modifications:** Ask Mode
**Creates Documentation:** Architect Mode

---

## Best Practices

### 1. Let Agent Choose Mode

Unless you have a specific reason, let the agent auto-select:

### 2. Switch When Needed

If the agent isn't approaching the problem right:

### 3. Use Orchestrator for Big Projects

### 4. Ask Mode for Learning

### 5. Debug Mode for Problems

---

## Troubleshooting Modes

### "Agent is in wrong mode"

**Switch manually:**

### "Agent keeps switching modes"

**This is normal for complex tasks.** Orchestrator mode does this intentionally.

### "Mode isn't working as expected"

**Try being more specific:**

---

## Next Steps

- Learn about [How to Use](./how-to-use) for practical examples
- Read [Best Practices](../agent-guide/best-practices) for expert tips
- See [Examples](./examples) for real-world mode usage
- Explore [AGI Capabilities](../agent-guide/agi-capabilities) for advanced features

---

*Modes help the agent think differently about your problem. Choose the right tool for the job, or let the agent decide!*