> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI planning phase: architecture analysis

> How the AI planning phase works, what structured architecture, test plan, work units, and cross-story comments it posts to your ticketing system, and how to enable, disable, or configure it per project mapping.

When `planningEnabled=true` (the default), AI-Implement runs a planning pass before handing an issue to the implementation workflow. Claude reads your codebase in read-only mode and posts structured analysis directly to the originating issue (Linear comments or Jira comments, depending on the project mapping's provider). That analysis is then fetched by the implementation workflow and injected into the Claude prompt, giving the implementation run a head start on architectural decisions, files to change, and known risks.

## How the planning phase works

<Steps>
  <Step title="Orchestrator dispatches the planning workflow">
    When the orchestrator picks up an eligible issue, it dispatches `claude-plan.yml` in the target repo with the issue details as workflow inputs.
  </Step>

  <Step title="Claude explores the codebase read-only">
    Claude uses `Read`, `Glob`, and `Grep` to explore the codebase. It does not create any branches, files, or commits during this phase.
  </Step>

  <Step title="Claude posts structured planning comments">
    Claude posts up to four comments on the issue, each with a fixed header that the implementation workflow can locate later:

    * **Architecture Analysis** (`## 🏗️ AI Planning: Architecture Analysis`) — approach, specific files to create or modify, key architectural decisions, and risks or open questions.
    * **Test Plan** (`## 🧪 AI Planning: Test Plan`) — unit tests, integration tests, and a manual verification checklist.
    * **Work Units** (`## 🔧 AI Planning: Work Units`) — a breakdown of the issue into smaller pieces, separated into ones that can be implemented in parallel and ones that must follow. Skipped when the issue is too small or too tightly coupled to decompose.
    * **Cross-Story Context** (`## 🔗 AI Planning: Cross-Story Context`) — posted only when the issue has dependencies or sibling stories with meaningful coordination needs, covering upstream dependencies, downstream impact, and coordination notes.

    <Info>
      When eligible for **Work Units**, the implementation phase spins up multiple Claude subagents in parallel — each scoped to a specific set of files — so independent chunks land at the same time.
    </Info>
  </Step>

  <Step title="Issue marker is updated">
    After the planning workflow finishes successfully, the orchestrator updates the marker on the issue:

    <Tabs>
      <Tab title="Linear">
        The `AI-Planning` label is removed and `Plan-Complete` is added.
      </Tab>

      <Tab title="Jira">
        The `AI-Implement Status` field is set to `Plan Approved`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implementation starts automatically">
    The orchestrator dispatches the implementation workflow immediately after planning succeeds.

    <Note>
      The `autoApprovePlans` field on each project mapping is reserved for a future manual-approval gate but does **not currently affect dispatch behavior** — implementation always starts automatically after planning, regardless of this setting.
    </Note>
  </Step>

  <Step title="Implementation workflow injects planning context">
    `claude-implement.yml` fetches the planning comments from the issue, sanitizes them, and prepends them to the Claude prompt. Claude is instructed to follow the planning decisions unless it discovers a concrete reason not to, and to explain any deviations in the PR description.
  </Step>
</Steps>

## Disabling the planning phase

To skip planning for a specific project mapping, set `planningEnabled=false` on that mapping in the admin UI at `/admin`. Implementation will dispatch directly without a preceding planning run.

## Choosing a planning model

Set the `model:` key in `PLANNING.md` front matter to control which model Claude uses during planning:

```yaml theme={null}
---
model: claude-sonnet-4-6
---
```

For `provider=bedrock`, this field is required and must be a valid Bedrock model ID or inference-profile ARN. For `provider=anthropic`, it defaults to `claude-sonnet-4-6` when omitted.

## Customizing the planning prompt

`PLANNING.md` in the target repo is your planning prompt template. After the initial sync, AI-Implement never overwrites it. Edit the **Repo context** section to focus Claude on the directories, patterns, and conventions that matter most for your codebase.

<Tip>
  Well-written planning output directly improves implementation quality. Customize `PLANNING.md` to point Claude at the areas of your codebase where architectural decisions are most consequential — for example, schema migration directories, shared API contracts, or modules with strict backward-compatibility requirements.
</Tip>