Skip to content
Agentic Coding Toolkit

Work

Execute an implementation plan systematically, phase by phase. The core contract is simple: completed work must be reflected truthfully in the plan file before the run is considered successful.

Usage

Section titled “Usage”
Terminal window
/act-workflow-work <plan-file> [type] [--single-phase] [--do-not-commit] [--create-pr]

Arguments:

  • plan-file (required): path to the plan file
  • type (optional, default: lite): knowledge level to load before execution
  • --single-phase: execute exactly the first incomplete phase, then stop
  • --do-not-commit: skip git side effects but still update the plan on disk
  • --create-pr: after all phases are complete and validation passes, push and open a PR

--create-pr and --do-not-commit are mutually exclusive.

Knowledge levels

Section titled “Knowledge levels”
  • official — load official Flutter rules only
  • lite — load essential patterns, principles, and breaking changes
  • full — load broader setup and implementation guidance

For advanced workflows outside work, see Knowledge Loading.

Examples

Section titled “Examples”
Terminal window
/act-workflow-work ai_specs/feature-plan.md
/act-workflow-work ai_specs/feature-plan.md --single-phase
/act-workflow-work ai_specs/feature-plan.md --do-not-commit
/act-workflow-work ai_specs/feature-plan.md full
/act-workflow-work ai_specs/feature-plan.md lite --create-pr

What it does

Section titled “What it does”

1. Reads the plan and spec

Section titled “1. Reads the plan and spec”

Loads the plan file, any referenced spec, and the files needed for the first in-scope phase.

2. Prepares the project

Section titled “2. Prepares the project”

Infers whether this is a Flutter or Dart CLI project, creates the project if needed, and loads the right ACT knowledge and testing skills.

3. Determines scope

Section titled “3. Determines scope”

Runs either all remaining incomplete phases, or just the first incomplete phase when --single-phase is used.

4. Executes the current phase

Section titled “4. Executes the current phase”

For each phase in scope, ACT:

  • reads the files referenced by that phase and checks existing patterns first
  • implements only the tasks in that phase
  • follows strict RED -> GREEN -> REFACTOR cycles for TDD: tasks
  • validates the current slice while working instead of deferring everything to the end

5. Reconciles the plan

Section titled “5. Reconciles the plan”

After each completed phase, ACT re-reads the plan and updates the matching checklist items from - [ ] to - [x].

This stage is mandatory. If work was completed but the plan was not updated to match, the run should fail rather than report success.

6. Validates the phase

Section titled “6. Validates the phase”

After reconciliation, ACT runs the correct validation commands for the project type:

  • Flutter: flutter analyze and flutter test
  • Dart CLI: dart analyze and dart test

7. Commits or ships

Section titled “7. Commits or ships”
  • By default, each successful completed phase that changed files ends with a local commit
  • With --do-not-commit, ACT leaves changes in the working tree
  • With --create-pr, ACT pushes and opens a PR only after all phases are complete and final validation passes

Hard invariants

Section titled “Hard invariants”

Before work can report success:

  • every completed in-scope checklist item is marked [x] in the plan
  • blocked items stay unchecked and are documented
  • the correct analysis and test commands pass
  • --single-phase runs do not spill into the next phase
  • normal runs do not leave successful completed phase work uncommitted
  • --do-not-commit runs have no git side effects

Key principles

Section titled “Key principles”

Start with a thin end-to-end slice

Section titled “Start with a thin end-to-end slice”

Phase 1 proves the critical path across all layers. Do not build broad horizontal layers in isolation.

Test-first with vertical slices

Section titled “Test-first with vertical slices”

For TDD: tasks: write one failing test, add the minimum implementation, refactor, then repeat.

Keep the plan truthful

Section titled “Keep the plan truthful”

A phase is not complete until the plan has been reconciled to match what was actually finished, what is still blocked, and what remains next.

Commit only validated slices

Section titled “Commit only validated slices”

Every commit must be in a working state: no analysis failures, no failing tests, and no knowingly partial WIP slices.

Error handling

Section titled “Error handling”
  • Validation failures — the phase does not succeed until the root cause is fixed
  • Plan mismatch — if finished work is not reflected in the plan, the run fails
  • Blocked progress — blocked items stay unchecked and get a brief blocker note in the plan
  • Missing requirements or manual decisions — ACT stops and asks before continuing
Section titled “Related”