Planning

Kavi can decompose complex work into structured execution plans. Plans are directed acyclic graphs (DAGs) of tasks with dependency tracking, multiple execution modes, and a well-defined lifecycle.

Automatic vs Manual Planning

Kavi supports two planning modes:

• Automatic -- Kavi detects that a request is complex and triggers planning automatically
• Manual -- You explicitly request a plan by asking Kavi to "plan" or "break down" a task

In both cases, Codex materializes the execution graph. Codex is the designated planner because of its strength in architecture and decomposition.

Execution Graphs (DAGs)

A plan is a directed acyclic graph where each node is a task and edges represent dependencies. This structure ensures tasks execute in a valid order while maximizing parallelism.

┌──────────────┐
│ Setup DB     │
│ (codex)      │
└──────┬───────┘
       │
  ┌────┴────┐
  │         │
  ▼         ▼
┌─────┐  ┌──────────┐
│ API │  │ Auth     │
│(codex)│ │(codex)   │
└──┬──┘  └────┬─────┘
   │          │
   └────┬─────┘
        │
        ▼
  ┌───────────┐
  │ UI Pages  │
  │ (claude)  │
  └─────┬─────┘
        │
        ▼
  ┌───────────┐
  │ Integration│
  │ Tests     │
  └───────────┘

Task Properties

Each task in a plan includes:

• ID -- unique identifier (ULID)
• Description -- what the task should accomplish
• Agent -- which agent should execute it (codex or claude)
• Dependencies -- list of task IDs that must complete first
• Execution mode -- how the task relates to others temporally
• Path claims -- files and directories the task will modify
• Status -- current state (pending, active, completed, blocked, failed)

Execution Modes

Tasks can run in three modes:

Blocking

The task must complete before any dependent tasks can start. This is the default mode for tasks with dependencies.

Parallel

The task can run concurrently with other parallel tasks that share no dependencies. Kavi automatically identifies parallelizable tasks from the DAG structure.

Follow-up

The task is scheduled after its parent task completes, typically for verification, review, or cleanup work. Follow-up tasks are created automatically from review comments or manually by the operator.

Path Claims

Each task in a plan declares which files and directories it intends to modify. Path claims serve multiple purposes:

• Conflict detection -- Kavi warns if two concurrent tasks claim overlapping paths
• Routing validation -- Claims are checked against routing rules for consistency
• Worktree isolation -- Claims inform the worktree manager about expected file changes

Task: "Build user API"
  Claims: ["src/backend/routes/users.ts", "src/backend/models/user.ts", "prisma/schema.prisma"]
  Agent: codex
  Mode: blocking

Plan Lifecycle

Plans move through a well-defined set of states:

Draft

The plan has been generated but not yet approved by the operator. In draft state, you can:

• Review the proposed task breakdown
• Modify task descriptions or dependencies
• Add or remove tasks
• Change agent assignments
• Adjust execution modes

Active

The plan has been approved and execution has begun. The daemon schedules tasks according to the DAG, respecting dependencies and execution modes. Tasks transition through their own states (pending, active, completed, failed) as execution progresses.

Completed

All tasks in the plan have completed successfully. Landing can proceed.

Blocked

One or more tasks have failed or are waiting on operator input. The plan pauses until the blocking condition is resolved. You can:

• Retry failed tasks
• Skip blocked tasks
• Modify the plan and re-activate

Planner Task

The planner itself is a special task that runs in Codex. When planning is triggered, Kavi:

1. Creates a planner task with the original request as context
2. Sends the request to Codex with planning instructions
3. Receives a structured plan (tasks, dependencies, claims)
4. Validates the plan for DAG integrity (no cycles, valid dependencies)
5. Presents the plan to the operator for review

The planner task appears in the TUI like any other task, so you can observe the planning process in real time.

Modifying Active Plans

Plans can be modified during execution:

• Add tasks -- insert new tasks with dependencies on existing ones
• Cancel tasks -- remove pending tasks from the plan
• Re-route tasks -- change the assigned agent for a pending task
• Add dependencies -- introduce new ordering constraints

Modifications to active plans are validated to ensure the DAG remains acyclic and all dependencies are satisfiable.