Intents

An intent is an outcome you agree with your agent before anything is built. It says what should change and why, in words you accepted. Everything your agent does afterwards, the design, the plan, the tasks and the code, exists to deliver that outcome.

Why intents come first

An AI agent will build whatever you ask for, including the wrong thing. An intent puts one step in front of the code: before your agent designs or builds a feature, a component or a change in behaviour, you and your agent agree what it should achieve.

Small, self-contained work does not need an intent. A typo, a copy tweak or an obvious one-file fix is just a task. Anything that changes how the product behaves gets an intent, even when it looks simple, because that is where unexamined assumptions cost the most.

An intent belongs to the workspace, not to one repository, so a single intent can span several areas. It usually sits under a mission.

The outcome list

The heart of an intent is its outcome list: one to seven short lines, each a single promise written the way you would read it in release notes.

Outcomes list

1. Self-serve sign-up — A new user can create an
   account and reach the dashboard without talking
   to sales. [user]
2. Invite links — An account owner can invite a
   teammate with a link that expires after 7 days.
   [customer]
3. No lost sign-ups — A user who closes the browser
   mid sign-up can finish later from the email link.
   [user]

Each line names who notices the change and what they can do, never how it is built. Your agent proposes the list, and you accept it, comment on it or rewrite lines until the whole list is right. Only lines you accepted are written to the intent, together with why the change matters, what is out of scope and how success will be checked.

The outcome list is also how the intent is judged at the end. When the work is ready for review, each line is checked against what was built and marked as delivered or dropped.

Intent statuses

An intent moves through these statuses, in this order:

An intent can also be cancelled at any point, with the reason recorded.

Each step from new to in_review is one gate of the intent flow. Your agent does not skip a gate and does not move to the next one without asking you.

Your agent keeps the intent current

You do not maintain the intent by hand. As you talk, your agent writes to it:

• the outcome you accepted, with the why, the scope and the success check;
• the design you approved;
• the plan: the tasks, their order and the notes that apply to all of them;
• the work log: every decision with its reason, every blocker, and a record of each status change.

A status change always carries the reason for it, so the log tells the story of the intent: why this outcome, which approach won and what was rejected, what shipped. When you come back after a week, or another agent picks the intent up, that history is what they read first.

Asking your agent about intents

~/acme

❯ I want new users to sign up without a sales call.

Your agent: That changes how the product behaves, so
I'll frame it as an intent first. One question:
who should be able to sign up on their own?

  a) Anyone with an email address (recommended:
     the beta is open, and this keeps it simplest)
  b) Only people with an invite
  c) Something else, tell me

Other things you can ask:

• "What intents are open under the current mission?"
• "Show me the outcomes of the sign-up intent."
• "Cancel the dark-mode intent, we've decided against it."
• "Which intents are waiting for my review?"

Intents in the OrbitMap app

The OrbitMap app shows the same intents your agent works with. Each intent shows its status and its outcome list, with a check next to each delivered outcome and a cross next to a dropped one. You can open an intent to read its design, its plan, its tasks and the work log, and the dashboard lists the intents waiting for your review.

Next

• The intent flow: what you decide at each gate, from brainstorm to review.
• Missions: the time-boxed focus that intents belong to.