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"
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
[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
- 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:
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.
