Concepts

#Mental Model

flowchart TD
  issue["GitHub issue"] --> select["Selection or explicit target"]
  select --> claim["Claim issue"]
  claim --> workspace["Managed workspace"]
  workspace --> phases["Agent phases"]
  phases --> readiness["Readiness gate"]
  readiness --> verify["Verification gate"]
  verify --> publish["Pull request"]
  phases --> artifacts["Run artifacts"]
  verify --> artifacts

#Control Checkout

The control checkout is the repository directory where you invoke roark.

Roark reads .roark/config.json from this checkout, writes run artifacts under .roark/runs, and uses it as the source for ignored local files copied into managed workspaces.

The control checkout should stay clean and should not be shared by humans while scheduled Roark jobs are running.

#Managed Workspace

A managed workspace is an isolated clone where Roark lets the agent modify files.

Default layout:

~/.roark/workspaces/<owner>-<repo>/issue-<number>

Each issue gets a persistent workspace so failed uncommitted work can be inspected and recovered.

#Issue Branch

Roark creates or reuses an issue branch named:

roark/issue-<number>

Publishing pushes this branch and opens a pull request against the configured base branch.

#Attempt

An attempt is one Roark run for one issue.

Attempts are stored under:

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

roark continue resumes an attempt by reading this artifact directory and the persistent managed workspace.

#Phase

A phase is one workflow step, such as fetch, triage, plan, implement, review, fix, or readiness.

Standalone phase commands are useful for debugging, but most users should prefer roark do, roark auto, or roark continue.

#Independent Review Axes

Roark reviews changes on two independent axes:

• Spec and Correctness: did we build the right behavior correctly?
• Standards and Maintainability: did we build it in a way that fits the repository?

A change must pass both. Success on one axis never compensates for failure on the other.

Review findings separate routing from constraints. handling says whether work belongs in the current fix pass, a follow-up, or an optional suggestion. blockedBy independently records outside access, information, dependencies, or human decisions. Roark fixes unblocked current work before stopping on unresolved external constraints.

Every review records concrete inspected evidence, a completeness status, and structured limitations. A limitation can block approval without being disguised as a code finding. Finding IDs are semantic and remain stable across review passes while the same concern persists.

#Readiness Gate

The readiness gate validates Roark's final readiness.json artifact. The run can publish only when its structured decision status is:

ready-for-pr

readiness.md is a deterministic human rendering of the same decision; it is never parsed to decide whether to publish.

#Verification Gate

The verification gate runs the configured shell command, such as bun run check.

The run can publish only when the command exits 0. Command output is recorded in verification.md.

#Labels

Labels control autorun eligibility and lifecycle state.

The default ready label is ready-for-agent. Default workflow skip labels include needs-triage, blocked, needs-human, triage-rejected, wont-fix, agent-in-progress, agent-failed, and agent-pr-opened.

See Label semantics.

#Pull Requests

Roark opens pull requests only after readiness and verification pass.

Roark does not:

• merge pull requests
• close issues
• make final review decisions

#Run Artifacts

Artifacts are durable files that explain what happened and support recovery. They are also the easiest place to debug failed runs.

Start with Artifacts, then use Troubleshooting for common failures.

#Next Steps

• Use Quickstart for the first successful run.
• Use Usage for command selection.
• Use Architecture for contributor-level internals.