ControlFlow Spec
Overview
Capture a short, durable specification before $controlflow-planning. The spec records the outcome, exclusions, success proof, constraints, and unresolved questions so planning does not infer requirements from loose chat context.
When to Use
Use $controlflow-spec before $controlflow-planning when:
- work is
SMALL, MEDIUM, or LARGE and no accepted spec exists
- acceptance criteria, boundaries, constraints, risks, or success metrics are still implied
- the work crosses multiple files, plugin surfaces, schemas, agents, or documentation paths
- planning would require Codex to invent priorities, exclusions, or verification gates
Skip this skill for TRIVIAL fixes where the expected behavior and verification command are already explicit.
Workflow
- Restate the requested outcome in one or two sentences.
- Ask one clarification round only for requirements that would change scope, acceptance, constraints, or risk handling.
- Save a Markdown spec artifact, usually at
plans/artifacts/<task-slug>/spec.md, unless the user gives another path.
- Keep the spec focused on requirements and proof of completion; do not decompose implementation phases.
- Hand off to
$controlflow-planning with spec_path and intended plan_path.
Spec Capture Template
# Spec: <task name>
## Objective
<What outcome is needed and why it matters.>
## In-Scope
<Files, workflows, behaviors, or artifacts that planning may include.>
## Out-of-Scope
<Related work that must not be absorbed into this effort.>
## Acceptance Criteria
<Observable conditions that must be true when the work is done.>
## Constraints
<Compatibility, governance, source-use, security, dependency, schedule, or verification limits.>
## Success Metrics
<Commands, review gates, artifacts, or measurable outcomes that prove completion.>
## Risks/Open Questions
<Unresolved assumptions, unknowns, and questions that block or shape planning.>
Handoff to Planning
After writing the spec artifact, invoke $controlflow-planning with a concise handoff that includes:
spec_path: the saved Markdown spec artifactplan_path: the intended plan artifact, usually plans/<task-slug>-plan.md- objective summary
- in-scope and out-of-scope boundaries
- acceptance criteria and success metrics
- constraints and verification commands
- risks/open questions that must become research, clarification, or explicit assumptions in the plan
Example handoff phrasing:
Use $controlflow-planning to create plan_path=plans/<task-slug>-plan.md from spec_path=plans/artifacts/<task-slug>/spec.md.
Stop Condition
If the request is still ambiguous after one clarification round, stop before planning. Ask the smallest set of blocking Codex-local questions, explain which planning decision each answer controls, and do not call $controlflow-planning until the answer is available or the user explicitly accepts a documented assumption.
1---
2name: controlflow-spec
3description: "Use before planning non-trivial Codex work when the requirements, acceptance criteria, boundaries, constraints, or success measures are not yet clear enough for a safe implementation plan."
4---56
7# ControlFlow Spec
8
9## Overview
10
11Capture a short, durable specification before `$controlflow-planning`. The spec records the outcome, exclusions, success proof, constraints, and unresolved questions so planning does not infer requirements from loose chat context.
12
13## When to Use
14
15Use `$controlflow-spec` before `$controlflow-planning` when:
16
17- work is `SMALL`, `MEDIUM`, or `LARGE` and no accepted spec exists
18- acceptance criteria, boundaries, constraints, risks, or success metrics are still implied
19- the work crosses multiple files, plugin surfaces, schemas, agents, or documentation paths
20- planning would require Codex to invent priorities, exclusions, or verification gates
21
22Skip this skill for `TRIVIAL` fixes where the expected behavior and verification command are already explicit.
23
24## Workflow
25
261. Restate the requested outcome in one or two sentences.
272. Ask one clarification round only for requirements that would change scope, acceptance, constraints, or risk handling.
283. Save a Markdown spec artifact, usually at `plans/artifacts/<task-slug>/spec.md`, unless the user gives another path.
294. Keep the spec focused on requirements and proof of completion; do not decompose implementation phases.
305. Hand off to `$controlflow-planning` with `spec_path` and intended `plan_path`.
31
32## Spec Capture Template
33
34```markdown
35# Spec: <task name>
36
37## Objective
38<What outcome is needed and why it matters.>
39
40## In-Scope
41<Files, workflows, behaviors, or artifacts that planning may include.>
42
43## Out-of-Scope
44<Related work that must not be absorbed into this effort.>
45
46## Acceptance Criteria
47<Observable conditions that must be true when the work is done.>
48
49## Constraints
50<Compatibility, governance, source-use, security, dependency, schedule, or verification limits.>
51
52## Success Metrics
53<Commands, review gates, artifacts, or measurable outcomes that prove completion.>
54
55## Risks/Open Questions
56<Unresolved assumptions, unknowns, and questions that block or shape planning.>
57```
58
59## Handoff to Planning
60
61After writing the spec artifact, invoke `$controlflow-planning` with a concise handoff that includes:
62
63- `spec_path`: the saved Markdown spec artifact
64- `plan_path`: the intended plan artifact, usually `plans/<task-slug>-plan.md`
65- objective summary
66- in-scope and out-of-scope boundaries
67- acceptance criteria and success metrics
68- constraints and verification commands
69- risks/open questions that must become research, clarification, or explicit assumptions in the plan
70
71Example handoff phrasing:
72
73`Use $controlflow-planning to create plan_path=plans/<task-slug>-plan.md from spec_path=plans/artifacts/<task-slug>/spec.md.`
74
75## Stop Condition
76
77If the request is still ambiguous after one clarification round, stop before planning. Ask the smallest set of blocking Codex-local questions, explain which planning decision each answer controls, and do not call `$controlflow-planning` until the answer is available or the user explicitly accepts a documented assumption.
Smithbox-ai