PLANNING.md supplies the planning prompt for Claude or Codex. The planning run renders it, reads the codebase, and writes comments for the orchestrator to post to your issue.
Choose the agent and execution settings in Agent settings per stage. Changing prompt text does not switch agents. The workflow remains claude-plan.yml.
File structure
LikeWORKFLOW.md, PLANNING.md has two parts:
YAML front matter (between the --- lines at the top) — read by the workflow to configure the run. Stripped before the agent sees the prompt.
Markdown body — everything after the front matter. A fixed list of variables is substituted into it, and the result is sent to the planning agent.
Front matter keys
model
model
Selects the planning model for legacy projects. Configured projects use the planning stage model instead; see Agent settings per stage.For a legacy Bedrock project, supply a compatible Bedrock model ID or inference-profile ARN. Omitting it can fall back to an Anthropic model ID that Bedrock cannot use.
Variables available in the body
The variables below are substituted into the body by a regular expression, not byenvsubst. Reference any of them anywhere in the body.
Only
${NAME} forms are substituted, and a token that is not on this list is treated differently than shell semantics would suggest. Workflow template files covers the rules and what they mean for a shell example in your body.Planning comment format
The supplied template asks the planner to write the files below. Keep their exact headers so implementation and review can find the right context.Implementation Map
File:ai-output/comments/01-implementation-map.md
Header: ## 🗺 AI Planning: Implementation Map
Keep the map within 60 lines. Include:
- Approach — a short description of the existing pattern and the change.
- Files — paths with the verbs Create, Modify, Test, or Delete.
- Constraints — relevant ordering or shared-file constraints.
Acceptance Bar
File:ai-output/comments/02-acceptance-bar.md
Header: ## ✅ AI Planning: Acceptance Bar
List testable claims covering the acceptance criteria. For each claim, name the behavior and how to check it. Include material edge cases. The reviewer uses this comment to assess the result.
Risks & Open Questions
File:ai-output/comments/03-risks.md
Header: ## ⚠️ AI Planning: Risks & Open Questions
Record material uncertainties, prerequisites, and easily missed behavior. If none exist, say so in one sentence.
Sync preserves existing
PLANNING.md files. Older templates can still ask for Architecture Analysis or Test Plan comments. Edit an existing template deliberately; a workflow sync does not replace its output instructions.Codex planning limits
Codex planning can read and search repository text. It can write planning comments underai-output/comments/. It cannot change source files, run commands, delegate work, or use network tools.
Keep instructions within those capabilities. Put executable setup and validation in the implementation workflow’s hooks.
Customizing the “Repo context” section
The## Repo context section is where you point the planning agent at the right parts of your codebase and establish the conventions that matter for architectural decisions.
Example: adding analysis prompts
You can add repo-specific analysis instructions anywhere in the body. For example, to always have the planner check the migration directory when database changes are involved:The sync workflow seeds
PLANNING.md into your repo once and never overwrites it. Every change you make is permanent — future syncs will not touch this file.