Skip to main content

Documentation Index

Fetch the complete documentation index at: https://atcyrus.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Labels are the primary way you control where Cyrus works and how it approaches a task. Use this page to decide which labels to apply to a Linear issue based on the outcome you want.

​
What Labels Control

Labels influence Cyrus’s behavior in the following order:
  1. Repository routing – where the work happens
  2. Work approach – how Cyrus reasons and executes
  3. Model selection (optional) – which AI model is used
If labels are missing or ambiguous, Cyrus falls back to safe defaults.

​
Route Issues to the Right Repository

Labels allow you to route issues more precisely than team-based routing alone.

​
Routing Priority

Cyrus applies routing rules in this order:
  1. Description tag — [repo=...] or repos=... in the issue description (highest)
  2. Routing labels — labels mapped to repositories
  3. Project assignment — Linear project mapped to a repository
  4. Team selection — the issue’s Linear team (lowest)
Higher-priority signals always override lower-priority ones.

​
Route With a Description Tag

The most explicit way to target a repository is to add an inline tag to the issue description: 
[repo=repo-name]
The tag can appear anywhere in the description. Cyrus also accepts the unbracketed form: 
repo=repo-name

​
Override the Base Branch

Append #branch-name to check out from a branch other than the repository’s default: 
[repo=repo-name#branch-name]
repo=repo-name#branch-name
This is useful for stacked work or for branching from a release branch.

​
Route to Multiple Repositories

A single issue can fan out to several repositories. Cyrus will create a separate worktree and agent session for each target. There are three equivalent ways to do this. Multiple description tags: 
[repo=frontend-app]
[repo=backend-api]
Comma-separated list: 
repos=frontend-app,backend-api
Multiple routing labels: Apply more than one routing label to the issue. Each label that maps to a repository will trigger a session in that repository. 
Labels: frontend, backend
Per-target base branch overrides work the same way: 
[repo=frontend-app#release-2.0]
[repo=backend-api]

​
Split Work Within a Team Using Labels

This is the most common setup. 
Team: ENGINEERING
Labels:
  frontend → frontend-app repository
  backend  → backend-api repository
  mobile   → mobile-app repository
This allows one Linear team to ship to multiple codebases without ambiguity.

​
When to Use Each Style

Use a description tag when:
  • You want one-off, explicit routing for a specific issue
  • You need to override the base branch
  • You want the issue to fan out to multiple repos without managing labels
Use routing labels when:
  • A team owns multiple repositories with stable, recurring routing
  • You use a monorepo with distinct domains
  • You want routing to be visible at a glance from the Linear board
Use team-based routing when:
  • Each team owns a single repository
  • Simplicity matters more than precision

​
Worked Example: One Issue → Frontend + Backend

A team owns both a frontend-app and a backend-api repository, and an issue requires changes to both. 
Title: Add user avatar upload
Team: ENGINEERING
Description:
  We need to add avatar upload to the profile page.

  [repo=frontend-app]
  [repo=backend-api#main]
Cyrus will:
  • Open a worktree in frontend-app from its default branch
  • Open a worktree in backend-api from main
  • Run an agent session in each, posting progress back to the same Linear issue
The same fan-out happens if you instead apply both the frontend and backend routing labels.

​
Choose How Cyrus Approaches the Work

Different tasks require different approaches. Labels tell Cyrus how to reason about the issue before writing code.

​
Fix a Bug

Use when: Something is broken or incorrect Labels: 
Bug
Hotfix
Cyrus will:
  • Investigate the root cause
  • Make minimal, targeted fixes
  • Add test coverage where appropriate
→ Uses the debugger workflow

​
Build or Improve Something

Use when: Adding features or improving existing behavior Labels: 
Feature
Improvement
Cyrus will:
  • Follow existing code patterns
  • Implement fully scoped changes
  • Verify before opening a pull request
→ Uses the builder workflow

​
Coordinate Large or Multi-Part Work

Use when: The task is too large for a single pass Labels: 
Orchestrator
Epic
Cyrus will:
  • Break work into smaller sub-issues
  • Coordinate execution across them
  • Track overall progress
→ Uses the orchestrator workflow

​
Large Work With Stacked Pull Requests

Use when: Each step depends on the previous one Labels: 
Graphite
Orchestrator
Cyrus will:
  • Create stacked pull requests
  • Execute work sequentially
  • Respect dependency order
Requirement: Graphite CLI must be installed

​
(Optional) Override the AI Model

In most cases, Cyrus selects the right model automatically. You can override this behavior with labels.

​
Available Model Labels

Sonnet → Balanced performance (default)
Opus   → Highest capability
Haiku  → Fast and cost-efficient

​
When to Override

Use Opus for:
  • Complex architectural decisions
  • Critical bug fixes
  • Difficult debugging scenarios
Use Haiku for:
  • Small changes
  • Documentation updates
  • Quick tasks
If no model label is present, Cyrus uses Sonnet.

​
Practical Examples

​
Bug Fix

Title: Login button not responding on mobile
Labels: Bug
Team: FRONTEND
→ Debugger workflow
→ Targeted fix with tests

​
New Feature

Title: Add dark mode toggle
Labels: Feature
Team: FRONTEND
→ Builder workflow
→ Full implementation and verification

​
Large Feature

Title: Implement complete authentication system
Labels: Orchestrator, Epic
Team: BACKEND
→ Work decomposed into sub-issues
→ Coordinated execution

​
Incremental Refactor

Title: Refactor database layer
Labels: Graphite, Orchestrator
Team: BACKEND
→ Stacked PRs using Graphite

​
If Something Feels Wrong

If Cyrus:
  • Picked the wrong repository
  • Used the wrong approach
  • Did less (or more) than expected
Check:
  1. Label spelling
  2. Routing priority
  3. Missing intent labels
→ See Troubleshooting

​
Want to Go Deeper?

To customize how Cyrus approaches work — review checklists, deploy runbooks, team playbooks — see Skills. Skills can be scoped by repository, Linear team, or Linear label. For historical context on the rigid workflow Skills replaced, see the Procedure Reference.
cyrus-f1

Cyrus Community

Get support on Discord