Linear - Ticket Management

You are tasked with managing Linear tickets, including creating tickets from thoughts documents, updating existing tickets, and following a structured workflow using the Linearis CLI.

Prerequisites Check

First, verify that Linearis CLI is installed and configured:

if ! command -v linearis &> /dev/null; then
    echo "❌ Linearis CLI not found"
    echo ""
    echo "Install with:"
    echo "  npm install -g --install-links ryanrozich/linearis#feat/cycles-cli"
    echo ""
    echo "Configure with:"
    echo "  export LINEAR_API_TOKEN=your_token"
    echo "  # or create ~/.linear_api_token file"
    exit 1
fi

Configuration

Read team configuration from .claude/config.json:

CONFIG_FILE=".claude/config.json"

# Read team key (e.g., "ENG", "PROJ")
TEAM_KEY=$(jq -r '.catalyst.linear.teamKey // "PROJ"' "$CONFIG_FILE")

# Read default team name (optional)
DEFAULT_TEAM=$(jq -r '.catalyst.linear.defaultTeam // null' "$CONFIG_FILE")

# Read thoughts repo URL
THOUGHTS_URL=$(jq -r '.catalyst.linear.thoughtsRepoUrl // "https://github.com/org/thoughts/blob/main"' "$CONFIG_FILE")

Configuration in .claude/config.json:

{
  "linear": {
    "teamKey": "ENG",
    "defaultTeam": "Backend",
    "thoughtsRepoUrl": "https://github.com/coalesce-labs/thoughts/blob/main"
  }
}

Initial Response

If tools are available, respond based on the user's request:

For general requests:

I can help you with Linear tickets. What would you like to do?
1. Create a new ticket from a thoughts document
2. Add a comment to a ticket (I'll use our conversation context)
3. Search for tickets
4. Update ticket status or details
5. Move ticket through workflow

Then wait for the user's input.

---

Workflow & Status Progression

This workflow ensures alignment through planning before implementation:

Workflow Statuses

1. Backlog → New ideas and feature requests
2. Triage → Initial review and prioritization
3. Spec Needed → Needs problem statement and solution outline
4. Research Needed → Requires investigation
5. Research in Progress → Active research underway
6. Ready for Plan → Research complete, needs implementation plan
7. Plan in Progress → Writing implementation plan
8. Plan in Review → Plan under discussion
9. Ready for Dev → Plan approved, ready to implement
10. In Dev → Active development
11. In Review → PR submitted
12. Done → Completed

Note: These statuses must be configured in your Linear workspace settings. The Linearis CLI will read and use whatever states exist in your workspace.

Key Principle

Review and alignment happen at the plan stage (not PR stage) to move faster and avoid rework.

Workflow Commands Integration

These commands automatically update ticket status:

• /catalyst-dev:create_plan → Moves ticket to "Plan in Progress"
• Plan completed → Moves to "Plan in Review"
• /catalyst-dev:implement_plan → Moves to "In Dev"
• /catalyst-dev:create_pr → Moves to "In Review"
• /catalyst-dev:merge_pr → Moves to "Done"

---

Important Conventions

URL Mapping for Thoughts Documents

When referencing thoughts documents, always provide GitHub links:

• thoughts/shared/... → {thoughtsRepoUrl}/repos/{project}/shared/...
• thoughts/{user}/... → {thoughtsRepoUrl}/repos/{project}/{user}/...
• thoughts/global/... → {thoughtsRepoUrl}/global/...

Default Values

• Status: Create new tickets in "Backlog" status
• Priority: Default to Medium (3) for most tasks
  • Urgent (1): Critical blockers, security issues
  • High (2): Important features with deadlines, major bugs
  • Medium (3): Standard implementation tasks (default)
  • Low (4): Nice-to-haves, minor improvements

---

Action-Specific Instructions

1. Creating Tickets from Thoughts

Steps to follow:

1. Locate and read the thoughts document:

   • If given a path, read the document directly
   • If given a topic/keyword, search thoughts/ directory using Grep
   • If multiple matches found, show list and ask user to select
   • Create a TodoWrite list to track: Read document → Analyze → Draft → Create

2. Analyze the document content:

   • Identify the core problem or feature being discussed
   • Extract key implementation details or technical decisions
   • Note any specific code files or areas mentioned
   • Look for action items or next steps
   • Identify what stage the idea is at (early ideation vs ready to implement)

3. Check for related context (if mentioned in doc):

   • If the document references specific code files, read relevant sections
   • If it mentions other thoughts documents, quickly check them
   • Look for any existing Linear tickets mentioned

4. Draft the ticket summary: Present a draft to the user:

   ## Draft Linear Ticket
   
   **Title**: [Clear, action-oriented title]
   
   **Description**:
   [2-3 sentence summary of the problem/goal]
   
   ## Key Details
   - [Bullet points of important details from thoughts]
   - [Technical decisions or constraints]
   - [Any specific requirements]
   
   ## Implementation Notes (if applicable)
   [Any specific technical approach or steps outlined]
   
   ## References
   - Source: `thoughts/[path]` ([View on GitHub](converted URL))
   - Related code: [any file:line references]
   
   ---
   Based on the document, this seems to be at the stage of: [ideation/planning/ready to implement]
   

5. Interactive refinement: Ask the user:

   • Does this summary capture the ticket accurately?
   • What priority? (Default: Medium/3)
   • Any additional context to add?
   • Should we include more/less implementation detail?
   • Do you want to assign it to yourself?

   Note: Ticket will be created in "Backlog" status by default.

6. Create the Linear ticket using Linearis CLI:

   # Create issue with linearis
   linearis issues create \
     --team "$TEAM_KEY" \
     --title "[refined title]" \
     --description "[final description in markdown]" \
     --priority [1-4] \
     --status "Backlog"
   
   # Capture the created issue ID from output
   ISSUE_ID=$(linearis issues create ... | jq -r '.id')
   

   Note: Linearis creates issues in the team's default backlog state. To set specific status or assignee, create first then update:

   # Assign to self
   linearis issues update "$ISSUE_ID" --assignee "@me"
   

7. Post-creation actions:

   • Show the created ticket URL
   • Ask if user wants to:
     • Add a comment with additional implementation details
     • Update the original thoughts document with the ticket reference
   • If yes to updating thoughts doc:

     Add at the top of the document:
     ---
     linear_ticket: [TEAM-123]
     created: [date]
     ---
     

2. Adding Comments to Existing Tickets

When user wants to add a comment to a ticket:

1. Determine which ticket:

   • Use context from the current conversation to identify the relevant ticket
   • If uncertain, use linearis issues read TEAM-123 to show ticket details and confirm

2. Format comments for clarity:

   • Keep concise (~10 lines) unless more detail needed
   • Focus on key insights or most useful information
   • Include relevant file references with backticks and GitHub links

3. File reference formatting:

   • Wrap paths in backticks: thoughts/user/example.md
   • Add GitHub link after: ([View](url))
   • Do this for both thoughts/ and code files

4. Comment structure example:

   Implemented retry logic in webhook handler to address rate limit issues.
   
   Key insight: The 429 responses were clustered during batch operations, so exponential backoff
   alone wasn't sufficient - added request queuing.
   
   Files updated:
   
   - `src/webhooks/handler.ts` ([GitHub](link))
   - `thoughts/shared/rate_limit_analysis.md` ([GitHub](link))
   

5. Add comment with Linearis:

   linearis comments create TEAM-123 --body "Your comment text here"
   

3. Moving Tickets Through Workflow

When moving tickets to a new status:

1. Get current status:

   linearis issues read TEAM-123 | jq -r '.state.name'
   

2. Suggest next status based on workflow:

   Backlog → Triage (for initial review)
   Triage → Spec Needed (needs more detail) OR Research Needed (needs investigation)
   Spec Needed → Research Needed (once problem outlined)
   Research Needed → Research in Progress (starting research)
   Research in Progress → Ready for Plan (research complete)
   Ready for Plan → Plan in Progress (starting plan with /catalyst-dev:create_plan)
   Plan in Progress → Plan in Review (plan complete)
   Plan in Review → Ready for Dev (plan approved)
   Ready for Dev → In Dev (starting work with /catalyst-dev:implement_plan)
   In Dev → In Review (PR created)
   In Review → Done (PR merged)
   

3. Automatic status updates: When certain commands are run, automatically update ticket status:

   • /catalyst-dev:create_plan with ticket → Move to "Plan in Progress"
   • Plan synced and linked → Move to "Plan in Review"
   • /catalyst-dev:implement_plan with ticket → Move to "In Dev"
   • /catalyst-dev:create_pr with ticket → Move to "In Review"
   • /catalyst-dev:merge_pr with ticket → Move to "Done"

4. Manual status updates:

   linearis issues update TEAM-123 --state "In Progress"
   

5. Add comment explaining the transition:

   linearis comments create TEAM-123 --body "Moving to In Progress: Starting implementation"
   

4. Searching for Tickets

When user wants to find tickets:

1. Gather search criteria:

   • Query text
   • Status filters
   • Assignee filters

2. Execute search:

   # List all issues (linearis issues list only supports --limit, not --team)
   linearis issues list --limit 100
   
   # Filter by team using jq
   linearis issues list --limit 100 | jq '.[] | select(.team.key == "TEAM")'
   
   # Filter by status using jq
   linearis issues list --limit 100 | jq '.[] | select(.state.name == "In Progress")'
   
   # Filter by assignee using jq
   linearis issues list --limit 100 | jq '.[] | select(.assignee.email == "user@example.com")'
   
   # Search by text (filter JSON output with jq)
   linearis issues list --limit 100 | \
     jq '.[] | select(.title | contains("search term"))'
   

3. Present results:

   • Show ticket ID, title, status, assignee
   • Include direct links to Linear
   • Parse JSON output for display

---

Integration with Other Commands

Automatic Ticket Updates

When these commands are run, check if there's a related Linear ticket and update it:

During /catalyst-dev:create_plan:

1. If ticket mentioned, move to "Plan in Progress"
2. When plan complete, add comment with plan link
3. Move to "Plan in Review"

During /catalyst-dev:implement_plan:

1. If ticket in plan metadata, move to "In Dev"
2. Add comment: "Started implementation from plan: [link]"

During /catalyst-dev:create_pr:

1. If ticket mentioned in PR or plan, move to "In Review"
2. Add comment with PR link

During /catalyst-dev:merge_pr:

1. Move ticket to "Done"
2. Add comment with merge details

---

Example Workflows

Workflow 1: Thought → Ticket → Plan → Implement

# 1. Research and document
/catalyst-dev:research_codebase "authentication patterns"
# Saves to thoughts/shared/research/auth-patterns.md

# 2. Create ticket from research
/catalyst-dev:linear create thoughts/shared/research/auth-patterns.md
# Creates ticket in Backlog

# 3. Create plan
/catalyst-dev:create_plan
# Reads research, creates plan
# Ticket moves to "Plan in Progress" → "Plan in Review"

# 4. Implement
/catalyst-dev:implement_plan thoughts/shared/plans/2025-01-08-auth-feature.md
# Ticket moves to "In Dev"

# 5. Create PR
/catalyst-dev:create_pr
# Ticket moves to "In Review"

# 6. Merge PR
/catalyst-dev:merge_pr
# Ticket moves to "Done"

Workflow 2: Quick Ticket Updates

# Add progress comment
linearis comments create PROJ-123 --body "Completed phase 1, moving to phase 2"

# Move ticket forward
linearis issues update PROJ-123 --state "In Dev"

# Search for related tickets
linearis issues list --team PROJ | jq '.[] | select(.title | contains("authentication"))'

---

Linearis CLI Reference

Common Commands

# List issues (only --limit supported, use jq for filtering)
linearis issues list --limit 50

# Filter by status using jq
linearis issues list --limit 100 | jq '.[] | select(.state.name == "In Progress")'

# Read specific issue
linearis issues read TICKET-123

# Create issue
linearis issues create "Title" --description "Description" --state "Todo"

# Update issue state
linearis issues update TICKET-123 --state "In Progress"

# Update assignee
linearis issues update TICKET-123 --assignee <user-id>

# Add comment
linearis comments create TICKET-123 --body "Comment text"

# List cycles
linearis cycles list --team TEAM [--active]

# Read cycle
linearis cycles read "Sprint 2025-10" --team TEAM

JSON Output Parsing

Linearis returns JSON, parse with jq:

# Get ticket status
linearis issues read TEAM-123 | jq -r '.state.name'

# Get ticket title
linearis issues read TEAM-123 | jq -r '.title'

# Get assignee
linearis issues read TEAM-123 | jq -r '.assignee.name'

# Filter list by keyword
linearis issues list --team TEAM | jq '.[] | select(.title | contains("bug"))'

---

Notes

• Configuration: Use .claude/config.json for team settings
• Status mapping: Use status names that exist in your Linear workspace
• Automation: Workflow commands auto-update tickets when ticket IDs are referenced
• CLI required: Linearis CLI must be installed and configured with LINEAR_API_TOKEN

This command integrates seamlessly with the create_plan → implement_plan → validate_plan workflow while keeping Linear tickets in sync!