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 (optional): 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 uncommitted) — asks whether to commit before planning
  3. Researches your codebase — identifies project structure, state management, conventions, and reference implementations
  4. Primes testing guidance — loads 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 — 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 (no flag): ACT quickly inspects your codebase using Glob, Grep, and Read. Fast, focused on what the spec touches.

--use-subagents mode: Launches parallel background 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. Skip it for simple features where the context is obvious.

Plan style

Section titled “Plan style”

Plans follow a strict style contract:

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

Tips

Section titled “Tips”
  • Start from a spec for best results. Quick plans from task descriptions work but miss edge cases.
  • Phase 1 should be thin. A working end-to-end slice is more valuable than a complete data layer with no UI.
  • Review phase boundaries. Each phase should produce something testable — if a phase can’t be verified independently, merge it with the next.
Section titled “Related commands”