Workflow
How one agent hands work to the next, through GitHub, the way a team does.
No central process directs the agents. Each agent finishes by leaving a trace on GitHub, such as a label, a pull request or a review, and that trace is the event that starts the next agent. Every step stays visible on GitHub. One loop stays on the machine: the internal review, where a reviewer reads a change before it reaches GitHub.
One hand-off
The triage agent decides that an issue is ready, and the implementer takes it:
- Starts the factory
- An agent, each in its color
Two files make this link. The first may write the label; the second starts on it.
when: [issue.opened, issue.commented]
agent: triage
can:
- add_comment
- add_labels: [ready-for-agent, needs-info, needs-investigation]What starts what
| When the engine writes | It starts |
|---|---|
A label (add_labels) | issue.labeled or pull_request.labeled with that label |
A pull request (create_pull_request) | pull_request.opened, and pull_request.labeled for each label of create_pull_request: [a, b] |
Commits (push_to_pull_request) | pull_request.updated, and pull_request.checks_failed if the checks they run fail |
A review (request_changes) | pull_request.changes_requested |
An issue (create_issue) | issue.opened, and issue.labeled for each label of create_issue: [a, b] |
A close (close_issue, close_pr), a removed label (remove_labels) | Nothing |
A merge (merge_pull_request) | default_branch.updated, as a person's merge does |
A comment (add_comment) | Nothing |
Comments start nothing by design: otherwise an agent that comments on an issue it listens to would restart itself forever. For the other writes, validate refuses an automation whose own output would start it again; the events reference lists each case.
A complete loop
The 02-sdlc template takes an issue from creation to merge in three stages.
1. Triage
The triage agent reads the new issue and adds one label:
- Starts the factory
- A person acts
- An agent
2. Implementation, reviewed before the pull request
The implementer makes the change, and the reviewer reads it before anything reaches GitHub:
- A person acts
- An agent, each in its color
3. A person merges, or asks for more
The pull request reaches you with one line on its review. Merge it, or mention @openfabriq in a comment: the implementer goes back to it, and the reviewer reads that change too.
- A person acts
- An agent
The studio draws this graph for your own factory, from its files: see Workflow.

The internal review
An automation that publishes code can name the agent that reviews it:
when:
issue.labeled: { labels: [ready-for-agent] }
agent: implementer
reviewed_by: reviewer
can: [create_pull_request, add_comment]When the implementer finishes and the checks pass, the engine runs the reviewer in the same checkout. The reviewer changes nothing and writes nothing on GitHub: it answers with a verdict, approved, needs_changes or needs_human, and findings.
- Needs changes: the implementer gets the findings, fixes them and finishes again; the checks run again, then the review.
- Approved: the pull request opens, or the push goes, with one line at the end of its description,
Reviewed before opening by reviewer: approved after 2 rounds, risk low., and the labelsready-to-mergeandrisk:low(orrisk:medium,risk:high). - Needs a person, or
review_roundsrounds spent: the pull request opens anyway, withneeds-humanand an Internal review section listing only the findings still open. For a push, the same list goes in a comment.
Every round is on the run's page in the studio, with its verdict, findings and cost. The rules are under reviewed_by.
How a loop stops
The engine hands work to a person with needs-human, its own label for that:
- past
review_roundsinfactory.yaml, instead of starting another round: rounds of review inside a run withreviewed_by, or, for a factory that reviews on GitHub, review and rework rounds on a pull request; - after a failed run, or a code change whose checks still fail;
- after a run started by changes requested that pushes nothing: without new commits, no new review would come.
Watch for needs-human on GitHub, or filter the studio's board on Needs you. A pull request the internal review approved gets ready-to-merge and a risk label instead, so one ready to merge never looks like one a person must rescue; a reviewer on GitHub, as in 05-code-review, adds the same labels itself. While a run works on an issue or a pull request, it carries openfabriq:working, which starts nothing (While a run works). See the labels the engine puts.
People in the loop
A run never waits for a person. People act on GitHub, and their action starts the next run:
- answering a triage's questions starts
issue.commented; - adding
ready-for-agentwhen a spec is settled starts the implementation, as in 10-spec-first; - merging a migration's plan starts
default_branch.updated, and the planner opens the first tickets; each later merge opens the tickets it unblocks. In Webflow to Astro, a maintainer merges the plan, then each pull request the parity review approved before it opened, and the factory builds the rest; - merging is a person's decision, except what
merge_pull_requestallows.