Skip to content
Agentic Coding Toolkit

Plan

Create a phased implementation plan from a spec, grounded in your codebase’s actual patterns and conventions.

Usage

Section titled “Usage”
Terminal window
/act-workflow-plan [spec-file or task description] [--use-subagents]

Arguments:

  • Spec file path: ai_specs/auth-spec.md
  • Task description: "fix the login timeout bug"
  • --use-subagents: launch parallel research agents for deeper codebase analysis

What it does

Section titled “What it does”
  1. Reads the spec — extracts goal, requirements, user flows, boundaries, and validation criteria
  2. Commits the spec — if the spec is uncommitted, ACT can ask whether to commit it first
  3. Researches your codebase — identifies project structure, state management, conventions, and reference implementations
  4. Loads testing guidance — brings in TDD and robot-testing guidance when the spec requires them
  5. Creates the plan — phased implementation with concrete tasks, file paths, and verification steps
  6. Saves to file — typically ai_specs/[feature-name]-plan.md

Plan structure

Section titled “Plan structure”
## Overview
Short summary of what we're building and the approach.


**Spec**: `ai_specs/feature-spec.md`


## Context
- **Structure**: feature-first
- **State management**: Riverpod
- **Reference implementations**: lib/src/features/auth/
- **Assumptions/Gaps**: none


## Plan


### Phase 1: [Thin end-to-end slice]
- **Goal**: Prove the critical path
- [ ] `lib/src/features/settings/settings_screen.dart` - Create screen
- [ ] TDD: toggle persists theme preference -> then implement
- [ ] Verify: `flutter analyze` && `flutter test`


### Phase 2: [Expand]
...


## Risks / Out of scope
- **Risks**: Theme migration for existing users
- **Out of scope**: Custom color picker

Default vs deep research

Section titled “Default vs deep research”

Default mode: ACT quickly inspects the codebase using Glob, Grep, and Read. Fast, focused, and usually enough.

--use-subagents mode: ACT launches background research agents:

  • act-codebase-researcher — maps project structure and conventions
  • act-flutter-patterns-researcher — finds relevant Flutter patterns and principles

Use --use-subagents for complex features where you need thorough codebase understanding.

Plan style

Section titled “Plan style”

Plans follow a strict style contract:

  • Telegraphic — fragments over prose, no filler
  • Task-oriented — every line is a checkbox with a file path
  • TDD-first — test tasks use TDD: with behavior descriptions
  • Phase 1 = vertical slice — prove the critical path end-to-end before expanding
  • Verification built in — every phase ends with analysis and tests

Tips

Section titled “Tips”
  • Start from a spec for best results
  • Keep Phase 1 thin so you prove the end-to-end path quickly
  • Review phase boundaries so every phase ends in something testable
Section titled “Related”