Linear Workflow Agent Rules
Project Context
You are using Linear for engineering project management. Linear prioritizes speed and clarity over ceremony — keep the board lean, automate transitions, and let the Git integration do the heavy lifting.
Issue Identifiers & Linking
- Every issue has a unique identifier: `TEAM-123` — always include the full identifier, never just the number.
- Reference issues in git branches: `feature/ENG-123-oauth-login` — Linear detects the ID automatically.
- Reference issues in PR titles and bodies: `Fixes ENG-123: add OAuth2 login` — triggers auto-close on merge.
- Use magic words for auto-close: `Fixes`, `Closes`, `Resolves` — all work. `Related to` links without closing.
- Multiple closes: `Fixes ENG-123, ENG-124` — Linear closes both issues when the PR merges.
- Let the Git integration handle status transitions — avoid manual status updates that conflict with automation.
Issue Writing
- Write titles as user-facing outcomes or specific technical goals — not implementation verbs: `OAuth login with Google` not `Implement OAuth handler`.
- Write descriptions with enough context for any team member to pick up the issue cold.
- Add acceptance criteria as a checklist in the description — each item verifiable, not vague.
- Attach relevant Figma links, error logs, and screenshots directly to the issue.
- Tag issues with labels during triage — at minimum: type (`bug`, `feature`, `improvement`, `tech-debt`) and area.
- Set estimate during triage using the configured scale (story points or T-shirt sizes).
Status Workflow
- Default flow: `Backlog → Todo → In Progress → In Review → Done`.
- Move to `In Progress` when you start work; move to `In Review` when the PR is opened.
- Use `Cancelled` for abandoned issues — add a comment explaining the reason for future reference.
- Do not add custom intermediate states without a clear, enforceable entry/exit criteria.
- The Git integration automatically moves issues to `Done` when the PR merges — do not duplicate this manually.
Priority Levels
- `Urgent` (1): Production down, data loss risk, or blocking critical business function — requires same-day response.
- `High` (2): Impactful bug or critical feature — address in the current cycle.
- `Normal` (3): Standard priority for planned work — schedule in upcoming cycles.
- `Low` (4): Nice-to-have, deferred improvements — address when capacity allows.
- `No Priority` (0): Requires triage before it can be scheduled.
- Set priority deliberately — every Urgent and High issue auto-activates SLA tracking.
Cycles (Sprints)
- Default cycle duration: 2 weeks — consistent cadence enables velocity tracking.
- Plan cycles by pulling from active projects and the prioritized backlog.
- Do not overcommit — leave 20% capacity buffer for unexpected bugs and review work.
- Review cycle scope at the midpoint — adjust if blockers or discoveries have changed the picture.
- Configure auto-rollover to move incomplete issues to the next cycle with a flag for review.
- Use cycle velocity trend to improve planning accuracy over time — not as a team performance metric.
Projects & Roadmaps
- Use Projects for multi-cycle, cross-team initiatives with milestones: `Q2 Auth Revamp`, `GDPR Compliance`.
- Use Cycles for week-to-week execution of concrete tasks.
- Link issues to projects when they contribute to a larger initiative — gives roadmap visibility.
- Post async project status updates instead of status meetings: use the built-in status update feature.
- Set project target dates and health status (on track, at risk, off track) weekly during active development.
Labels & Organization
- Maintain a consistent workspace-level label taxonomy: `bug`, `feature`, `improvement`, `docs`, `tech-debt`, `security`.
- Use area labels for routing: `frontend`, `backend`, `infrastructure`, `mobile`.
- Color-code labels for quick visual scanning on the board.
- Apply at most 3 labels per issue — more than that signals insufficient label taxonomy design.
- Never use labels as a substitute for priority or status fields — use the dedicated fields.
Triage
- Triage is the inbox for issues from integrations, bug reports, and external requests.
- Review triage inbox daily — keep it at zero by end of day.
- Triage actions: Accept (→ Backlog with priority and labels), Decline (with comment), Merge (duplicate).
- Rotate triage responsibility across team members on a weekly schedule.
- All issues entering the backlog from triage must have priority, labels, and a clear title.
Automation
- Use the GitHub/GitLab integration for all status transitions — configure once and let it run.
- Set up SLA rules for Urgent and High priority issues using Linear's built-in SLA tracking.
- Configure sub-issue completion rules: parent auto-closes when all children are Done.
- Use cycle auto-rollover to handle incomplete work at sprint boundaries.
- Use Linear's API for custom automation when built-in rules are insufficient — avoid duplicating automation across Linear and CI.
Sub-Issues & Dependencies
- Use sub-issues to decompose a parent issue into concrete tasks within one team.
- Use `Blocks` relationships for cross-team dependencies — blocked issues display a red flag.
- Identify blocking dependencies during planning and surface them at the beginning of the cycle.
- Keep sub-issue depth to one level — deeply nested hierarchies are hard to track on the board.
Linear
