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.

REQUIRED: ticket format gate

Before creating ANY ticket, apply the /catalyst-dev:gherkin-ticket standard. Every ticket must open with a scannable use-case — an outcome-first title (<actor> should <outcome> [so that <benefit>], no internal-mechanism jargon, no [Component] prefix) and a body that leads with a plain-English use case followed by tiered Gherkin (Given/When/Then) acceptance criteria. This is a hard gate: do not draft a title or description without first consulting that skill. Component goes in a Linear label, not the title.

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 linearis"
    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 .catalyst/config.json:

CONFIG_FILE=".catalyst/config.json"
[[ ! -f "$CONFIG_FILE" ]] && CONFIG_FILE=".claude/config.json"

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

# Read team UUID — required for issues create and issues search (keys don't work)
# Use `linearis teams usage` to discover UUIDs — see /catalyst-dev:linearis
TEAM_UUID=$(jq -r '.catalyst.linear.teamUuid // empty' "$CONFIG_FILE")
if [ -z "$TEAM_UUID" ]; then
  echo "WARNING: Could not resolve team UUID for $TEAM_KEY. issues create/search may target wrong team."
  echo "Add teamUuid to .catalyst/config.json — see /catalyst-dev:linearis for lookup commands"
fi

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

Configuration in .catalyst/config.json:

{
  "catalyst": {
    "linear": {
      "teamKey": "ENG",
      "teamUuid": "<team-uuid>"
    }
  }
}

To find your team UUID, see /catalyst-dev:linearis for team discovery commands.

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

Catalyst maps workflow phases to your Linear workspace states via stateMap in .catalyst/config.json. Default mapping (matches standard Linear states):

Customization: Override any key to match your workspace. Set to null to skip that transition.

Note: These states must exist in your Linear workspace. The defaults match what Linear provides out of the box (plus "In Review" which is commonly added to the Started category).

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 using stateMap config:

• /research-codebase → Moves ticket to stateMap.research (default: "In Progress")
• /create-plan → Moves ticket to stateMap.planning (default: "In Progress")
• /implement-plan → Moves to stateMap.inProgress (default: "In Progress")
• /create-pr → Moves to stateMap.inReview (default: "In Review")
• /merge-pr → Moves to stateMap.done (default: "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 following the /catalyst-dev:gherkin-ticket standard. Present a draft to the user:

   ## Draft Linear Ticket
   
   **Title**: [outcome-first use-case sentence — <actor> should <outcome> [so that <benefit>];
   no mechanism/file/symbol names, no [Component] prefix]
   
   **Description**:
   [short plain-English use case — who benefits and why — so a reader who didn't write it gets oriented]
   
   [Gherkin acceptance criteria in a ```gherkin fenced block, at the right tier:
    A = features/bugs (full Given/When/Then), B = bugs (Then states correct behavior + # CURRENTLY:),
    C = pure chores (Context/Motivation/Outcome prose)]
   
   ## Technical notes
   - [implementation detail, technical decisions, constraints — preserved, but BELOW the use case]
   - [any specific requirements]
   
   ## 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:

   Use linearis issues usage for create syntax, or see /catalyst-dev:linearis.

   Important: --team only accepts UUIDs, not team keys/names (upstream bug: czottmann/linearis#56). Team keys silen