Workflow Overview

The ACT workflow turns an idea into reviewed requirements, planned implementation tasks, and verified code. Each stage creates focused context for the next stage, with human review points before the agent moves on.

The pipeline

Interview -> Create Spec -> Create Work Items -> Implement

The diagram below shows how each stage turns one artifact into the next:

1. Task description

2. act-interview

3. Rich context and resolved decisions

4. act-create-spec

5. Spec and Interview Ledger

6. act-refine-spec

   Optional quality gate

7. Spec ready for planning

8. act-create-issues

9. Work Items

10. act-implement

11. Code changes and verification summary

Use Refine Spec as an optional quality gate for non-trivial work.

Prerequisite: configure workflow storage

Run /act-config once per project to choose where ACT saves Specs and Work Items. Some workflow skills can also run setup when required config is missing.

Run this on a branch or worktree

Always run implementation work on an isolated git branch or worktree, not directly on main. This keeps your main branch clean and lets you review changes before merging. See Git Workflow Strategies for how to choose between branches and worktrees.

Choose the right path

Use the plain skills for general work. Use the Flutter/Dart skills when the project or task is Flutter/Dart.

Stage	General	Flutter/Dart
Interview	/act-interview	/act-interview-flutter
Create Spec	/act-create-spec	/act-create-spec-flutter
Refine Spec, optional	/act-refine-spec	/act-refine-spec-flutter
Create Work Items	/act-create-issues	/act-create-issues-flutter
Implement	/act-implement	/act-implement-flutter

1. Interview

Skill	/act-interview or /act-interview-flutter
Input	A task description
Output	Rich context and resolved decisions

The interview stage gathers rich context before a single line of code is written. It resolves intent, language, constraints, tradeoffs, and dependencies while changes are still cheap to make.

This matters because late changes are expensive. If the agent misunderstands the goal, uses the wrong project language, or misses a dependency, the mistake can spread through the Spec, Work Items, tests, and implementation. The interview is where ACT slows down enough to make those decisions explicit upfront.

Human checkpoint: Confirm the answers and decisions before creating the Spec.

2. Create Spec

Skill	/act-create-spec or /act-create-spec-flutter
Input	Current conversation context, usually including interview decisions
Output	A Spec and an Interview Ledger

A Spec is a requirements document that describes what should be built before code changes start. It captures goals, constraints, user flows, acceptance criteria, and important exclusions.

An Interview Ledger is Q/A-first traceability for materially resolved decisions. It is written when the Spec is created. It is not a raw transcript and not a second Spec; it records the important answers that influenced the requirements.

Human checkpoint: Review the Spec line by line. Confirm that it describes the right thing before planning implementation tasks.

3. Refine Spec (optional)

Skill	/act-refine-spec or /act-refine-spec-flutter
Input	A Spec
Output	Findings and suggested Spec updates

Performs an adversarial review pass. It looks for contradictions, missing requirements, weak assumptions, and codebase misalignment before implementation tasks are created.

Use this for complex or high-risk work. For small tasks, you may skip it.

Human checkpoint: Decide which findings to address and update the Spec before creating Work Items.

4. Create Work Items

Skill	/act-create-issues or /act-create-issues-flutter
Input	A Spec
Output	Work Items

Specs are often too big to be implemented by a single agent in one safe pass. This step decomposes the Spec into independently executable Work Items that contain enough context, acceptance criteria, and dependency information for an agent to execute.

act-create-issues checks unresolved questions, explores the codebase where needed, maps each Work Item back to the Spec and Interview Ledger, and identifies blockers or blocking decisions before implementation starts.

It pauses before writing Work Items so you can review the proposed breakdown, granularity, dependency order, and coverage.

Human checkpoint: Review the Work Items. Confirm that each task is independently executable, correctly ordered, and clear enough to hand to an agent or human.

5. Implement

Skill	/act-implement or /act-implement-flutter
Input	A single Work Item or Spec
Output	Code changes, verification results, and a summary

Implementation is where the planned work becomes code. act-implement takes a bounded Work Item, checks that blockers are resolved, and keeps the session focused on that unit of work instead of drifting into adjacent tasks.

The end result is code that satisfies the acceptance criteria, fits the agreed scope, and has been checked with the relevant analysis and tests.

Human checkpoint: Review the code, run or inspect the verification results, and smoke test behavior where needed.

When to skip stages

Not every task needs the full pipeline:

• Small task: Create a Spec, then run /act-implement directly on it
• Simple feature: Interview, create a Spec, create Work Items, then implement one Work Item at a time
• Complex feature: Include Refine Spec before creating Work Items
• Flutter/Dart feature: Use the -flutter workflow path instead of expecting Flutter behavior to activate inside the plain skills

Next steps

• Learn about AI Verification
• See the Skill Map for a quick reference of skills and commands
• Read Git Workflow Strategies for branch vs worktree workflows