roark

Search documentation

Search across all Roark documentation pages.

Type to search across the docs.

docs/label-semantics.md

Roark label semantics

Labels Roark reads, creates, and applies.

Last updated

View Markdown

#Autorun eligibility

Autorun is label-gated. An open issue is eligible only when both are true:

  1. The issue has the configured ready label. The default ready label is ready-for-agent.
  2. The issue has none of the configured skip labels.

autorun is not a special label by default. It only becomes the ready label if autorun is invoked with --label autorun.

#Autorun labels

Label Default role Notes Configurable flag
ready-for-agent Ready label Opts an issue into autorun eligibility when no skip label is present. --label
needs-triage Skip/status label Prevents autorun until a maintainer approves the issue for agent work. --skip-label / --skip-labels
blocked Skip/status label Prevents autorun from selecting the issue; also used for terminal blocked triage outcomes. --skip-label / --skip-labels
needs-human Skip/status label Prevents autorun from selecting the issue; also used for terminal human-decision outcomes. --skip-label / --skip-labels
triage-rejected Skip/status label Prevents autorun from selecting the issue; applied when triage rejects the issue. --skip-label / --skip-labels
wont-fix Skip label Prevents autorun from selecting the issue. --skip-label / --skip-labels
agent-in-progress Claim label and skip label Applied when an agent claims or resumes an issue so concurrent runs skip it. --in-progress-label; replacements are always added to the effective skip set
agent-failed Failure label and skip label Applied when readiness or verification fails. --failure-label; replacements are always added to the effective skip set
agent-pr-opened Success label and skip label Applied after an agent opens a PR. --success-label; replacements are always added to the effective skip set

Default skip set: needs-triage, blocked, needs-human, triage-rejected, wont-fix, agent-in-progress, agent-failed, agent-pr-opened.

Before doing any issue work, auto checks for the ready, in-progress, failure, success, blocked, needs-human, and triage-rejected labels.

  • Missing required labels are created with Roark's default color and description.
  • Existing labels are not changed.
  • --dry-run reports missing labels without creating them.
  • Custom skip-only labels are not created unless they also serve one of the required roles.

#Generated issue labels

create-issues assigns these labels to issues generated from review findings:

Label Applied to Meaning
needs-triage All generated issues Marks newly generated issues for maintainer triage.
review:external-blocker Generated blocking issues Classifies an issue generated from an external-blocker reviewer finding.
review:follow-up Generated follow-up issues Classifies valid non-blocking work discovered during review.
review:suggestion Generated suggestion issues Classifies optional improvement work discovered during review.

Generated issues do not receive needs-human by default. That status is reserved for a concrete decision, clarification, or approval requested by the agent.

#Configurable label flags

  • --label <label> — ready label for autorun eligibility. Defaults to ready-for-agent.
  • --skip-label <label> — autorun skip label; repeatable. Passing it replaces the default skip set on first use; Roark still appends required lifecycle/status skip labels.
  • --skip-labels <labels> — comma-separated autorun skip labels. Passing it replaces the default skip set on first use; Roark still appends required lifecycle/status skip labels.
  • --in-progress-label <label> — label applied when claiming an issue. Defaults to agent-in-progress.
  • --success-label <label> — label applied after opening a PR. Defaults to agent-pr-opened.
  • --failure-label <label> — label applied when readiness or verification fails. Defaults to agent-failed.

#Lifecycle transitions

State Typical labels What Roark does next
Ready for automation ready-for-agent and no skip labels Eligible for roark auto discovery.
Claimed or resumed agent-in-progress Run is in progress; other autorun processes skip it.
Published agent-pr-opened PR has been opened; future autorun skips it.
Failed readiness or verification agent-failed Operator should inspect artifacts and use roark continue.
Blocked by triage or external condition blocked Autorun skips it until a human changes labels or scope.
Needs human decision needs-human Autorun skips it until a human resolves the decision.
Rejected by triage triage-rejected Autorun skips it unless the issue is revised and the label is removed.

An issue has at most one workflow-state label. Each transition removes the old state before applying the new one. Topic labels such as bug, auth, or storage are unaffected.

Use native GitHub dependency links for issue-to-issue blocking. Reserve the blocked label for external conditions that cannot be represented by a dependency link.

Passing an issue directly to roark auto skips the ready-label requirement. Skip labels and active GitHub dependencies still apply.

#Migrating older repositories

Roark does not rewrite an existing .roark/config.json. Migrate an older repository in one pass:

  1. Add ready-for-agent to issues that currently use afk, then remove the afk label.
  2. Rename roark-in-progress, roark-failed, and roark-pr-opened to their agent-* equivalents.
  3. Replace wontfix with wont-fix and remove the unused roark-ready-for-review skip entry.
  4. Rename reviewer-generated external-blocker, follow-up, and suggestion labels to their review:* equivalents when those labels are not also used as general repository taxonomy.
  5. Update .roark/config.json to the defaults documented above.
  6. Remove conflicting workflow-state labels so each open issue has at most one of them.

GitHub cannot rename afk directly when ready-for-agent already exists, so those issue assignments must be merged before deleting afk.

#Check labels

Preview selection:

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

Inspect one issue:

bash
gh issue view 123 --repo owner/repo --json labels,state,assignees