roark · docs
docs/quickstart.md

Quickstart

First-run path from installation to a successful Roark issue workflow.

Last updated

Edit on GitHubView Markdown

#Prerequisites

Install and authenticate the tools Roark uses:

bash
bun --version
gh auth status
git status --short

You need:

  • a GitHub checkout for the target repository
  • a clean control checkout
  • gh authenticated as a user or bot with issue, pull request, and branch push permissions
  • a verification command that can run non-interactively
  • any required ignored local files available in the control checkout

Roark uses GitHub CLI for repository operations and runs shell commands in local workspaces. Review Security and secrets before running on public or shared repositories.

#Install Roark

From the Roark source checkout:

bash
bun install
bun install -g "$PWD"
roark --help

For persistent servers, pin the checkout to a tag or commit before installing globally.

#Initialize a Target Repository

Run roark init from the target repository checkout:

bash
cd /path/to/target-repo
roark init

This writes:

text
.roark/config.json
.roark/WORKFLOW.md
.roark/.gitignore

Open .roark/config.json and confirm:

  • repo is the expected owner/repo
  • baseBranch matches the repository default branch
  • verify is a command you trust
  • lifecycle hooks are non-interactive
  • ignored local file paths are configured through workspace.copyToWorktree only when needed

See Configuration for the full config reference.

#Confirm Labels

Roark's autorun mode is label-gated. The default ready label is afk.

For a first dry run, make sure the target issue has the ready label and none of the skip labels:

bash
gh issue edit 123 --repo owner/repo --add-label afk

Roark creates required lifecycle labels during normal autorun when they are missing. A dry run reports missing required labels without creating them.

See Labels and Label semantics.

#Preview Autorun Selection

Before letting Roark claim work, preview selection:

bash
roark auto --repo owner/repo --limit 1 --dry-run

Expected result:

  • Roark lists an eligible issue.
  • No issue is assigned.
  • No branch is created.
  • No workspace is changed.

If nothing is selected, use Troubleshooting.

#Run One Issue Manually

For a controlled first run, use do with one issue:

bash
roark do 123 --repo owner/repo

Roark will:

  1. fetch the issue
  2. triage it
  3. plan the implementation
  4. run the implementation agent
  5. run independent review agents
  6. apply fix passes when needed
  7. write readiness output

do is useful for local validation. Use auto when you want claiming, labels, publishing, and scheduler-friendly behavior.

#Run One Autorun Attempt

When the dry run and manual run are understood, run a single autorun attempt:

bash
roark auto --repo owner/repo --limit 1

On success, Roark opens a pull request only after readiness and verification pass.

On failure, Roark leaves the managed workspace and artifacts for inspection. It does not merge, close issues, or mark PRs ready for review.

#Inspect Results

Issue run artifacts are written under:

text
.roark/runs/issue/<issue-number>/attempts/<attempt-number>/

Open these files first:

  • summary.json for the artifact index and final status
  • verification.md for the verification command result
  • readiness.md for the publish gate decision
  • implementation-log.md for implementation details
  • review-a.md and review-b.md for reviewer findings

See Artifacts for the complete layout.

#Recover a Failed Attempt

If an autorun attempt stops before publishing:

bash
roark continue 123 --repo owner/repo --attempt 1

If --attempt is omitted, Roark uses the latest recorded attempt.

Continue reuses valid existing artifacts, regenerates missing or invalid phase outputs, reruns readiness and verification, and publishes only when both gates pass. See Recovery.

#Next Steps