Issue to fix

Enter the change you want. Laufwerk runs this workflow in your repository:

Desired change → Planner → Plan reviewer → Implementer + tests → Code reviewer → Human notification
                    ↑             │                                  │
                    └─────────────┴──── feedback, up to 2 passes ─────┘

On the first pass, either reviewer's rejection sends its feedback back to the planner. Two passes total: on pass two, the workflow continues even if reviewers still object. It applies the candidate after verification passes and includes unresolved objections in the human notification. A completed run therefore does not necessarily mean reviewers approved.

Verification errors, malformed review output, provider failures and write-back conflicts stop the run. They produce a failure notification instead of a successful result. Notifications are recorded locally in Studio/Inbox; they do not send email or Slack messages.

You need: Bun ≥1.4.2, Node ≥22, Git and a Codex subscription login. Set up your host first. Windows also needs Git for Windows Bash. Local agents have your host permissions; a working copy is not a security sandbox.

1. Add the workflow

If you followed getting started, your repository already contains laufwerk/. Download the local example below, then save it as laufwerk/workflows/issue-to-fix/workflow.ts, creating the issue-to-fix folder first:

Download the issue-to-fix workflow

For a new repository without Laufwerk, you can install it together with the example:

bunx laufwerk@0.0.1-alpha.13 init --example issue-to-fix --execution local

Use a small test directory for this exercise. From the repository root:

mkdir project

Then check the workflow and your provider setup, and open Studio:

bun run --cwd laufwerk check
bunx laufwerk@0.0.1-alpha.13 doctor
bunx laufwerk@0.0.1-alpha.13 studio

Resolve readiness failures first. Open the URL Studio prints and leave it running. Docker is available when you want enforced read-only workspace access for planning and reviews.

2. Enter the desired change

In Studio, click Start run, choose issue-to-fix, and enter:

{
  "executionKey": "greeting-1",
  "source": "project",
  "request": "Create greeting.txt containing exactly Hello from Laufwerk! followed by a newline. Make no other changes.",
  "verify": "node -e \"require('node:assert/strict').equal(require('node:fs').readFileSync('greeting.txt','utf8'),'Hello from Laufwerk!\\n')\""
}

Click Start workflow. The planner inspects the workspace and proposes a plan. A separate session reviews it. The implementer changes the working copy and runs your verification command. A fresh code-review session inspects the actual result. Each review uses a validated approved boolean and feedback string.

A first-pass rejection returns to planning with the previous plan and feedback. The second pass reuses the working copy so implementation can repair the candidate. The limit is shared by both reviews, not two retries per reviewer.

3. Inspect the result and notification

Open project/greeting.txt and check its content. In Studio, inspect the planner, review sessions, verification result and final notification. Session keys include their pass number, such as planner-1 and code-reviewer-2.

The notification reports either the applied change, any unresolved objections at the limit, or the failure. There is no human approval pause in this default workflow. Nothing commits, pushes or opens a pull request.

Reviews are model judgments. Your verification command proves only what it checks. Local planning and review sessions are instructed not to edit files; local execution cannot enforce that restriction. Review the resulting diff yourself before publishing.

First-run harness downloads can take several minutes per session. If a run fails, keep its ID and inspect the error. Alpha 8 corrects a Codex reconnect handling problem; the affected Mac network path remains unverified.

4. Make the workflow yours

Open laufwerk/workflows/issue-to-fix/workflow.ts. The complete TypeScript file defines the input, three agent roles, two review stages, two-pass loop, verification, write-back and human notification.

For your next change, update request, choose your repository's verification command and use a new executionKey. The same key returns to the same recorded execution; it does not start a new attempt. source is a directory inside the consumer project. For dependencies excluded from the working copy, include your locked installation command in verify.

Next: turn a real task into a pull request →

Prefer the terminal?

Save the input JSON as task.json and this script as run.ts. Run bun run.ts from the project root:

const input = await Bun.file('task.json').json();
const child = Bun.spawn([
  process.execPath, 'x', 'laufwerk@0.0.1-alpha.13',
  'run', 'issue-to-fix', '--input', JSON.stringify(input),
], { stdout: 'inherit', stderr: 'inherit' });
process.exit(await child.exited);