Project Setup

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

Run act-config

Run act-config once from the directory where you want ACT to save generated docs and implementation tasks:

/act-config

act-config creates or updates these project-local files:

• .act/config.yaml — the source of truth for where generated docs and implementation tasks are saved.
• .act/workflow.md — a project-local guide that tells agents how ACT files and terms work in this project.
• AGENTS.md or CLAUDE.md — a short pointer that tells agents to read .act/config.yaml and .act/workflow.md.

If .act/config.yaml is missing, act-create-spec or act-create-issues can invoke act-config automatically before writing generated docs or implementation tasks.

Specs, Work Items, and Interview Ledger

ACT uses these artifact names in the current workflow:

• Spec — a requirements document that describes what should be built before code changes start.
• Work Item — a small implementation task created from a Spec, with context, acceptance criteria, dependencies, and verification steps.
• Interview Ledger — a record of important questions and answers that influenced the Spec.

Work Items are created from a parent Spec and are saved in the same place as that Spec.

Where ACT saves files

ACT can save Specs and Work Items in two places:

• Local Markdown files — Specs and Work Items are saved under a configured local path.
• GitHub Issues — Specs and Work Items are saved as GitHub Issues.

ACT uses GitHub storage if the repo has a GitHub origin, and local Markdown files otherwise. This is configurable when act-config is called. The config lives in the current working directory and looks like this for local files:

workflow:
  backend: local

local:
  path: ai_specs

For GitHub Issues, the config uses GitHub mode:

workflow:
  backend: github

GitHub mode only saves Specs and Work Items as Issues. It does not add labels, Projects, issue closure, PR lifecycle, or merge automation.

Local file paths

When workflow.backend is local, local.path is resolved relative to the current working directory. The default path is ai_specs, but projects can choose another local folder.

Local Specs live in numbered folders under the configured local path:

<local.path>/0001-settings/spec.md
<local.path>/0001-settings/interview-ledger.md

Derived Work Items live under the parent Spec’s work-items/ folder:

<local.path>/0001-settings/work-items/01-settings-screen.md
<local.path>/0001-settings/work-items/02-settings-persistence.md

The ai_specs/ path is therefore an example of a configured local path, not a universal requirement. If your .act/config.yaml uses another local.path, ACT uses that path instead.

Project knowledge

ACT can also use project knowledge files that live alongside your code:

• GLOSSARY.md — shared terminology for common domain language and project-specific meanings.

• ai_logs/ — optional session logs for debugging and review.

You don’t need to create these manually before using ACT. Workflow skills create required workflow files as needed, and session logs are disabled by default.

GLOSSARY.md

GLOSSARY.md gives ACT and human contributors a shared language for terms that are frequently used within the project. It is especially useful when a word has a project-specific meaning, when business rules depend on exact wording, or when a term should be used consistently across Specs and Work Items.

ai_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.

To enable it, edit the global ACT settings file created by the installer, ~/.config/agentic-coding-toolkit/act-settings.json, and set enableLogging to true:

{
  "enableLogging": true
}

Once enabled, ACT writes session logs to your project’s ai_logs/ folder. You don’t need to create ai_logs/ manually; it appears after the first logged session.

Project layout

You have two common options for where to place ACT files relative to your Flutter project. These examples show ai_specs/ as the default local path for Specs and Work Items.

Subfolder (recommended)

Place your Flutter app inside a subfolder, with ACT files at the repo root:

my_repo/
├── .act/
├── AGENTS.md
├── GLOSSARY.md
├── ai_specs/
└── my_flutter_app/
    ├── .dart_tool/
    ├── android/
    ├── ios/
    ├── lib/
    ├── test/
    └── pubspec.yaml

This keeps ACT files 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 or AGENTS.md so agents know where to find the app:

Flutter app folder: my_flutter_app/

Root

Place ACT files directly alongside your Flutter project files:

my_flutter_app/
├── .act/
├── .dart_tool/
├── AGENTS.md
├── GLOSSARY.md
├── ai_specs/
├── android/
├── ios/
├── lib/
├── test/
└── pubspec.yaml

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