Maelstrom CLI Skill

This skill provides CLI commands for managing Linear tasks, querying Sentry issues, and handling git/GitHub workflows directly from Claude Code.

Core Workflows

Task-Based Development (with Linear)

For tasks that need planning first:

1. •/plan-task PROJ-XXX - Research and create implementation plan (plan mode required)
2. •/continue-task PROJ-XXX - Read plan from Linear and implement

For large tasks that need subtask breakdown:

1. •/create-subtasks PROJ-XXX - Research and break down into subtasks (plan mode required)
2. •/continue-task - Pick up the first subtask and start implementation

For standard tasks:

Code Review Before PR

Use /review-branch to review your changes before creating a PR:

Git-Only Workflow (without Linear)

For quick changes without task tracking:

Quick Reference: Common Commands

Prerequisites

GitHub CLI

Install and authenticate the GitHub CLI (gh) for git/GitHub commands:

brew install gh
gh auth login

Environment Variables

Set these in your project's .env file:

• •LINEAR_API_KEY - Linear API key (required for Linear commands)
• •SENTRY_API_KEY - Sentry auth token with event:read scope (required for Sentry commands)

Configuration

Add integration settings to your project's .maelstrom.yaml:

# Linear integration
linear_team_id: "your-team-uuid-here"
linear_workspace_labels:  # Optional: custom labels for worktrees
  - alpha
  - bravo
  - charlie

# Sentry integration
sentry_org: "your-org-slug"
sentry_project: "your-project-id"

Linear Commands

mael linear list-tasks

List tasks in the current cycle.

mael linear list-tasks [--status STATUS]

Options:

• •--status: Filter by status name (partial match, case-insensitive)

Examples:

# List all tasks in current cycle
mael linear list-tasks

# List only in-progress tasks
mael linear list-tasks --status "In Progress"

mael linear read-task

Read task details as markdown, including subtasks and Sentry issues.

mael linear read-task <issue-id>

Arguments:

• •issue-id: Linear issue identifier (e.g., PROJ-123)

Output includes:

• •Title, status, parent (if subtask), cycle, labels
• •Full description
• •List of subtasks with completion status
• •Comments
• •Attachments (Sentry links automatically fetch issue details)

mael linear start-task

Start working on a task. Sets status to "In Progress" and adds worktree label.

mael linear start-task <issue-id>

Behavior:

• •Sets task status to "In Progress"
• •Detects worktree from current directory (alpha, bravo, etc.)
• •Adds worktree name as label, removes other worktree labels
• •If task is a subtask, also updates parent task with same status/label

mael linear complete-task

Mark a task as complete.

mael linear complete-task <issue-id>

Behavior:

• •Subtasks: Set status to "Done"
• •Parent/standalone tasks: Set status to "Unreleased"
• •If completing a subtask and all siblings are complete, parent is set to "Unreleased"

mael linear create-subtask

Create a subtask on a parent issue.

mael linear create-subtask <parent-id> <title> [description]

Arguments:

• •parent-id: Parent issue identifier (e.g., PROJ-123)
• •title: Subtask title
• •description: Optional subtask description

Behavior:

• •Creates subtask linked to parent
• •Inherits cycle from parent issue

mael linear write-plan

Write an implementation plan to a Linear task's description.

mael linear write-plan <issue-id> <plan-file>

Arguments:

• •issue-id: Linear issue identifier (e.g., PROJ-123)
• •plan-file: Path to the markdown plan file

Behavior:

• •Reads plan file content and stores it in the issue description between markers
• •Replaces any existing plan (idempotent for re-planning)
• •Updates status from "Todo" to "Planned" if applicable

mael linear read-plan

Read the implementation plan from a Linear task's description.

mael linear read-plan <issue-id>

Arguments:

• •issue-id: Linear issue identifier (e.g., PROJ-123)

Behavior:

• •Extracts plan content from between markers in the issue description
• •Outputs the plan markdown to stdout
• •Fails with helpful error if no plan is found

Git & GitHub Commands

mael sync

Rebase the current worktree against origin/main. Run this before starting work.

mael sync [target]

Arguments:

• •target (optional): Project/worktree identifier (uses current directory if omitted)

Behavior:

• •Fetches latest from remote (git fetch origin)
• •Rebases current branch against origin/main using --autostash
• •On conflicts: displays helpful instructions with commands to resolve

mael gh create-pr

Create a new pull request or push updates to an existing one.

mael gh create-pr [target] [--draft]

Arguments:

• •target (optional): Project/worktree identifier

Options:

• •--draft: Create PR as a draft (only for new PRs)

Behavior:

• •Fetches from origin to update tracking refs
• •Force-pushes current branch to origin (--force-with-lease -u)
• •If no PR exists: creates one using first commit message as title
• •If PR exists: just pushes the latest changes
• •Returns the PR URL

mael gh read-pr

Check PR status, review comments, and CI results.

mael gh read-pr [target]

Arguments:

• •target (optional): Project/worktree identifier

Output includes:

• •PR number, title, URL, and merge status
• •Unresolved review comments (file, line, author, preview)
• •CI check status grouped by: Failed, Pending, Passing
• •For failed checks: truncated logs and available artifacts

mael gh check-log

View full GitHub Actions logs for a workflow run.

mael gh check-log <run_id> [--failed-only]

Arguments:

• •run_id: GitHub Actions workflow run ID

Options:

• •--failed-only: Show only failed step logs

mael gh download-artifact

Download artifacts from a workflow run.

mael gh download-artifact <run_id> <artifact_name> [-o OUTPUT_DIR]

Arguments:

• •run_id: GitHub Actions run ID
• •artifact_name: Name of artifact to download

Options:

• •-o, --output: Output directory (defaults to current directory)

mael gh show-code

Show committed and/or uncommitted changes in the worktree.

mael gh show-code [target] [--committed] [--uncommitted]

Arguments:

• •target (optional): Project/worktree identifier

Options:

• •--committed: Show only commits since branching from main
• •--uncommitted: Show only working directory changes
• •Default (no flags): Show both

Output includes:

• •Commits since diverging from origin/main with full diffs
• •Working directory diff (git diff HEAD)

Sentry Commands

mael sentry list-issues

List unresolved issues for the project.

mael sentry list-issues [--env ENV]

Options:

• •--env: Environment filter (default: prod)

Output includes:

• •Short ID (e.g., PROJ-ABC)
• •Title
• •Last seen (relative time)
• •Count: Total events (all time)
• •Trend: Change in events over last 12h vs previous 12h

mael sentry get-issue

Get issue details as markdown.

mael sentry get-issue <issue-id>

Arguments:

• •issue-id: Sentry issue ID (numeric)

Output includes:

• •Exception type and message
• •Event metadata (ID, project, date)
• •Tags
• •Full stacktrace with code context and variable values

Status Transitions

Status Flow

• •Todo -> Planned (when plan is written via write-plan)
• •Planned / Todo -> In Progress (when start-task is called)
• •In Progress -> In Review (when submit-pr is called)
• •In Review -> Done / Unreleased (when completed)

Subtasks (issues with a parent)

• •Starting work: Set to "In Progress"
• •Completing work: Set to "Done"

Parent Tasks (issues with subtasks)

• •Starting work: Set to "In Progress" (when first subtask starts)
• •Completing work: Set to "Unreleased" only when ALL subtasks are Done/Canceled

Standalone Tasks (no parent, no subtasks)

• •Starting work: Set to "In Progress"
• •Completing work: Set to "Unreleased"

Workflow: Git & Pull Requests

1. •

   Before starting work, sync with main:

   bash

   mael sync
   

2. •

   During work, commit changes regularly (see "Workflow: Creating Commits" below)

3. •

   When ready for review, create or update PR:

   bash

   mael gh create-pr
   

Workflow: Checking PR Status

1. •

   Check if PR was merged or has issues:

   bash

   mael gh read-pr
   

   This shows: merge status, unresolved comments, and CI check results.

2. •

   For failed CI checks, view full logs:

   bash

   mael gh check-log <run_id>
   

3. •

   Download artifacts (test results, screenshots, etc.):

   bash

   mael gh download-artifact <run_id> <artifact_name>
   

Workflow: Code Review (Before Creating PR)

Use the /review-branch command to review your feature branch before creating a PR. This command requires plan mode and produces review findings as the implementation plan.

1. •

   Enter plan mode and run the review:

   code

   /review-branch
   

   (Requires plan mode - the review findings become your plan)

2. •

   Review the findings and approve the plan

3. •

   Fix issues, committing each fix with:

   bash

   git add <fixed-files>
   git commit --fixup=<original-sha>
   

4. •

   Squash fixup commits into originals:

   bash

   mael review squash
   

5. •

   Create PR after all fixes:

   bash

   mael gh create-pr
   

Review CLI Commands

mael review squash

Squash all fixup! commits into their target commits using git's autosquash.

mael review squash

Behavior:

• •Finds all commits starting with "fixup! "
• •Runs non-interactive rebase with --autosquash
• •Combines fixup commits with their targets
• •Aborts on conflicts (manual resolution required)

mael review status

Show pending fixup commits that haven't been squashed.

mael review status

Viewing Code Changes

Use these commands to inspect changes in your worktree:

1. •

   Review all changes (committed + uncommitted):

   bash

   mael gh show-code
   

2. •

   Review only committed changes (since branching from main):

   bash

   mael gh show-code --committed
   

3. •

   Review only uncommitted changes (working directory):

   bash

   mael gh show-code --uncommitted
   

Workflow: Creating Commits

Git commands run directly in the worktree directory (no -C flag needed).

Commit Message Format

Do not use heredocs (<<EOF or <<'EOF') for git commit messages — they fail in sandboxed environments because heredocs create temp files in /tmp which is not writable.

Use printf piped to git commit -F - instead:

git add file1.py file2.py
printf 'feat: add new feature\n\nDetailed description of the change.\n' | git commit -F -

Commit Flow

1. •

   Review uncommitted changes before committing:

   bash

   mael gh show-code --uncommitted
   

2. •

   Stage and commit with a descriptive message:

   bash

   git add <files>
   printf 'Description of changes\n' | git commit -F -
   

3. •

   For atomic commits, stage related changes together. Use git add -p for partial file staging if needed.

Workflow: Planning a Task

1. •

   Get issue details:

   bash

   mael linear read-task PROJ-123
   

2. •

   Research codebase: Explore relevant code to understand context

3. •

   Write implementation plan (stored in issue description):

   bash

   mael linear write-plan PROJ-123 plan.md
   

4. •

   For complex tasks, create subtasks for each phase:

   bash

   mael linear create-subtask PROJ-123 "Phase 1: Core functionality" "Description here"
   

Workflow: Working on a Task

1. •

   Find next task:

   bash

   mael linear list-tasks --status "In Progress"
   # or
   mael linear read-task PROJ-123
   

2. •

   Start the task (marks In Progress, adds worktree label):

   bash

   mael linear start-task PROJ-124
   

3. •

   Do the implementation work

4. •

   Complete the task:

   bash

   mael linear complete-task PROJ-124
   

Workflow: Debugging Production Errors

1. •

   List unresolved issues:

   bash

   mael sentry list-issues
   

2. •

   Prioritize by: escalating trend > recency > frequency

3. •

   Get issue details:

   bash

   mael sentry get-issue 12345678
   

4. •

   Investigate the stacktrace and fix the issue

Error Handling

Commands exit with code 1 and display error messages for:

• •Missing environment variables (LINEAR_API_KEY, SENTRY_API_KEY)
• •Missing configuration (linear_team_id, sentry_org, sentry_project)
• •Issue not found
• •API errors
• •Missing workflow states ("Planned", "In Progress", "Done", "Unreleased")