266 lines
6.5 KiB
Markdown
266 lines
6.5 KiB
Markdown
---
|
|
name: linear-lifecycle
|
|
description: Use when working with Linear issues across development workflow - uses Linearis CLI with JSON output for zero-context issue management. Get details, create issues, update status, and add comments without consuming tokens in main session.
|
|
---
|
|
|
|
# Linear Lifecycle Management with Linearis CLI
|
|
|
|
## Overview
|
|
|
|
**Core principle:** Use Linearis CLI for all Linear operations instead of loading 20k token Linear MCP. CLI returns structured JSON for parsing without context overhead.
|
|
|
|
**Tool:** [Linearis](https://github.com/czottmann/linearis) - Linear CLI built for LLM agents with ~1000 token footprint vs 13k+ for MCP.
|
|
|
|
**Context savings:** 100% - no MCP loaded, just bash commands with JSON output.
|
|
|
|
## Setup
|
|
|
|
**One-time dependencies install:**
|
|
|
|
Use `/linear-setup` to install Linearis CLI (required for this skill to work).
|
|
|
|
**Token configuration:**
|
|
|
|
Automatic! On first use, Claude will:
|
|
|
|
1. Check if `~/.linear_api_token` exists
|
|
2. If not, prompt you for your Linear API token
|
|
3. Save it to `~/.linear_api_token` with secure permissions
|
|
4. Verify the connection works
|
|
|
|
**Get your token:** Linear Settings → Security & Access → Personal API keys
|
|
|
|
## When to Use
|
|
|
|
**Use this skill when:**
|
|
|
|
- Starting work on a Linear issue (need issue details)
|
|
- Creating new issues from bugs or features discovered
|
|
- Updating issue status during development
|
|
- Adding comments or progress updates
|
|
- Searching for issues across teams/projects
|
|
|
|
**Don't use when:**
|
|
|
|
- Issue tracking not needed for current work
|
|
- Working on non-Linear projects
|
|
|
|
## Implementation
|
|
|
|
**IMPORTANT: Always check for token on first Linear operation in a skill invocation:**
|
|
|
|
```bash
|
|
# Check if token exists
|
|
if [ ! -f ~/.linear_api_token ]; then
|
|
echo "⚠️ Linear API token not found."
|
|
echo ""
|
|
echo "Get your token from: Linear Settings → Security & Access → Personal API keys"
|
|
echo ""
|
|
# Use AskUserQuestion tool to prompt for token
|
|
# Save response to ~/.linear_api_token
|
|
# Set permissions: chmod 600 ~/.linear_api_token
|
|
# Verify it works with: linearis issues list -l 1
|
|
fi
|
|
```
|
|
|
|
After token is confirmed, proceed with Linear operations. Linearis automatically reads from `~/.linear_api_token`.
|
|
|
|
### Creating a New Issue
|
|
|
|
**IMPORTANT: Keep it simple! Specify the team key directly. Never use --labels or --priority.**
|
|
|
|
**User request:** "Create a Linear issue for fixing the avatar crop bug"
|
|
|
|
**Command:**
|
|
|
|
```bash
|
|
linearis issues create "Fix avatar crop bug" \
|
|
--team BET \
|
|
--description "Avatar images are cropping incorrectly on mobile devices. Need to adjust aspect ratio handling."
|
|
```
|
|
|
|
**Key rules:**
|
|
|
|
- ✅ Use `--team TEAM_KEY` (get from user's Linear workspace, e.g. BET, ENG, etc.)
|
|
- ✅ Keep description clear and concise
|
|
- ❌ NEVER use --labels (causes errors)
|
|
- ❌ NEVER use --priority (unnecessary)
|
|
|
|
**Parse response:**
|
|
|
|
```bash
|
|
# Returns JSON with: {identifier, title, url, ...}
|
|
# Extract: issue ID (e.g., BET-145) and URL
|
|
```
|
|
|
|
**Response to user:**
|
|
|
|
```markdown
|
|
✓ Created issue BET-145: Fix avatar crop bug
|
|
https://linear.app/your-workspace/issue/BET-145
|
|
```
|
|
|
|
### Starting Work on an Issue
|
|
|
|
**User request:** "Start working on bet-123"
|
|
|
|
**Command:**
|
|
|
|
```bash
|
|
linearis issues read BET-123
|
|
```
|
|
|
|
**Parse JSON response for:**
|
|
|
|
- title
|
|
- description
|
|
- state (current status)
|
|
- priority
|
|
- labels
|
|
- branchName (suggested git branch)
|
|
|
|
**Response to user:**
|
|
|
|
```markdown
|
|
Issue: BET-123 - [Title]
|
|
Status: [State]
|
|
Description: [Brief description]
|
|
Labels: [labels]
|
|
Branch: [branchName or generate from title]
|
|
|
|
Creating branch [branch-name]...
|
|
```
|
|
|
|
**Then create branch and proceed with development.**
|
|
|
|
### Updating Issue Status
|
|
|
|
**User request:** "Update bet-456 to in progress"
|
|
|
|
**Command:**
|
|
|
|
```bash
|
|
linearis issues update BET-456 --state "In Progress"
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```markdown
|
|
✓ Updated BET-456 to In Progress
|
|
```
|
|
|
|
### Adding Comments
|
|
|
|
**User request:** "Add comment to bet-789 about the refactor being done"
|
|
|
|
**Command:**
|
|
|
|
```bash
|
|
linearis comments create BET-789 --body "Completed auth refactor. Moved from Context API to Zustand for better performance. All tests passing."
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```markdown
|
|
✓ Added comment to BET-789
|
|
```
|
|
|
|
### Searching for Issues
|
|
|
|
**User request:** "Find all open bugs with label 'authentication'"
|
|
|
|
**Command:**
|
|
|
|
```bash
|
|
linearis issues search "authentication" --team "$LINEAR_TEAM_KEY" | jq '.[] | select(.labels[]? | contains("bug")) | {id: .identifier, title: .title, state: .state.name}'
|
|
```
|
|
|
|
**Parse and format results as table.**
|
|
|
|
### Completing Work
|
|
|
|
**User request:** "Close bet-789, PR merged"
|
|
|
|
**Commands:**
|
|
|
|
```bash
|
|
# 1. Add completion comment
|
|
linearis comments create BET-789 --body "Feature complete. PR #456 merged to main."
|
|
|
|
# 2. Update status to done
|
|
linearis issues update BET-789 --state "Done"
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```markdown
|
|
✓ Marked BET-789 as Done
|
|
✓ Added completion comment
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
| Operation | Command Pattern |
|
|
|-----------|----------------|
|
|
| List recent issues | `linearis issues list -l 10` |
|
|
| Get issue details | `linearis issues read ABC-123` |
|
|
| Create issue | `linearis issues create "Title" --team TEAM_KEY --description "Description"` |
|
|
| Update status | `linearis issues update ABC-123 --state "In Progress"` |
|
|
| Add comment | `linearis comments create ABC-123 --body "Comment text"` |
|
|
| Search issues | `linearis issues search "query"` |
|
|
|
|
## Common Mistakes
|
|
|
|
**Not parsing JSON output**
|
|
|
|
- ❌ Don't show raw JSON to user
|
|
- ✅ Parse and format relevant fields cleanly
|
|
|
|
**Hardcoding team/project names**
|
|
|
|
- ❌ Don't assume team structure
|
|
- ✅ Let user specify or discover via linearis commands
|
|
|
|
**Using issue IDs incorrectly**
|
|
|
|
- ❌ Don't lowercase (bet-123) in commands
|
|
- ✅ Use proper case (BET-123) - linearis handles both but be consistent
|
|
|
|
## Real-World Impact
|
|
|
|
**Before (Linear MCP):**
|
|
|
|
- 20k tokens consumed at session start
|
|
- All tools loaded in context
|
|
- Context budget: 180k/200k remaining
|
|
|
|
**After (Linearis CLI):**
|
|
|
|
- 0 tokens in session (just bash commands)
|
|
- JSON parsing lightweight
|
|
- Context budget: 200k/200k remaining
|
|
- **100% context savings**
|
|
|
|
**Performance:**
|
|
|
|
- Linearis usage docs: ~1000 tokens
|
|
- MCP tool definitions: ~13000 tokens
|
|
- **92% reduction even for reference material**
|
|
|
|
## Advanced: Multi-Team Operations
|
|
|
|
**List issues across teams:**
|
|
|
|
```bash
|
|
linearis issues list --team Frontend -l 5
|
|
linearis issues list --team Backend -l 5
|
|
```
|
|
|
|
**Create issue in specific team:**
|
|
|
|
```bash
|
|
linearis issues create "Fix API timeout" --team Backend
|
|
```
|
|
|
|
**No workspace switching needed** - all commands accept `--team` flag for cross-team operations within same Linear workspace.
|