Spec

Transform a task description into a structured specification: a concrete artifact you can review, challenge, and refine before any code is written.

Usage

/act-workflow-spec [task description or file path]

Arguments:

File path: ai_specs/001-initial-prompt.md
Text description: "add user authentication with OAuth"
No argument: ACT asks what you want to build

Recommended: save your prompt to a file first

Rather than passing a long description inline, write your initial prompt or idea to a file and pass the file path:

ai_specs/001-initial-prompt.md

/act-workflow-spec ai_specs/001-initial-prompt.md

ACT generates ai_specs/001-initial-prompt-spec.md alongside the original. Both files sort together alphabetically, making it easy to trace from initial idea to finished spec.

What it does

Gathers context — examines files mentioned in the description and looks for reference implementations and patterns
Asks clarifying questions — 2-4 targeted questions to fill genuine gaps
Maps user flows — identifies happy paths, alternative flows, error and recovery flows, and edge cases
Shows a preview outline — you approve or adjust before the full spec is written
Generates the spec — a structured document with goal, requirements, user flows, boundaries, implementation notes, and validation criteria
Saves to file — typically ai_specs/[feature-name]-spec.md

Spec structure

ACT specs describe concrete behavior and technical decisions in a scannable format. They are not PRDs full of abstract user stories.

The generated spec includes these sections:

Goal — what to build and why it matters
Background — tech stack, project context, relevant constraints
User flows — concrete screen-by-screen sequences
Requirements — functional decisions, error handling, edge cases, validation
Boundaries — out of scope, explicit limits, what not to do
Implementation — files to create or modify, patterns to follow, what to avoid
Validation — how to test the implementation and what the expected behavior is
Done when — measurable completion criteria

Example

/act-workflow-spec "add a dark mode toggle to the settings screen"

ACT might ask:

“Should the theme persist across app restarts?”
“Should the app respect the system theme setting, or always use the user’s explicit choice?”

After your answers, it generates a spec covering the toggle UI, persistence strategy, provider updates, and edge cases.

After the spec

ACT typically offers these next steps:

Review spec — run /act-workflow-refine-spec for adversarial review
Commit spec — commit the spec file with /act-git-commit
Create plan — run /act-workflow-plan to create an implementation plan
Create plan (deep) — run /act-workflow-plan --use-subagents for deeper research

When to use specs

Use specs for features spanning multiple layers. A screen involving UI, state management, API calls, and persistence has many small decisions that benefit from being enumerated before you start coding.

Skip specs for isolated, well-defined tasks. A single-function algorithm, a bug fix with a clear reproduction, or a refactor with obvious scope usually does not need a full spec.

Skip specs for business-dense logic. Pricing rules, state machines, and concurrency controllers are usually clearer in code plus tests than in prose.

Tips

Be specific about the outcome, not the implementation
Mention constraints early if you need specific packages or patterns
Review the preview outline before generating the full spec
One feature per spec for better results
Watch for spec bloat — if you start writing pseudocode, write real code instead

/act-workflow-refine-spec — review the spec for gaps
/act-workflow-plan — create a plan from the spec
Commands to Skills Migration — understand the naming changes

See it in practice

Watch the Spec-Driven Development Walkthrough (Video) for a full example of using spec, refine-spec, plan, and work on a real brownfield Flutter task.