Skip to content
Agentic Coding Toolkit

Spec

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

Usage

Section titled “Usage”
Terminal window
/act:workflow:spec [task description or file path]

Arguments:

  • File path (recommended): ai_specs/001-initial-prompt.md
  • Text description: "add user authentication with OAuth"
  • No argument: ACT will ask what you want to build
Section titled “Recommended: save your prompt to a file first”

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

ai_specs/001-initial-prompt.md
Terminal window
/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.

This approach is recommended because:

  • Traceability — the original prompt is preserved as-is, so you can always see what you started with
  • Organization — numbered prefixes (001-, 002-) keep specs ordered chronologically and grouped with their source files
  • Editability — you can refine a longer, more detailed prompt in your editor before running the command

What it does

Section titled “What it does”
  1. Gathers context — examines files mentioned in the description, looks for reference implementations and patterns in your codebase
  2. Asks clarifying questions — 2-4 targeted questions to fill genuine gaps (not things already stated or inferable)
  3. Maps user flows — identifies happy paths, alternative flows, error/recovery flows, and edge cases
  4. Shows a preview outline — you approve, adjust, or ask more questions before the full spec is generated
  5. Generates the spec — a structured document with goal, requirements, user flows, boundaries, implementation notes, and validation criteria
  6. Saves to file — typically ai_specs/[feature-name]-spec.md

Spec structure

Section titled “Spec structure”

ACT specs describe concrete behavior and technical decisions in a scannable format — not PRDs full of “As a user…” stories. (See Philosophy — What specs are and aren’t for more on this design choice.)

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, not abstract user stories
  • Requirements — numbered technical decisions: functional, error handling, edge cases, validation
  • Boundaries — what’s out of scope, what NOT to do, explicit limits
  • Implementation — files to create/modify, patterns to follow, what to avoid
  • Validation — how to test, expected behavior, TDD expectations
  • Done when — measurable completion criteria

Example

Section titled “Example”
Terminal window
/act:workflow:spec "add a dark mode toggle to the settings screen"

ACT might ask:

  • “Should the theme persist across app restarts? (SharedPreferences / Hive / system default)”
  • “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, theme provider updates, and edge cases (what happens on first launch, system theme changes, etc.).

After the spec

Section titled “After the spec”

ACT 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

Section titled “When to use specs”

Use specs for features spanning multiple layers — a screen that involves UI, state management, API calls, and persistence has many small decisions that benefit from being enumerated before you start coding. This is the sweet spot.

Skip specs for isolated, well-defined tasks — a single-function algorithm, a bug fix with a clear reproduction, or a refactor with obvious scope. Write code and tests directly.

Skip specs for business-dense logic — pricing rules, state machines, concurrency controllers. Code is the most precise notation for that kind of work. Write it directly with tests. (See Philosophy — What specs are and aren’t for more on this.)

Tips

Section titled “Tips”
  • Be specific about the outcome, not the implementation. “Users can reset their password via email” is better than “add a password reset endpoint.”
  • Mention constraints early. If you’re using Riverpod, or need offline support, or have a specific API — say so in the task description.
  • Review the preview outline. This is your cheapest opportunity to catch scope issues before a full spec is generated.
  • One feature per spec. Break large features into separate specs for better results.
  • Watch for spec bloat. If you find yourself writing field-by-field schemas or pseudocode algorithms in the spec, you’ve crossed from specification into obfuscated code. Write real code instead.
Section titled “Related commands”