Sequence

Multi-step work as one observable run. A sequence is a predefined pipeline of steps with typed inputs and outputs, where each step's output feeds the next. A run can move forward, loop back to an earlier step, and pause for you.

Sequence sits above dispatch the way a conductor sits above the orchestra: it owns no execution. Steps that need an agent fan out into dispatch as ordinary jobs.

This is what a /toryo-code invocation actually starts.

The five kinds of step#

A worker step is the expensive one: a whole agent session, with tools and a repository. A completion step is the cheap one for the times you only need the model to decide something ("grade this", "rank these") and hand back structured data a later step can branch on.

A human step is the gate. The run parks, board raises an OS notification, and nothing proceeds until you acknowledge it, whether by approving, rejecting, or sending the work back with written feedback. A gate can also present the agent's own questions as pickable options, so the planner can ask you which of two approaches to take and get a real answer rather than guessing.

The shipped sequences#

Three, and they are how we work rather than how you have to:

• code-task, the full engineering lifecycle, and the one you will use most. Plan → you approve the plan → implement in an isolated worktree → self-review → open a PR → formal review → merge check → you approve the merge → record what was learned. It is a file rather than something compiled into toryo: toryo setup offers to install it, toryo sequence install-shipped adds it later, and you can read, edit or fork it like any sequence you wrote yourself. Declining the offer is fine, you get an empty catalog and everything else still works.
• review-task, which grades a whole codebase and produces a report, optionally published into the library. A file too, installed by the same offer as code-task, and yours to read, edit or fork once it is there.
• research-task, which researches a topic or URL into a library finding, behind an approval gate. A file too, installed by the same offer as code-task, and yours to read, edit or fork once it is there.

A fourth, ideas-verify, ships as well but belongs to the system rather than to you: it re-checks filed ideas against the code as it stands now so the ones already solved get closed instead of read again. toryo sequence list leaves it out unless you pass --include-system, and it is described on Ideas as the behavior it is.

Writing your own#

The three are defaults, not doctrine. Plenty of people run them as they are and never write one, which is a fine way to use toryo. When your process differs, write yours down instead.

A sequence is a YAML file in your own repository, under .toryo/sequences/. There is no fork, no plugin to register, and nothing compiled into toryo: the engine reads your file and runs it exactly as it runs the built-in ones. Name yours after one of ours and yours is the one that runs.

What you are writing down is your own process. The steps, what each hands the next, which of them run an agent, and where the run should stop and ask a person. The things a team argues about in review, or that a senior engineer does from memory, become something that runs the same way every time.

Because it is a file in your repository, it travels the way the rest of your code does: reviewed in a pull request, versioned, forked by another team, and handed to a new hire as a working definition of how you build rather than a wiki page about it.

There are four ways to make one, and only one of them involves typing YAML. See Writing your own sequences. github.com/ForceBuilders/toryo-pr-example is a complete one to read.

What makes a run recoverable#

Runs are durable. The daemon can restart mid-run and pick up where it left off, and a few behaviors are worth knowing:

• Work happens in an isolated git worktree, not your checkout, so your working tree stays clean while a task runs. On success it is cleaned up; on failure it is kept so you can inspect it.
• Cycles are bounded. Self-review loops until the diff grades well; a reviewer that requests changes sends the run back to implement, but only when it flags something genuinely blocking, and only a capped number of times.
• A moved base branch is handled. If another PR merges underneath a run and the branch no longer merges cleanly, the run goes back and merges the new base in rather than failing.
• API errors retry themselves with backoff before the run is failed.
• A step failing the same way repeatedly escalates to you instead of looping.
• retry re-arms a stuck run in place, keeping its worktree, PR, plan, and history, which cancelling and starting over would throw away.

Chaining runs#

A run can declare that it depends on others. It stays blocked, never reaching dispatch and never minting a worktree, until every prerequisite has succeeded. For a coding task, "succeeded" means the PR was merged, so a dependent run picks up its predecessor's changes with no branch plumbing.

Use it when one task must build on what another produces, instead of letting two runs invent the same helper twice.

Where things go wrong#

• A run sits awaiting-human. It is waiting on you, in board's Sequence screen or the inbox notification.
• A run sits blocked. Either a dependency has not succeeded yet, or a step escalated after failing identically several times.
• A run failed but the work looks salvageable. Use retry rather than starting over; the accumulated context is worth keeping.

Full command surface: CLI & contract reference.