Plan Mode Guide

Plan Mode is ByteBuddy's advanced feature that enables complex task planning and multi-step execution. This guide explains how to leverage Plan Mode to break down complex development tasks into manageable steps.

What is Plan Mode?

Plan Mode allows ByteBuddy to:

• Break complex tasks into smaller, executable steps
• Create detailed implementation plans
• Execute multi-step workflows automatically
• Track progress and handle errors gracefully

Enabling Plan Mode

Basic Configuration

Enable Plan Mode in your configuration:

# .bytebuddy/config.yaml
planMode:
  enabled: true
  maxSteps: 20
  timeout: 300 # 5 minutes

Advanced Settings

Fine-tune Plan Mode behavior:

planMode:
  enabled: true
  maxSteps: 50
  timeout: 600 # 10 minutes
  retryAttempts: 3
  confirmationRequired: true # Require approval before execution

  # Step execution settings
  executeStepsAutomatically: true
  parallelExecution: false # Execute steps sequentially by default

  # Error handling
  onError: "pause" # pause, continue, abort
  rollbackOnError: true

Using Plan Mode

Activating Plan Mode

Trigger Plan Mode through chat:

"Please implement a user authentication system with login, registration, and password reset features. Use Plan Mode to break this down."

Or use the explicit command:

"@plan Create a REST API for a todo application with full CRUD operations"

Plan Generation

When Plan Mode is activated, ByteBuddy will:

1. Analyze the Request: Understand the scope and requirements
2. Break Down Tasks: Divide the request into discrete steps
3. Create a Plan: Present a detailed execution plan
4. Request Confirmation: Ask for approval before proceeding

Example plan output:

Plan for User Authentication System:

1. Create user model/schema
2. Implement user registration endpoint
3. Implement user login endpoint
4. Implement password reset functionality
5. Add email verification
6. Implement JWT token generation
7. Add middleware for authentication
8. Create unit tests for all endpoints
9. Update API documentation
10. Deploy to staging environment

Estimated time: 2-3 hours

Plan Configuration

Custom Plan Templates

Define reusable plan templates:

planMode:
  enabled: true
  templates:
    - name: "web-api"
      description: "Template for web API development"
      steps:
        - "Define API endpoints and schemas"
        - "Create database models"
        - "Implement controllers"
        - "Add middleware"
        - "Write unit tests"
        - "Create integration tests"
        - "Document API"
        - "Deploy to staging"

    - name: "react-component"
      description: "Template for React component development"
      steps:
        - "Define component props and state"
        - "Create component structure"
        - "Implement styling"
        - "Add unit tests"
        - "Create storybook stories"
        - "Document component usage"
        - "Integrate with application"

Plan Constraints

Set constraints for plan execution:

planMode:
  enabled: true
  constraints:
    maxExecutionTime: 3600 # 1 hour
    maxApiCalls: 100
    maxFileModifications: 50
    allowedFileTypes:
      - ".js"
      - ".ts"
      - ".jsx"
      - ".tsx"
      - ".md"
    restrictedDirectories:
      - "/production"
      - "/secrets"

Step Execution

Manual vs Automatic Execution

Control how steps are executed:

planMode:
  enabled: true
  execution:
    mode: "interactive" # automatic, interactive, manual

    # Interactive mode settings
    interactive:
      askBeforeEachStep: true
      showDiffBeforeApply: true
      requireFinalConfirmation: true

    # Automatic mode settings
    automatic:
      executeWithoutPrompt: true
      logAllActions: true
      sendCompletionNotification: true

Step Dependencies

Define dependencies between steps:

planMode:
  enabled: true
  stepDependencies:
    - step: "implement-login"
      dependsOn:
        - "create-user-model"
        - "setup-database-connection"

    - step: "add-jwt-authentication"
      dependsOn:
        - "implement-login"

    - step: "create-unit-tests"
      dependsOn:
        - "implement-login"
        - "add-jwt-authentication"

Advanced Plan Features

Conditional Steps

Add conditional logic to plans:

planMode:
  enabled: true
  conditionalSteps:
    - condition: "projectType === 'react'"
      steps:
        - "create-react-component"
        - "add-storybook-story"

    - condition: "projectType === 'nodejs'"
      steps:
        - "create-express-route"
        - "add-middleware"

    - condition: "needsDatabase"
      steps:
        - "setup-database-connection"
        - "create-models"

Parallel Execution

Execute independent steps in parallel:

planMode:
  enabled: true
  parallelExecution:
    enabled: true
    maxParallelSteps: 5

    # Define which steps can run in parallel
    parallelGroups:
      - steps:
          - "create-models"
          - "setup-database-connection"
          - "configure-logging"
        maxConcurrent: 3

      - steps:
          - "write-unit-tests"
          - "create-documentation"
        maxConcurrent: 2

Integration with Other Features

Plan Mode and RAG

Enhance plans with RAG context:

planMode:
  enabled: true
  ragIntegration:
    enabled: true
    contextSources:
      - "similarProjects"
      - "bestPractices"
      - "frameworkGuidelines"

    # Use RAG to inform plan decisions
    adaptivePlanning:
      enabled: true
      adjustBasedOn:
        - "codebaseComplexity"
        - "teamExperience"
        - "projectRequirements"

Plan Mode and Continuous AI

Combine with Continuous AI workflows:

continuousAI:
  enabled: true
  workflows:
    - name: "automated-feature-development"
      trigger:
        eventType: "featureRequest"
      actions:
        - action: "createPlan"
          mode: "plan-mode"
          template: "web-api"

        - action: "executePlan"
          confirmationRequired: false

        - action: "reviewResults"
          rules:
            - "code-quality"
            - "security-best-practices"

Plan Monitoring and Control

Progress Tracking

Monitor plan execution progress:

planMode:
  enabled: true
  monitoring:
    enabled: true
    trackProgress: true
    updateFrequency: "30s"

    notifications:
      onStepCompletion: true
      onPlanCompletion: true
      onError: true
      progressUpdates: "hourly"

Pause and Resume

Control plan execution:

planMode:
  enabled: true
  executionControl:
    pauseCapability: true
    resumeCapability: true
    cancelCapability: true

    # Save state for resume
    statePersistence:
      enabled: true
      storageLocation: "~/.bytebuddy/plans"

Example Plans

Web API Development Plan

planMode:
  enabled: true
  examples:
    - name: "todo-api"
      description: "REST API for todo application"
      steps:
        1:
          name: "define-api-spec"
          description: "Create OpenAPI specification"
          estimatedTime: "30m"

        2:
          name: "setup-project"
          description: "Initialize project structure"
          estimatedTime: "15m"

        3:
          name: "create-models"
          description: "Define database models"
          estimatedTime: "45m"

        4:
          name: "implement-controllers"
          description: "Create route handlers"
          estimatedTime: "2h"

        5:
          name: "add-validation"
          description: "Implement input validation"
          estimatedTime: "1h"

        6:
          name: "write-tests"
          description: "Create unit and integration tests"
          estimatedTime: "2h"

        7:
          name: "document-api"
          description: "Update API documentation"
          estimatedTime: "1h"

        8:
          name: "deploy-staging"
          description: "Deploy to staging environment"
          estimatedTime: "30m"

React Component Plan

planMode:
  enabled: true
  examples:
    - name: "dashboard-component"
      description: "Complex dashboard React component"
      steps:
        1:
          name: "design-component-api"
          description: "Define props, state, and callbacks"
          estimatedTime: "30m"

        2:
          name: "create-component-structure"
          description: "Implement basic component structure"
          estimatedTime: "1h"

        3:
          name: "add-styling"
          description: "Implement component styling"
          estimatedTime: "1h"

        4:
          name: "implement-functionality"
          description: "Add interactive features"
          estimatedTime: "2h"

        5:
          name: "add-error-handling"
          description: "Implement error boundaries and handling"
          estimatedTime: "45m"

        6:
          name: "write-tests"
          description: "Create unit and integration tests"
          estimatedTime: "1.5h"

        7:
          name: "create-storybook"
          description: "Add Storybook stories"
          estimatedTime: "1h"

        8:
          name: "document-usage"
          description: "Create usage documentation"
          estimatedTime: "30m"

Troubleshooting

Common Issues

Plan Generation Failures

1. Unclear Requirements: Provide more specific details
2. Overly Complex Tasks: Break tasks into smaller pieces
3. Missing Context: Ensure adequate codebase context

Execution Errors

1. Permission Issues: Check file and directory permissions
2. Dependency Problems: Verify all dependencies are available
3. Resource Limits: Adjust timeout and resource settings

Debugging Commands

# View current plan status
bytebuddy plan status

# List available plan templates
bytebuddy plan templates

# Execute a specific plan
bytebuddy plan execute --template=web-api

# Pause current plan execution
bytebuddy plan pause

# Resume paused plan
bytebuddy plan resume

Best Practices

Plan Design

1. Start Simple: Begin with basic plans and add complexity
2. Be Specific: Clearly define each step's objectives
3. Estimate Time: Provide realistic time estimates
4. Include Testing: Always include testing steps

Execution Control

1. Use Interactive Mode: For complex or risky operations
2. Monitor Progress: Keep track of execution status
3. Review Changes: Examine diffs before applying changes
4. Backup First: Create backups before major changes

Template Management

1. Organize Templates: Group by project type or domain
2. Version Control: Track template changes
3. Share Templates: Make useful templates available to team
4. Refine Templates: Continuously improve based on results

Next Steps

After mastering Plan Mode, explore these related guides:

• Continuous AI - Automate development workflows
• Custom Code RAG - Optimize code context understanding
• Understanding Configs - Deep dive into all configuration options