Initial commit

2025-11-30 08:39:39 +08:00
commit 88c4c55b57
5 changed files with 342 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "linear-lifecycle",
+  "description": "Manage Linear issues via Linearis CLI with zero-context overhead. Create, update, and track issues without loading large MCPs.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Matthew Fornaciari",
+    "url": "https://github.com/mattforni"
+  },
+  "skills": [
+    "./skills/linear-lifecycle/SKILL.md"
+  ],
+  "commands": [
+    "./commands/linear-setup.md"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# linear-lifecycle
+
+Manage Linear issues via Linearis CLI with zero-context overhead. Create, update, and track issues without loading large MCPs.
--- a/commands/linear-setup.md
+++ b/commands/linear-setup.md
@@ -0,0 +1,10 @@
+---
+name: linear-setup
+description: Configure Linear API token and team key for the linear-lifecycle plugin
+---
+
+Copying setup command to clipboard...
+
+```bash
+echo "bash ~/.claude/plugins/marketplaces/skillset/plugins/linear-lifecycle/skills/linear-lifecycle/scripts/setup.sh" | pbcopy && echo "✓ Command copied to clipboard! Paste it in your terminal to run the setup."
+```
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,49 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:mattforni/skillset:plugins/linear-lifecycle",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "0e2fd118290016fc48e36030b27c3edc8be30049",
+    "treeHash": "ffbadf819f26df96d1fa0ab84f6bd9b5dc215b309ee83a18e287e8eadc0ca3af",
+    "generatedAt": "2025-11-28T10:27:03.114045Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "linear-lifecycle",
+    "description": "Manage Linear issues via Linearis CLI with zero-context overhead. Create, update, and track issues without loading large MCPs.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "be4fe1901701199ba0044ce6baa90c5ff0b0fd7df8f7b4303e1c6bd1aa5351d4"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "162b6f9f47d9cd4ccf8dcc17e19c10593f4338a7eefe93507bedc6d4b1c9471f"
+      },
+      {
+        "path": "commands/linear-setup.md",
+        "sha256": "a0e0569b14a9915787cd11e636c6a1a331ab8da8b5a011f40e6fad7355e58212"
+      },
+      {
+        "path": "skills/linear-lifecycle/SKILL.md",
+        "sha256": "077bd9aa9d1831fd0e84f5bfcc8754d34448d09059ef8a4e9963b427772a8403"
+      }
+    ],
+    "dirSha256": "ffbadf819f26df96d1fa0ab84f6bd9b5dc215b309ee83a18e287e8eadc0ca3af"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/linear-lifecycle/SKILL.md
+++ b/skills/linear-lifecycle/SKILL.md
@@ -0,0 +1,265 @@
+---
+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.