Imported from aurabx/nightowl (.agents/skills/linear-workflow/SKILL.md). Install upstream with npx skills add aurabx/nightowl --skill linear-workflow. Copyright stays with the author.

Linear Workflow

Standardized workflow patterns for managing Linear issues with AI agents.

Core Principles

1. Always transition states — Never leave an issue in the wrong state
2. Tag agent work — All agent-touched issues get the "agent" label
3. Communicate progress — Use comments to track decisions and blockers
4. Link related work — Connect issues, PRs, and commits

Standard Workflow

When Starting Work on an Issue

1. Read the issue to understand context, requirements, and acceptance criteria
2. Check current state — if not already "In Progress", transition it
3. Add the "agent" label to mark agent involvement
4. Add a comment noting what you're starting and your approach (optional for trivial issues)

Example:

Starting work on this issue.

Plan:
- Update API endpoint to accept new parameter
- Add validation for email format
- Update tests

Estimated completion: 20 minutes

During Work

• Update comments if you hit blockers, change approach, or discover new requirements
• Link related issues if you discover dependencies
• Ask questions in comments rather than making assumptions

When Completing Work

1. Transition to "Needs Review" (or equivalent review state)
2. Add a completion comment summarizing what was done
3. Link the PR if code was generated
4. Note any follow-up items discovered during implementation

Example:

✅ Implementation complete

Changes:
- Added email validation to User.create()
- Updated API endpoint POST /users to accept optional email field
- Added 3 new test cases covering valid/invalid/missing email

PR: #123

Follow-up:
- Consider adding email verification flow (created issue #456)

State Transitions

Never transition directly to "Done" — always go through review first.

Labeling Strategy

Required Labels

• agent — Applied to all issues touched by an agent

Suggested Labels

• needs-testing — Implementation done but needs test coverage
• breaking-change — Changes that affect existing APIs or behavior
• documentation — Requires docs update
• security — Security-related changes
• performance — Performance optimization or concern

Comments Best Practices

Good Comment Patterns

✅ Progress updates

Updated User model to include email validation.
Next: API endpoint changes.

✅ Blocker reporting

⚠️ Blocked: Need clarification on password reset flow.
Should we send email immediately or queue it?

✅ Decision documentation

Decision: Using bcrypt for password hashing (industry standard, OWASP recommended).
Rejected argon2 due to deployment environment constraints.

Avoid

❌ Verbose play-by-play of every minor action
❌ Restating what's already in the code/PR
❌ Uncertainty without asking for clarification ("I think maybe...")

Working with Projects

• Always assign issues to the active project/cycle if one exists
• Update project status if the issue affects milestones
• Check project dependencies before closing issues

Working with Teams

• Respect team ownership — don't reassign issues across teams without confirmation
• Follow team conventions — check team-specific labels, workflows, or templates
• Tag team members when their input is needed

Integration with Git

When creating commits or PRs related to Linear issues:

• Reference issue IDs in commit messages: feat: add email validation (LIN-123)
• Link PRs in Linear comments
• Use Linear's Git integration — if configured, commits with issue IDs auto-link

Error Handling

If you cannot complete an issue:

1. Document the blocker in a comment
2. Transition to "Blocked" state (if available)
3. Tag relevant people who can unblock
4. Create follow-up issues for discovered work
5. Never leave the issue in "In Progress" if you've stopped working on it

Tools Usage

Starting Work

// 1. Get the issue
const issue = await linear_get_issue({ issueId: "LIN-123" });

// 2. Check if "agent" label exists, create if needed
const labels = await linear_list_labels({ teamId: issue.team.id });
const agentLabel = labels.find(l => l.name === "agent");
if (!agentLabel) {
  await linear_create_label({
    teamId: issue.team.id,
    name: "agent",
    color: "#5E6AD2" // Linear purple
  });
}

// 3. Transition to In Progress + add label
await linear_update_issue({
  issueId: "LIN-123",
  stateId: "<in-progress-state-id>",
  labelIds: [...issue.labelIds, agentLabel.id]
});

// 4. Add starting comment (optional)
await linear_create_comment({
  issueId: "LIN-123",
  body: "Starting work on this issue.\n\nPlan:\n- ..."
});

Completing Work

// 1. Transition to Needs Review
await linear_update_issue({
  issueId: "LIN-123",
  stateId: "<needs-review-state-id>"
});

// 2. Add completion comment
await linear_create_comment({
  issueId: "LIN-123",
  body: "✅ Implementation complete\n\nChanges:\n- ...\n\nPR: #123"
});

Quick Reference

Every time you work on a Linear issue:

1. ✅ Read the issue first
2. ✅ Transition to "In Progress"
3. ✅ Add "agent" label
4. ✅ Do the work
5. ✅ Transition to "Needs Review"
6. ✅ Add completion comment with summary

Never:

• ❌ Leave issues in wrong state
• ❌ Skip the review state
• ❌ Make assumptions without documenting them
• ❌ Close issues without human review