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
- 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.
- 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.
- Map likely files, tests, commands, dependencies, and change boundaries before phase
decomposition.
- Read references/complexity-tiers.md; assign one tier.
Any unresolved HIGH-impact semantic risk forces LARGE regardless of file count.
- Fill all seven semantic risk categories (see
references/plan-format.md); never skip a row — use
not_applicable with justification.
- 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.
- 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.
- Add Mermaid diagrams per tier:
sequenceDiagram for MEDIUM+ non-trivial orchestration;
flowchart TD + sequenceDiagram for LARGE. Each diagram ≤30 lines.
- Set
status: ABSTAIN or REPLAN_REQUIRED when confidence is below 0.9 or evidence is
insufficient; include the terminal-outcome structure from the template.
- Add a research or spike phase before implementation when a HIGH-impact risk is
unresolved.
- 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
1---2name: controlflow-plan-23description: "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."4metadata:5 source: https://skillmd.com/skills/gabrielmoreira/controlflow-plan-26---78# ControlFlow Plan910## Overview1112Produce a durable, execution-ready plan in the shared ControlFlow format. The format is13not restated here: it is single-sourced from `schemas/planner.plan.schema.json` (the14machine-enforced contract) and `plans/templates/plan-document-template.md` (the human15document skeleton). Read both at invoke time and conform to them; do not paraphrase the16contract from memory.1718Invoke this skill via `/controlflow-claude-code:controlflow-plan`.1920## Local Contract2122- Read the repository before phase decomposition; keep verified facts separate from23 assumptions with a bounded scope statement.24- The saved artifact defines scope, risks, files, phases, validation, review route, and25 handoff without depending on plugin-host runtime contracts.26- Apply [references/llm-behavior-guidelines.md](references/llm-behavior-guidelines.md) for27 assumption, simplicity, scope, and verification discipline.28- Ask the user directly when an answer changes file scope, user-visible behavior,29 architecture, or destructive-risk handling; otherwise record a bounded assumption.3031## Workflow32331. Create a saved plan when the user asks for one or when work is SMALL, MEDIUM, or LARGE;34 skip only for truly TRIVIAL work. Save to `plans/<task-slug>-plan.md` unless the user35 names another path.362. Read `schemas/planner.plan.schema.json` and37 `plans/templates/plan-document-template.md` — these are the authoritative format. Use38 [references/plan-format.md](references/plan-format.md) as a compact checklist, not a39 substitute for them.403. Map likely files, tests, commands, dependencies, and change boundaries before phase41 decomposition.424. Read [references/complexity-tiers.md](references/complexity-tiers.md); assign one tier.43 Any unresolved HIGH-impact semantic risk forces LARGE regardless of file count.445. Fill all seven semantic risk categories (see45 [references/plan-format.md](references/plan-format.md)); never skip a row — use46 `not_applicable` with justification.476. Write the artifact using the template's header, 10 sections in order, and the five48 lifecycle sections (`## Progress`, `## Discoveries`, `## Decision Log`, `## Outcomes`,49 `## Idempotence & Recovery`) for SMALL+ plans.507. Every phase declares exactly one `executor_agent` from the schema enum, lists concrete51 files, tests, acceptance criteria, quality gates, and failure expectations, and keeps52 steps in numbered prose with NO code blocks.538. Add Mermaid diagrams per tier: `sequenceDiagram` for MEDIUM+ non-trivial orchestration;54 `flowchart TD` + `sequenceDiagram` for LARGE. Each diagram ≤30 lines.559. Set `status: ABSTAIN` or `REPLAN_REQUIRED` when confidence is below 0.9 or evidence is56 insufficient; include the terminal-outcome structure from the template.5710. Add a research or spike phase before implementation when a HIGH-impact risk is58 unresolved.5911. For `READY_FOR_EXECUTION`, include a Handoff section pointing execution to60 `plans/<task-slug>-plan.md` — do NOT inline the plan in chat. See61 [references/inline-execution.md](references/inline-execution.md) for how execution62 treats waves, the context packet, and optional delegation.6364## Review Route (tier-gated, runs after this skill)6566Hand non-TRIVIAL plans to `/controlflow-claude-code:controlflow-verify`, which runs inline67adversarial verification: SMALL → phase 1; MEDIUM → phases 1–2; LARGE → phases 1–3.6869## Planning-Specific Failure Checks7071- Do not plan from chat memory when reading the repo would change scope.72- Do not skip a semantic risk category because the tier feels low.73- Do not decompose phases before mapping likely files and tests.74- Do not mark READY_FOR_EXECUTION without a review route and artifact destination.75- Do not restate the schema/template in the artifact — conform to them.7677## References7879- `references/plan-format.md`80- `references/complexity-tiers.md`81- `references/inline-execution.md`82- `references/llm-behavior-guidelines.md`