@dabble/linear-cli 1.0.0

package/claude/commands/done.md

@@ -0,0 +1,65 @@
+# /done - Complete work on an issue
+
+Help the developer wrap up their work on the current Linear issue.
+
+## Usage
+
+```
+/done           # Complete the issue detected from branch name
+/done ISSUE-12   # Complete a specific issue
+```
+
+## Steps
+
+1. **Detect the issue** from the branch name or use the provided ID
+2. **Summarize the work** by checking:
+   - `git log --oneline <base>..HEAD` to see commits
+   - `git diff --stat <base>..HEAD` to see files changed
+3. **Ask what they want to do** using AskUserQuestion:
+   - Close the issue in Linear
+   - Create a PR first
+   - Add final notes to the issue
+   - Just clean up (worktree only)
+
+## After Selection
+
+### If they want to create a PR:
+1. Run `gh pr create --title "ISSUE-12: Issue title" --body "..."` with a summary
+2. Then proceed to closing if requested
+
+### If they want to add notes:
+1. Ask what notes to add
+2. Run `linear issue update ISSUE-12 --append "..."` with the notes
+
+### If they want to close:
+1. Run `linear done ISSUE-12` to close the issue
+
+### Worktree cleanup:
+If in a worktree, `linear done` will output commands to clean up. Let the user know they can copy those commands or run them manually.
+
+## Example Flow
+
+```
+User: /done
+
+Claude: Let me check what you've been working on...
+
+[Runs git log and git diff]
+
+You've made 3 commits on ISSUE-12: Add caching layer
+- src/cache.ts (new file, 45 lines)
+- src/api.ts (modified, +12 -3)
+
+What would you like to do?
+1. Create PR and close issue
+2. Close issue (no PR)
+3. Add notes and close
+4. Just clean up worktree (don't close)
+```
+
+## Notes
+
+- Always show a summary of the work done before asking
+- If there are no commits, skip the PR option
+- The `linear done` command handles the mechanical parts (closing, worktree detection)
+- Don't auto-close - always confirm with the user first

package/claude/commands/next.md

@@ -0,0 +1,94 @@
+# /next - Find the next issue to work on
+
+Help the developer find and start working on their next Linear issue, or do product planning.
+
+## Usage
+
+```
+/next           # Show unblocked issues to choose from
+/next ISSUE-12   # Skip selection, start working on ISSUE-12 directly
+```
+
+## If an issue ID is provided
+
+Skip straight to starting work on that issue (see "Starting Work on an Issue" below).
+
+## If no issue ID is provided
+
+1. Run `linear issues --unblocked` to get issues ready to work on
+2. Parse the output and count the issues
+3. Present options using the format below
+
+### Presenting Options
+
+Always present a numbered list with these rules:
+- Show up to **5 issues maximum** (yours are already sorted first by the CLI)
+- If more than 5 issues exist, note how many more after the list
+- **Always** include "Product planning" as the final option
+
+### Format
+
+```
+Here's what's ready to work on:
+
+1. ISSUE-5: Add caching layer [Backlog] (assigned to you)
+2. ISSUE-8: Fix login timeout [Backlog]
+3. ISSUE-12: Update API docs [Backlog]
+4. ISSUE-18: Do Something Else [Backlog]
+5. ISSUE-29: Another thing [Backlog]
+   ... and 7 more unblocked issues
+6. Product planning - brainstorm features, review backlog, plan next phase
+
+Which would you like to work on?
+```
+
+### If NO unblocked issues:
+
+```
+No unblocked issues at the moment.
+
+1. Product planning - brainstorm features, review backlog, plan next phase
+
+Would you like to work on product planning?
+```
+
+### If exactly ONE issue:
+
+```
+There's one issue ready to work on:
+
+1. ISSUE-5: Add caching layer [Backlog] (assigned to you)
+2. Product planning - brainstorm features, review backlog, plan next phase
+
+Which would you like?
+```
+
+## Starting Work on an Issue
+
+When the user selects an issue (or provides one directly via `/next ISSUE-12`):
+
+1. Run `linear issue start <id>` to assign and set In Progress
+2. Run `linear branch <id>` to create a git branch
+3. Run `linear issue show <id>` to display full context
+4. **Enter plan mode** using the EnterPlanMode tool
+
+This ensures every issue starts with a proper implementation plan before writing code.
+
+## If they choose "Product planning"
+
+Start a planning session by asking:
+
+"What would you like to focus on?"
+- Review and prioritize the backlog
+- Brainstorm new features
+- Plan the next phase
+- Something specific
+
+Then follow the product-planning skill guidelines to facilitate the session.
+
+## Notes
+
+- Always use long flags (--unblocked, not -u) for clarity
+- The CLI already sorts your assigned issues first
+- If presenting options, use the AskUserQuestion tool for a clean interface
+- The "Product planning" option ensures there's always something productive to do

package/claude/commands/standup.md

@@ -0,0 +1,63 @@
+# /standup - Daily standup summary
+
+Generate a summary of your work for standup meetings.
+
+## Usage
+
+```
+/standup        # Show standup summary from Linear + GitHub
+```
+
+## What It Shows
+
+Run `linear standup` to get:
+
+**From Linear:**
+- Issues you completed yesterday
+- Issues currently in progress
+- Issues that are blocked
+
+**From GitHub (if in a repo):**
+- Commits you made yesterday
+- PRs you opened or merged yesterday
+
+## After Running
+
+1. Present the output from `linear standup` to the user
+2. Offer to help with:
+   - Drafting a standup message for Slack/Teams
+   - Identifying what to work on next (suggest `/next`)
+   - Resolving any blockers
+
+## Example Flow
+
+```
+User: /standup
+
+Claude: [Runs linear standup]
+
+Here's your standup summary:
+
+**Yesterday:**
+✓ ISSUE-5: Add caching layer
+✓ ISSUE-6: Fix login timeout
+
+**Today:**
+→ ISSUE-8: Implement worktree support
+
+**Blocked:**
+⊘ ISSUE-12: Waiting on API credentials
+
+**GitHub:**
+- 4 commits on beautiful-tech
+- PR #42 merged: ISSUE-5: Add caching layer
+
+Would you like me to help draft a standup message, or shall we look at what to work on next?
+```
+
+## Notes
+
+- The `linear standup` command handles all the data fetching
+- GitHub info requires the `gh` CLI to be installed and authenticated
+- If not in a git repo, GitHub section will be skipped
+- Use `--no-github` flag to skip GitHub even if available

package/claude/skills/linear-cli.md

@@ -0,0 +1,193 @@
+---
+name: linear-cli
+description: Manage Linear issues and projects from the command line. This skill allows automating Linear project management.
+allowed-tools: Bash(linear:*), Bash(curl:*)
+---
+
+# Linear CLI
+
+A cross-platform CLI for Linear's GraphQL API, with unblocked issue filtering.
+
+Install: `npm install -g @dabble/linear-cli`
+
+## First-Time Setup
+
+```bash
+linear login
+```
+
+This will:
+1. Open Linear API settings in your browser
+2. Prompt you to paste your API key
+3. Show available teams and let you pick one (or create a new team)
+4. Save config to `./.linear`
+
+Use `--global` to save to `~/.linear` instead.
+
+## Configuration
+
+Config is loaded in order: `./.linear` → `~/.linear` → env vars
+
+```
+# .linear file format
+api_key=lin_api_xxx
+team=ISSUE
+```
+
+## Quick Reference
+
+```bash
+# Auth
+linear login                    # Interactive setup
+linear login --global           # Save to ~/.linear
+linear logout                   # Remove config
+linear whoami                   # Show current user/team
+
+# Issues
+linear issues --unblocked       # Ready to work on (no blockers)
+linear issues --open            # All non-completed issues
+linear issues --in-progress     # Issues currently in progress
+linear issues --mine            # Only your assigned issues
+linear issues --label bug       # Filter by label
+# Flags can be combined: linear issues --in-progress --mine
+linear issue show ISSUE-1        # Full details with parent context
+linear issue start ISSUE-1       # Assign to you + set In Progress
+linear issue create --title "Fix bug" --project "Phase 1" --assign --estimate M
+linear issue create --title "Blocked task" --blocked-by ISSUE-1
+linear issue update ISSUE-1 --state "In Progress"
+linear issue update ISSUE-1 --append "Notes..."
+linear issue update ISSUE-1 --blocks ISSUE-2  # Add blocking relation
+linear issue close ISSUE-1
+linear issue comment ISSUE-1 "Comment text"
+
+# Projects
+linear projects                 # Active projects
+linear projects --all           # Include completed
+linear project show "Phase 1"   # Details with issues
+linear project create "Name" --description "..."
+linear project complete "Phase 1"
+
+# Labels
+linear labels                   # List all labels
+linear label create "bug" --color "#FF0000"
+
+# Git
+linear branch ISSUE-1            # Create branch: ISSUE-1-issue-title
+```
+
+## Estimation
+
+Use t-shirt sizes for estimates. Always use `--estimate` (not `-e`) for clarity.
+
+| Size | Meaning |
+|------|---------|
+| XS | Trivial, < 1 hour |
+| S | Small, couple hours |
+| M | Medium, a day or so |
+| L | Large, multi-day - consider breaking down |
+| XL | Very large - should definitely break down |
+
+```bash
+# Create with estimate (use long flags for clarity)
+linear issue create --title "Add caching" --estimate M --assign
+
+# L/XL issues should be broken into sub-issues
+linear issue create --title "Implement auth" --estimate L
+linear issue create --title "Add login endpoint" --parent ISSUE-5 --estimate S
+linear issue create --title "Add JWT validation" --parent ISSUE-5 --estimate S
+```
+
+## Git Conventions
+
+Always link git work to Linear issues:
+
+```bash
+# Create branch from issue (recommended)
+linear branch ISSUE-5            # Creates: ISSUE-5-add-caching-layer
+
+# Commit message format
+git commit -m "ISSUE-5: Add cache invalidation on logout"
+
+# Include issue ID in PR title
+gh pr create --title "ISSUE-5: Add caching layer"
+```
+
+## Workflow Guidelines
+
+### Starting work on an issue
+```bash
+linear issues --unblocked       # Find what's ready
+linear issue show ISSUE-2        # Review it (shows parent context)
+linear issue start ISSUE-2       # Assign + set In Progress
+linear branch ISSUE-2            # Create git branch
+```
+
+### When you hit a blocker
+If work cannot continue due to a dependency or external factor:
+
+```bash
+# Create the blocking issue
+linear issue create --title "Need API credentials" --blocks ISSUE-5
+
+# Or mark existing issue as blocking
+linear issue update ISSUE-3 --blocks ISSUE-5
+```
+
+This removes ISSUE-5 from `--unblocked` results until the blocker is resolved.
+
+### When a task is larger than expected
+If you discover an M issue is actually L/XL, break it down:
+
+```bash
+# Create sub-issues
+linear issue create --title "Step 1: Research approach" --parent ISSUE-5 --estimate S
+linear issue create --title "Step 2: Implement core logic" --parent ISSUE-5 --estimate M
+linear issue create --title "Step 3: Add tests" --parent ISSUE-5 --estimate S
+
+# Start working on the first sub-issue
+linear issue start ISSUE-6
+```
+
+### Completing work
+After finishing implementation, ask the developer if they want to close the issue:
+
+```bash
+# Suggest closing
+linear issue close ISSUE-5
+```
+
+Do not auto-close issues. Let the developer review the work first.
+
+### Adding notes while working
+```bash
+linear issue update ISSUE-2 --append "## Notes\n\nDiscovered X, trying Y approach..."
+# or for quick updates
+linear issue comment ISSUE-2 "Found the root cause in auth.ts:142"
+```
+
+### Completing a phase
+```bash
+linear issue close ISSUE-7       # Close remaining issues
+linear project complete "Phase 1"
+# Then update CLAUDE.md status table
+```
+
+## Parent Context
+
+When viewing an issue with `linear issue show`, you'll see where it fits in the larger work:
+
+```
+# ISSUE-6: Add JWT validation
+
+State: In Progress
+...
+
+## Context
+
+ISSUE-3: Implement authentication system
+  - [Done] ISSUE-4: Add login endpoint
+  → [In Progress] ISSUE-6: Add JWT validation  ← you are here
+  - [Backlog] ISSUE-7: Add refresh tokens
+```
+
+This helps understand the scope and what comes before/after the current task.

package/claude/skills/product-planning.md

@@ -0,0 +1,136 @@
+---
+name: product-planning
+description: Help with product planning, feature brainstorming, and backlog management using Linear.
+allowed-tools: Bash(linear:*), Bash(curl:*)
+---
+
+# Product Planning Skill
+
+Help the developer think through product direction, brainstorm features, and manage their Linear backlog.
+
+## When to Use This Skill
+
+Use this skill when the developer wants to:
+- Brainstorm new features or improvements
+- Review and prioritize the backlog
+- Break down large ideas into actionable issues
+- Plan a new phase or milestone
+- Think through product strategy
+
+## Approach
+
+### 1. Understand Current State
+
+First, gather context:
+
+```bash
+# See all open issues (backlog + in progress, excludes completed)
+linear issues --open
+
+# See active projects/phases
+linear projects
+```
+
+### 2. Facilitate Discussion
+
+Ask good questions to help clarify thinking:
+
+- "What problem are we trying to solve?"
+- "Who benefits from this feature?"
+- "What's the simplest version that would be valuable?"
+- "What are the dependencies or blockers?"
+- "How does this fit with the current phase?"
+
+### 3. Break Down Ideas
+
+When a feature is identified, help break it into Linear issues:
+
+**For small features (S/M):**
+- Create a single issue with clear acceptance criteria
+- Assign appropriate estimate
+
+**For large features (L/XL):**
+- Create a parent issue describing the overall goal
+- Break into sub-issues, each S or M sized
+- Identify dependencies between sub-issues
+
+```bash
+# Create parent issue
+linear issue create --title "User authentication system" --estimate L --project "Phase 2"
+
+# Create sub-issues
+linear issue create --title "Design auth flow" --parent ISSUE-10 --estimate S
+linear issue create --title "Implement login endpoint" --parent ISSUE-10 --estimate M
+linear issue create --title "Add session management" --parent ISSUE-10 --estimate M --blocked-by ISSUE-12
+```
+
+### 4. Organize Into Phases
+
+If planning a new phase:
+
+```bash
+# Create the phase
+linear project create "Phase 3: User Dashboard" --description "Build the main user-facing dashboard with key metrics"
+
+# Add issues to it
+linear issue create --title "Dashboard layout" --project "Phase 3" --estimate M
+```
+
+## Brainstorming Prompts
+
+When the developer is stuck, try these prompts:
+
+**For new features:**
+- "What do users complain about most?"
+- "What manual process could we automate?"
+- "What would make you excited to use this product?"
+
+**For improvements:**
+- "Where do users get confused?"
+- "What takes too long?"
+- "What breaks most often?"
+
+**For prioritization:**
+- "What would have the biggest impact with the least effort?"
+- "What's blocking other work?"
+- "What do users ask for most?"
+
+## Output Format
+
+After a planning session, summarize:
+
+1. **New issues created** - List with IDs and estimates
+2. **Backlog changes** - Any reprioritization or updates
+3. **Next steps** - What to work on next
+4. **Open questions** - Things that need more thought
+
+## Example Session
+
+```
+Developer: "I want to add user notifications"
+
+Claude: Let me check the current state...
+[runs linear issues --all]
+
+Good context. A few questions:
+1. What triggers notifications? (events, mentions, etc.)
+2. Where do they appear? (in-app, email, push?)
+3. Is this blocking other work?
+
+Developer: "Just in-app for now, triggered by comments on their issues"
+
+That's a nicely scoped M-sized feature. Let me create it:
+[runs linear issue create --title "In-app notifications for issue comments" --estimate M --project "Phase 2"]
+
+Created ISSUE-15. Should I break this down further, or is it small enough to tackle as one unit?
+```
+
+## Integration with /next
+
+When invoked from the `/next` command (user chose "product planning"), start by asking:
+
+"What would you like to focus on today?"
+- Review and prioritize the backlog
+- Brainstorm new features
+- Plan the next phase
+- Something specific (let them describe)

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@dabble/linear-cli",
+  "version": "1.0.0",
+  "description": "Linear CLI with unblocked issue filtering, built for AI-assisted development",
+  "type": "module",
+  "bin": {
+    "linear": "./bin/linear.mjs"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.mjs",
+    "preuninstall": "node preuninstall.mjs"
+  },
+  "files": [
+    "bin/",
+    "claude/",
+    "postinstall.mjs",
+    "preuninstall.mjs"
+  ],
+  "keywords": [
+    "linear",
+    "cli",
+    "project-management",
+    "issues",
+    "claude"
+  ],
+  "author": "Dabble",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dabblewriter/linear-cli"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,54 @@
+import { cpSync, mkdirSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname, relative } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const src = join(__dirname, 'claude');
+const dest = join(homedir(), '.claude');
+
+// Copy skill and command files
+try {
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  // Recursively copy claude/ to ~/.claude/
+  cpSync(src, dest, { recursive: true });
+
+  const files = readdirSync(src, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => relative(src, join(e.parentPath, e.name)));
+
+  console.log(`\x1b[32m✓\x1b[0m Installed Claude files to ~/.claude/`);
+  for (const file of files) {
+    console.log(`  - ${file}`);
+  }
+} catch (err) {
+  console.log(`\x1b[33m⚠\x1b[0m Could not install Claude files: ${err.message}`);
+}
+
+// Add linear permission to settings.json
+const PERMISSION = 'Bash(linear:*)';
+const settingsPath = join(dest, 'settings.json');
+
+try {
+  let settings = { permissions: { allow: [], deny: [] } };
+
+  if (existsSync(settingsPath)) {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  }
+
+  // Ensure structure exists
+  settings.permissions = settings.permissions || {};
+  settings.permissions.allow = settings.permissions.allow || [];
+
+  // Add permission if not already present
+  if (!settings.permissions.allow.includes(PERMISSION)) {
+    settings.permissions.allow.push(PERMISSION);
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`\x1b[32m✓\x1b[0m Added ${PERMISSION} to ~/.claude/settings.json`);
+  }
+} catch (err) {
+  console.log(`\x1b[33m⚠\x1b[0m Could not update settings: ${err.message}`);
+}

package/preuninstall.mjs

@@ -0,0 +1,52 @@
+import { unlinkSync, existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, dirname, relative } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const src = join(__dirname, 'claude');
+const dest = join(homedir(), '.claude');
+
+// Remove files that were installed from claude/
+let removedCount = 0;
+try {
+  const files = readdirSync(src, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => relative(src, join(e.parentPath, e.name)));
+
+  for (const file of files) {
+    const filePath = join(dest, file);
+    try {
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+        removedCount++;
+      }
+    } catch (err) {
+      // Silently ignore removal errors
+    }
+  }
+} catch (err) {
+  // Silently ignore if claude/ dir doesn't exist
+}
+
+if (removedCount > 0) {
+  console.log(`\x1b[32m✓\x1b[0m Removed ${removedCount} Claude file(s) from ~/.claude/`);
+}
+
+// Remove linear permission from settings.json
+const PERMISSION = 'Bash(linear:*)';
+const settingsPath = join(dest, 'settings.json');
+
+try {
+  if (existsSync(settingsPath)) {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+
+    if (settings.permissions?.allow?.includes(PERMISSION)) {
+      settings.permissions.allow = settings.permissions.allow.filter(p => p !== PERMISSION);
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      console.log(`\x1b[32m✓\x1b[0m Removed ${PERMISSION} from ~/.claude/settings.json`);
+    }
+  }
+} catch (err) {
+  // Silently ignore settings errors
+}