controlflow-plan

name	controlflow-plan
description	Use when a repository task needs a high-quality ControlFlow plan before coding — 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/. Single-sources the plan format from schemas/planner.plan.schema.json and the plan template.

ControlFlow Plan

Overview

Produce a durable, execution-ready plan in the shared ControlFlow format. The format is not restated here: it is single-sourced from schemas/planner.plan.schema.json (the machine-enforced contract) and plans/templates/plan-document-template.md (the human document skeleton). Read both at invoke time and conform to them; do not paraphrase the contract from memory.

Invoke this skill via /controlflow-claude-code:controlflow-plan.

Local Contract

• Read the repository before phase decomposition; keep verified facts separate from assumptions with a bounded scope statement.
• The saved artifact defines scope, risks, files, phases, validation, review route, and handoff without depending on plugin-host runtime contracts.
• Apply references/llm-behavior-guidelines.md for assumption, simplicity, scope, and verification discipline.
• Ask the user directly when an answer changes file scope, user-visible behavior, architecture, or destructive-risk handling; otherwise record a bounded assumption.

Workflow

1. Create a saved plan when the user asks for one or when work is SMALL, MEDIUM, or LARGE; skip only for truly TRIVIAL work. Save to plans/<task-slug>-plan.md unless the user names another path.
2. Read schemas/planner.plan.schema.json and plans/templates/plan-document-template.md — these are the authoritative format. Use references/plan-format.md as a compact checklist, not a substitute for them.
3. Map likely files, tests, commands, dependencies, and change boundaries before phase decomposition.
4. Read references/complexity-tiers.md; assign one tier. Any unresolved HIGH-impact semantic risk forces LARGE regardless of file count.
5. Fill all seven semantic risk categories (see references/plan-format.md); never skip a row — use not_applicable with justification.
6. Write the artifact using the template's header, 10 sections in order, and the five lifecycle sections (## Progress, ## Discoveries, ## Decision Log, ## Outcomes, ## Idempotence & Recovery) for SMALL+ plans.
7. Every phase declares exactly one executor_agent from the schema enum, lists concrete files, tests, acceptance criteria, quality gates, and failure expectations, and keeps steps in numbered prose with NO code blocks.
8. Add Mermaid diagrams per tier: sequenceDiagram for MEDIUM+ non-trivial orchestration; flowchart TD + sequenceDiagram for LARGE. Each diagram ≤30 lines.
9. Set status: ABSTAIN or REPLAN_REQUIRED when confidence is below 0.9 or evidence is insufficient; include the terminal-outcome structure from the template.
10. Add a research or spike phase before implementation when a HIGH-impact risk is unresolved.
11. For READY_FOR_EXECUTION, include a Handoff section pointing execution to plans/<task-slug>-plan.md — do NOT inline the plan in chat. See references/inline-execution.md for how execution treats waves, the context packet, and optional delegation.

Review Route (tier-gated, runs after this skill)

Hand non-TRIVIAL plans to /controlflow-claude-code:controlflow-verify, which runs inline adversarial verification: SMALL → phase 1; MEDIUM → phases 1–2; LARGE → phases 1–3.

Planning-Specific Failure Checks

• Do not plan from chat memory when reading the repo would change scope.
• Do not skip a semantic risk category because the tier feels low.
• Do not decompose phases before mapping likely files and tests.
• Do not mark READY_FOR_EXECUTION without a review route and artifact destination.
• Do not restate the schema/template in the artifact — conform to them.

References

• references/plan-format.md
• references/complexity-tiers.md
• references/inline-execution.md
• references/llm-behavior-guidelines.md