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
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.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.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.
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.
Issue marker is updated
After the planning workflow finishes successfully, the orchestrator updates the marker on the issue:
- Linear
- Jira
The
AI-Planning label is removed and Plan-Complete is added.Implementation starts automatically
The orchestrator dispatches the implementation workflow immediately after planning succeeds.
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.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.Disabling the planning phase
To skip planning for a specific project mapping, setplanningEnabled=false on that mapping in the admin UI at /admin. Implementation will dispatch directly without a preceding planning run.
Choosing a planning model
Set themodel: key in PLANNING.md front matter to control which model Claude uses during planning:
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.