Linear workflow patterns and conventions reference. Use when commands or agents need Linear workflow context, issue writing guidance, or branch naming conventions.
npx claudepluginhub kinginyellows/yellow-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Reference patterns and conventions for Linear PM workflows. Loaded by commands and agents for consistent behavior.
Use when yellow-linear plugin commands or agents need shared Linear workflow context, including issue-writing guidance, branch naming conventions, or workflow state definitions.
This skill is not user-invokable. It provides shared context for the yellow-linear plugin's commands and agents.
Linear team names match GitHub repository names exactly. Auto-detected from git remote:
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:
Format: <type>/<TEAM-ID>-<description>
Examples:
feat/ENG-123-auth-flowfix/ENG-456-login-redirectrefactor/ENG-789-api-cleanupIssue 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.
## 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 | 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 |
## 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]
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 |
All $ARGUMENTS values are user input and must be validated before use:
^[A-Z]{2,5}-[0-9]{1,6}$ exactly. Reject anything
else.$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.
Before any write operation using a branch-extracted issue ID, call get_issue
to verify:
This prevents cross-workspace data corruption from ID collisions.
Between user review and confirmation, issues may change. Re-fetch state before applying bulk changes.
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.
gt submitgh pr view, gh apigh pr create for PR creationAlways quote variables when handling Linear-derived data:
# 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 | 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. |
For commands that issue multiple writes (triage, plan-cycle):
update_issue call for batches >5 itemsUse when implementing any feature or bugfix, before writing implementation code