# Intent

The approved, versioned agreement about what a piece of work should accomplish — and the rules that stop it quietly changing.

Status: Available

Documentation updated: 2026-09-28

Source: https://docs.orneos.com/docs/intent

Intent is a statement of what a piece of work is meant to accomplish, attached to an issue, approved by a person, and versioned.

It is the part of Orneos that exists because of the review problem. A reviewer looking at a change needs something to judge it *against*. A title does not do it; a description drifts; chat scrollback is not a record. Intent is the thing the reviewer reads first.

## Write and approve your first Intent

Open an issue, find its **Intent** panel, and choose **Write manually**. You do not need an AI key. For the fictional “Export filtered issues to CSV” change from the [quickstart](https://docs.orneos.com/docs/quickstart), enter:

| Field | Example writing |
|---|---|
| **Goal** | Let someone export the issues currently shown in a filtered view to a CSV file. |
| **Acceptance criteria** | Only matching issues are exported. The export includes visible columns in their displayed order. An empty result produces headers and no issue rows. Enter these as separate items. |
| **Not in scope** | Scheduled exports, importing CSV, and exporting hidden columns. |

This example describes a proposed change, not an available Orneos CSV feature. Use the requirements your reviewer actually agreed to.

Read the fields, then choose **Approve**. **Check that it worked:** the panel shows the approved revision, approver and time, with **Revise** available. A first approval is revision 1. Check pending or failed changes; the context export only identifies an agreement as confirmed after server confirmation.

To change the agreement, choose **Revise**, edit the relevant fields, review and approve again. Changed content receives a new revision; an unchanged ordinary revision keeps the existing approval. Copy any writing you need to retain before closing an editing session, which is held in memory until submission.

Next, use [Copy context bundle](https://docs.orneos.com/docs/context-bundles) to send the agreement with its revision and supporting task context to a reviewer. **Copy intent** serves a different purpose: it copies the displayed writing without approval metadata.

## What it contains

| Part | What it is for |
|---|---|
| **Goal** | One statement of what should be true when this is done. |
| **Acceptance criteria** | The specific, checkable conditions the team agreed to. These are what a reviewer maps evidence to. |
| **Non-goals** | What this explicitly does not cover. The part everyone skips and then argues about. |

## The four states

The panel on an issue is in one of four states, and the whole design goal was that getting from the first to the last is two clicks plus whatever editing you want:

**Empty.** Choose *Draft with AI* using a [personal drafting key](https://docs.orneos.com/docs/ai-keys) or [Orneos credit when enabled](https://docs.orneos.com/docs/ai-funding), or choose *Write manually*.

**Drafting.** A request is in flight. Cancellable.

**Draft.** Edit the labelled Goal, Acceptance criteria and Not in scope fields, then review and use **Approve**. An editable draft is not an approved agreement.

**Approved.** `✓ v3 · approved by Sam · 11 Sep 2026`, with a **Revise** button. Superseded revisions are behind a compact history disclosure, collapsed by default because nobody reads history on the happy path.

## The rules that make it worth having

These four properties are the mechanism. Without them Intent is a second description field.

### A draft is not an agreement

Nothing is approved until a person clicks Approve. If AI drafted it, that is disclosed. A generated draft that nobody read is not an agreement, and the product never treats it as one.

### Approval names a person and a revision

Approval stamps a revision number, the approver's name, and the time. "The team agreed" is not a fact the system can record; "Sam approved revision 3 on 11 September" is.

### An approval does not follow later revisions

If the agreement changes to v4, the approval of v3 does not come with it. v4 needs its own approval.

This is the property that makes Intent usable as a standard. An agreement that silently updated to match whatever the work became could never be used to judge whether the work was right.

### Revise creates nothing until you approve

Clicking **Revise** opens an editing session over the approved revision. It does not create a revision. Approving compares what you have with what was approved: if the content is identical, nothing is approved and the panel says so — the existing revision keeps its approver, timestamp and number.

The consequence to know: **your editing session is in memory until you approve.** It is not a saved draft. The editor says so rather than implying otherwise, but if you close the tab mid-revision you lose the edit, not the approved revision.

## Staleness is advisory, never blocking

If the issue's title or description changes after approval, the panel marks the Intent as **possibly stale**.

What that badge does and does not mean:

- It is a **signal**, computed by comparing the issue against a fingerprint taken at approval time.
- It never changes state, never invalidates anything, and never disables a control.
- **A stale Intent is still the approved Intent** until a human approves a replacement.
- `Not stale` is not proof of freshness — it also covers "we could not establish staleness", for instance when the fingerprint is missing.

Blocking on staleness was considered and rejected. An agreement that the system can invalidate on its own is an agreement the system is a party to, and it is not.

## Redrafting and rejected submissions

**Redraft from current task** prepares a proposal against the task as it now reads. Approving that explicit re-anchoring can create a new revision even when the text is unchanged; ordinary unchanged approval keeps the existing revision. Review the new proposal before approving it.

If a submitted approval loses a conflict or is rejected, a recovery notice preserves the submitted writing in the local queue. **Restore as draft for review** lets you review it against the current approved revision; **Copy submitted writing** provides a separate way to retain the text. Neither recovery action overrides confirmed history. This protection applies to a retained submission, not to an unsaved in-memory editing session, and clearing local storage destroys that local recovery material.

## AI drafting

With a [drafting key](https://docs.orneos.com/docs/ai-keys) configured, *Draft with AI* sends the assembled, export-filtered task context directly from your browser to Anthropic. Enabled [funded drafting](https://docs.orneos.com/docs/ai-funding) sends that context through Orneos to its configured provider instead.

The context can include task fields, confirmed Intent when available, project details, parent/sub-issues and relations, available discussion, and eligible Vault titles and links. It does not include Vault page bodies. Restricted/private Vault enrichment and references of unknown visibility are excluded; URLs already in user-authored text remain. See [Privacy and your data](https://docs.orneos.com/docs/privacy-and-data) before sending project material.

It proposes. You read it, edit it and approve it. The disclosure that a draft was AI-assisted is part of the record, because "who wrote this agreement" is a thing a reviewer may reasonably want to know.

Without a personal key, BYO drafting is unavailable; manual writing still works. A separate funded option depends on [server configuration and allowance](https://docs.orneos.com/docs/ai-funding).

## Exporting

**Copy intent**, in the Intent panel, copies the intent text currently shown: goal, acceptance criteria and non-goals. While editing, it copies your unapproved draft. With no editor open, it copies the displayed approved revision. This plain-text copy does not add revision or approval metadata and does not approve anything.

The issue's **Copy context bundle** is a separate action. It exports task context and the server-confirmed Intent with revision and approval details when available; pending or unavailable confirmation is disclosed. It does not substitute an unapproved editing buffer for the confirmed agreement. See [Context bundles](https://docs.orneos.com/docs/context-bundles).

## When to write one

Not on every issue. The cost is real and a bad Intent is worse than none.

Write one when:

- someone other than the author will judge whether it is done;
- an agent is going to do the work, or did;
- the thing is contentious, or the scope has already moved once.

Skip it for obvious small work. A typo fix does not need an agreement.

## Related

- [Context bundles](https://docs.orneos.com/docs/context-bundles) — how an Intent reaches a reviewer with its supporting material.
- [The review workflow](https://docs.orneos.com/docs/review-workflow) — what happens with it in a pilot.
- [Drafting keys](https://docs.orneos.com/docs/ai-keys) — enabling AI-assisted drafting.