Walkthrough

This page follows one issue through Legion, step by step, and each step names what you see. The screenshots and the narrated video show example data: a Storefront project in Dispatch. The two terminal recordings in the operator’s view show an example daemon: legion status, legion state and legion claims list, then the controller starting and registering with it.

1. Hand the issue over

The issue has a title that states the outcome and a spec with acceptance criteria. You add the legion label from the issue header and set the status to todo.

2. Admission and the architect’s claim

With a slot free, the daemon admits the issue: the status becomes in_progress, and moments later the architect claims it, so the issue shows it as claimed by Legion’s session.

3. Decisions and the spec approval

The architect grows the spec into a design and writes each open question as a decision block, which reaches the assignee’s Inbox. Once every block is answered, it asks for approval with a summary. The Inbox opens the request in its reading column: the spec as the version to approve, with Approve and Request changes above it.

4. The phases run

After approval the daemon starts the planner, then the implementer, which opens the pull request, then the tester and the reviewer. The issue’s status follows: in_progress, testing, needs_review, then retro once the reviewer has approved and the architect has accepted.

5. The pull request

The pull request’s body follows Legion’s template: the outcome, why, the change, how it was proven, what is not proven, and after the merge the production check your project asks for. Legion’s reviewer approves it as the review App. In Dispatch, the issue’s header links the pull request.

6. The acceptance

When the reviewer approves, the architect reads the evidence (the tester’s handoff, each check of the issue with its latest result, the approval of the head) and accepts the change with a comment on the issue, which moves it to retro; a change that falls short goes back to the implementer or the tester instead. Retro runs next.

7. The merge

The merger reads the pull request and merges it itself, at the head it read and under a message it writes — the pull request’s title and number, with an empty body — so GitHub’s own default, which joins every commit message of the branch, puts none of Legion’s internal trailers on your default branch. The merge lands under the repository’s own rules, the checks it requires among them. It closes the issue: the daemon reads the merged pull request and moves the issue to done.

8. The production check

After the close the tester gets the production check in its live session — the role your project’s production_check names, which is the tester unless the setting is off, where no check opens. It asks your deploy role to carry the merge and waits for no reply; when production does not carry the merge yet it reports pending with wake_at, the time it wants to look again, its pod goes, and the daemon brings it back at that time. Nothing else wakes a check. The look that finds the merge in production drives the change and records the result of the issue’s after_merge check, naming the merge commit and what woke the look, with that result’s line on the pull request. A closed issue takes such a result, a comment and a message, and no other write.

The operator’s view

An operator’s terminal on an example daemon: legion status, legion state and legion claims list read it, with one issue’s architect running; then legion controller start starts the project’s controller, which registers with that same daemon. Last, the controller’s daily report in Dispatch.