Philosophy

AI agents are most useful when they are treated like capable collaborators, not magic text boxes.

They can search a codebase, draft requirements, write tests, change code, and run verification. But they still need the same things a good human contributor needs: clear intent, shared vocabulary, bounded scope, and a way to prove the work is correct.

ACT exists to provide that structure.

The core idea

ACT turns one fragile conversation into a sequence of reviewable handoffs.

Instead of asking an agent to jump from a vague request to a finished implementation, ACT moves the work through durable artifacts:

Interview -> Spec -> Work Items -> Implementation

Each artifact has one job:

• Interview resolves intent, terminology, constraints, and important decisions before requirements are written.
• Spec describes what should be true when the change is complete.
• Interview Ledger preserves the important questions and answers that shaped the Spec.
• Work Items turn the Spec into small executable tasks with acceptance criteria, dependencies, and verification expectations.
• Implementation executes one bounded task and reports what was changed and checked.

The goal is not more process. The goal is better control over agent work.

Why this matters

Most failed agent sessions do not fail because the model cannot write code. They fail because the model was given weak context.

Common failure modes look like this:

• The agent guessed what a vague term meant.
• A decision was made in chat and then lost later.
• The task was too large, so implementation drifted.
• The agent copied the wrong pattern from the codebase.
• The code compiled, but the intended behavior was never verified.

ACT makes those failure modes visible earlier, while they are still cheap to fix.

Slow down decisions, speed up execution

Good AI-assisted development is not about making every step automatic. It is about putting human judgment at the points where judgment matters most.

ACT slows down when a wrong answer would be expensive:

• What are we actually building?
• Which term is canonical in this project?
• What behavior is in scope?
• Which edge cases should be tested?
• What must not change?

Once those decisions are clear, ACT speeds up execution by handing the agent a small task with the right context already attached.

Durable context beats long context

Long chats are a poor source of truth. They contain abandoned options, stale assumptions, failed hypotheses, and details that were true for one branch of the conversation but not the final decision.

ACT keeps the useful signal and lets the noisy conversation be discarded.

The Spec, Interview Ledger, and Work Items become durable context files or GitHub Issues, depending on your configured Workflow Storage. That means you can reset the agent session between stages and keep only the artifact that matters.

This is the practical context-management bet behind ACT: a short session with the right artifact usually beats a huge session with every prior thought still in memory.

Specs are for intent, not implementation scripts

A Spec is the requirements source of truth for a change. It should capture the problem, intended outcome, user-facing behavior, constraints, important technical decisions, testing strategy, and explicit boundaries.

A Spec should not become pseudocode.

The useful test is simple: if two competent agents could produce incompatible observable behavior without this detail, it probably belongs in the Spec. If the detail only describes one acceptable implementation route, it usually belongs in a Work Item, a test, or the code itself.

This keeps Specs useful for humans and agents:

• Specific enough to prevent guessing.
• Short enough to review.
• Stable enough to decompose into Work Items.

The Interview Ledger preserves why

The Interview Ledger is not a transcript. It is traceability for decisions that matter.

During a real interview, important answers often include constraints that are easy to weaken later:

• Retry should preserve existing input.
• External services should be faked in tests.
• A screen should support empty, loading, and error states.
• A feature should not add account creation yet.

The ledger gives those answers stable IDs, such as L1 or L2, so later stages can reference them without copying the entire conversation. The Spec can cite ledger IDs, and Work Items can show which decisions they cover.

That makes it easier to catch when a later artifact quietly drops a constraint the user already answered.

Work Items keep agents focused

Large agent tasks drift. A broad feature request invites the agent to solve adjacent problems, over-edit the codebase, and produce a diff that is hard to review.

ACT uses Work Items to create bounded execution units.

A good Work Item says:

• What to build now.
• Which Spec requirements and ledger decisions it covers.
• Which other Work Items block it.
• Which acceptance criteria must pass.
• Which verification steps are expected.

For Flutter and Dart work, the -flutter workflow path carries additional expectations around user flows, UI states, test seams, vertical slices, and verification commands.

Verification is part of the work

ACT treats verification as a feedback loop, not a final decoration.

An implementation task should not end at “I changed the code.” It should end with evidence:

• Static analysis ran.
• Focused tests ran.
• The relevant full suite ran when feasible.
• Acceptance criteria were checked.
• Any skipped or blocked verification was reported.

For Flutter/Dart projects, this usually means fast loops around flutter analyze, flutter test, focused widget tests, unit tests, and robot-style journey tests where they are useful.

The principle is simple: agents get better when they can verify their own work against explicit expectations.

Storage should fit the project

ACT can store Specs, Interview Ledgers, and Work Items as local Markdown files or 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. Either way, the workflow terms stay the same: a Spec is still a Spec, a Work Item is still a bounded task, and the configured storage should not change the meaning of the artifact.

Project setup keeps this split intentional:

• .act/config.yaml stores the mechanical Workflow Storage choice.
• .act/workflow.md explains the project-local ACT vocabulary and storage rules for agents.
• GLOSSARY.md, when present, records durable project language.

The mechanical settings stay machine-readable. The workflow meaning stays human-readable.

ACT keeps you in the loop

ACT is not trying to remove the developer from the loop.

It gives the developer better checkpoints:

• Approve the important decisions before a Spec is written.
• Review the Spec before implementation is planned.
• Review the Work Item breakdown before tasks are created.
• Review verification evidence before accepting code.

Between those checkpoints, the agent can do real work with much more autonomy because the boundaries are clear.

That is the ACT philosophy: use humans for judgment, use agents for execution, and use durable artifacts to keep both sides honest.

Next steps

• Follow the Quickstart to run the workflow on a project.
• Read the Workflow Overview for each stage in detail.
• Read Context Management to understand why ACT resets between stages.
• Read AI Verification for the feedback-loop model behind implementation.