Linear Task Selector

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

• Prefer linear.defaultProject from claude/config.json (currently "wavemill"); CLAUDE.md may also name the project
• Common projects: "wavemill", "SalesBot MVP", "Hokusai data pipeline", "Hokusai infrastructure"
• If unclear, ask the user which project to use

Step 2: Fetch Linear Backlog

Run the lean backlog tool (faster query, limited to 50 items) with the appropriate project name:

npx tsx tools/list-backlog-json.ts "PROJECT_NAME"

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

npx tsx tools/list-backlog-json.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 tools/list-backlog-json.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 tools/list-backlog-json.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