Skip to content
Agentic Coding Toolkit

Add a Feature

Add a new feature to an existing Flutter app using the spec-first workflow. ACT analyzes your codebase and builds on your existing patterns.

Scenario

Section titled “Scenario”

You have a working Flutter app and need to add a new feature — a settings screen, a search function, a new data model, or anything else. You want the new code to follow the conventions already established in your project.

Prerequisites

Section titled “Prerequisites”
  • ACT installed and configured in your project (Project Setup)
  • An existing Flutter app with at least one working feature
  • A Claude Code or OpenCode session open in your project directory
  • A clear idea of what the new feature should do

Steps

Section titled “Steps”

1. Start from main

Section titled “1. Start from main”

Make sure you are on a clean main branch with the latest changes:

Terminal window
/act:git:switch-main-pull

2. Write the spec

Section titled “2. Write the spec”

Describe the feature you want to add. Mention constraints and existing patterns:

Terminal window
/act:workflow:spec "add a search screen that lets users search expenses by category or description, with debounced input and empty state handling. Use the same Riverpod patterns as the existing expense list feature."

ACT will inspect your codebase, ask clarifying questions, and generate a spec that references your actual file structure and conventions.

See Spec for tips on writing effective task descriptions.

3. Refine the spec (optional)

Section titled “3. Refine the spec (optional)”

For complex features, run an adversarial review:

Terminal window
/act:workflow:refine-spec ai_specs/search-spec.md

This is especially valuable when the feature touches multiple existing screens or data models. Requires ACT Pro — see Refine Spec.

4. Create the plan

Section titled “4. Create the plan”

Generate a phased implementation plan:

Terminal window
/act:workflow:plan ai_specs/search-spec.md

The plan will reference existing files in your project and follow your established patterns. Review it to confirm:

  • Phase 1 is a thin end-to-end slice (not just models or just UI)
  • File paths match your project structure
  • The plan reuses existing providers, repositories, or services where appropriate

See Plan for plan structure details.

5. Execute the plan

Section titled “5. Execute the plan”

Run the implementation:

Terminal window
/act:workflow:work ai_specs/search-plan.md

ACT implements each phase, runs analysis and tests after each one, commits working code, and creates a pull request when done.

See Work for execution details.

Expected output

Section titled “Expected output”

After completing these steps, you should have:

  • A spec documenting the feature requirements and edge cases
  • A plan with phased tasks, all marked complete
  • New code that follows your existing project conventions
  • Tests for the new feature, all passing
  • No regressions in existing tests
  • A pull request with a clear summary

Common pitfalls

Section titled “Common pitfalls”
  • Not mentioning existing patterns. If your app uses Riverpod, GoRouter, or a specific folder structure, say so in the spec input. ACT will discover patterns on its own, but explicit hints produce better results faster.
  • Feature too large for one spec. If the feature involves more than 3-4 screens or major architectural changes, break it into smaller specs. For example, split “add user profiles with avatars, settings, and activity history” into three separate features.
  • Ignoring the plan review. The plan is your cheapest checkpoint. If it creates files in the wrong directory, duplicates existing logic, or structures phases poorly, fix it before running work.
  • Forgetting to pull latest. Starting from a stale branch leads to merge conflicts. Always begin with /act:git:switch-main-pull.

Next steps

Section titled “Next steps”