Tasks and workflow

Start with Tasks

Tasks is the main page. You can use it on your own, without connecting an agent:

1. Choose New task and write what needs doing. Save it to Inbox if you have not chosen a project yet, or choose the project directly.
2. Organise the task when needed: choose an owner, set a scheduled date or deadline, or use Move to put it on a project page.
3. Do the work, then use the completion circle or state button to mark it DONE. Ordinary human tasks do not need someone else's approval.

Use Mine for work you own or have claimed and Agenda for dated work. Projects keep related tasks and notes together. You can still open existing daily notes by their dated links; they are documents, not the task home.

A task is a heading, or a list item, that starts with a keyword:

## TODO Renew car insurance #admin

scheduled:: <2026-10-10 Sat 09:00>
deadline:: <2026-10-12 Mon -3d>
owner:: @planner
agent:: Compare quotes and draft a summary. Ask before paying anything.
agent_ask:: spend
budget:: £450

Everything about it lives in the text, in key:: value lines under the heading, so you can read and edit it anywhere. org works out the rest.

States

A task's keyword comes from a TODO sequence. Keywords before the | are open; keywords after it are finished. The default is:

todo:
  - [TODO, '|', DONE, CANCELLED]

Set your own for a page in its frontmatter, or for a whole space or org in settings, such as [TODO, NEXT, WAIT, "|", DONE, CANCELLED]. A page can have several sequences at once, for example one for tasks and one for bugs; a task stays within its own sequence.

Each keyword falls into a class, which is what views and agents go by:

• active: open, and something can happen
• hold: open, but parked. An org setting says which keywords count, such as WAIT
• done: finished
• cancelled: finished without doing it. CANCELLED, CANCELED, KILL and ABANDONED count, and a space can add more

Keywords can log what happens, as in Org: DONE(d!) records when a task was done, and WAIT(w@) asks for a note when a task starts waiting.

Where a task stands

Separately from its keyword, org works out a task's status in the queue. The first that applies wins:

A scheduled date never blocks. A task scheduled for next week is ready now, if you want to get ahead. Every task says what's blocking it, by short ID and reason.

Scheduled versus deadline

These are the two dates a task can have, as in Org mode:

• Scheduled is when you plan to start it. The task shows on the agenda from that day, and it keeps showing as "scheduled 3 days ago" until it's done. Nothing moves it for you.
• Deadline is when it must be done. The task shows on the agenda ahead of time, from its warning period: 14 days by default, or what -3d on the timestamp says. A deadline with a time is overdue after that time; a date-only deadline is due until the end of that day.

A task can have both: start on the 10th, finish by the 12th. It then shows twice on the agenda, once for each. Any other active timestamp in a task or a note, such as <2026-10-14 Wed 15:00>, is an appointment and shows at that time.

Times without a zone float: 9:00 is 9:00 wherever you are. Add a zone, <2026-10-14 Wed 15:00 @Europe/London>, to pin one.

Dates and repeaters

• Timed deadlines are overdue after their instant.
• Date-only deadlines stay due until the end of that day (viewer's zone).
• Scheduled items in the past with an active state show as "scheduled N days ago" in the agenda, until they're done, as Org does. There's no automatic rescheduling.

A repeater on a date makes the task come round again when it's done:

• When a repeater advances, scheduled and deadline shift by the same rule (each is evaluated independently if both repeat). last_repeat:: [now] is written, the state change is logged, and the state is reset to the first active keyword of the sequence (or to the repeat_to_state property if it's set).
• Cancelling doesn't advance.
• Warning -3d on a deadline sets when it starts showing in the agenda (the default is 14 days, from org setting deadline_warning_days). Delay -2d on scheduled hides it until then. -- applies only to the first occurrence, as in Org.

Owners

owner:: says whose task it is. An owner is one of:

• a person, such as @daniel
• an agent, such as @planner. The agent must be able to see the task's space
• a team, such as @finance. The task shows in the team's queue, and in the queues of the teams above it. Any member can claim it, person or agent, and the team stays the owner

With no owner, anyone who can see the task can pick it up. Whoever created a task is recorded, but never assumed to be its owner. A new task with no page goes to its owner's inbox, or yours.

Claims

A claim is how an agent says "I'm on this", so two agents never do the same work. It's a lease that runs out on its own:

1. The agent finds ready tasks, and reads the context of the one it picks.
2. It claims it with a claim ID it makes up, for 1 to 240 minutes (30 by default). The task is now working, and nobody else can claim it.
3. While it works, it renews the claim before it runs out.
4. When it's finished, it submits the work with evidence. If it can't finish, it releases the claim with a handoff note saying what it learned, and the next person or agent starts from there.

If a claim runs out, the task is ready again. If someone changes what the task asks for while it's claimed (its title, body, acceptance, dependencies, owner, dates or agent guidance), the claim goes stale: the agent can't renew or submit it, only release it and start again with the new requirements. You can always edit the text; it's the agent that has to catch up.

People don't need to claim: you can just do the task. If you change a task someone else has claimed, org warns you, and records it if you go ahead.

Reviews

Submitted work waits for someone to approve or reject it, and that someone is never the submitter. Each task has a review policy, set with review:: on the task or a parent, or for the whole org:

• Review agent completions (auto, the default): an agent's work needs review, and yours doesn't, unless a human has enabled Allow direct task completion for that agent.
• Review required (required): everyone's work needs review, including yours.
• No review (none): nothing is reviewed.

An agent's human owner can enable direct task completion in Settings → Your agents. Team managers and org admins can also manage this setting. The agent can then mark a task done without claiming or submitting it under Review agent completions. A task's own or inherited Review required policy still requires approval. Changing the agent's owner turns this permission off unless the human explicitly enables it again.

Approving completes the task. Rejecting sends it back to ready, with your feedback in its log, for the next attempt. Evidence is Markdown: links, a pull request, attached files, what was checked. Some tasks and spaces need a person to approve agent work; the review queue shows what's waiting for you.

The activity timeline distinguishes work performed by an agent from a completion it recorded after its human owner reported doing the work. The latter reads, for example, “Recorded by @planner from Daniel’s report.” It records the report, without treating it as independent verification or bypassing a required review.

Decisions

When a task says to ask first, the agent asks you in its own chat window, and org records your answer as a decision on the task: who asked, what, and what you said. Where it matters, such as spending money or revealing a secret, org can ask for a verified decision, which you confirm with your passkey on a page the agent links you to.

You can also make standing decisions in the app, such as "@planner may always draft emails in the Car space", so the agent doesn't have to ask each time.

Guidance for agents

agent::, agent_allow::, agent_ask:: and budget:: tell an agent how to go about a task: what it may do without asking, what to ask about first, and how much it may spend. The categories are research, draft, contact, spend, irreversible and code. Guidance is inherited from parent headings, and every agent sees it on every task.

It's guidance, not a lock. What an agent can see and change is enforced; how it should behave is what you write here. The exceptions: a secret a task names can only be revealed while the task is claimed, and where a task says to ask about a category, org won't let the agent act on that category without a recorded decision.

Order in the queue

Tasks list in this order unless a view sorts them otherwise: overdue deadlines first, then priority, then the nearest deadline, the nearest scheduled date, their order on the page, and when they were created. org never invents urgency, and never reschedules anything for you.

Tasks, Mine and Inbox

Tasks has All open, Mine, Inbox and Unassigned presets. Mine shows work owned or claimed by you. Unassigned shows open work without an owner, including work with a date.

Inbox is a holding place for tasks you capture before filing them into a project. Tasks on an Inbox page stay there until you move or complete them, even when they have an owner or date. Other unassigned, unscheduled tasks also appear in the Inbox preset.

Use the task's Move action to choose a project or another page you can edit. The task and its nested entries move together, keeping their IDs and history. Its existing owners and dates remain in the text.

Choose any layout, including Agenda, while keeping the same filter. Use Save view to keep the applied filter and layout. Open a saved view to Edit view or Delete view; deleting the view keeps its tasks and pages.

Shared projects

Open Projects to create a project in a space you can edit. A project is an ordinary Markdown page with the project tag. Give it a team owner when its tasks belong to that team. Org owners and admins can create teams and invite people from Projects.

Ownership and access are separate: members need access to the project's space. New project can explicitly give the team Editor access to that whole space. The form shows the scope of that choice before saving.

Use New task on a project to select its page and inherited team owner. Capture's Save to and Owner controls let you choose another destination, a named person or Unassigned before saving. You can also write tasks directly in the project page's editor.

Finding tasks

Views, the agenda, search, tasks for agents and ?q= in the API all use one query language:

query    := or
or       := and ("OR" and)*
and      := unary (WS unary)*            (implicit AND)
unary    := "-" unary | "(" or ")" | term
term     := WORD | "\"" PHRASE "\"" | "/" REGEX "/" | "#" TAG | "@" HANDLE | KEY ":" VALUE

Also accepted:

• level: (Org LEVEL) and tag:/re/ (Org {re})
• sort:-field for descending order
• comparisons against relative words (scheduled:<today)
• an explicit AND
• effort:90 (bare minutes)

Semantics:

• is:open means the active or hold class.
• Priority comparisons go by importance (priority:>=B means A or B), and a missing priority counts as the default (B).
• Tags are case-sensitive.
• Words and phrases match whole tokens.

Org match syntax is accepted in the match: field of agenda blocks and through org-query::parse_org_match, for example +work-boss+priority="A"/TODO|NEXT, LEVEL>2, TODO="WAIT" and SCHEDULED<"<today>". Each one compiles to the same IR (intermediate representation).