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-spec3description: 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---5
6# ControlFlow Spec
7
8## Overview
9
10Capture 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.
11
12## When to Use
13
14Use `$controlflow-spec` before `$controlflow-planning` when:
15
16- work is `SMALL`, `MEDIUM`, or `LARGE` and no accepted spec exists
17- acceptance criteria, boundaries, constraints, risks, or success metrics are still implied
18- the work crosses multiple files, plugin surfaces, schemas, agents, or documentation paths
19- planning would require Codex to invent priorities, exclusions, or verification gates
20
21Skip this skill for `TRIVIAL` fixes where the expected behavior and verification command are already explicit.
22
23## Workflow
24
251. Restate the requested outcome in one or two sentences.
262. Ask one clarification round only for requirements that would change scope, acceptance, constraints, or risk handling.
273. Save a Markdown spec artifact, usually at `plans/artifacts/<task-slug>/spec.md`, unless the user gives another path.
284. Keep the spec focused on requirements and proof of completion; do not decompose implementation phases.
295. Hand off to `$controlflow-planning` with `spec_path` and intended `plan_path`.
30
31## Spec Capture Template
32
33```markdown
34# Spec: <task name>
35
36## Objective
37<What outcome is needed and why it matters.>
38
39## In-Scope
40<Files, workflows, behaviors, or artifacts that planning may include.>
41
42## Out-of-Scope
43<Related work that must not be absorbed into this effort.>
44
45## Acceptance Criteria
46<Observable conditions that must be true when the work is done.>
47
48## Constraints
49<Compatibility, governance, source-use, security, dependency, schedule, or verification limits.>
50
51## Success Metrics
52<Commands, review gates, artifacts, or measurable outcomes that prove completion.>
53
54## Risks/Open Questions
55<Unresolved assumptions, unknowns, and questions that block or shape planning.>
56```
57
58## Handoff to Planning
59
60After writing the spec artifact, invoke `$controlflow-planning` with a concise handoff that includes:
61
62- `spec_path`: the saved Markdown spec artifact
63- `plan_path`: the intended plan artifact, usually `plans/<task-slug>-plan.md`
64- objective summary
65- in-scope and out-of-scope boundaries
66- acceptance criteria and success metrics
67- constraints and verification commands
68- risks/open questions that must become research, clarification, or explicit assumptions in the plan
69
70Example handoff phrasing:
71
72`Use $controlflow-planning to create plan_path=plans/<task-slug>-plan.md from spec_path=plans/artifacts/<task-slug>/spec.md.`
73
74## Stop Condition
75
76If 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