linear-workflows

# Linear Workflow Patterns ## What It Does Reference patterns and conventions for Linear PM workflows. Loaded by commands and agents for consistent behavior. ## When to Use Use when yellow-linear plugin commands or agents need shared Linear workflow context, including issue-writing guidance, branch naming conventions, or workflow state definitions. ## Usage This skill is not user-invocable. It provides shared context for the yellow-linear plugin's commands and agents. ## Team Context Linear team names match GitHub repository names exactly. Auto-detected from git remote: ```bash git remote get-url origin 2>/dev/null | sed 's|.*/||' | sed 's|\.git$||' ``` The extracted repo name is matched against `list_teams` results (case-sensitive exact match). This means: - No manual team selection needed in most cases - Works across multiple repos/teams automatically - If multiple teams match the same name, prompt user to disambiguate via AskUserQuestion - Falls back to AskUserQuestion if no match found ## Branch Naming Convention Format: `<type>/<TEAM-ID>-<description>` Examples: - `feat/ENG-123-auth-flow` - `fix/ENG-456-login-redirect` - `refactor/ENG-789-api-cleanup` Issue ID extraction pattern: `[A-Z]{2,5}-[0-9]{1,6}` (case-sensitive, first match wins). Always validate the extracted ID via `get_issue` before use. ## Issue Writing Tips ### Good Titles - Start with what's affected: "Auth token refresh fails on slow connections" - Be specific: "Login page returns 500 on empty email" not "Login broken" - Include scope: "API v2: Add rate limiting to /users endpoint" ### Acceptance Criteria Format ```markdown ## Acceptance Criteria - [ ] User can reset password via email link - [ ] Reset link expires after 24 hours - [ ] Error message shown for expired links - [ ] Rate limit: max 3 reset requests per hour ``` ### Priority Definitions | Priority | When to Use | | -------- | ---------------------------------------------- | | Urgent | Production is down, data loss, security breach | | High | Major feature blocked, significant user impact | | Medium | Normal feature work, non-critical bugs | | Low | Nice-to-have, cosmetic issues, tech debt | ## Triage Flow 1. Review unassigned issues (sorted by creation date) 2. For each issue: - Set priority based on definitions above - Assign to team member based on domain expertise - Move from Triage → Backlog (or Todo if urgent) - Add relevant labels 3. Confirm bulk changes before applying (>3 issues) ## Cycle Planning Checklist 1. Review current cycle completion stats 2. Carry over incomplete high-priority items 3. Pull from backlog by priority (Urgent → High → Medium) 4. Balance workload across team members 5. Ensure no single person has >5 active issues 6. Leave 20% capacity buffer for unplanned work ## Status Update Template ```markdown ## Weekly Status: [Project Name] ### Progress - Completed: X issues (list highlights) - In Progress: Y issues - Blocked: Z issues (list with reasons) ### Highlights - [Key achievement or milestone] ### Risks - [Blocker or risk with mitigation plan] ### Next Week - [Planned focus areas] ``` ## Workflow States Do NOT hardcode status names. Always fetch valid statuses from `list_issue_statuses` for the target team. Common patterns: | Typical State | Meaning | | ------------- | ----------------------------- | | Triage | New, needs review | | Backlog | Accepted, not started | | Todo | Planned for current cycle | | In Progress | Actively being worked on | | In Review | PR submitted, awaiting review | | Done | Completed and verified | | Cancelled | Won't do | ## Input Validation All `$ARGUMENTS` values are user input and must be validated before use: - **Issue IDs:** Must match `^[A-Z]{2,5}-[0-9]{1,6}$` exactly. Reject anything else. - **Titles/descriptions:** Max 500 characters. Strip HTML tags before passing to API. - **Cycle/filter names:** Alphanumeric, spaces, and hyphens only. Max 100 characters. - **General rule:** Never interpolate `$ARGUMENTS` into shell commands. Pass to MCP tools as API parameters only. If validation fails, report the format error and prompt the user to correct it. ## Security Patterns ### C1: Issue ID Validation Before any write operation using a branch-extracted issue ID, call `get_issue` to verify: - The issue exists - It belongs to the user's workspace This prevents cross-workspace data corruption from ID collisions. ### H1: Bulk Operation TOCTOU Between user review and confirmation, issues may change. Re-fetch state before applying bulk changes. ### M3: Agent Write Safety (Two-Tier Model) Linear state transitions follow a two-tier safety model based on reversibility and impact: **Tier 1 — Auto-apply (notify only):** Non-terminal, reversible transitions triggered by explicit user actions. Applied with post-hoc notification (e.g., "Updated ENG-123 to In Review") but no pre-confirmation. | Transition | Trigger | Rationale | |------------|---------|-----------| | `* → In Progress` | `/linear:work` starts work on issue; `/linear:delegate` delegates to Devin | Reversible, no external notifications | | `* → In Review` | `/smart-submit` creates a PR | Reversible, user explicitly submitted code | | `In Review → In Progress` | Moving backward (re-opening work) | Reversible, no data loss | **Tier 2 — Confirm (AskUserQuestion required):** Terminal, ambiguous, or externally-visible transitions. Requires explicit user confirmation via `AskUserQuestion` before applying. | Transition | Trigger | Rationale | |------------|---------|-----------| | `* → Done` | PR merged, work verified | Terminal, triggers notifications, may close PRs | | `* → Cancelled` | Issue abandoned | Terminal, may have cascading effects | | `* → Backlog` | De-prioritization | Ambiguous intent, may lose cycle assignment | **Classification criteria:** Auto-apply when ALL of these hold: (1) transition is reversible, (2) no information is destroyed, (3) minimal external notifications, (4) no cascading side effects. Confirm when ANY criterion fails. **Evolution note:** This is an evolution of the original M3 rule ("always confirm before writes"). The original rule was overly conservative for transitions triggered by explicit user workflow actions (e.g., submitting a PR implies intent to move to "In Review"). Tier 2 preserves the original M3 behavior for all terminal transitions. Agents that modify Linear state outside the two-tier model (e.g., custom status updates) must still use Tier 2 confirmation. Read-only agents never modify state. ## PR Convention - Create PRs via the active stacked-PR provider (resolved via the `stack-provider-router` skill) — Graphite: `gt submit`; GitHub: `github-stack-runtime.js submit` - Read PR state via GitHub: `gh pr view`, `gh api` - Never use `gh pr create` for PR creation - Link issues to PRs by adding a comment with the PR URL ## Shell Patterns Always quote variables when handling Linear-derived data: ```bash # Extract issue ID from branch name branch_name="$(git branch --show-current)" issue_id="$(printf '%s' "$branch_name" | grep -oE '[A-Z]{2,5}-[0-9]{1,6}' | head -n1)" # Validate before use if [ -z "$issue_id" ]; then printf '[linear] No issue ID found in branch name "%s"\n' "$branch_name" >&2 exit 1 fi # Call MCP tool (never interpolate $ARGUMENTS into shell commands) # Pass as API parameters only ``` ## Error Handling Guidance | Error | Action | | ----------------------- | ----------------------------------------------------------------- | | Authentication required | Re-run command to trigger OAuth re-authentication | | Rate limited (429) | Exponential backoff: wait 1s, 2s, 4s. Max 3 retries. | | Issue not found | Verify issue ID exists in your Linear workspace | | Team not found | Check git remote matches a Linear team name | | Partial batch failure | Report which items succeeded/failed. Offer to retry failed items. | ### Bulk Operation Rate Limiting For commands that issue multiple writes (triage, plan-cycle, sync-all): - Add a brief delay between each `save_issue` call for batches >5 items - If a 429 rate limit response occurs, pause and retry with exponential backoff - On partial failure, report results so far and offer to retry remaining items - Never leave the user guessing about state after a partial failure