Skip to main content

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:

StepRunsModelOutcomes
plan-checkthe rubric plan-check.yaml over the issue's title and planJev 1.14.0passed, rejected, unsettled
plan-readythe linear_post_plan_ready activity—posted
plan-needs-workthe linear_post_plan_verdict activity—posted
implementan agent loop with github_push, starting the build conversationOpus 5.5pushed
reviewan agent loop with submit_reviewOpus 5.5findings, passed
fixan agent loop with github_push, continuing the build conversationOpus 5.5pushed
open-pran agent loop with github_open_pull_request, continuing the build conversationSonnet 5.5opened
link-prthe 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-check rubric 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 implement reads the code. When every criterion is answered yes, plan-ready posts a comment saying that implementation starts. When any is answered no or unsettled, plan-needs-work posts 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 creates auto-swe/<identifier> from the head of main. 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 review step 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_review returns findings, and the fix step fixes them. A later review marks as fixed each finding that the fix addressed.

  • Fix rounds. The fix step 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 to open-pr, and the pull request's summary names each finding still open.

  • Open. The open-pr step writes the reading guide and calls github_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 against main.

  • Link. The link-pr step 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:

StepInstructions
implementimplement.md
fiximplement.md, fix.md
reviewreview.md, ../_shared/review-procedure.md, ../_shared/review-rules.md
open-propen.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​

SettingDefaultMeaning
max_changed_files40github_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 the plan-check rubric'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/ runs implement on 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 whether review passes a correct change, and whether it finds a defect planted in one.
  • evals/open_pr/ scores the reading guide open-pr writes 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:

DeliveryWork item
An issue moved to another open stateissue, 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 unchangedissue, action labeled, one per label added
An issue moved to a completed, canceled or duplicate state, or deletedissue, action closed or removed. It ends the issue's session
A Linear agent session created by a mention of the appcomment, action created, with the Linear agent session and the comment that mentions the app
A message in the app's Linear agent sessioncomment, action prompted, with the message. A signal, such as Stop, makes no work item

It drops every other delivery.