Skip to main content
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

1

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.
2

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.
3

Claude posts structured planning comments

Claude posts one comment per planning section, each with a fixed header the implementation workflow locates later:
  • Implementation Map — the approach, the files to touch, and the constraints not to break.
  • Acceptance Bar — numbered claims the review pass checks the diff against.
  • Risks & Open Questions — edge cases and unknowns found while exploring.
Comment types Claude must post covers the exact headers and what each one has to contain.
4

Issue marker is updated

After the planning workflow finishes successfully, the orchestrator updates the marker on the issue:
The AI-Planning label is removed and Plan-Complete is added.
5

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.
6

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, 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:
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.
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.