Project Setup

After installing ACT, set up your project for structured AI-assisted development.

The AI folders

ACT uses three folders alongside your project code to keep AI context organized:

• ai_specs/ — structured planning and execution (specs and plans for ongoing work)
• ai_docs/ — persistent project knowledge (living documentation that evolves with the project)
• ai_logs/ — session logs for debugging (disabled by default)

You don’t need to create these manually — ACT commands create them on the fly as needed.

ai_specs/ — Structured planning and execution

This is where specs and plans live. Think of it as guardrails that keep AI agents on track during implementation.

The workflow is:

1. Create a spec — outline requirements for a feature, bug fix, or refactor
2. Generate a plan — feed the spec to the AI and iterate until satisfied
3. Implement the plan — execute one phase at a time for easier review
4. Verify — run tests and manual checks

ACT workflow commands read from and write to this directory:

• ai_specs/feature-name.md — your initial idea or braindump about what you want to accomplish
• ai_specs/feature-name-spec.md — specifications created by /act:workflow:spec
• ai_specs/feature-name-plan.md — plans created by /act:workflow:plan

In practice, it’s convenient to use a numeric prefix (e.g. 001-, 002-) when naming spec files. This keeps them sorted chronologically. Example:

Over time, ai_specs/ becomes a historical record of all your prompts and plans — like a local copy of GitHub issues and PRs. Content may become outdated as the project evolves, but it remains a useful reference.

Note

ACT looks for an ai_specs/ folder by default, but you’re not forced to use this convention. Your project might use ai/specs/, specs/, or prompts/ instead. The key thing to know is that when you call /act:workflow:spec /path/to/file.md, it generates /path/to/file-spec.md in the same directory — so any folder structure works.

ai_docs/ — Persistent project knowledge

A living knowledge base for AI agents — documentation that evolves with the project. This is where you put information the AI needs but can’t find directly in the code:

• API documentation and integrations
• Architecture and design documents
• Non-code business logic
• Project-specific patterns unique to your codebase
• Session insights captured by /act:workflow:compound, organized by category (feature-delivery, bug-fixes, refactors, etc.)

The key distinction: ai_docs/ is living documentation you keep updated, while ai_specs/ is a historical task record that may go stale.

ai_logs/ — Session logs

Session logging is disabled by default. When enabled, the session logging hook tracks prompts and tool usage for each session. Useful for debugging and reviewing what happened during a session.

Project layout

You have two options for where to place the AI folders relative to your Flutter project.

Subfolder (recommended)

Place your Flutter app inside a subfolder, with AI folders at the repo root:

my_repo/
├── ai_docs/
├── ai_specs/
└── my_flutter_app/
    ├── .dart_tool/
    ├── android/
    ├── ios/
    ├── lib/
    ├── test/
    └── pubspec.yaml

This keeps the AI folders clearly visible and separate from your app code. It also works well for monorepo setups where you have multiple Flutter apps or packages in the same repo.

When using this layout, add one line to your CLAUDE.md so ACT knows where to find the app:

Flutter app folder: my_flutter_app/

Root

Place the AI folders directly alongside your Flutter project files:

my_flutter_app/
├── .dart_tool/
├── ai_docs/
├── ai_specs/
├── android/
├── ios/
├── lib/
├── test/
└── pubspec.yaml

This works well for simple single-app repos where you don’t need the extra separation.