All docs

Work

Workflows and the engine

Intents, workflows and runs; how the report block drives hand-offs; wake-ups, review gates, closing, worktrees, maps and the Journal.

The engine is the code in the Desk that moves runs through their workflows. It does everything that is certain: hand-offs, wake-ups, closing, dispatching tasks from a map. Models produce only judgment and content.

Intents, workflows, steps

workflows.yaml in the official plugin defines these intents:

Intent Used for Steps
implement Changing repository content: features, fixes, refactoring, docs, configuration execute, reviewed by execute-review, completes the task
implement-frontend Changes involving presentation, interaction or UI execute-frontend, reviewed by execute-review, completes the task
plan Delivering a reviewable plan first plan, reviewed by plan-review
assist Look-ups, records, and operations done the repository's existing way assistant
research Analysis, investigation, comparing options research
learn Learning and revising; you talk to teacher directly teacher (chat)
new-project Creating a project or repository from nothing new-project
architect Planning something large that splits into many tasks, owned through to acceptance architect, reviewed by architect-review, completes the task
prototype Testing feasibility or performance and delivering a conclusion with evidence prototype, completes the task
upgrade Examining how aiL runs and is designed, and improving the plugins with your approval upgrader

The engine reads these files each time it needs them and caches nothing: change a file, and the next dispatch or the next step follows the new version.

Runs

One dispatch is one run, with an id like r261121-010214-3fa9. The author of each step starts on the Client its role is bound to; a gated step starts its reviewer the first time it is sent for review. Client, harness, model and thinking all come from the role binding and cannot be chosen at dispatch.

Before starting a Worker the engine checks three things: the Client the role is bound to is online, that Client has the harness, and the dispatcher is authorized for that Client. If not, nothing starts; the error says what is missing, and nothing else is substituted.

The report block

The author and the reviewer of a step end the final message of every turn with a report block, and the engine moves only by it:

```ail-report
{"state": "ready", "summary": "the result in a sentence or two", "evidence": ["what verifies it"]}
```
State Where it goes
ready Everything it can do in this step is done. A gated step goes to review; once accepted the engine closes the step, then starts the next one or ends the run
waiting It is waiting for your answer: it has pushed a Review Report, and the answer goes straight into its queue
blocked The run stays open and the Router is notified
dropped Abandoned: the task record is archived as dropped and the run ends
progress The turn is over and the work continues. Nobody is notified

When a report is invalid or cannot move the workflow, the engine asks the Worker to correct it once, and notifies the Router if that fails. A report that ends a run must carry a debrief: the summary written for you.

Wake-ups

A Worker does not rely on the harness to wake itself. To wait for something (a long command, a deployment) it detaches the command to the background and reports progress with wake_after_s (10 to 3600 seconds). When the time comes the engine sends it a message: look at the output; if it is not done, report progress again; if it is, carry on.

Pending wake-ups are stored in the database and sent at the planned time after a Desk restart. If a turn produces no event for 60 minutes (the default), the board marks it as possibly stalled.

Review gates

Closing

After a step is accepted the engine does the following; none of it costs the Worker a turn:

  1. if the step completes the task, merge the task's changes;
  2. archive the task record;
  3. commit and push the task directory, committing only this task's paths;
  4. write a Journal entry;
  5. start the next step, or end the run.

If the engine cannot do one of these it stops there and messages the author to deal with it.

Changes

Several Workers change one repository at the same time. The main checkout only moves forward and never switches branch; each change is made in its own worktree and rebased in when done.

Command What it does
ail worktree start <name> Create a worktree on branch task/<name>, from the latest commit of the target branch
ail worktree finish <path> Rebase onto the latest commit of the target branch, push, fast-forward the main checkout, delete the worktree and the branch
ail worktree drop <path> Delete the worktree and its branch
ail worktree leftovers List the worktrees left behind

How a change lands is fixed at start: push (the default, pushed upstream), local (merged locally only) or manual (the repository has its own release steps and the engine does not merge for the author).

Maps

Something large that splits into many tasks is planned by an architect into a map: an exploration graph first answers what has not been verified, and an execution graph gets the work done. The engine dispatches ready tasks by dependency, with no more than the parallel limit (3 by default) in progress at once. A blocked task on a map does not come to you: the engine hands the report to the architect, who replies.

Called roles

A Worker can hand work such as reading a large body of material, watching or listening to media files, or building report pages to a called role (brief, media and reporter in the official plugin). ail call <role> "<what to do>" returns a number at once, and when the work is done the engine delivers the result to the caller.

Journal, organizations and the board