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
- Intent: what your sentence asks for. The Router classifies by intent only.
- Workflow: the sequence of steps bound to an intent.
- Step: one role doing one thing. It has three parameters:
review(a review gate: after the author reports ready this role reviews, and the step is accepted only on a pass),archive(this step completes the task: once accepted, the engine merges the change and archives the task record) andchat(a conversation: you talk to this Worker directly on its session page).
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
- Each round the reviewer writes its review into
reviews/in the task directory, and the author replies item by item. - A
verdictofpass: the step is accepted and the engine closes it. - A
verdictofchanges: the author revises and reportsreadyagain, starting the next round. - If the verdict is still
changesat the round limit (3 by default), the engine stops sending it for review and asks the author to turn every unresolved item into a Review Report for you to decide.
Closing
After a step is accepted the engine does the following; none of it costs the Worker a turn:
- if the step completes the task, merge the task's changes;
- archive the task record;
- commit and push the task directory, committing only this task's paths;
- write a Journal entry;
- 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
- The Journal is your history: the engine writes one entry each time a step is accepted. It is a file in the main repository, one per month.
- A workflow organization is a run not triggered by another run, together with every run it triggers directly or indirectly. Reports are grouped by organization.
- The board has one card per run, in groups: Needs you, In conversation, In progress, To archive, Ended. Cards of one organization form a tree.