From a task to a pull request

The first run created a file. Now use the same code-defined workflow to deliver something useful in your repo.

Your first factory has five steps:

Task → Codex implements → automated check → your decision → checked files → PR

Start the task in Studio. You do not need a GitHub issue, webhook or background service. Laufwerk handles implementation, verification and a recorded approval before write-back. You inspect the final diff and publish the PR in this first version.

1. Prepare your repo

Open a normal local clone of a GitHub repo you can contribute to. If you need a clone, run gh repo clone OWNER/REPO, replacing OWNER/REPO, then open that directory. The optional publication steps need GitHub CLI and gh auth login.

From the repo root, check for existing changes:

git status --short

Start from a clean working tree. Commit your current work or use a separate clone before continuing. Use a normal clone for this tutorial: native copy mode does not support the .git file used by linked Git worktrees.

If this repo does not yet contain laufwerk/, initialize it once:

bunx laufwerk@0.0.1-alpha.7 init --execution local

Inspect and commit the generated workflow, configuration, lockfile and authoring skills as a setup change, following your repo's contribution process. Do not rerun init over an existing project. For an existing setup, check that laufwerk/workflows/coding/workflow.ts uses createLocalExecution and Codex.

Create a branch for the task:

git switch -c laufwerk/local-development
bunx laufwerk@0.0.1-alpha.7 doctor
bun run --cwd laufwerk check

Resolve readiness failures first.

2. Add a decision in code

In your editor, copy laufwerk/workflows/coding/workflow.ts to laufwerk/workflows/factory/workflow.ts. Make three small edits:

1. Change name: "coding" to name: "factory" in Workflow.make.
2. Add Human to the import from @laufwerk/sdk.
3. Insert this immediately before yield* Workspace.writeBack({ workspace });, after the session closes and the failure check:

const accepted = yield* Human.confirm({
  key: "accept-candidate",
  title: "Apply this candidate to your checkout?",
  description: result.value,
});
if (!accepted) return "declined";

The rest of the generated file stays intact. You have changed the process itself: every successful candidate now waits for your answer before it reaches your checkout. The description is the agent's summary, not an independent review or a complete diff.

bun run --cwd laufwerk check
git add laufwerk/workflows/factory/workflow.ts
git commit -m "Add approval before workflow write-back"
bunx laufwerk@0.0.1-alpha.7 studio

Open the printed URL and keep Studio running.

3. Give it a useful first task

We'll create a short local-development guide based on the repo's actual configuration. Choose a repo where docs/local-development.md does not already exist; if it does, choose a different small task and adjust the check.

In Studio, click Start run, choose factory, and paste:

{
  "executionKey": "local-development-1",
  "source": ".",
  "request": "Create docs/local-development.md: a concise guide to running this repository locally. Read the existing README, manifests, lockfiles and CI configuration. Include prerequisites, dependency installation, development and verification commands only where supported by those files. Explicitly identify anything you cannot determine; do not invent commands or claim you ran them. Make no changes outside docs/local-development.md. Do not commit, push or open a PR.",
  "verify": "node -e \"const fs=require('node:fs');const assert=require('node:assert/strict');assert.ok(fs.readFileSync('docs/local-development.md','utf8').trim().length > 0, 'Development guide must not be empty')\""
}

Here, source: "." means the current repository, resolved from the project root. The generated workflow gives Codex a working copy. Local mode still has your host permissions; it is appropriate for this supervised run on a repo you trust.

Click Start workflow. Inspect the agent and verification operations in Studio. Expect the run to reach waiting with a confirmation in Studio. Inspect the agent work and verification result, then answer the pending confirmation to accept the candidate. The workflow continues, completes healthy and writes the guide into your checkout.

Declining completes with the result declined and skips write-back. A completed run alone does not mean a candidate was accepted.

This first check only proves the file exists and contains text. It does not prove the instructions are correct. That is your next step.

4. Review the result

In a second terminal at the repo root:

git status --short

Open docs/local-development.md. Check each command against the actual scripts and CI configuration. Try the documented setup and checks where applicable. Check that no other files changed. New untracked files do not appear in plain git diff; inspect them in your editor before staging.

If something is wrong, start a new run with a new execution key and specific correction instructions. A failed run is not permission to publish. Inspect failures before starting another attempt.

Once satisfied, stage only the intended file and review the staged diff:

git add docs/local-development.md
git diff --cached --check
git diff --cached

5. Open the pull request

The following commands publish the reviewed change to your GitHub repo. Run them after review, in the same second terminal:

git commit -m "Document local development"
git push -u origin laufwerk/local-development
gh pr create --draft --fill

This first PR includes the new factory workflow and its resulting guide; review both. GitHub CLI prints the PR URL. Wait for your repo's required CI and review before merging. If publication is interrupted, inspect the branch and gh pr list --head laufwerk/local-development before retrying; an interrupted command may already have created the PR.

You now have a repeatable path from task description to a reviewed pull request, with the agent work and verification recorded by Laufwerk.

6. Use a GitHub issue as the input

When you want a shared task list, create an issue with GitHub CLI:

gh issue create --title "Document local development" --body "Create docs/local-development.md using the repository's actual setup and CI commands. Change no other files. Acceptance: a maintainer can follow the guide; unsupported assumptions are explicitly identified."

Use the number it returns in gh issue view NUMBER. Copy its title, description and acceptance criteria into the Studio input's request field, and use a new key such as issue-12-attempt-1. Keep source and the appropriate verification command.

After implementation and review, include Closes #12 in the PR description, using the actual issue number. GitHub closes the issue when that PR merges. This is a manual issue handoff; the workflow does not poll GitHub or automatically create PRs.

Make the workflow yours

Open laufwerk/workflows/factory/workflow.ts. You already own the factory's implementation and check steps. For the next task:

• Replace the documentation request with a small bug or feature and explicit acceptance criteria.
• Set verify to your repo's real CI checks. Working copies exclude node_modules, so include dependency installation when the checks require it. Use your repo's package manager and locked install command.
• Move a repeated verification command into the workflow code once you want every task to follow the same rule. Remove the corresponding input field then, so callers cannot change the rule.

Checks execute the command you supplied. The agent is instructed to limit its edits, but the starter does not independently enforce the requested file boundary or protect test files against modification. Review the diff and use independent CI before accepting application changes.

You have already added a human decision. You can later add isolated independent review with Docker and a GitHub publisher. Add automatic issue selection only when those steps are reliable for your repo. The factory integration reference explains durable publication receipts and recovery for that next version.

Understand and extend the workflow →