# Engage

> Start from the computed ready set, work one task, and write the result back before the agent run ends.

**Engage is doing the work.** It produces work done and the task's result written back into the graph: what was made, where the task now stands, and why.

## How to do it

### Choose from what is ready

What is ready, what holds the rest and how the ready set is ranked are computed on every read ([P5](https://flow.ttoss.dev/docs/method/principles.md#p5-what-to-do-next-is-computed-not-remembered)); [How Flow works](https://flow.ttoss.dev/docs/start/concepts.md#what-flow-computes) has all three. Most tasks carry no priority, so for most of the list **leverage** decides: how many tasks finishing this one would free.

### Work one task per agent run

The task is the brief. An agent picking one up reads it in full: title, references, edges, waits and anything that justifies it. That should be enough context. If it isn't, the task is under-specified: say so and improve the task, rather than briefing the agent in chat and leaving the task thin.

1. **Choose.** Ask [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) for the next action. It answers one task, the strongest, rather than a list to choose from again; agree on it, or ask for more if it is not the one.
2. **Read.** Load it with [`get-task`](https://flow.ttoss.dev/docs/reference/get-task.md), everything hanging off it included.
3. **Take.** A person assigns it to themselves with `assignee: "me"`, so nobody else is offered it. An agent takes it with its run instead: naming the task in the run's `works_on` is the claim.
4. **Work.** Stay inside the task. Anything else you notice is [written down](https://flow.ttoss.dev/docs/method/capture.md), not done.
5. **Write back.** Before the agent run ends, write what was produced, where the task stands and why, and what it waits on ([GTF-S3](https://flow.ttoss.dev/docs/agents/protocol.md#agent-runs)). The test: a fresh agent run, with no memory of this one, reads the task with [`get-task`](https://flow.ttoss.dev/docs/reference/get-task.md) and can carry on without asking what happened. Chat logs, memory files and the pull request's description are not where a commitment's state lives.

### Take it before you start

A task names who has taken it on: a person in the project, or one of its teams when the work is routed but nobody in particular has it yet. [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) offers only what nobody has taken and what is yours or your team's, so work somebody took is never offered to anyone else. `assignee=any` shows everyone's.

- **Route to a team, then let the team resolve it.** Make teams with [`create-team`](https://flow.ttoss.dev/docs/reference/create-team.md) (Product, Engineering) and assign the task to the team. Whoever in it takes it assigns it to themselves, with no flag.
- **Taking somebody else's work is not refused, and never silent.** The write lands, the task is flagged, and the answer names `previous_assignee`: talk to them before both of you work on it.
- **Release what you stop.** `assignee: null` puts it back in everyone's ready set.

Agents working for one person are all that person to the assignee, so the assignee cannot tell them apart and they leave it alone. What tells them apart is the run each one records: naming a task in the run's `works_on` takes it, and a task another running run already has comes back under `contended`, as [many agents](https://flow.ttoss.dev/docs/method/roles.md#many-agents) describes.

### Run many agents at once

[`get-order`](https://flow.ttoss.dev/docs/reference/get-order.md) returns the `blocks` graph in [waves](https://flow.ttoss.dev/docs/start/concepts.md#what-flow-computes): give each agent one task from the first wave, and a credential of its own.

With no target to order, ask [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) for as many tasks as you will start, with `limit`. Its default answer is one task, the strongest, because a person given a list is handed back the choice the ranking made; an agent dividing work needs the next few instead. `total` beside the answer says how many are ready, so one answer is never read as the only one.

### Pursue a target

You can name a target, a task or a goal, and ask an agent to finish it: "finish the March close", "finish the v2 launch". The agent then works through everything upstream of it, one task at a time, without asking you again for each. It reads [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) with `upstream_of` set to the target, takes one ready task with its run, works it, writes it back, and reads again. When nothing upstream is ready, it stops and tells you what is left and what holds each task.

The method is the same for everyone. What finishing a task takes is not, so you write it down once, as a [standing rule](https://flow.ttoss.dev/docs/method/roles.md#standing-rules) that says four things:

| The rule says                     | Someone shipping software                        | An accountant                                           |
| --------------------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| What the agent may do to finish   | Merge its own pull request once checks pass      | Send a return once the figures reconcile                |
| What evidence closes a task       | The merged pull request                          | The filing receipt                                      |
| Which choices it may make itself  | Test names, internal refactors inside one module | Classify an expense that has a precedent for the client |
| What it may tidy after a delivery | Complete another task the merged PR also meets   | Complete another task the same filing also settles      |

Anything the rule does not list is yours. When the work needs a choice the rule does not delegate, such as which of two designs to build or whether a client files the simple or the full return, the agent does not make it. It moves the task to `waiting` on you, with the question, the options and its recommendation in the wait, and goes on to the next ready one; a choice that holds several tasks is a [decision](https://flow.ttoss.dev/docs/method/connect.md#decisions-are-tasks) that `blocks` them. Either way the work leaves the ready set without anyone judging anything, and the question shows up in your `waiting_on_me`. Answer it, and the work is ready again for the next run.

Work the agent finds on the way is handled the same way it always is. A prerequisite the current task cannot be finished without becomes a task that `blocks` it. Everything else is [written down](https://flow.ttoss.dev/docs/method/capture.md) as an `incubated` task, so the target only grows by what the work requires, and you promote or discard the rest. An act you kept for yourself, such as the merge or the filing, is not done for you: the task waits on you, with what is ready attached.

A delivery also changes tasks besides the one worked. The delivery names them, such as in the pull request's body, and whoever writes the task once it lands tidies what the rule's fourth line hands over ([tidying after a delivery](https://flow.ttoss.dev/docs/method/roles.md#tidying-after-a-delivery)); a rule that says nothing about tidying leaves all of it to you.

A target can also be open-ended: everything ready in a project, or under a tag, for as long as the rule stands. An agent run then reads that project or tag where it would read `upstream_of`, works what it may start, and ends when nothing it may start is ready. The next run, whoever starts it, takes up from the graph. Such runs are usually [unattended](https://flow.ttoss.dev/docs/agents/protocol.md#unattended-runs): nobody reads them while they work.

[Name a target, and let the agent finish it](https://flow.ttoss.dev/docs/examples/pursue-a-target.md) runs the whole loop, a question for the person included.

### Close with an outcome or a reason

Every close says how it ended:

- `completed` with an **outcome**: what was achieved. "Merged in PR #212, deployed 14 Sep."
- `cancelled` with a **reason**: why a real commitment was dropped. "Superseded by the pricing rewrite."
- `discarded` with a **reason**: it was never a real commitment. It was created in error, or turned out to be a duplicate.

Closing needs a cause ([P4](https://flow.ttoss.dev/docs/method/principles.md#p4-every-change-to-a-commitment-carries-its-cause)). When the cause is another record in the graph, such as a decision, an evidence record or the task this one duplicates, cite its id as the basis. When it lives outside the graph, as a merged PR usually does, cite its URL as the basis: `basis: ["https://github.com/acme/app/pull/212"]`. Flow attaches it to the task as a reference, and the close raises no flag. When the cause is the person's answer to your proposal, cite their words as they said them: `basis: [{ "said": "yes, close it" }]`. When the cause is the standing rule your run acts under, your run already names it as its `authority`, and a write that names no basis inherits it. Every way, the cause ends up written down, on the change it justified.

Delivered is not in effect. When the work is handed over but nobody has seen it take effect where it matters, don't close yet: code is merged but nobody has seen it running, a return is sent but not yet accepted. Leave a check in its place:

- **When you can say when it shows,** move the task to `calendar` with a `scheduled` wait. Its `until` is the earliest moment the effect can be seen, worked out from something you can point to, such as the release schedule or the processing time the tax office states. Its reason is the check: what to look at, where, and what you expect to find. "The v2.3 release reaches production by 14:00 on its schedule. Check: the export page offers CSV, and the export log shows no error since."
- **When you can't,** move it to `waiting` with an `external` wait naming the event, the check in its reason and the date to chase in `until`: "Until the return shows as processed. Check: the portal lists it as accepted."

When other work in the graph has to happen first, such as a release step, it `blocks` this task ([connect](https://flow.ttoss.dev/docs/method/connect.md)), and the check is written once it is done.

The task leaves the ready set and says why. When the date comes, [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md) answers it in `slice=date_came` (or `slice=hold_cleared`, once somebody clears the wait), and whoever reads it runs the check: close it with what was observed as its outcome, or move it back to `active` with what was observed in its body. Either way the check is part of this task. A new "verify X" task would close the work before anyone saw it take effect.

A closed task is final. To reopen the work, create a new task that `supersedes` the old one.

## The person

- **Choose what to start.** An agent does not pick for you unless you asked it to.
- **Name a target to finish,** and write down once what an agent may do to finish it. Everything you leave out stays yours.
- **Set priorities.** Priority is the one input to the ranking only you can give. Leave it empty where nothing special is at stake, and leverage will order the rest.
- **Ask for the write-back.** "Let's stop here" is the cue for the agent to write back and tell you in one line what it wrote.

The agent's side is the protocol: [GTF-E1 to GTF-E9 and GTF-T1 to GTF-T6](https://flow.ttoss.dev/docs/agents/protocol.md#engage).

## Failure modes

- **Working from memory.** The task that was ready yesterday may be blocked, done or cancelled today. Read the graph.
- **The brief lives in chat.** The next agent run will not have the chat. Put what the work needs on the task.
- **"Done" without evidence.** A close with no outcome and nothing attached is a claim nobody can check.
- **Making the choice to keep going.** Pursuing a target, an agent that settles an open choice itself finishes faster and builds what nobody decided. Put the question to the person and move on.
- **Leaving without writing back.** The work happened, but the graph says it didn't, and the next reader believes the graph.

## In Flow

| To                                           | Call                                                             |
| -------------------------------------------- | ---------------------------------------------------------------- |
| The ready set, ranked, plus what has drifted | [`get-next`](https://flow.ttoss.dev/docs/reference/get-next.md)                           |
| Waves of parallel work                       | [`get-order`](https://flow.ttoss.dev/docs/reference/get-order.md)                         |
| What is left before one goal                 | `get-next` or `get-order` with `upstream_of`                     |
| One task with everything on it               | [`get-task`](https://flow.ttoss.dev/docs/reference/get-task.md)                           |
| Take a task, as a person, or route it        | [`update-tasks`](https://flow.ttoss.dev/docs/reference/update-tasks.md)                   |
| Take a task, as an agent                     | [`upsert-agent-run`](https://flow.ttoss.dev/docs/reference/upsert-agent-run.md)           |
| Make or change a team                        | [`create-team`](https://flow.ttoss.dev/docs/reference/create-team.md)                     |
| Move a status, close, set priority           | [`update-tasks`](https://flow.ttoss.dev/docs/reference/update-tasks.md)                   |
| Attach what the work produced                | [`update-tasks`](https://flow.ttoss.dev/docs/reference/update-tasks.md) with `references` |

**Example:** [Break a feature into waves](https://flow.ttoss.dev/docs/examples/break-a-feature-into-waves.md) finishes a foundation task and frees the three that waited on it.