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

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

The spec command 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

Command	/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 command builds the best spec it can. The refine-spec command tries to break it — surfacing gaps, wrong assumptions, and codebase conflicts that a constructive pass is unlikely to catch. While refine-spec is optional, I found it to be extremely effective at catching edge cases and misalignments that would otherwise be missed.

3. Plan

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

The plan command 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 command marks complete as it goes, with commits at each phase boundary. This makes progress visible in your git history — not just in the chat session.

4. Work

Command	/act:workflow:work
Input	A plan file
Output	Working code with commits and a pull request

The work command executes the plan phase by phase:

• Loads Flutter knowledge (patterns, principles, breaking changes)
• Executes the plan phase by phase, with commits at logical checkpoints
• Runs flutter analyze and flutter test at each phase
• Creates a pull request when all phases are complete

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

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

The compound command 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 command produces artifacts that the next command 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 + commits + 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 plan — just describe the fix and use /act:workflow:work with a task description
• 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

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