How agents work

You steer the work with missions and intents. Your agent does the rest: it breaks an agreed intent into tasks, works through them, writes down what it decided and changed, and keeps the documents it reads up to date. This page explains what your agent keeps in OrbitMap while it works, so you know what you are looking at when you open an intent.

Tasks are your agent's work

A task is one unit of work your agent can build and test on its own. You do not write tasks and you do not keep a task list by hand. Your agent creates them.

Where tasks come from

Tasks appear at the plan step of the intent flow. Once you have agreed the outcome and the design of an intent, your agent turns the design into tasks under that intent. Each task carries:

• the instructions your agent will follow when it builds it, including the files and sources it needs,
• the tests that prove it works,
• the tasks it depends on, so the work runs in the right order.

The plan also includes one test for the intent as a whole, which checks every outcome line you agreed. Your agent shows you the plan before anything is built.

How your agent works through them

During the build step your agent works through the tasks of the intent. You start it with one sentence:

❯ execute IN-w8d3kq

Intent "Weekly digest email" is at build with 5 tasks.
Recording a test baseline, then branching intent/w8d3kq-weekly-digest.

Wave 1: TS-k2so77 Digest query, TS-r2d2x1 Email template
Wave 2: TS-c3po42 Schedule the send (depends on TS-k2so77)
...

Your agent runs independent tasks in parallel and the rest in order, runs each task's tests, commits each task on the intent branch, and finishes with the intent test and a full test run compared with the baseline. A task that gets stuck is marked blocked with the reason, and the rest of the intent carries on. At the end every finished task waits in review on one branch, and your agent reports what shipped, what it decided and what is blocked.

Nothing is merged for you. You review the branch and merge it yourself.

You can also point your agent at a single task, for example work on TS-k2so77. It starts or resumes that task, builds and tests it, and leaves it in review.

What you see

Open an intent in the app to see its tasks, their status and their work log. You do not need to move tasks around: your agent sets the status as it works, and a finished task waits in review until you check it.

The work log

Your agent writes a work log as it goes. Each entry is short and has a type:

• decision: what your agent chose and why, including the option it rejected,
• code_change: what was built and where,
• blocker: what stopped the work and what is needed to continue,
• note: anything else worth keeping, such as a resume point for the next session.

Entries sit on tasks, and the ones that matter beyond a single task also go on the intent, worded for a reader who never saw the task. The log records what git cannot: the reasons behind a change, a claim in the plan that turned out wrong, a risk found along the way. It does not repeat file lists or test counts.

When a session ends before the work is done, your agent leaves a resume point. The next session, on any machine and with any connected agent, reads the log and picks up where the last one stopped.

An intent also keeps its own log. Every status change of an intent must carry at least one entry, so each step of the intent flow leaves a written record of what was decided.

Documents

Documents hold the knowledge your agent should not have to rediscover: specs, architecture notes, guides, API references, decisions. A document belongs to your workspace and can be linked to one or more areas, or to none, which makes it workspace-wide.

Each document has a short note on when it is relevant. Your agent uses that note to pick the right document, then reads only what it needs: the table of contents first, then a single section, and the full text only as a last resort.

Your agent also keeps documents current. When a finished intent changes how something works, your agent updates the matching document or writes a new one, for example a maintenance guide or a release note. Every change goes through the orbitmap CLI, so each document keeps a version and a changelog.

You can ask for this directly:

❯ read the API spec and check whether the new endpoint matches it

Reading "Agent API Specification", section "## Endpoints".
The spec lists the endpoint without the `since` filter. I will add it
and record the change in the changelog.

Ideas, issues and vibes

Three small records catch what falls outside a planned intent.

Ideas

An idea is a possibility for the future, not a problem. When you or your agent think of something worth doing later, it goes in as an idea instead of turning into work straight away. An idea can belong to one area or to the whole workspace. When you decide to build it, your agent brainstorms it into an intent and marks the idea as used.

Issues

An issue is a problem: a bug, a failing check, something that behaves wrong. It has a severity and moves from open through investigating to resolved, or is closed as a duplicate or as not worth fixing. Your agent registers issues it runs into along the way, logs its diagnosis on the issue, and links the task that fixes it.

Vibes

A vibe is a log entry for ad-hoc work outside any task: a quick fix, an exploration, something your agent discovered while reading the code. It keeps that work on record without inventing a task for it.