roark · one-shot coding workflow runner

autonomous implementation · human-controlled merge

Draft PRs from opted-in GitHub issues.

Label an issue afk. Roark claims it, plans, implements, reviews, fixes, verifies, and opens a draft PR — never a merge.

install from sourcerevise PR flow

trust boundaries

Controlled autonomy, explicit gates.

  • Opt-in only

    Issues must carry the ready label, defaulting to afk.

  • One at a time

    --limit defaults to 1 so operators can build trust slowly.

  • Branch isolated

    Each issue runs on roark/issue-<n> in its own worktree.

  • Two gates

    readiness.md must say ready-for-pr and --verify must exit 0.

  • Draft only

    Roark opens gh pr create --draft; humans merge.

  • No daemon

    Drive a one-shot CLI from cron, launchd, or GitHub Actions.

good install path

Use the path the CLI README says is reliable.

$ git clone https://github.com/marcellocurto/roark-coding-agent.git$ cd roark-coding-agent$ bun install$ bun install -g "$PWD"$ roark --help

Bun currently needs an absolute package path for the global link. The landing page now avoids package-registry commands the CLI README does not promise.

workflow

Nine phases to a draft PR.

The important part is not that Roark writes code. It is that it stops when the evidence says stop.

  1. 01

    Fetch

    Pull the GitHub issue, body, comments, and dependency context.

  2. 02

    Triage

    Decide proceed, blocked, reject, or needs-human before coding.

  3. 03

    Plan

    Write a concrete plan for the implementation agent.

  4. 04

    Implement

    Edit on roark/issue-<n>, branched from the configured base.

  5. 05

    Review

    Run two independent review agents over the diff.

  6. 06

    Fix

    Apply up to --max-fix-passes fix/review loops.

  7. 07

    Readiness

    Require ## Status to resolve to ready-for-pr.

  8. 08

    Verify

    Run your shell gate, defaulting to bun run typecheck.

  9. 09

    Draft PR

    Push and open a draft PR. Never merge. Never close.

command matrix

More than auto.

  • full runroark do https://github.com/owner/repo/issues/123

    Run the full workflow by hand for one issue.

  • autorunroark auto --repo owner/repo --limit 1

    Pick one eligible afk issue and try for a draft PR.

  • recoverroark continue 123 --cwd /repo --repo owner/repo --attempt 1

    Resume a stopped attempt with its artifacts and branch.

  • revise prroark revise-pr 123 --repo owner/repo

    Respond to unresolved PR feedback without starting over.

artifacts

Every run leaves a paper trail.

Roark writes reasoning and recovery files under .roark/runs/. Operators can inspect what happened before trusting the PR.

.roark/runs/issue/123/attempts/1
  • issue.mdwritten
  • triage.mdwritten
  • implementation-plan.mdwritten
  • implementation-log.mdwritten
  • review-a.mdwritten
  • review-b.mdwritten
  • fix-log-1.mdwritten
  • final-review-1.mdwritten
  • readiness.mdwritten
  • verification.mdwritten
  • attempt.jsonwritten

recovery

Failed attempts are meant to be resumed.

$ roark continue 123 --cwd /repo --repo owner/repo --attempt 1

A stopped autorun leaves the branch, worktree path, failing artifact, attempt metadata, and the exact continue command for inspection. Relabeling and starting from scratch should be the exception.

pr feedback

Revise the draft without replaying the issue.

$ roark revise-pr 123 --repo owner/repo

Roark fetches unresolved review threads and PR comments, classifies feedback, applies current must-fix items, verifies, pushes, and posts one summary comment only after review and verification pass.

read the revise-pr safety boundaries

operator requirements

Bring your own scheduler.

bungh auth statusclean worktreelabels configuredverify command
$ # hourly, serialized by your scheduler$ roark auto --cwd /srv/roark/repos/app --repo owner/repo --limit 1

Cron, launchd, and GitHub Actions are orchestration choices owned by the operator. Roark should fail clearly when repo, auth, label, or verification configuration is missing.

positioning

A one-shot coding workflow runner with an audit trail.

clone the repository ↗read the docsrecovery docs