Skip to content

USER_GUIDE.md

Latest commit

 

History

History
346 lines (260 loc) · 9.57 KB

USER_GUIDE.md

File metadata and controls

346 lines (260 loc) · 9.57 KB
Raw

Linear Assistant - User Guide

How Users Will Use the Plugin

Installation & Setup (One-time)

Step 1: Install the Plugin

/plugin install linear-assistant@cosmictaco-marketplace

Step 2: Add Linear API Key to Your Project

  1. Get your API key from https://linear.app/settings/api-keys
  2. Add it to your project's .env file at the root:
echo "LINEAR_API_KEY=lin_api_xxx" >> .env

Step 3: Initialize Your Workflow

bun run cli init

This will:

  1. Auto-detect your Linear teams from the API key
  2. Show you available teams to choose from
  3. Ask about your workflow (e.g., "Review todos, check requirements, assign to developers")
  4. Offer workflow presets (Review & Analyze, Ralph Agent, Custom)
  5. Generate a personalized skill in .claude/skills/linear-{team}-workflow.md

Example output:

🚀 Linear Assistant - Initialization Wizard

This wizard will help set up your personalized Linear workflow.

🔍 Fetching your Linear teams...

1. ASCOP (ASC) - ID: 7d832321-d9bc-41bd-aeca-aa1f2675d5da
2. Engineering (ENG) - ID: 9f4c7d2e-a1b3-4e5f-8c9d-2b6a4f7e8c9d

Select team number (or paste ID directly): 1

✅ Selected: ASCOP

📝 Describe your Linear workflow:
(e.g., 'Review all todos, check requirements, assign to developers')
Your workflow: Review client todos, analyze requirements, update descriptions, assign to developers

Would you like to use a workflow preset? (yes/no): yes

Available presets:
1. Review & Analyze - Review todos, analyze, update, assign
2. Ralph Agent - Create tasks and assign to Ralph agents
3. Custom - Use your own workflow
Select preset (1-3): 1

✅ Workflow skill created!
📁 Location: /Users/john/.claude/skills/linear-ascop-workflow/SKILL.md

💡 Next step: Load the skill with /skill in Claude

Daily Usage (Once initialized)

Step 1: Load Your Workflow Skill

In Claude, type:

/skill linear-ascop-workflow

This loads your personalized skill with all the commands documented.

Step 2: Use Linear Commands in Claude

Now you can use linear commands directly from Claude. Your skill documents all available commands:

# List all todos
linear list-issues --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --state "Todo"

# Review a specific issue
linear get-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-123

# After analyzing, update the title and move to In Progress
linear update-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-123 \
  --title "Better title" \
  --description "Updated requirements" \
  --state "In Progress"

# Add a comment
linear add-comment --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-123 \
  --message "Reviewed and ready to implement"

# When done, move to In Review
linear update-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-123 \
  --state "In Review"

Example Workflow: Review & Analyze

Your generated skill includes a step-by-step guide:

Step 1: List all todos

linear list-issues --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --state "Todo"

Output:

ID      | Title                          | State  | Assignee    | Priority
--------|--------------------------------|--------|-------------|----------
ASC-120 | Fix login dropdown menu        | Todo   | Unassigned  | 2
ASC-121 | Add password reset flow        | Todo   | Unassigned  | 2
ASC-122 | Update user profile page       | Todo   | Unassigned  | 3

Step 2: Review each issue

linear get-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-120

Output:

📋 Issue: ASC-120 - Fix login dropdown menu

Status: Todo
Assignee: Unassigned
Priority: 2
URL: https://linear.app/ascop/issue/ASC-120

Description:
The dropdown menu on the login page doesn't close when clicking outside. 
Users get stuck and have to refresh the page.

Client requirement: Must close on click-outside or ESC key

📎 Images (1):
  1. https://uploads.linear.app/abc/def/screenshot.png

💬 Comments (2):
  @alice (2024-01-15):
  Can you add a video of the bug?
  
  @bob (2024-01-16):
  Added screenshot, user says it happens on Chrome & Firefox

Step 3: Analyze and update

After reviewing, you decide:

  • Title needs clarification: "Fix dropdown - close on click-outside + ESC"
  • Priority is correct (2 = High)
  • Assign to John (developer)
linear update-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-120 \
  --title "Fix dropdown - close on click-outside + ESC key" \
  --description "Dropdown menu on login page must close when: (1) clicking outside, (2) pressing ESC. Currently doesn't close. Affects Chrome & Firefox. See screenshot in comments." \
  --state "In Progress" \
  --assignee john-id

Step 4: Add follow-up comment

linear add-comment --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-120 \
  --message "Reviewed and assigned to John. Updated title and description based on client feedback. Ready to implement."

Step 5: When John finishes

linear update-issue --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-120 \
  --state "In Review"

linear add-comment --team 7d832321-d9bc-41bd-aeca-aa1f2675d5da --id ASC-120 \
  --message "Implementation complete. Ready for QA review."

Multiple Projects

You can work with multiple Linear projects by creating different workflow skills for each:

bun run cli init  # Run again for a different team
# Select team 2: Engineering
# Creates: .claude/skills/linear-engineering-workflow/SKILL.md

/skill linear-engineering-workflow  # Load that workflow

Now you have both:

  • /skill linear-ascop-workflow → for ASCOP project
  • /skill linear-engineering-workflow → for Engineering project

Each uses its own team ID and workflow.

Features

1. Auto-detect Teams

The wizard automatically finds all teams you have access to. No manual ID lookups needed.

2. Image Extraction

When you get-issue, it automatically extracts image URLs from descriptions:

📎 Images (2):
  1. https://uploads.linear.app/abc/def/screenshot.png
  2. https://uploads.linear.app/xyz/qrs/error.png

You can download these to review locally.

3. Comment History

All comments are displayed with author and timestamp, so you see the full context.

4. JSON Output

All commands support --json for automation:

linear list-issues --team 7d832321... --state "Todo" --json

Returns structured JSON for piping to other tools.

5. Personalized Skills

Each workflow skill is generated based on YOUR workflow:

  • Your description is documented
  • Your team ID is pre-filled
  • Workflow presets (Review, Ralph) include your specific steps

Troubleshooting

"LINEAR_API_KEY not found"

Make sure your .env file exists at the project root:

cat .env | grep LINEAR_API_KEY
# Should show: LINEAR_API_KEY=lin_api_xxx

"Team not found"

List available teams:

linear list-teams

Make sure you're using the exact team ID from the list.

"State not found"

Different teams have different workflow states. Use the exact state name from Linear UI (e.g., "Todo", "In Progress", "In Review", "Done").

Commands aren't executing

Make sure you:

  1. Have bun installed
  2. Ran bun run cli init from your project root
  3. Have LINEAR_API_KEY in .env
  4. Loaded the generated skill with /skill

API Reference

list-issues

List issues with optional filters

linear list-issues --team <TEAM_ID> [--state <STATE>] [--json]

get-issue

Get full details of a specific issue

linear get-issue --team <TEAM_ID> --id <ISSUE_ID> [--json]

create-issue

Create a new issue

linear create-issue --team <TEAM_ID> --title <TITLE> \
  [--description <DESC>] [--priority <1-4>] [--assignee <USER_ID>] [--json]

Priority: 1 (Urgent), 2 (High), 3 (Medium), 4 (Low)

update-issue

Update issue fields

linear update-issue --team <TEAM_ID> --id <ISSUE_ID> \
  [--state <STATE>] [--title <TITLE>] [--description <DESC>] \
  [--assignee <USER_ID>] [--priority <1-4>] [--json]

add-comment

Add a comment to an issue

linear add-comment --team <TEAM_ID> --id <ISSUE_ID> --message <MESSAGE> [--json]

list-projects

List all projects in a team

linear list-projects --team <TEAM_ID> [--json]

list-cycles

List cycles/sprints

linear list-cycles --team <TEAM_ID> [--active-only] [--json]

list-teams

List all available teams

linear list-teams [--json]

Tips & Best Practices

  1. Always review images - Issue descriptions often contain important screenshots
  2. Check comments - Context from the team is in comments
  3. Use --json - When piping to other tools or scripts
  4. Customize your skill - After generation, you can edit the skill to add custom steps
  5. One workflow per team - Keep things organized by team
  6. Batch updates - Process issues in groups (todos first, then assigned, etc.)

Example: Ralph Integration

If you selected the "Ralph Agent" preset, your skill includes steps for creating Ralph tasks:

# Step 1: Get the issue
linear get-issue --team 7d832321... --id ASC-123

# Step 2: Analyze and create Ralph task with issue context
# (You create the Ralph task with the issue data)

# Step 3: Move to In Progress
linear update-issue --team 7d832321... --id ASC-123 --state "In Progress"
linear add-comment --team 7d832321... --id ASC-123 --message "Assigned to Ralph agent"

# Step 4: When Ralph completes
linear update-issue --team 7d832321... --id ASC-123 --state "Done"
linear add-comment --team 7d832321... --id ASC-123 --message "Completed by Ralph agent"

Need help? Check the generated skill file or run:

linear help <command>