1.2 Planning vs. Execution Separation & Plan Output

Planning vs. Execution Separation & Plan Output

In advanced AI developer agent architectures, decoupling the Planning Phase from the Execution Phase is a fundamental design principle for achieving reliable, deterministic, and safe software automation. Early AI coding assistants attempted single-pass execution, generating code edits and executing commands in an unguided, reactive loop. This often led to infinite file modification cycles, token exhaustion, context drift, and corrupt code states. By enforcing explicit structural separation between plan generation and plan execution, modern agent frameworks create clear inspection checkpoints, constrain resource usage, and establish verifiable state transitions across complex software engineering tasks.

The Two-Phase Agent Architecture

The decoupled agent framework separates cognitive reasoning from stateful system actions through two discrete runtime phases:

+-------------------------------------------------------------------+
|                        1. PLANNING PHASE                          |
|  Issue Description + Context Files --> LLM Planner --> Plan Output |
+-------------------------------------------------------------------+
                                  |
                                  v
                        [ Human Approval Gate ]
                                  |
                                  v
+-------------------------------------------------------------------+
|                       2. EXECUTION PHASE                          |
|  Plan Output --> Step Execution Loop --> Tool Calls --> Verified PR|
+-------------------------------------------------------------------+

Phase 1: The Planning Phase

During the planning phase, the agent operates in a read-only or low-privilege environment focused exclusively on context assembly and strategy synthesis:

1. Repository Discovery & AST Inspection: The agent traverses file trees, inspects configuration dependencies, reads documentation, and parses relevant source code to construct a comprehensive mental graph of the codebase.
2. Problem Decomposition: The agent breaks the high-level objective into atomic, sequentially ordered sub-tasks (e.g., "Create interface", "Implement concrete service", "Update dependency container", "Add unit tests").
3. Precondition & Dependency Mapping: The agent identifies preconditions required for each sub-task, specifying target file paths, expected inputs/outputs, and external package dependencies.
4. Plan Document Generation: The agent formats its strategy into a standardized, structured Plan Output artifact (Markdown or JSON schema) detailing exact file edits, command invocations, and verification checks.

Crucially, no files are modified and no stateful tool calls are executed during the planning phase.

Phase 2: The Execution Phase

Once the plan is generated (and optionally validated by a human reviewer or policy engine), the agent transitions into the execution phase:

1. Plan Ingestion & Validation: The execution engine parses the approved plan document and validates step prerequisites.
2. Deterministic Step Execution: The agent executes steps sequentially using targeted tool calls (e.g., view_file, replace_file_content, run_command).
3. Step-Level Pre/Post-Condition Checks: Before and after each action, the agent verifies system state. If a file edit fails linter rules or a build step throws errors, execution pauses immediately.
4. State Tracking & Rollback Management: The engine maintains a versioned transaction log of file modifications, allowing clean rollback to prior step checkpoints if unrecoverable failures occur.

Benefits of Decoupling Planning from Execution

Establishing a strict boundary between planning and execution yields major operational advantages for enterprise AI workflows:

Anatomy of a Production-Grade Plan Output Specification

A production-grade Plan Output must be machine-readable and human-auditable. It typically contains five standardized components:

1. Objective & Executive Summary: Concise description of the engineering goal and high-level strategy.
2. Scope & Target File Manifest: Explicit list of files created, modified, or deleted, alongside protected files that must remain untouched.
3. Sequential Task Breakdown: Ordered sub-tasks containing target files, exact change descriptions, and required tool calls.
4. Verification Strategy: Concrete test commands, linter checks, and expected success criteria for step validation.
5. Rollback & Failure Criteria: Conditions under which the execution phase must abort and revert state.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "planId": "plan-refactor-auth-v2",
  "objective": "Refactor token validation logic to support RS256 JWT signatures",
  "targetFiles": {
    "modify": ["src/auth/jwt.ts", "src/config/auth.json"],
    "create": ["tests/auth/jwt.test.ts"],
    "readOnly": ["src/interfaces/user.ts"]
  },
  "steps": [
    {
      "stepId": 1,
      "description": "Add RS256 public key verification method to JwtValidator",
      "targetFile": "src/auth/jwt.ts",
      "toolAction": "replace_file_content",
      "verificationCommand": "npm run test:unit tests/auth/jwt.test.ts"
    },
    {
      "stepId": 2,
      "description": "Update auth configuration schema to include algorithm parameters",
      "targetFile": "src/config/auth.json",
      "toolAction": "replace_file_content",
      "verificationCommand": "npm run lint"
    }
  ],
  "globalVerification": "npm test",
  "rollbackStrategy": "git checkout main -- src/auth/ src/config/"
}

Plan Re-Evaluation and Dynamic Replanning

While execution should remain deterministic, complex codebase realities sometimes invalidate initial planning assumptions (e.g., discovering an undocumented internal dependency during step execution).

When an execution step encounters an unexpected error or unmet precondition:

1. Execution Freeze: The execution loop halts immediately to prevent error cascade.
2. Context Capture: The engine captures error stack traces, current file state diffs, and failing step parameters.
3. Plan Re-Evaluation Trigger: Control routes back to the Planning module with an enriched prompt containing the failure context.
4. Delta Plan Synthesis: The planner generates a revised delta plan addressing the specific blocker, which is submitted for re-approval before execution resumes.

Enterprise Scenario: Database Client Migration

Consider an enterprise task migrating an asynchronous database client library from pg-v7 to pg-v8 across a 20-module backend repository.

Under a unified reactive approach, an agent might start editing files at random, broken imports mid-way, run out of token window space, and leave 10 files in an uncompilable state.

Under a decoupled architecture:

1. Planning Phase: The agent scans the 20 modules, analyzes all database call sites, and outputs a structured 5-step Plan Document. The plan specifies modifying db/client.ts, updating helper interfaces in db/types.ts, and modifying test suites.
2. Human Inspection: A tech lead reviews the generated Plan Document, notices that the agent missed updating connection pool parameters in config/db.json, edits the plan markdown directly to add Step 6, and approves execution.
3. Execution Phase: The execution engine ingests the updated plan, runs steps 1 through 6 sequentially, executes unit tests after each step, and creates a perfectly verified pull request. This approach eliminates wasted tokens and guarantees code correctness.