controlflow-spec

name	controlflow-spec
description	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.

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

1. Restate the requested outcome in one or two sentences.
2. Ask one clarification round only for requirements that would change scope, acceptance, constraints, or risk handling.
3. Save a Markdown spec artifact, usually at plans/artifacts/<task-slug>/spec.md, unless the user gives another path.
4. Keep the spec focused on requirements and proof of completion; do not decompose implementation phases.
5. 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 artifact
• plan_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.