wit plan

Break down complex coding tasks into subtasks and execute them in parallel using specialized AI agents.

Overview

The plan command uses a multi-agent workflow to:

Analyze your task and codebase
Plan an execution strategy with parallel subtask groups
Execute subtasks using specialized AI agents
Review results and iterate if needed

This is ideal for large refactoring tasks, feature implementations, or any complex coding work that benefits from structured planning.

Usage

# Execute a complex task
wit plan "Add user authentication with JWT"

# Preview without executing
wit plan "Refactor database layer" --dry-run

# With additional context
wit plan "Add dark mode" -c "Use CSS custom properties"

# JSON output
wit plan "Fix all TypeScript errors" --json

# Check status
wit plan status

Options

Option	Alias	Description
`--dry-run`	`-n`	Preview plan without executing
`--verbose`	`-v`	Enable verbose output
`--no-stream`		Disable streaming output
`--no-branch`		Don’t create a feature branch
`--no-commit`		Don’t auto-commit changes
`--json`		Output results as JSON
`--max-iterations`	`-i`	Maximum planning iterations (default: 3)
`--max-parallel`	`-p`	Maximum parallel tasks (default: 5)
`--branch`	`-b`	Custom branch name
`--context`	`-c`	Additional context for planning

How It Works

1. Planner Agent

Analyzes your task and creates an execution plan:

Breaks the task into atomic subtasks
Identifies dependencies between subtasks
Groups independent subtasks for parallel execution
Estimates effort and risk

2. Executor Agents

Run subtasks in parallel within each group:

Read and understand relevant files
Make code changes incrementally
Follow existing code patterns
Report results

3. Reviewer Agent

Validates completed work:

Checks if tasks met acceptance criteria
Identifies issues and inconsistencies
Determines if re-planning is needed

Examples

Feature Implementation

wit plan "Add user authentication with JWT"

Output:

 Multi-Agent Planning Workflow

Task: Add user authentication with JWT
Max iterations: 3
Max parallel tasks: 5

Starting workflow...
------------------------------------------------------------

 Step: analyze-task
    Completed: analyze-task

 Step: create-plan
    Completed: create-plan

 Step: execute-plan
    Completed: execute-plan

 Step: review-results
    Completed: review-results

------------------------------------------------------------

Workflow completed. Run with --json for full results.

Dry Run Preview

wit plan "Refactor the database layer to use connection pooling" --dry-run

Output:

[DRY RUN] Planning workflow will preview without executing changes.

 Multi-Agent Planning Workflow

Task: Refactor the database layer to use connection pooling

============================================================
WORKFLOW RESULTS
============================================================

Status:  Success
Total iterations: 1
Total duration: 2.34s

 Execution Plan:
   Summary: Implement connection pooling by creating a pool manager, updating queries, and adding configuration
   Groups: 3

   Group 1: Foundation
       [DRY RUN] Create connection pool types and interfaces
       [DRY RUN] Add pool configuration options

   Group 2: Implementation
       [DRY RUN] Implement pool manager class
       [DRY RUN] Update database queries to use pool

   Group 3: Integration
       [DRY RUN] Add pool lifecycle management
       [DRY RUN] Update configuration loading

[DRY RUN] Would execute 6 subtasks in 3 groups

With Context

wit plan "Implement dark mode" -c "Use CSS custom properties and respect system preferences"

JSON Output

wit plan "Fix all TypeScript errors" --json

Returns structured JSON with:

Plan details
Execution results
Files modified
Commits created

Execution Plan Structure

The planner creates a structured execution plan:

{
  "id": "plan-1234567890",
  "version": 1,
  "originalTask": "Add user authentication",
  "summary": "Implement JWT auth in 3 phases",
  "parallelGroups": [
    {
      "id": "group-1",
      "name": "Foundation",
      "executionOrder": 1,
      "subtasks": [
        {
          "id": "task-1",
          "title": "Create auth types",
          "description": "Define User, Token, and Session types",
          "priority": "high",
          "estimatedEffort": "small",
          "dependencies": [],
          "targetFiles": ["src/types/auth.ts"],
          "acceptanceCriteria": [
            "Types are exported",
            "Types include all required fields"
          ]
        }
      ]
    }
  ],
  "estimatedTotalEffort": "2-3 hours"
}

Status Command

Check AI availability and workflow status:

wit plan status

Output:

 Multi-Agent Planning Status

AI Available:  Yes
Model: anthropic/claude-opus-4-5
Provider: anthropic

Workflow Components:
   Planner Agent - Breaks down tasks into subtasks
   Executor Agents - Run subtasks in parallel
   Reviewer Agent - Validates results and triggers re-planning

Capabilities:
   Iterative task planning
   Parallel subtask execution
   Automatic dependency management
   Result validation and re-planning
   Branch creation and auto-commit

Git Integration

By default, wit plan:

Creates a feature branch (e.g., ai-planning/add-auth-lxk4m2n7)
Executes subtasks
Commits changes after each group
Leaves you on the feature branch

Disable with --no-branch and --no-commit.

Environment Variables

Variable	Description
`OPENAI_API_KEY`	OpenAI API key (for GPT models)
`ANTHROPIC_API_KEY`	Anthropic API key (for Claude models)
`WIT_AI_MODEL`	Model to use (default: anthropic/claude-opus-4-5)

Tips

Start with --dry-run to preview the plan before executing. This helps you understand what changes will be made.

Use --context to provide important constraints or preferences that should guide the implementation.

For large tasks, increase --max-parallel to speed up execution (if your API rate limits allow).

The plan command modifies files and creates commits. Always review the changes before pushing.

wit agent - Interactive AI agent
wit ai - AI-powered commands
wit review - AI code review

Get Started

Commands

Visual Interfaces

AI & Intelligence

Workflows

GitHub & Team

Advanced

Configuration

Platform

Architecture

Database

plan

wit plan

Overview

Usage

Options

How It Works

1. Planner Agent

2. Executor Agents

3. Reviewer Agent

Examples

Feature Implementation

Dry Run Preview

With Context

JSON Output

Execution Plan Structure

Status Command

Git Integration

Environment Variables

Tips

​wit plan

​Overview

​Usage

​Options

​How It Works

​1. Planner Agent

​2. Executor Agents

​3. Reviewer Agent

​Examples

​Feature Implementation

​Dry Run Preview

​With Context

​JSON Output

​Execution Plan Structure

​Status Command

​Git Integration

​Environment Variables

​Tips

​Related Commands

wit plan

Overview

Usage

Options

How It Works

1. Planner Agent

2. Executor Agents

3. Reviewer Agent

Examples

Feature Implementation

Dry Run Preview

With Context

JSON Output

Execution Plan Structure

Status Command

Git Integration

Environment Variables

Tips

Related Commands