/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](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](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](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](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](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`