linear-task-selector

name	linear-task-selector
description	Fetch tasks from Linear backlog and handle user selection. Saves selected task context for use in feature/bug/plan workflows. Reduces context usage by consolidating Linear API interactions.

Linear Task Selector

This skill handles fetching tasks from Linear and managing user selection for workflow, bugfix, and plan commands.

When to Use

Use this skill when:

• Starting a workflow, bugfix, or plan command
• User needs to select a task from Linear backlog
• You need to fetch and display Linear issues for selection

Instructions

Step 1: Determine Project Name

• Check CLAUDE.md for the correct Linear project name
• Common projects: "SalesBot MVP", "Hokusai data pipeline", "Hokusai infrastructure"
• If unclear, ask the user which project to use

Step 2: Fetch Linear Backlog

Run the Linear backlog tool with the appropriate project name:

npx tsx ~/.claude/tools/get-backlog.ts "PROJECT_NAME"

For bug-specific tasks, add "bug" filter:

npx tsx ~/.claude/tools/get-backlog.ts "PROJECT_NAME" "bug"

Step 3: Present Tasks to User

• Number each task (1, 2, 3, etc.)
• Display: task number, title, labels, state
• Format as a clean numbered list
• Use osascript -e 'beep' to alert the user

Example output:

Select a task from Linear:

1. [HOK-123] Add user authentication
   Labels: feature, backend
   State: Backlog

2. [HOK-124] Fix payment processing bug
   Labels: bug, critical
   State: Backlog

Please select a task by entering its number:

Step 4: Capture User Selection

• Wait for user to provide a number
• Extract the corresponding task details:
  • Task ID (e.g., HOK-123)
  • Task title
  • Task description
  • Labels
  • State

Step 5: Save Context

1. Sanitize the task title to create a feature name:

   • Lowercase all characters
   • Replace spaces with hyphens
   • Remove special characters (keep only alphanumeric and hyphens)
   • Example: "Add User Authentication!" → add-user-authentication

2. Create the feature directory:

mkdir -p features/<feature-name>

3. Save the selected task context to features/<feature-name>/selected-task.json:

{
  "taskId": "HOK-123",
  "title": "Add user authentication",
  "description": "Full task description from Linear",
  "labels": ["feature", "backend"],
  "state": "Backlog",
  "projectName": "SalesBot MVP",
  "workflowType": "feature",
  "featureName": "add-user-authentication",
  "contextPath": "features/add-user-authentication/selected-task.json",
  "selectedAt": "2025-01-11T10:30:00Z"
}

Set workflowType based on labels:

• Contains "bug": "workflowType": "bugfix"
• Large/epic task: "workflowType": "plan"
• Otherwise: "workflowType": "feature"

Step 6: Return Summary

Return a concise summary to the user:

✓ Selected: [HOK-123] Add user authentication
  Type: feature
  Feature directory: features/add-user-authentication/
  Context saved to: features/add-user-authentication/selected-task.json

Examples

Example 1: Feature Selection

User: /workflow
Assistant uses linear-task-selector:
1. Checks CLAUDE.md → finds "SalesBot MVP" project
2. Runs: npx tsx ~/.claude/tools/get-backlog.ts "SalesBot MVP"
3. Displays 5 tasks with numbers
4. User selects: 3
5. Creates: features/implement-email-generation/
6. Saves task to features/implement-email-generation/selected-task.json
7. Returns: "✓ Selected: [HOK-125] Implement email generation"

Example 2: Bug Selection

User: /bugfix
Assistant uses linear-task-selector:
1. Checks CLAUDE.md → finds "SalesBot MVP" project
2. Runs: npx tsx ~/.claude/tools/get-backlog.ts "SalesBot MVP" "bug"
3. Displays 3 bugs with numbers
4. User selects: 1
5. Creates: features/fix-contact-discovery-timeout/
6. Saves bug to features/fix-contact-discovery-timeout/selected-task.json with workflowType: "bugfix"
7. Returns: "✓ Selected: [HOK-130] Fix contact discovery timeout"

Error Handling

Linear API Issues

If the Linear API fails:

1. Check for LINEAR_API_KEY in environment
2. Verify network connectivity
3. Check Linear API status
4. Provide helpful error message to user

No Tasks Found

If no tasks are returned:

1. Verify project name is correct
2. Check if tasks exist in Linear for that project
3. Suggest checking Linear directly
4. Ask user if they want to try a different project

Invalid Selection

If user selects an invalid number:

1. Show error: "Please select a number between 1 and N"
2. Re-display the numbered list
3. Wait for valid selection

Output

This skill outputs:

• features/<feature-name>/selected-task.json: Selected task context for downstream workflows
• features/<feature-name>/: Created feature directory for all workflow artifacts
• Console: Summary message confirming selection
• Side effect: Beep sound to alert user

Note: Using feature-specific paths prevents conflicts when multiple Claude sessions run concurrently.

Integration

Next steps after this skill:

• workflow: Use task context to create feature branch and generate PRD
• bugfix: Use task context to create bugfix branch and generate investigation plan
• plan: Use task context to decompose epic into sub-issues