Workflow Overview

The ACT workflow is a structured pipeline where each stage produces artifacts that feed the next. Humans review between stages — AI does the work, you make the decisions.

The pipeline

Spec → Refine Spec → Plan → Work → Compound

Run this on a branch or worktree

Always run the workflow on an isolated git branch or worktree — not directly on main. This keeps your main branch clean and lets you review changes via a pull request before merging. See Git Workflow Strategies for how to choose between branches and worktrees.

1. Spec

Skill	/act-workflow-spec
Input	A task description (text or file)
Output	A detailed specification in ai_specs/

The spec skill transforms a vague idea into a precise document:

• Asks 2-4 clarifying questions to fill gaps
• Maps user flows (happy path, errors, edge cases)
• Produces numbered requirements
• Specifies validation criteria and test expectations

Human checkpoint: Review the spec. Is this what you want built?

Don’t skip the spec review

Reviewing the spec is one of the biggest value-adds in the entire workflow. It’s your chance to confirm the AI understood what you want to build, or change course if needed. Read the spec line-by-line and iterate until you’re happy — catching misunderstandings here saves significant time and rework later.

2. Refine Spec

Skill	/act-workflow-refine-spec
Input	A spec file
Output	Findings organized by severity, with suggested fixes

An adversarial review that catches problems before implementation:

• Gaps — missing requirements or underspecified behavior
• Wrong assumptions — things the spec assumes that don’t match your codebase
• UX incoherence — flows that don’t make sense from a user’s perspective
• Data model issues — models that don’t support the described UX
• Codebase misalignment — patterns that conflict with how your project actually works

Human checkpoint: Decide which findings to address before planning.

Why adversarial?

The spec skill builds the best spec it can. The refine-spec skill tries to break it, surfacing gaps, wrong assumptions, and codebase conflicts that a constructive pass is unlikely to catch. While refine-spec is optional, it is extremely effective at catching edge cases and misalignments that would otherwise be missed.

3. Plan

Skill	/act-workflow-plan
Input	A spec file (or task description)
Output	A phased implementation plan in ai_specs/

The plan skill analyzes your codebase and creates a concrete implementation strategy:

• Researches project structure, state management, and conventions
• Breaks work into phases with specific file paths and tasks
• Includes TDD test-first tasks where applicable
• Each phase has verification steps (flutter analyze && flutter test)

Use --use-subagents for deeper research with parallel background agents.

Human checkpoint: Review the plan. Does the approach make sense?

How is this different from built-in plan mode?

/act-workflow-plan creates a *-plan.md file that becomes part of your project. Each phase contains checkbox tasks that the work skill marks complete as it goes, with per-phase commits on normal runs. This makes progress visible in your git history, not just in the chat session.

4. Work

Skill	/act-workflow-work
Input	A plan file
Output	Working code, reconciled plan state, phase commits by default, plus an optional pull request

The work skill executes the plan phase by phase:

• Loads Flutter knowledge (patterns, principles, breaking changes)
• Executes all remaining phases, or exactly one phase with --single-phase
• Reconciles plan checkboxes and blocker notes after each completed phase
• Runs analysis and tests for the current project type at each phase
• Commits each successful completed phase by default, or skips git side effects with --do-not-commit
• Optionally pushes and creates a pull request when run with --create-pr

Human checkpoint: Run the app and smoke test. Request visual tweaks or fixes as needed.

Tests as guardrails

Tests are baked into implementation so behavior stays explicit and future agent runs stay on track. TDD-style guidance when it helps — without turning every task into ceremony.

5. Compound

Skill	/act-workflow-compound
Input	Current session context (optionally: spec/plan path, hints)
Output	A reusable insight document in ai_docs/solutions/

The compound skill captures what was learned during the session:

• Extracts key decisions and tradeoffs
• Documents patterns and pitfalls
• Saves reusable insights organized by category
• Future sessions can reference these insights

Why compound?

Solution docs accumulate project-specific knowledge that AI can’t get from training data — your architecture decisions, platform gotchas, and patterns that worked. Future sessions can reference these docs, so the AI gets smarter about your project over time.

The key insight: artifacts flow forward

Each skill produces artifacts that the next skill consumes:

Stage	Reads	Produces
Spec	Task description	*-spec.md
Refine Spec	*-spec.md + codebase	Findings + updated spec
Plan	*-spec.md + codebase	*-plan.md
Work	*-plan.md + *-spec.md	Code + reconciled plan + phase commits by default + optional PR
Compound	Session context	ai_docs/solutions/*.md

This chain reduces ambiguity at each step. By the time code is written, the AI has a spec with clear requirements, a plan with concrete tasks, and knowledge of your codebase’s patterns.

When to skip stages

Not every task needs the full pipeline:

• Quick fix: Skip spec and go straight to /act-workflow-plan "fix the bug", then run /act-workflow-work on the generated plan file
• Simple feature: Write a spec, skip refine-spec, go straight to plan
• Complex feature: Use the full pipeline including refine-spec and --use-subagents for planning
• Bug investigation: Start with spec to document what’s wrong, then plan the fix

Next steps

• Watch the Spec-Driven Development Walkthrough (Video) to see the workflow applied to a real brownfield feature
• 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