| name | controlflow-planning |
| description | Use when a repository task needs a strict ControlFlow-style implementation plan before coding, especially for small, medium, or large scope, cross-file edits, risky migrations, architectural uncertainty, or any work that should produce a saved Markdown plan artifact in plans/. |
ControlFlow Planning
Overview
Create a durable, execution-ready Codex plan. Keep the contract local: the saved artifact defines scope, risks, files, phases, validation, review route, and handoff without depending on VS Code agent mode.
Local Contract
- Read the repository before phase decomposition; keep verified facts separate from assumptions.
- Use references/plan-template.md as the plan contract, not a loose outline.
- Apply references/llm-behavior-guidelines.md for generic assumption, simplicity, scope, and verification discipline.
- Keep Codex portable: ask the user directly when a requirement changes scope, or record a bounded assumption when it does not.
Workflow
- Create a saved plan when the user asks for one or when work is
SMALL, MEDIUM, or LARGE; skip it only for truly TRIVIAL work.
- Save to
plans/<task-slug>-plan.md unless the user names another path.
- Clarify only when the answer changes file scope, user-visible behavior, architecture, or destructive-risk handling.
- Map likely files, tests, commands, dependencies, and change boundaries before phase decomposition.
- Read references/complexity-tiers.md and references/semantic-risk-taxonomy.md; assign one tier and fill all seven risk categories.
- Write the artifact using references/plan-template.md.
- For non-trivial Codex plans (
SMALL, MEDIUM, LARGE), include the five fixed lifecycle sections in this exact order and with these exact headings: ## Progress, ## Discoveries, ## Decision Log, ## Outcomes, ## Idempotence & Recovery. These headings are required by ../../scripts/validate-strict-artifacts.ps1 and must match the template and fixtures exactly.
- Use
ABSTAIN or REPLAN_REQUIRED when confidence is below 0.9 or evidence is insufficient.
- Add research or spike phases before implementation when a
HIGH-impact risk is unresolved.
- Keep phases incremental, testable, and explicit about files, dependencies, quality gates, and failure expectations.
- Route non-trivial plans through strict review:
SMALL -> controlflow-plan-audit; MEDIUM/LARGE -> add controlflow-assumption-verifier; unresolved HIGH risk -> include controlflow-assumption-verifier regardless of size.
- Check references/controlflow-portability.md before handoff.
Spec Capture Handoff
When requirements, acceptance criteria, boundaries, or verification gates are not explicit, use controlflow-spec first. Carry its spec_path, scope, acceptance criteria, constraints, success metrics, and open risks into the plan. If spec capture is unnecessary, state why the request is already clear enough.
Planning-Specific Failure Checks
- Do not plan from chat memory when a spec is required; cite the spec artifact or create one.
- Do not skip semantic risk review because the tier feels low; fill every category.
- Do not decompose phases before reading the repository and mapping likely files/tests.
- Do not mark
READY_FOR_EXECUTION without a strict review route and artifact destination.
- Generic anti-rationalization rules live in references/llm-behavior-guidelines.md.
Mandatory Output Contract
- Prefer structured text over raw JSON.
- Default plan file path:
plans/<task-slug>-plan.md.
- Use the ControlFlow-style header and section order from references/plan-template.md.
- Write
Agent: Planner in the artifact so the document matches the original conceptual role even though the implementation is a Codex skill.
- Record assumptions separately from verified facts.
- For
READY_FOR_EXECUTION plans, include a clear handoff section that points execution to orchestration.
References
references/plan-template.mdreferences/complexity-tiers.mdreferences/semantic-risk-taxonomy.mdreferences/controlflow-portability.mdreferences/planner-output-contract.mdreferences/llm-behavior-guidelines.md
