Intents

An intent is a work item authored against real board elements, handed off to developers, and returned with evidence.

What an intent is

An intent is a live spec. It stores why this should happen and what must become true, then continues through delivery.

It stays anchored to the elements it concerns. For structural requests, a later push from the repo either confirms the change or shows that it still needs attention. A requirements document is usually static; an intent accumulates delivery evidence.

Intents are a facet of an app board. The hub shows intents waiting on you, and the Intents screen holds the full queue. Any board contributor can author them.

The fields

An intent has four main fields:

Why stores reasoning: what you worried about, considered, or ruled out. It is optional and collapsed by default. Many intents are only a line and a link.

There's no priority field on an intent. Priority is a property of an insight; an intent is ordered by its status and by what the hub says needs your decision.

Eight ways one gets created

Every path leads to the same editor and queue. Only the prefilled context changes.

• From an insight. The main path: an analysis or /monitor produces a batch of insights, you review them, and the ones worth acting on become intents. Each intent keeps its origin. See Insights.
• By hand, from an element. Right-click a node, edge, or board on the canvas or board map and choose "Create intent for {name}". You can also use the ⊕ toggle on any element or aspect row to add it to an intent you are already building. The intent is pre-anchored to the item you chose.
• From the Intents screen or the hub. Use Create intent on the screen or New intent on the hub's intents card for work that spans elements. During an active session, either control reads Open intent editor and reopens that session.
• From a captured board edit. On an app board, code is the source of truth for structure. Editing a fact, such as adding a node, redrawing an edge, or deleting an element, stages that edit. Committing your working copy files it as an intent for the code side to make true. Naming, descriptions, and layout still save normally.
• Filed by a plugin. A plugin run can file work it found, anchored to the elements involved and back-linked to the insight behind it. Those are created as drafts waiting for a person.
• Drafted in chat. Ask chat to turn the two riskiest insights from last night's batch into intents. It asks for your approval in the conversation, and what it creates is a draft for the same review as everything else.
• Drafted from a bound document. Bind an existing PRD or RFC and draft intents from it. Each intent records the document it came from. Below.
• Captured from the running UI. /inspect opens your running app in a real browser; the screens you pick and annotate become an intent's visual context.

The intent editor

One editor session makes one intent. It opens in the dock and stays with you as you navigate.

Anchors split into two kinds. Changed on the board holds elements the intent proposes to change. In discussion holds context elements nobody is being asked to touch.

While recording, click elements to add them to the intent. A depth dial can limit capture to one layer. The editor groups anchors by board and shows which ones still need explanation.

The queue

The Intents screen opens on where the plan stands. A band across the top gives one number per stage, Draft, Handed off, In progress, and Completed, with who holds each and how many completed intents a sync has confirmed. Stages an intent only sometimes visits (Needs clarification, Declined, Resolved) appear when something is in them. To the right, Flagged counts the intents that are Drifted or In conflict. Click any number to narrow the list to it; click it again to clear.

Under the band, one line does search and filter: type a name, an anchor, a tag, or a status and pick a value to turn it into a filter chip. The View menu groups and sorts the list; the toggle beside it switches to the grid.

The list leads with Needs you: drafts to hand off, questions from developers, and live intents that drifted or conflict. Everything else follows, grouped by status. Each row carries the name, one line saying where it stands (who asked what, what moved, who is on it, when a sync confirmed it), and the elements it touches. Hover a draft for Hand off to Dev; the ⋯ menu tags or deletes it. Select rows to hand off, tag, or delete a batch.

The count under the title says which scope you are reading, on this board or across this board tree, with a link to switch. On a command center, the queue always covers the whole tree.

Click a row to open the intent in the editor dock. There is no separate detail page. Every anchor is a link.

The grid

The grid shows the same queue as a plan. Switch from List to Grid to spread intents across a matrix.

Rows use your chosen grouping. By default, they follow the board map, so the plan reads down the same tree you navigate.

Columns show the wave, or how many groups of intents must finish before this one can start.

Wave 1 waits on nothing; everything in wave 3 follows something in wave 2. Read left to right to see the migration sequence. Read down to see who carries it.

Author the sequence on the grid. Drag a card onto the intent it follows to move it into the next wave. Click a card to highlight every intent before and after it. Remove a dependency from the strip above the grid.

An intent can wait on several others from any board under the same root. You can change the order at any status, including after completion. The grid refuses dependency cycles.

Columns can also show status, priority, effort, or a phase. A phase is your own ordered tag vocabulary; set the order in Settings → Context tags. Drifted is never a column. A drifted intent appears as a tan card in its current column, so this state remains visible across the grid.

The grid uses the same search, filters, and stage band as the list. Its state travels in the address bar, so copy the link to share a plan.

Status

Hand off to developers locks the intent and makes it visible to /intents. A draft can be complete; you are deciding when to hand it off.

Needs clarification returns an intent for revision when the board has drifted under it.

Deleting an intent

Delete removes the intent. The board keeps what you committed. If the intent added elements, they stay on the board until code catches up or you remove them. If it removed a code-owned element, the next sync brings it back. Intents a developer has claimed cannot be deleted until they release them; Completed intents stay as the record of what shipped.

Drifted, In conflict, and Completed

Three marks can appear next to a status:

• ≠ Drifted means the anchors moved after the intent was written. Review it before anyone builds against an outdated board.
• In conflict means another intent changes the same element. Developers cannot pull either intent until you choose the order, usually by deleting or re-scoping one.
• ✓ Confirmed appears on a Completed intent after /sync finds the change in code.

Only structural intents can earn the check. Answering Remove on an anchored element creates a claim that sync can test. Prose-only intents complete on the developer's evidence and never show the check.

Visual context

An intent can include the screen it concerns. Each page captured by /inspect is stored as a page capture: a clean screenshot plus an element map. From the editor, you can annotate it:

• Pick a component. The highlight snaps to the smallest element under your cursor, down to a page's internal components, and resolves to the source file it renders from. The anchor points a developer at real code, not at a description.
• Draw an annotation. Box any region and add a note, such as "this spacing is wrong" or "make this a dropdown". The annotation stays with the intent.
• Work from the list instead. The capture's render tree sits beside the image, so you can pick a component by name rather than by pixel.

Expand

/intents shows the annotated screen, picked components, and files behind them. Pages covers captures.

Drafted from

Bind a PRD or RFC as a reference source and draft intents from it. Each intent records a Drafted from line, linked when the source has a URL. That line is:

• Provenance, not a sync. The document is never modified, and nothing keeps the two in step. If the PRD changes, the intents drafted from it do not change. They are work items now, with their own lifecycle.
• Recorded, not required. An intent drafted from your own description in conversation has no source document and shows no line. Nothing is missing.
• Yours, still. The document stays where it lives. The board adds anchors and evidence: which elements the requirement touches, and whether the code made it true.

How developers receive them

Developers pick up work from the repo with /intents, in the code plugin or the connect plugin. It follows a fixed sequence: claim, gap review, implement, and resolve.

The gap review happens before any edit, so a drifted intent returns as Needs clarification. An intent is completed only with recorded verify evidence from project checks.

What's next