The implementation agent
The implementation agent takes a Linear issue that has a plan, and turns it into a draft
pull request. The plan is the issue's attachment titled plan.md. An issue without that
attachment has its plan in its description, such as the Cause and Fix of an issue the
triage agent filed. The worker downloads the attachment from uploads.linear.app with
its Linear credential. It also downloads every other upload that is text of at most
100,000 characters, and writes it to the sandbox's context_files directory, outside the
checkout, before each step. Every step's prompt gives the issue's description, the path
of each of those files, such as a specification the plan cites, and the issue's links
and the uploads it did not copy. The sandbox has no Linear credential. The plan has no
required format. Jev checks the plan first, and the agent posts the problems of an
incomplete plan on the issue for its author.
It reviews its own branch before it opens the pull request, and fixes the important
findings of that review. The pull request's body is a reading guide written with the
pr-reading-guide skill.
It is the implement agent, agents/implement/agent.yaml, which
runs in one session per issue. It has these steps:
| Step | Runs | Model | Outcomes |
|---|---|---|---|
plan-check | the rubric plan-check.yaml over the issue's title and plan | Jev 1.14.0 | passed, rejected, unsettled |
plan-ready | the linear_post_plan_ready activity | — | posted |
plan-needs-work | the linear_post_plan_verdict activity | — | posted |
implement | an agent loop with github_push, starting the build conversation | Opus 5.5 | pushed |
review | an agent loop with submit_review | Opus 5.5 | findings, passed |
fix | an agent loop with github_push, continuing the build conversation | Opus 5.5 | pushed |
open-pr | an agent loop with github_open_pull_request, continuing the build conversation | Sonnet 5.5 | opened |
link-pr | the linear_post_pull_request_link activity | — | posted |
Every step has the same credentials and egress, so every step runs in the same sandbox.
The agent starts when an issue with the label auto-swe:implement moves to the Ready
for Agent state, or when the label is added to an issue in that state. A team that uses
the agent needs a workflow state of that name. A mention of the Linear write app, or a
message in the Linear agent session that the mention started, also starts the agent.
How the steps follow each other
-
Plan check. The
plan-checkrubric step asks Jev, in one request, whether the plan states each of these:- the problem and how we know it;
- the change, with the files, modules or functions it touches;
- the expected behavior;
- the tests to write or the check commands to run, and the result each must show;
- no open question;
- one approach for each part of the change;
- one change for one pull request.
Jev reads only the issue's title and plan. No step before
implementreads the code. When every criterion is answered yes,plan-readyposts a comment saying that implementation starts. When any is answered no or unsettled,plan-needs-workposts the criteria Jev did not answer yes. It mentions the issue's assignee and moves the issue to In Planning, and the agent run ends. An issue whose team has no In Planning state keeps its state. To check the revised plan, move the issue back to Ready for Agent, mention the app again, or write in its Linear agent session. A mention's text does not change the check. -
Implement. The agent reads the plan and the files it names, then implements the plan in its sandbox. It writes the tests the plan names, and adds tests for changed behavior they do not cover. It runs the repository's checks on the changed files, commits, and pushes its commits with
github_push. The first push createsauto-swe/<identifier>from the head ofmain. Where the code differs from the plan in a detail, the agent follows what the plan means. When the plan cannot work as written, the agent comments on the issue with what it expected, what it found and what the plan must say, pushes nothing, and the agent run ends. -
Review. The
reviewstep starts from its prompt each time, so it never reads the conversation that wrote the code. Its request quotes the final reply of the step that pushed, as$last_reply: what that step left out and why, where the code differed from the plan, the choices it made, and each check that still fails. It reviews the branch with the review procedure and rules it shares with the pull-request agent, checks each expected behavior and check the plan states, and judges each reason in that reply. Nothing it finds is posted. While an important finding is open,submit_reviewreturnsfindings, and thefixstep fixes them. A later review marks as fixed each finding that the fix addressed. -
Fix rounds. The
fixstep fixes each finding that is right, and declines one that is wrong with its evidence, in the reply the next review reads. It runs at most twice in one agent run. When a third review still has findings, the agent run goes toopen-pr, and the pull request's summary names each finding still open. -
Open. The
open-prstep writes the reading guide and callsgithub_open_pull_request. Its summary ends with what the plan left out, where the change departs from the plan, any check that still fails, and any important finding the last review left open. The body describes the final change, not the review rounds. Its footer gives the agent run's estimated cost and tokens by model. The tool opens a draft pull request againstmain. -
Link. The
link-prstep posts the pull request's link in a comment on the issue. The comment mentions the issue's assignee. The step then moves the issue to In Review. An issue whose team has no In Review state keeps its state.
No step runs for a completed or canceled issue.
A mention of the app starts a Linear agent session on the issue. When the agent run's
first step starts, the issue's auto_swe session posts a Linear agent activity of type
thought to the Linear agent session. A mention that arrives while an agent run is in
progress gets a thought saying it is queued, as it arrives. Linear marks a Linear agent
session unresponsive unless the app posts a Linear agent activity within 10 seconds of
the mention. When the state and label start the agent, the issue has no Linear agent
session, and shows only the comments the tools post.
Files
The agent's instructions.md is the system prompt of every step. Each agent step
appends its own file:
| Step | Instructions |
|---|---|
implement | implement.md |
fix | implement.md, fix.md |
review | review.md, ../_shared/review-procedure.md, ../_shared/review-rules.md |
open-pr | open.md |
Every agent step has the prompt prompt.md, which gives the issue and its plan. Each
step's request says what the step asks for. The plan-check step's questions are in
plan-check.yaml.
Settings
| Setting | Default | Meaning |
|---|---|---|
max_changed_files | 40 | github_push refuses commits that together change more files |
Evaluating the steps
Each eval scores one step on saved inputs against what a person confirmed. An eval that runs its step runs it in a dry run. The evals are:
evals/plan_check/asks Jev theplan-checkrubric's questions about each saved plan, and scores whether the plan passes and which criteria Jev does not answer yes. It starts no session.evals/implement/runsimplementon a saved plan, then runs the case's checks and the tests of the change a person merged in the step's sandbox.evals/implement_review/scores whetherreviewpasses a correct change, and whether it finds a defect planted in one.evals/open_pr/scores the reading guideopen-prwrites for a change, including whether its summary names a finding the last review left open.
workflows/auto_swe/scripts/README.md says how to run them and add a case.
Turning it on
The implement agent is on by default. Every one of its triggers is on a
linear.issue work item, so it runs only in sessions the Linear webhook starts.
The Linear write app's webhook, set up as
Deploying auto_swe describes, reduces these
deliveries to linear.issue work items:
| Delivery | Work item |
|---|---|
| An issue moved to another open state | issue, action state_changed. Its labels are the issue's labels after the update, including any the same update added |
| An issue created, or updated with a label added and its state unchanged | issue, action labeled, one per label added |
| An issue moved to a completed, canceled or duplicate state, or deleted | issue, action closed or removed. It ends the issue's session |
| A Linear agent session created by a mention of the app | comment, action created, with the Linear agent session and the comment that mentions the app |
| A message in the app's Linear agent session | comment, action prompted, with the message. A signal, such as Stop, makes no work item |
It drops every other delivery.