Skip to content

wrsmith108/linear-claude-skill

Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.

FileKindSize
SKILL.mdskill md22.7 KB
scripts/__tests__/bulk-create.test.tsscript5.0 KB
scripts/__tests__/issue-description.test.tsscript6.8 KB
scripts/__tests__/lin-cli.test.tsscript3.8 KB
scripts/__tests__/lint-issues.test.tsscript2.3 KB
scripts/__tests__/retry.test.tsscript8.2 KB
scripts/__tests__/smoke.test.tsscript7.0 KB
scripts/__tests__/validate-description.test.tsscript4.3 KB
scripts/build.mjsscript1.4 KB
scripts/bulk-create.tsscript12.5 KB
scripts/create-initiative-update.tsscript5.8 KB
scripts/create-issue-with-project.tsscript8.0 KB
scripts/create-project-update.tsscript5.5 KB
scripts/extract-image.tsscript2.2 KB
scripts/lib/agent-selection.tsscript8.7 KB
scripts/lib/exit-codes.tsscript357 B
scripts/lib/index.tsscript3.1 KB
scripts/lib/initiative.tsscript5.0 KB
scripts/lib/issue-description.tsscript7.1 KB
scripts/lib/labels.tsscript7.6 KB
scripts/lib/lin-cli.tsscript7.3 KB
scripts/lib/linear-utils.tsscript9.3 KB
scripts/lib/project-template.tsscript8.8 KB
scripts/lib/retry.tsscript4.8 KB
scripts/lib/taxonomy-data.tsscript8.1 KB
scripts/lib/taxonomy-validation.tsscript10.0 KB
scripts/lib/taxonomy.tsscript3.6 KB
scripts/lib/verify.tsscript6.6 KB
scripts/linear-api.mjsexecutablescript12.1 KB
scripts/linear-ops.tsscript69.1 KB
scripts/lint-issues.tsscript6.9 KB
scripts/phase-complete.tsscript12.4 KB
scripts/query.shexecutablescript498 B
scripts/query.tsscript3.5 KB
scripts/run.shexecutablescript321 B
scripts/setup.tsscript8.6 KB
scripts/sync-skill-version.mjsscript2.0 KB
scripts/sync.tsscript5.7 KB
scripts/upload-image.tsscript4.4 KB

scripts/linear-ops.ts

View on GitHub
#!/usr/bin/env npx tsx
/**
 * Linear High-Level Operations
 *
 * Simple commands for common Linear operations without needing to understand the API.
 *
 * Usage:
 *   npx tsx linear-ops.ts <command> [args]
 *
 * Commands:
 *   create-issue <project> <title> [desc]    Create an issue in a project
 *   create-sub-issue <parent> <title> [desc] Create a sub-issue under a parent issue
 *   set-parent <parent> <child-issues...>    Set parent-child relationships
 *   list-sub-issues <parent>                 List sub-issues of a parent
 *   create-initiative <name> [description]   Create a new initiative
 *   create-project <name> [initiative]       Create a project (optionally linked to initiative)
 *   create-project-update <project> <body>   Create a project update
 *   create-initiative-update <init> <body>   Create an initiative update
 *   add-link <project|initiative> <url> <label>  Add external link to project or initiative
 *   status <state> <issue-numbers...>        Update issue status (Done, In Progress, etc.)
 *   update-issue <issue-id> <field> <value>  Update issue title or description
 *   list-initiatives                         List all initiatives
 *   list-projects [initiative]               List projects (optionally filter by initiative)
 *   setup                                    Check setup and configuration
 *   whoami                                   Show current user and organization
 *   search <query>                           Search issues across workspace
 *   list-issues [--team X] [--state Y]       List issues with optional filters
 */

// Defined at build time by esbuild (see scripts/build.mjs)
declare const __BUNDLED__: boolean | undefined;

import {
  LinearClient,
  ProjectUpdateHealthType,
  InitiativeUpdateHealthType,
  type Issue
} from '@linear/sdk';
import { EXIT_CODES } from './lib/exit-codes.js';
import {
  getAllLabels,
  getLabelsByCategory,
  validateLabels,
  suggestLabels,
  selectAgentsForIssue,
  formatValidationResult,
  formatSuggestions,
  formatAgentSelection,
  formatAgentMatrix,
  getLinearClient,
  tryLin,
  isLinCliAvailable,
  linUpdateIssueState,
  validateIssueDescription,
  buildIssueTemplate,
  formatDescriptionValidationResult,
  formatWarningsOnly,
  isStrictMode
} from './lib';

// lin >=2026.x wraps `--json` output in container objects (e.g. { issues: [...] } or
// { initiatives: { nodes: [...] } }); older lin returned flatter shapes (bare arrays / flat
// objects). These helpers unwrap either, and stay null-safe if `lin` ever emits a bare `null`.
function unwrapLinList(data: unknown, key: string): unknown[] {
  if (Array.isArray(data)) return data;
  const wrapped = (data as Record<string, unknown> | null)?.[key];
  if (Array.isArray(wrapped)) return wrapped;
  const nested = (wrapped as Record<string, unknown> | undefined)?.nodes;
  return Array.isArray(nested) ? nested : [];
}

function unwrapLinObject(data: unknown, key: string): Record<string, unknown> {
  const root = (data as Record<string, unknown> | null) ?? {};
  const wrapped = root[key];
  return typeof wrapped === 'object' && wrapped !== null ? (wrapped as Record<string, unknown>) : root;
}

// Lazy API key validation and client creation
// Commands that don't need the API (help, labels taxonomy/validate/suggest/agents/matrix)
// can run without LINEAR_API_KEY being set.
function requireApiKey(): string {
  const key = process.env.LINEAR_API_KEY;
  if (!key) {
    console.error('\n[ERROR] LINEAR_API_KEY environment variable is required\n');
    console.error('To fix this:');
    console.error('  1. Go to Linear -> Settings -> Security & access -> Personal API keys');
    console.error('  2. Create a new API key');
    console.error('  3. Run: export LINEAR_API_KEY="lin_api_..."');
    console.error('\nOr run setup to check all requirements:');
    console.error('  npx tsx setup.ts\n');
    process.exit(1);
  }
  return key;
}

function requireClient(): LinearClient {
  try {
    return getLinearClient();
  } catch {
    // Provide the friendly error message with setup instructions
    console.error('\n[ERROR] LINEAR_API_KEY environment variable is required\n');
    console.error('To fix this:');
    console.error('  1. Go to Linear -> Settings -> Security & access -> Personal API keys');
    console.error('  2. Create a new API key');
    console.error('  3. Run: export LINEAR_API_KEY="lin_api_..."');
    console.error('\nOr run setup to check all requirements:');
    console.error('  npx tsx setup.ts\n');
    process.exit(1);
  }
}

type UpdateIssueField = 'title' | 'description';

interface ParsedUpdateIssueValue {
  value: string;
  force: boolean;
  strictFlag?: boolean;
}

const ISSUE_IDENTIFIER_RE = /^([A-Z][A-Z0-9]*)-(\d+)$/i;
const ISSUE_NUMBER_RE = /^\d+$/;

function usageUpdateIssue(): void {
  console.error('Usage: update-issue <issue-id> <field> <value> [--force] [--strict=false]');
  console.error('       update-issue <issue-id> description --file <path> --force');
  console.error('       update-issue <issue-id> description --stdin --force');
  console.error('Fields: title, description');
  console.error('Example: update-issue ENG-123 description "New description text" --force');
  console.error('Example: update-issue ENG-123 title "Corrected title" --force');
}

function previewText(value: string | null | undefined, max = 500): string {
  const text = value?.trim() || '(empty)';
  return text.length <= max ? text : `${text.slice(0, max)}...`;
}

async function readStdinUtf8(): Promise<string> {
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk as Buffer);
  }
  return Buffer.concat(chunks).toString('utf8');
}

async function parseUpdateIssueValue(
  field: UpdateIssueField,
  valueParts: string[]
): Promise<ParsedUpdateIssueValue> {
  let force = false;
  let strictFlag: boolean | undefined;
  let filePath: string | undefined;
  let readStdin = false;
  const valueTokens: string[] = [];

  for (let i = 0; i < valueParts.length; i++) {
    const part = valueParts[i];
    if (part === '--force') {
      force = true;
    } else if (part === '--strict=false') {
      strictFlag = false;
    } else if (part === '--strict=true') {
      strictFlag = true;
    } else if (part === '--file') {
      if (!valueParts[i + 1]) {
        console.error('[ERROR] --file requires a path');
        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
      }
      filePath = valueParts[i + 1];
      i++;
    } else if (part === '--stdin') {
      readStdin = true;
    } else if (part.startsWith('--')) {
      console.error(`[ERROR] Unknown flag: ${part}`);
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    } else {
      valueTokens.push(part);
    }
  }

  if ((filePath || readStdin) && field !== 'description') {
    console.error('[ERROR] --file and --stdin are only supported for description updates');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }
  if (filePath && readStdin) {
    console.error('[ERROR] Use either --file or --stdin, not both');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }
  if ((filePath || readStdin) && valueTokens.length > 0) {
    console.error('[ERROR] Provide the description either positionally, with --file, or with --stdin');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }

  let value: string;
  if (filePath) {
    const { readFileSync } = await import('node:fs');
    try {
      value = readFileSync(filePath, 'utf8');
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);
      console.error(`[ERROR] Cannot read file "${filePath}": ${msg}`);
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    }
  } else if (readStdin) {
    value = await readStdinUtf8();
  } else {
    value = valueTokens.join(' ');
  }

  if (value.length === 0) {
    console.error('[ERROR] Update value is required');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }

  return { value, force, strictFlag };
}

async function resolveIssueForUpdate(
  client: LinearClient,
  issueIdentifier: string
): Promise<Issue> {
  const trimmed = issueIdentifier.trim();
  const fullIdentifier = trimmed.match(ISSUE_IDENTIFIER_RE);

  if (fullIdentifier) {
    const normalized = `${fullIdentifier[1].toUpperCase()}-${parseInt(fullIdentifier[2], 10)}`;
    try {
      return await client.issue(normalized);
    } catch {
      console.error(`[ERROR] Issue ${normalized} not found`);
      process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
    }
  }

  if (!ISSUE_NUMBER_RE.test(trimmed)) {
    console.error(`[ERROR] "${issueIdentifier}" is not a valid issue identifier`);
    console.error('Use a full identifier like ENG-123, or a bare number like 123 in single-team workspaces.');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }

  const issueNum = parseInt(trimmed, 10);
  const issues = await client.issues({ first: 25, filter: { number: { eq: issueNum } } });

  if (issues.nodes.length === 0) {
    console.error(`[ERROR] Issue #${issueNum} not found`);
    console.error('If your workspace has multiple teams, pass the full identifier, e.g. ENG-123.');
    process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
  }

  if (issues.nodes.length > 1) {
    const candidates = issues.nodes.map(issue => issue.identifier).join(', ');
    console.error(`[ERROR] Multiple issues match #${issueNum}: ${candidates}`);
    console.error('Pass the full identifier, e.g. ENG-123.');
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }

  return issues.nodes[0];
}

async function confirmIssueUpdate(
  issue: Issue,
  field: UpdateIssueField,
  value: string
): Promise<void> {
  console.log(`Current ${field} on ${issue.identifier}:`);
  console.log(previewText(field === 'title' ? issue.title : issue.description));
  console.log('');
  console.log(`New ${field}:`);
  console.log(previewText(value));
  console.log('');

  const { createInterface } = await import('node:readline/promises');
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  try {
    const answer = await rl.question(`Replace ${field} on ${issue.identifier}? [y/N] `);
    if (!/^y(es)?$/i.test(answer.trim())) {
      console.error('[ERROR] Update cancelled');
      process.exit(EXIT_CODES.PERMISSION_DENIED);
    }
  } finally {
    rl.close();
  }
}

// Command implementations
const commands: Record<string, (...args: string[]) => Promise<void>> = {

  async 'create-issue'(projectName: string, title: string, description?: string, ...flags: string[]) {
    // --template short-circuit: no project/title required, just print template and exit
    const allArgs = [projectName, title, description, ...flags].filter((a): a is string => typeof a === 'string');
    if (allArgs.includes('--template')) {
      process.stdout.write(buildIssueTemplate(title && title !== '--template' ? title : undefined));
      return;
    }

    if (!projectName || !title) {
      console.error('Usage: create-issue <project-name> <title> [description] [--priority 1-4] [--labels label1,label2] [--strict=false]');
      console.error('Example: create-issue "My Project" "Fix login bug" "Users cannot log in..."');
      console.error('\nPriority: 1=urgent, 2=high, 3=medium, 4=low (default: 3)');
      console.error('Print template: create-issue --template');
      process.exit(1);
    }

    // Parse flags
    let priority = 3;
    let labelNames: string[] = [];
    let strictFlag: boolean | undefined;

    for (let i = 0; i < flags.length; i++) {
      if (flags[i] === '--priority' && flags[i + 1]) {
        priority = parseInt(flags[i + 1], 10);
        i++;
      } else if (flags[i] === '--labels' && flags[i + 1]) {
        labelNames = flags[i + 1].split(',').map(l => l.trim());
        i++;
      } else if (flags[i] === '--strict=false') {
        strictFlag = false;
      } else if (flags[i] === '--strict=true') {
        strictFlag = true;
      }
    }

    // Validate description BEFORE any API work (runs before tryLin too, so the
    // lin-CLI fast-path is also gated).
    const descResult = validateIssueDescription(description ?? '');
    if (!descResult.valid || descResult.warnings.length > 0) {
      const strict = isStrictMode(strictFlag);
      const output = formatDescriptionValidationResult(descResult);
      if (!descResult.valid && strict) {
        console.error(output);
        process.exit(EXIT_CODES.VALIDATION_ERROR);
      } else if (!descResult.valid) {
        console.warn('[WARN] Description validation downgraded (strict mode off):');
        console.warn(output);
      } else if (descResult.warnings.length > 0) {
        console.warn(formatWarningsOnly(descResult));
      }
    }

    console.log(`Creating issue in project: ${projectName}...`);

    // Find project by name
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: projectName } }
    });

    if (projects.nodes.length === 0) {
      console.error(`[ERROR] Project "${projectName}" not found`);
      process.exit(1);
    }

    const project = projects.nodes[0];
    console.log(`  Found project: ${project.name}`);

    // Get team from project
    const teams = await requireClient().teams();
    if (teams.nodes.length === 0) {
      console.error('[ERROR] No teams found in your workspace');
      process.exit(1);
    }
    const team = teams.nodes[0];
    console.log(`  Using team: ${team.name}`);

    // Resolve label names to IDs if provided
    const labelIds: string[] = [];
    if (labelNames.length > 0) {
      const labels = await team.labels();
      for (const name of labelNames) {
        const label = labels.nodes.find(l =>
          l.name.toLowerCase() === name.toLowerCase()
        );
        if (label) {
          labelIds.push(label.id);
          console.log(`  Found label: ${label.name}`);
        } else {
          console.log(`  [WARNING] Label "${name}" not found, skipping`);
        }
      }
    }

    const result = await requireClient().createIssue({
      teamId: team.id,
      projectId: project.id,
      title,
      description: description || '',
      priority,
      ...(labelIds.length > 0 && { labelIds })
    });

    const issue = await result.issue;
    if (issue) {
      console.log('\n[SUCCESS] Issue created!');
      console.log(`  ID:       ${issue.identifier}`);
      console.log(`  Title:    ${issue.title}`);
      console.log(`  Priority: ${priority}`);
      console.log(`  Project:  ${project.name}`);
      console.log(`  URL:      ${issue.url}`);
    } else {
      console.error('[ERROR] Failed to create issue');
      process.exit(1);
    }
  },

  async 'create-initiative'(name: string, description?: string) {
    if (!name) {
      console.error('Usage: create-initiative <name> [description]');
      console.error('Example: create-initiative "Q1 2025 Goals" "Key initiatives for Q1"');
      process.exit(1);
    }

    console.log(`Creating initiative: ${name}...`);

    const me = await requireClient().viewer;
    const result = await requireClient().createInitiative({
      name,
      description: description || `Initiative: ${name}`,
      ownerId: me.id
    });

    const initiative = await result.initiative;
    if (initiative) {
      // Get the URL by querying the initiative
      const initiatives = await requireClient().initiatives({ filter: { id: { eq: initiative.id } } });
      const url = initiatives.nodes[0]?.url || `https://linear.app/initiative/${initiative.id}`;

      console.log('\n[SUCCESS] Initiative created!');
      console.log(`  Name: ${initiative.name}`);
      console.log(`  ID:   ${initiative.id}`);
      console.log(`  URL:  ${url}`);
    } else {
      console.error('[ERROR] Failed to create initiative');
      process.exit(1);
    }
  },

  async 'create-project'(name: string, initiativeName?: string) {
    if (!name) {
      console.error('Usage: create-project <name> [initiative-name]');
      console.error('Example: create-project "Phase 1: Foundation" "Q1 2025 Goals"');
      process.exit(1);
    }

    console.log(`Creating project: ${name}...`);

    // Get first team (required for project)
    const teams = await requireClient().teams();
    if (teams.nodes.length === 0) {
      console.error('[ERROR] No teams found in your workspace');
      process.exit(1);
    }
    const team = teams.nodes[0];
    console.log(`  Using team: ${team.name}`);

    // Find initiative if specified
    let initiativeId: string | undefined;
    if (initiativeName) {
      const initiatives = await requireClient().initiatives({
        filter: { name: { containsIgnoreCase: initiativeName } }
      });

      if (initiatives.nodes.length === 0) {
        console.error(`[WARNING] Initiative "${initiativeName}" not found, creating unlinked project`);
      } else {
        initiativeId = initiatives.nodes[0].id;
        console.log(`  Linking to initiative: ${initiatives.nodes[0].name}`);
      }
    }

    const result = await requireClient().createProject({
      name,
      teamIds: [team.id],
      ...(initiativeId && { initiativeIds: [initiativeId] })
    });

    const project = await result.project;
    if (project) {
      console.log('\n[SUCCESS] Project created!');
      console.log(`  Name: ${project.name}`);
      console.log(`  ID:   ${project.id}`);
      console.log(`  URL:  ${project.url}`);
    } else {
      console.error('[ERROR] Failed to create project');
      process.exit(1);
    }
  },

  async 'project-status'(projectName: string, state: string) {
    if (!projectName || !state) {
      console.error('Usage: project-status <project-name> <state>');
      console.error('States: backlog, planned, in-progress, paused, completed, canceled');
      console.error('Example: project-status "Phase 8: MCP Decision Engine" completed');
      process.exit(1);
    }

    // Map user-friendly names to API values (Linear UI shows "In Progress" but API uses "started")
    const stateMap: Record<string, string> = {
      'backlog': 'backlog',
      'planned': 'planned',
      'in-progress': 'started',
      'inprogress': 'started',
      'started': 'started',  // Accept legacy value for backwards compatibility
      'paused': 'paused',
      'completed': 'completed',
      'canceled': 'canceled'
    };

    const normalizedInput = state.toLowerCase().replace(/\s+/g, '-');
    const apiState = stateMap[normalizedInput];

    if (!apiState) {
      console.error(`[ERROR] Invalid state: ${state}`);
      console.error('Valid states: backlog, planned, in-progress, paused, completed, canceled');
      process.exit(1);
    }

    const displayState = normalizedInput === 'started' ? 'in-progress' : normalizedInput;
    console.log(`Updating project status: ${projectName} -> ${displayState}...`);

    // Find project by name
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: projectName } }
    });

    if (projects.nodes.length === 0) {
      console.error(`[ERROR] Project "${projectName}" not found`);
      process.exit(1);
    }

    const project = projects.nodes[0];
    console.log(`  Found project: ${project.name}`);
    console.log(`  Current state: ${project.state}`);

    // 'state' is accepted by the GraphQL API but not in the SDK's ProjectUpdateInput type
    await requireClient().updateProject(project.id, { state: apiState } as Record<string, string>);

    console.log(`\n[SUCCESS] Project state updated!`);
    console.log(`  ${project.name}: ${project.state} -> ${displayState}`);
  },

  async 'link-initiative'(projectName: string, initiativeName: string) {
    if (!projectName || !initiativeName) {
      console.error('Usage: link-initiative <project-name> <initiative-name>');
      console.error('Example: link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"');
      process.exit(1);
    }

    console.log(`Linking project to initiative...`);

    // Find project by name
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: projectName } }
    });

    if (projects.nodes.length === 0) {
      console.error(`[ERROR] Project "${projectName}" not found`);
      process.exit(1);
    }

    const project = projects.nodes[0];
    console.log(`  Found project: ${project.name}`);

    // Find initiative by name
    const initiatives = await requireClient().initiatives({
      filter: { name: { containsIgnoreCase: initiativeName } }
    });

    if (initiatives.nodes.length === 0) {
      console.error(`[ERROR] Initiative "${initiativeName}" not found`);
      process.exit(1);
    }

    const initiative = initiatives.nodes[0];
    console.log(`  Found initiative: ${initiative.name}`);

    // Link project to initiative using createInitiativeToProject
    await requireClient().createInitiativeToProject({
      projectId: project.id,
      initiativeId: initiative.id
    });

    console.log(`\n[SUCCESS] Project linked to initiative!`);
    console.log(`  Project: ${project.name}`);
    console.log(`  Initiative: ${initiative.name}`);
  },

  async 'unlink-initiative'(projectName: string, initiativeName: string) {
    if (!projectName || !initiativeName) {
      console.error('Usage: unlink-initiative <project-name> <initiative-name>');
      console.error('Example: unlink-initiative "Phase 8: MCP Decision Engine" "Linear Skill"');
      process.exit(1);
    }

    console.log(`Unlinking project from initiative...`);

    // Find project by name
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: projectName } }
    });

    if (projects.nodes.length === 0) {
      console.error(`[ERROR] Project "${projectName}" not found`);
      process.exit(1);
    }

    const project = projects.nodes[0];
    console.log(`  Found project: ${project.name}`);

    // Find initiative by name
    const initiatives = await requireClient().initiatives({
      filter: { name: { containsIgnoreCase: initiativeName } }
    });

    if (initiatives.nodes.length === 0) {
      console.error(`[ERROR] Initiative "${initiativeName}" not found`);
      process.exit(1);
    }

    const initiative = initiatives.nodes[0];
    console.log(`  Found initiative: ${initiative.name}`);

    // Fetch all initiative-to-project links and filter client-side
    const allLinks = await requireClient().initiativeToProjects();
    const matchingLinks = allLinks.nodes.filter(
      (l) => l.initiativeId === initiative.id && l.projectId === project.id
    );

    if (matchingLinks.length === 0) {
      console.error(`[ERROR] Project "${project.name}" is not linked to initiative "${initiative.name}"`);
      process.exit(1);
    }

    const link = matchingLinks[0];

    // Delete the initiative-to-project link
    await requireClient().deleteInitiativeToProject(link.id);

    console.log(`\n[SUCCESS] Project unlinked from initiative!`);
    console.log(`  Project: ${project.name}`);
    console.log(`  Initiative: ${initiative.name}`);
  },

  async 'create-project-update'(projectName: string, body: string, healthFlag?: string) {
    if (!projectName || !body) {
      console.error('Usage: create-project-update <project-name> <body> [--health onTrack|atRisk|offTrack]');
      console.error('Example: create-project-update "My Project" "## Summary\\n\\nWork completed..."');
      process.exit(1);
    }

    // Parse health flag
    let health = ProjectUpdateHealthType.OnTrack;
    if (healthFlag === '--health' || healthFlag?.startsWith('--health=')) {
      const value = healthFlag.includes('=') ? healthFlag.split('=')[1] : body;
      if (value === 'atRisk') health = ProjectUpdateHealthType.AtRisk;
      else if (value === 'offTrack') health = ProjectUpdateHealthType.OffTrack;
    }

    console.log(`Creating project update for: ${projectName}...`);

    // Find project by name
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: projectName } }
    });

    if (projects.nodes.length === 0) {
      console.error(`[ERROR] Project "${projectName}" not found`);
      process.exit(1);
    }

    const project = projects.nodes[0];
    console.log(`  Found project: ${project.name}`);

    const result = await requireClient().createProjectUpdate({
      projectId: project.id,
      body,
      health
    });

    const update = await result.projectUpdate;
    if (update) {
      console.log('\n[SUCCESS] Project update created!');
      console.log(`  Health: ${health}`);
      console.log(`  URL:    ${update.url}`);
    } else {
      console.error('[ERROR] Failed to create project update');
      process.exit(1);
    }
  },

  async 'create-initiative-update'(initiativeName: string, body: string, healthFlag?: string) {
    if (!initiativeName || !body) {
      console.error('Usage: create-initiative-update <initiative-name> <body> [--health onTrack|atRisk|offTrack]');
      console.error('Example: create-initiative-update "My Initiative" "## Phase Complete\\n\\n..."');
      process.exit(1);
    }

    // Parse health flag
    let health = InitiativeUpdateHealthType.OnTrack;
    if (healthFlag === '--health' || healthFlag?.startsWith('--health=')) {
      const value = healthFlag.includes('=') ? healthFlag.split('=')[1] : body;
      if (value === 'atRisk') health = InitiativeUpdateHealthType.AtRisk;
      else if (value === 'offTrack') health = InitiativeUpdateHealthType.OffTrack;
    }

    console.log(`Creating initiative update for: ${initiativeName}...`);

    // Find initiative by name
    const initiatives = await requireClient().initiatives({
      filter: { name: { containsIgnoreCase: initiativeName } }
    });

    if (initiatives.nodes.length === 0) {
      console.error(`[ERROR] Initiative "${initiativeName}" not found`);
      process.exit(1);
    }

    const initiative = initiatives.nodes[0];
    console.log(`  Found initiative: ${initiative.name}`);

    const result = await requireClient().createInitiativeUpdate({
      initiativeId: initiative.id,
      body,
      health
    });

    const update = await result.initiativeUpdate;
    if (update) {
      console.log('\n[SUCCESS] Initiative update created!');
      console.log(`  Health: ${health}`);
      console.log(`  URL:    ${update.url}`);
    } else {
      console.error('[ERROR] Failed to create initiative update');
      process.exit(1);
    }
  },

  async 'add-link'(targetName: string, url: string, label: string) {
    if (!targetName || !url || !label) {
      console.error('Usage: add-link <project-or-initiative-name> <url> <label>');
      console.error('Example: add-link "Phase 6A" "https://github.com/..." "Implementation Plan"');
      console.error('\nAdds an external resource link to a project or initiative.');
      process.exit(1);
    }

    console.log(`Adding link to: ${targetName}...`);

    // Try to find as project first
    const projects = await requireClient().projects({
      filter: { name: { containsIgnoreCase: targetName } }
    });

    let entityType: 'project' | 'initiative' = 'project';
    let entityId: string;
    let entityName: string;

    if (projects.nodes.length > 0) {
      entityId = projects.nodes[0].id;
      entityName = projects.nodes[0].name;
      console.log(`  Found project: ${entityName}`);
    } else {
      // Try to find as initiative
      const initiatives = await requireClient().initiatives({
        filter: { name: { containsIgnoreCase: targetName } }
      });

      if (initiatives.nodes.length === 0) {
        console.error(`[ERROR] No project or initiative found matching "${targetName}"`);
        process.exit(1);
      }

      entityType = 'initiative';
      entityId = initiatives.nodes[0].id;
      entityName = initiatives.nodes[0].name;
      console.log(`  Found initiative: ${entityName}`);
    }

    // Use GraphQL directly since SDK doesn't expose entityExternalLinkCreate
    const API_URL = 'https://api.linear.app/graphql';
    const mutation = `
      mutation CreateExternalLink($input: EntityExternalLinkCreateInput!) {
        entityExternalLinkCreate(input: $input) {
          success
          entityExternalLink {
            id
            label
            url
          }
        }
      }
    `;

    const input: Record<string, string> = { url, label };
    if (entityType === 'project') {
      input.projectId = entityId;
    } else {
      input.initiativeId = entityId;
    }

    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': requireApiKey()
      },
      body: JSON.stringify({
        query: mutation,
        variables: { input }
      })
    });

    const data = await response.json();

    if (data.errors) {
      console.error('[ERROR] GraphQL errors:', JSON.stringify(data.errors, null, 2));
      process.exit(1);
    }

    if (data.data.entityExternalLinkCreate.success) {
      const link = data.data.entityExternalLinkCreate.entityExternalLink;
      console.log('\n[SUCCESS] External link added!');
      console.log(`  ID:    ${link.id}`);
      console.log(`  Label: ${link.label}`);
      console.log(`  URL:   ${link.url}`);
      console.log(`  Added to ${entityType}: ${entityName}`);
    } else {
      console.error('[ERROR] Failed to create external link');
      process.exit(1);
    }
  },

  async 'status'(state: string, ...issueNumbers: string[]) {
    if (!state || issueNumbers.length === 0) {
      console.error('Usage: status <state> <issue-numbers...>');
      console.error('Example: status Done 123 124 125');
      console.error('Example: status Done ENG-123 ENG-124  (prefix is stripped automatically)');
      console.error('\nAvailable states: Backlog, Todo, In Progress, In Review, Done, Canceled');
      process.exit(1);
    }

    // Normalize state name
    const stateMap: Record<string, string> = {
      'backlog': 'Backlog',
      'todo': 'Todo',
      'in progress': 'In Progress',
      'inprogress': 'In Progress',
      'in review': 'In Review',
      'inreview': 'In Review',
      'done': 'Done',
      'canceled': 'Canceled',
      'cancelled': 'Canceled'
    };

    const normalizedState = stateMap[state.toLowerCase()] || state;

    console.log(`Updating ${issueNumbers.length} issue(s) to "${normalizedState}"...\n`);

    // Get workflow states to find the state ID
    const states = await requireClient().workflowStates({
      filter: { name: { eq: normalizedState } }
    });

    if (states.nodes.length === 0) {
      console.error(`[ERROR] State "${normalizedState}" not found`);
      console.error('Available states: Backlog, Todo, In Progress, In Review, Done, Canceled');
      process.exit(1);
    }

    const stateId = states.nodes[0].id;

    // Process each issue
    let success = 0;
    let failed = 0;
    const linAvailable = await isLinCliAvailable();

    for (const num of issueNumbers) {
      // Strip prefix if present (e.g., "ENG-123" -> "123", "ENG-456" -> "456")
      const cleanedNum = num.replace(/^[A-Z]+-/i, '');
      const issueNum = parseInt(cleanedNum, 10);
      if (isNaN(issueNum)) {
        console.log(`  [SKIP] "${num}" is not a valid issue number`);
        failed++;
        continue;
      }

      // Try lin fast-path (requires full identifier e.g. "SMI-123")
      if (linAvailable && num.includes('-')) {
        const linResult = await linUpdateIssueState(num, normalizedState);
        if (linResult.success) {
          console.log(`  [OK] ${num} -> ${normalizedState}`);
          success++;
          continue;
        }
        // Silent fallback to SDK
      }

      try {
        // Find issue by number (SDK path)
        const issues = await requireClient().issues({
          filter: { number: { eq: issueNum } }
        });

        if (issues.nodes.length === 0) {
          console.log(`  [NOT FOUND] Issue #${issueNum}`);
          failed++;
          continue;
        }

        const issue = issues.nodes[0];
        await issue.update({ stateId });
        console.log(`  [OK] ${issue.identifier} -> ${normalizedState}`);
        success++;
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        console.log(`  [ERROR] Issue #${issueNum}: ${msg}`);
        failed++;
      }
    }

    console.log(`\nResult: ${success} updated, ${failed} failed`);
    if (failed > 0) process.exit(1);
  },

  async 'list-initiatives'() {
    console.log('Fetching initiatives...\n');

    const sdkListInitiatives = async () => {
      const initiatives = await requireClient().initiatives({ first: 50 });

      if (initiatives.nodes.length === 0) {
        console.log('No initiatives found.');
        return;
      }

      console.log('Initiatives:');
      for (const init of initiatives.nodes) {
        const status = init.status || 'No status';
        console.log(`  - ${init.name}`);
        console.log(`    ID: ${init.id}`);
        console.log(`    Status: ${status}`);
        console.log(`    URL: ${init.url}`);
        console.log('');
      }
    };

    await tryLin(['initiatives', 'list'], sdkListInitiatives, (data: unknown) => {
      const initiatives = unwrapLinList(data, 'initiatives');
      if (initiatives.length === 0) {
        console.log('No initiatives found.');
        return;
      }

      console.log('Initiatives:');
      for (const init of initiatives) {
        const i = init as Record<string, unknown>;
        console.log(`  - ${i.name}`);
        console.log(`    ID: ${i.id}`);
        console.log(`    Status: ${i.status || 'No status'}`);
        console.log(`    URL: ${i.url || ''}`);
        console.log('');
      }
    });
  },

  async 'list-projects'(initiativeName?: string) {
    console.log('Fetching projects...\n');

    let filter = {};
    if (initiativeName) {
      // Find initiative first
      const initiatives = await requireClient().initiatives({
        filter: { name: { containsIgnoreCase: initiativeName } }
      });

      if (initiatives.nodes.length === 0) {
        console.error(`[ERROR] Initiative "${initiativeName}" not found`);
        process.exit(1);
      }

      console.log(`Filtering by initiative: ${initiatives.nodes[0].name}\n`);
      filter = { initiatives: { id: { eq: initiatives.nodes[0].id } } };
    }

    const projects = await requireClient().projects({ first: 50, filter });

    if (projects.nodes.length === 0) {
      console.log('No projects found.');
      return;
    }

    console.log('Projects:');
    for (const proj of projects.nodes) {
      const status = await proj.status;
      console.log(`  - ${proj.name}`);
      console.log(`    ID: ${proj.id}`);
      console.log(`    Status: ${status?.name || 'No status'}`);
      console.log(`    URL: ${proj.url}`);
      console.log('');
    }
  },

  async 'setup'() {
    // Delegate to setup script — detect if running from dist/ or source
    const { execSync } = await import('child_process');
    const { dirname } = await import('path');
    const { fileURLToPath } = await import('url');

    const __dirname = dirname(fileURLToPath(import.meta.url));
    const isBundled = typeof __BUNDLED__ !== 'undefined';
    const runner = isBundled ? 'node' : 'npx tsx';
    const ext = isBundled ? '.js' : '.ts';
    execSync(`${runner} ${__dirname}/setup${ext}`, { stdio: 'inherit' });
  },

  async 'whoami'() {
    console.log('Fetching user info...\n');

    // SDK fallback
    const sdkWhoami = async () => {
      const me = await requireClient().viewer;
      const org = await me.organization;
      const teams = await me.teams();

      console.log('Current User:');
      console.log(`  Name:  ${me.name}`);
      console.log(`  Email: ${me.email}`);
      console.log(`  ID:    ${me.id}`);
      console.log('');
      console.log('Organization:');
      console.log(`  Name: ${org?.name || 'Unknown'}`);
      console.log(`  ID:   ${org?.id || 'Unknown'}`);
      console.log('');
      console.log('Teams:');
      for (const team of teams.nodes) {
        console.log(`  - ${team.name} (${team.key})`);
      }
    };

    await tryLin(['me'], sdkWhoami, (data: unknown) => {
      // Format lin JSON output to match existing display.
      const user = unwrapLinObject(data, 'viewer');
      console.log('Current User:');
      console.log(`  Name:  ${user.name || user.displayName || 'Unknown'}`);
      console.log(`  Email: ${user.email || 'Unknown'}`);
      console.log(`  ID:    ${user.id || 'Unknown'}`);
      console.log('');
      if (user.organization && typeof user.organization === 'object') {
        const org = user.organization as Record<string, unknown>;
        console.log('Organization:');
        console.log(`  Name: ${org.name || 'Unknown'}`);
        console.log(`  ID:   ${org.id || 'Unknown'}`);
        console.log('');
      }
      // Teams: legacy `teams` array, or current `teamMemberships.nodes[].team`.
      const teamList: unknown[] = Array.isArray(user.teams)
        ? user.teams
        : unwrapLinList(user, 'teamMemberships').map((m) => (m as Record<string, unknown>).team);
      if (teamList.length > 0) {
        console.log('Teams:');
        for (const team of teamList) {
          const t = team as Record<string, unknown>;
          console.log(`  - ${t.name} (${t.key})`);
        }
      }
    });
  },

  // Update issue fields (title, description)
  async 'update-issue'(issueIdentifier: string, field: string, ...valueParts: string[]) {
    if (!issueIdentifier || !field || valueParts.length === 0) {
      usageUpdateIssue();
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    }

    if (field !== 'title' && field !== 'description') {
      console.error(`[ERROR] Unknown field: ${field}. Supported: title, description`);
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    }

    const updateField = field as UpdateIssueField;
    const { value, force, strictFlag } = await parseUpdateIssueValue(updateField, valueParts);

    if (updateField === 'description') {
      const descResult = validateIssueDescription(value);
      if (!descResult.valid || descResult.warnings.length > 0) {
        const strict = isStrictMode(strictFlag);
        const output = formatDescriptionValidationResult(descResult);
        if (!descResult.valid && strict) {
          console.error(output);
          process.exit(EXIT_CODES.VALIDATION_ERROR);
        } else if (!descResult.valid) {
          console.warn('[WARN] Description validation downgraded (strict mode off):');
          console.warn(output);
        } else if (descResult.warnings.length > 0) {
          console.warn(formatWarningsOnly(descResult));
        }
      }
    }

    if (!force && !process.stdin.isTTY) {
      console.error('[ERROR] update-issue replaces existing content and requires --force in non-interactive mode');
      console.error('Run from a terminal for an interactive confirmation, or pass --force for scripts.');
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    }

    const client = requireClient();
    const issue = await resolveIssueForUpdate(client, issueIdentifier);
    const updateInput: Parameters<Issue['update']>[0] =
      updateField === 'title' ? { title: value } : { description: value };

    if (!force) {
      await confirmIssueUpdate(issue, updateField, value);
    }

    console.log(`Updating ${issue.identifier} - ${issue.title}...`);
    await issue.update(updateInput);

    console.log('\n[SUCCESS] Issue updated!');
    console.log(`  ${issue.identifier}: ${field} updated`);
    console.log(`  New ${field}: ${previewText(value, 160)}`);
    console.log(`  URL: ${issue.url}`);
  },

  // Alias: done <issue-numbers...> -> status Done <issue-numbers...>
  async 'done'(...issueNumbers: string[]) {
    if (issueNumbers.length === 0) {
      console.error('Usage: done <issue-numbers...>');
      console.error('Example: done 123 124 125');
      console.error('Example: done ENG-123 ENG-124  (prefix is stripped automatically)');
      console.error('\nThis is a shortcut for: status Done <issue-numbers...>');
      process.exit(1);
    }
    await commands['status']('Done', ...issueNumbers);
  },

  // Alias: wip <issue-numbers...> -> status "In Progress" <issue-numbers...>
  async 'wip'(...issueNumbers: string[]) {
    if (issueNumbers.length === 0) {
      console.error('Usage: wip <issue-numbers...>');
      console.error('Example: wip 123 124 125');
      console.error('Example: wip ENG-123 ENG-124  (prefix is stripped automatically)');
      console.error('\nThis is a shortcut for: status "In Progress" <issue-numbers...>');
      process.exit(1);
    }
    await commands['status']('In Progress', ...issueNumbers);
  },

  // Set parent-child relationship between issues
  async 'set-parent'(parentIssue: string, ...childIssues: string[]) {
    if (!parentIssue || childIssues.length === 0) {
      console.error('Usage: set-parent <parent-issue> <child-issues...>');
      console.error('Example: set-parent ENG-100 ENG-101 ENG-102');
      console.error('Example: set-parent 100 101 102  (prefix optional)');
      console.error('\nSets the first issue as parent of all subsequent issues (sub-issues).');
      process.exit(1);
    }

    // Parse parent issue number
    const parentNum = parseInt(parentIssue.replace(/^[A-Z]+-/i, ''), 10);
    if (isNaN(parentNum)) {
      console.error(`[ERROR] "${parentIssue}" is not a valid issue number`);
      process.exit(1);
    }

    console.log(`Setting parent-child relationships...`);

    // Find parent issue
    const parentIssues = await requireClient().issues({
      filter: { number: { eq: parentNum } }
    });

    if (parentIssues.nodes.length === 0) {
      console.error(`[ERROR] Parent issue #${parentNum} not found`);
      process.exit(1);
    }

    const parent = parentIssues.nodes[0];
    console.log(`  Parent: ${parent.identifier} - ${parent.title}`);

    // Process each child issue
    let success = 0;
    let failed = 0;

    for (const childIssue of childIssues) {
      const childNum = parseInt(childIssue.replace(/^[A-Z]+-/i, ''), 10);
      if (isNaN(childNum)) {
        console.log(`  [SKIP] "${childIssue}" is not a valid issue number`);
        failed++;
        continue;
      }

      try {
        const childIssues = await requireClient().issues({
          filter: { number: { eq: childNum } }
        });

        if (childIssues.nodes.length === 0) {
          console.log(`  [NOT FOUND] Issue #${childNum}`);
          failed++;
          continue;
        }

        const child = childIssues.nodes[0];
        await child.update({ parentId: parent.id });
        console.log(`  [OK] ${child.identifier} -> child of ${parent.identifier}`);
        success++;
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        console.log(`  [ERROR] Issue #${childNum}: ${msg}`);
        failed++;
      }
    }

    console.log(`\nResult: ${success} linked as sub-issues, ${failed} failed`);
    if (failed > 0) process.exit(1);
  },

  // Create a new issue as a sub-issue (child) of another issue
  async 'create-sub-issue'(parentIssue: string, title: string, description?: string, ...flags: string[]) {
    // --template short-circuit
    const allArgs = [parentIssue, title, description, ...flags].filter((a): a is string => typeof a === 'string');
    if (allArgs.includes('--template')) {
      process.stdout.write(buildIssueTemplate(title && title !== '--template' ? title : undefined));
      return;
    }

    if (!parentIssue || !title) {
      console.error('Usage: create-sub-issue <parent-issue> <title> [description] [--priority 1-4] [--labels label1,label2] [--strict=false]');
      console.error('Example: create-sub-issue ENG-100 "Implement feature" "Detailed description..."');
      console.error('Example: create-sub-issue 100 "Add tests" --priority 2');
      console.error('\nPrint template: create-sub-issue --template');
      process.exit(1);
    }

    // Parse parent issue number
    const parentNum = parseInt(parentIssue.replace(/^[A-Z]+-/i, ''), 10);
    if (isNaN(parentNum)) {
      console.error(`[ERROR] "${parentIssue}" is not a valid issue number`);
      process.exit(1);
    }

    // Parse flags
    let priority = 3;
    let labelNames: string[] = [];
    let strictFlag: boolean | undefined;

    for (let i = 0; i < flags.length; i++) {
      if (flags[i] === '--priority' && flags[i + 1]) {
        priority = parseInt(flags[i + 1], 10);
        i++;
      } else if (flags[i] === '--labels' && flags[i + 1]) {
        labelNames = flags[i + 1].split(',').map(l => l.trim());
        i++;
      } else if (flags[i] === '--strict=false') {
        strictFlag = false;
      } else if (flags[i] === '--strict=true') {
        strictFlag = true;
      }
    }

    // Validate description BEFORE any API work (before tryLin too).
    const descResult = validateIssueDescription(description ?? '');
    if (!descResult.valid || descResult.warnings.length > 0) {
      const strict = isStrictMode(strictFlag);
      const output = formatDescriptionValidationResult(descResult);
      if (!descResult.valid && strict) {
        console.error(output);
        process.exit(EXIT_CODES.VALIDATION_ERROR);
      } else if (!descResult.valid) {
        console.warn('[WARN] Description validation downgraded (strict mode off):');
        console.warn(output);
      } else if (descResult.warnings.length > 0) {
        console.warn(formatWarningsOnly(descResult));
      }
    }

    console.log(`Creating sub-issue for parent #${parentNum}...`);

    // Find parent issue
    const parentIssues = await requireClient().issues({
      filter: { number: { eq: parentNum } }
    });

    if (parentIssues.nodes.length === 0) {
      console.error(`[ERROR] Parent issue #${parentNum} not found`);
      process.exit(1);
    }

    const parent = parentIssues.nodes[0];
    const parentTeam = await parent.team;
    const parentProject = await parent.project;

    console.log(`  Parent: ${parent.identifier} - ${parent.title}`);
    console.log(`  Team: ${parentTeam?.name || 'Unknown'}`);
    if (parentProject) {
      console.log(`  Project: ${parentProject.name}`);
    }

    if (!parentTeam) {
      console.error('[ERROR] Could not determine team from parent issue');
      process.exit(1);
    }

    // Resolve label names to IDs if provided
    const labelIds: string[] = [];
    if (labelNames.length > 0) {
      const labels = await parentTeam.labels();
      for (const name of labelNames) {
        const label = labels.nodes.find(l =>
          l.name.toLowerCase() === name.toLowerCase()
        );
        if (label) {
          labelIds.push(label.id);
          console.log(`  Found label: ${label.name}`);
        } else {
          console.log(`  [WARNING] Label "${name}" not found, skipping`);
        }
      }
    }

    // Create issue with parent
    const result = await requireClient().createIssue({
      teamId: parentTeam.id,
      parentId: parent.id,
      title,
      description: description || '',
      priority,
      ...(parentProject && { projectId: parentProject.id }),
      ...(labelIds.length > 0 && { labelIds })
    });

    const issue = await result.issue;
    if (issue) {
      console.log('\n[SUCCESS] Sub-issue created!');
      console.log(`  ID:       ${issue.identifier}`);
      console.log(`  Title:    ${issue.title}`);
      console.log(`  Priority: ${priority}`);
      console.log(`  Parent:   ${parent.identifier}`);
      console.log(`  URL:      ${issue.url}`);
    } else {
      console.error('[ERROR] Failed to create sub-issue');
      process.exit(1);
    }
  },

  // List sub-issues (children) of a parent issue
  async 'list-sub-issues'(parentIssue: string) {
    if (!parentIssue) {
      console.error('Usage: list-sub-issues <parent-issue>');
      console.error('Example: list-sub-issues ENG-100');
      console.error('Example: list-sub-issues 100');
      console.error('\nLists all sub-issues (children) of the specified parent issue.');
      process.exit(1);
    }

    // Parse parent issue number
    const parentNum = parseInt(parentIssue.replace(/^[A-Z]+-/i, ''), 10);
    if (isNaN(parentNum)) {
      console.error(`[ERROR] "${parentIssue}" is not a valid issue number`);
      process.exit(1);
    }

    console.log(`Fetching sub-issues for #${parentNum}...\n`);

    // Find parent issue
    const parentIssues = await requireClient().issues({
      filter: { number: { eq: parentNum } }
    });

    if (parentIssues.nodes.length === 0) {
      console.error(`[ERROR] Issue #${parentNum} not found`);
      process.exit(1);
    }

    const parent = parentIssues.nodes[0];
    console.log(`Parent: ${parent.identifier} - ${parent.title}\n`);

    // Get children of this issue
    const children = await parent.children();

    if (children.nodes.length === 0) {
      console.log('No sub-issues found.');
      return;
    }

    console.log(`Sub-issues (${children.nodes.length}):`);
    for (const child of children.nodes) {
      const state = await child.state;
      console.log(`  - ${child.identifier}: ${child.title}`);
      console.log(`    Status: ${state?.name || 'Unknown'}`);
      console.log(`    URL: ${child.url}`);
      console.log('');
    }
  },

  // ==================== DESCRIPTION VALIDATION ====================

  // Pre-flight validator for MCP save_issue callers (and anyone else).
  // Runs without LINEAR_API_KEY — pure-logic reuse of validateIssueDescription.
  async 'validate-description'(...args: string[]) {
    let body: string | undefined;
    let filePath: string | undefined;
    let readStdin = false;
    let strictFlag: boolean | undefined;

    for (let i = 0; i < args.length; i++) {
      const a = args[i];
      if (a === '--file' && args[i + 1]) {
        filePath = args[i + 1];
        i++;
      } else if (a === '--stdin') {
        readStdin = true;
      } else if (a === '--strict=false') {
        strictFlag = false;
      } else if (a === '--strict=true') {
        strictFlag = true;
      } else if (!a.startsWith('--') && body === undefined) {
        body = a;
      }
    }

    if (readStdin) {
      const chunks: Buffer[] = [];
      for await (const chunk of process.stdin) {
        chunks.push(chunk as Buffer);
      }
      body = Buffer.concat(chunks).toString('utf8');
    } else if (filePath !== undefined) {
      const { readFileSync } = await import('node:fs');
      try {
        body = readFileSync(filePath, 'utf8');
      } catch (err) {
        const msg = err instanceof Error ? err.message : String(err);
        console.error(`[ERROR] Cannot read file "${filePath}": ${msg}`);
        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
      }
    }

    if (body === undefined) {
      console.error('Usage: validate-description <body>');
      console.error('       validate-description --file <path>');
      console.error('       validate-description --stdin');
      console.error('');
      console.error('Validate an issue description against the Acceptance Criteria contract.');
      console.error('Exit 0 = valid, 5 = invalid + strict, 2 = bad args.');
      console.error('Use --strict=false to downgrade failures to warnings (exit 0).');
      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
    }

    const result = validateIssueDescription(body);
    const strict = isStrictMode(strictFlag);

    if (!result.valid && strict) {
      console.error(formatDescriptionValidationResult(result));
      process.exit(EXIT_CODES.VALIDATION_ERROR);
    } else if (!result.valid) {
      console.warn('[WARN] Description validation downgraded (strict mode off):');
      console.warn(formatDescriptionValidationResult(result));
      // Exit 0 — caller asked to downgrade.
      return;
    } else if (result.warnings.length > 0) {
      console.warn(formatWarningsOnly(result));
    }

    console.log('✓ Issue description is valid.');
  },

  // ==================== LABEL TAXONOMY COMMANDS ====================

  async 'labels'(subcommand: string, ...args: string[]) {
    if (!subcommand) {
      console.error('Usage: labels <subcommand> [args]');
      console.error('Subcommands:');
      console.error('  taxonomy              Show full label taxonomy');
      console.error('  validate <labels>     Validate a comma-separated list of labels');
      console.error('  suggest <title>       Suggest labels based on issue title');
      console.error('  agents <labels>       Show agent recommendations for labels');
      console.error('  set <issue> <labels>  Set labels on an existing issue');
      process.exit(1);
    }

    switch (subcommand) {
      case 'taxonomy':
        await commands['labels-taxonomy']();
        break;
      case 'validate':
        await commands['labels-validate'](args.join(','));
        break;
      case 'suggest':
        await commands['labels-suggest'](args.join(' '));
        break;
      case 'agents':
        await commands['labels-agents'](args.join(','));
        break;
      case 'set':
        await commands['labels-set'](...args);
        break;
      default:
        console.error(`Unknown subcommand: ${subcommand}`);
        console.error('Run "labels" without arguments for usage.');
        process.exit(1);
    }
  },

  async 'labels-taxonomy'() {
    console.log('=== Label Taxonomy ===\n');

    console.log('TYPE LABELS (exactly one required per issue):');
    console.log('----------------------------------------------');
    for (const label of getLabelsByCategory('type')) {
      console.log(`  ${label.name.padEnd(15)} ${label.color}  ${label.description}`);
    }

    console.log('\nDOMAIN LABELS (1-2 recommended per issue):');
    console.log('----------------------------------------------');
    for (const label of getLabelsByCategory('domain')) {
      const agents = label.primaryAgents?.join(', ') || 'none';
      console.log(`  ${label.name.padEnd(15)} ${label.color}  ${label.description}`);
      console.log(`                    Primary agents: ${agents}`);
    }

    console.log('\nSCOPE LABELS (0-2 optional per issue):');
    console.log('----------------------------------------------');
    for (const label of getLabelsByCategory('scope')) {
      console.log(`  ${label.name.padEnd(15)} ${label.color}  ${label.description}`);
    }

    console.log('\n=== Summary ===');
    console.log(`Total labels: ${getAllLabels().length}`);
    console.log(`  Type labels:   ${getLabelsByCategory('type').length}`);
    console.log(`  Domain labels: ${getLabelsByCategory('domain').length}`);
    console.log(`  Scope labels:  ${getLabelsByCategory('scope').length}`);
  },

  async 'labels-validate'(labelString: string) {
    if (!labelString) {
      console.error('Usage: labels validate <labels>');
      console.error('Example: labels validate "feature,security,breaking-change"');
      process.exit(1);
    }

    const labels = labelString.split(',').map(l => l.trim()).filter(l => l);
    console.log(`Validating labels: ${labels.join(', ')}\n`);

    const result = validateLabels(labels);
    console.log(formatValidationResult(result));

    if (!result.valid) {
      process.exit(1);
    }
  },

  async 'labels-suggest'(title: string) {
    if (!title) {
      console.error('Usage: labels suggest <title>');
      console.error('Example: labels suggest "Fix XSS vulnerability in login form"');
      process.exit(1);
    }

    console.log(`Analyzing: "${title}"\n`);

    const suggestions = suggestLabels(title);
    console.log(formatSuggestions(suggestions));

    if (suggestions.length > 0) {
      const suggestedLabels = suggestions.map(s => s.label);
      console.log(`\nSuggested label set: ${suggestedLabels.join(', ')}`);
    }
  },

  async 'labels-agents'(labelString: string) {
    if (!labelString) {
      console.error('Usage: labels agents <labels>');
      console.error('Example: labels agents "security,performance"');
      process.exit(1);
    }

    const labels = labelString.split(',').map(l => l.trim()).filter(l => l);
    console.log(`Finding agents for labels: ${labels.join(', ')}\n`);

    const selection = selectAgentsForIssue(labels);
    console.log(formatAgentSelection(selection));
  },

  async 'labels-matrix'() {
    console.log('=== Agent-Domain Matrix ===\n');
    console.log(formatAgentMatrix());
  },

  async 'labels-set'(issueIdentifier: string, labelString: string, ...flags: string[]) {
    if (!issueIdentifier || !labelString) {
      console.error('Usage: labels set <issue-id> <labels> [--replace]');
      console.error('Example: labels set SMI-1770 mcp,DX,feature');
      console.error('Example: labels set ENG-123 bug,security --replace');
      console.error('\nOptions:');
      console.error('  --replace    Replace all existing labels (default: add to existing)');
      console.error('\nLabels are validated against the taxonomy before applying.');
      process.exit(1);
    }

    // Parse flags
    const replaceMode = flags.includes('--replace');

    // Parse label names
    const labelNames = labelString.split(',').map(l => l.trim()).filter(l => l);
    if (labelNames.length === 0) {
      console.error('[ERROR] No valid labels provided');
      process.exit(1);
    }

    console.log(`Setting labels on issue: ${issueIdentifier}...`);
    console.log(`  Labels: ${labelNames.join(', ')}`);
    console.log(`  Mode: ${replaceMode ? 'replace all' : 'add to existing'}`);

    // Validate labels against taxonomy
    const validation = validateLabels(labelNames);
    if (validation.warnings.length > 0) {
      for (const warn of validation.warnings) {
        console.log(`  [WARNING] ${warn}`);
      }
    }
    if (validation.parsed.unknown.length > 0) {
      console.log(`  [WARNING] Labels not in taxonomy: ${validation.parsed.unknown.join(', ')}`);
    }

    // Parse issue identifier (e.g., "SMI-1770" -> 1770, or just "1770")
    const issueNum = parseInt(issueIdentifier.replace(/^[A-Z]+-/i, ''), 10);
    if (isNaN(issueNum)) {
      console.error(`[ERROR] "${issueIdentifier}" is not a valid issue identifier`);
      process.exit(1);
    }

    // Find issue by number
    const issues = await requireClient().issues({
      filter: { number: { eq: issueNum } }
    });

    if (issues.nodes.length === 0) {
      console.error(`[ERROR] Issue #${issueNum} not found`);
      process.exit(1);
    }

    const issue = issues.nodes[0];
    console.log(`  Found: ${issue.identifier} - ${issue.title}`);

    // Get team for label resolution
    const team = await issue.team;
    if (!team) {
      console.error('[ERROR] Could not determine team from issue');
      process.exit(1);
    }

    // Build label map from workspace labels (case-insensitive lookup)
    // Fetch with higher limit to ensure we get all labels
    const workspaceLabels = await requireClient().issueLabels({ first: 250 });
    const labelMap = new Map<string, { id: string; name: string }>();
    for (const label of workspaceLabels.nodes) {
      labelMap.set(label.name.toLowerCase(), { id: label.id, name: label.name });
    }

    // Resolve label names to IDs
    const resolvedLabels: { id: string; name: string }[] = [];
    const notFound: string[] = [];

    for (const name of labelNames) {
      const found = labelMap.get(name.toLowerCase());
      if (found) {
        resolvedLabels.push(found);
      } else {
        notFound.push(name);
      }
    }

    if (notFound.length > 0) {
      console.log(`  [WARNING] Labels not found in workspace: ${notFound.join(', ')}`);
    }

    if (resolvedLabels.length === 0) {
      console.error('[ERROR] No valid labels could be resolved');
      process.exit(1);
    }

    // Get existing labels
    const existingLabels = await issue.labels();
    const existingNames = existingLabels.nodes.map(l => l.name);

    let finalLabelIds: string[];
    if (replaceMode) {
      // Replace mode: use only the new labels
      finalLabelIds = resolvedLabels.map(l => l.id);
    } else {
      // Add mode: merge with existing labels
      const existingIds = existingLabels.nodes.map(l => l.id);
      const newIds = resolvedLabels
        .filter(l => !existingIds.includes(l.id))
        .map(l => l.id);
      finalLabelIds = [...existingIds, ...newIds];
    }

    // Update issue
    await issue.update({ labelIds: finalLabelIds });

    // Verify the update
    const updatedIssue = await requireClient().issue(issue.id);
    const updatedLabels = await updatedIssue.labels();
    const updatedNames = updatedLabels.nodes.map(l => l.name);

    console.log('\n[SUCCESS] Labels updated!');
    console.log(`  Issue: ${issue.identifier}`);
    if (!replaceMode && existingNames.length > 0) {
      console.log(`  Previous: ${existingNames.join(', ')}`);
    }
    console.log(`  Current:  ${updatedNames.join(', ')}`);
    console.log(`  URL:      ${issue.url}`);
  },

  async 'search'(query: string) {
    if (!query) {
      console.error('Usage: search <query>');
      console.error('Example: search "fix login bug"');
      process.exit(1);
    }

    console.log(`Searching for "${query}"...\n`);

    const sdkSearch = async () => {
      const client = requireClient();
      const results = await (client as unknown as { issueSearch: (opts: { query: string; first: number }) => Promise<{ nodes: Array<{ identifier: string; title: string; state: Promise<{ name: string }> }> }> }).issueSearch({ query, first: 25 });

      if (!results || results.nodes.length === 0) {
        console.log('No results found.');
        return;
      }

      console.log(`Found ${results.nodes.length} issue(s):\n`);
      for (const issue of results.nodes) {
        const state = await issue.state;
        console.log(`  ${issue.identifier}  ${issue.title}`);
        console.log(`    State: ${state?.name || 'Unknown'}`);
      }
    };

    await tryLin(['search', query], sdkSearch, (data: unknown) => {
      const issues = unwrapLinList(data, 'issues');
      if (issues.length === 0) {
        console.log('No results found.');
        return;
      }

      console.log(`Found ${issues.length} issue(s):\n`);
      for (const issue of issues) {
        const i = issue as Record<string, unknown>;
        console.log(`  ${i.identifier || i.id}  ${i.title}`);
        if (i.state) console.log(`    State: ${typeof i.state === 'object' ? (i.state as Record<string, unknown>).name : i.state}`);
      }
    });
  },

  async 'list-issues'(...args: string[]) {
    // Parse flags: --team X --state Y
    let team: string | undefined;
    let state: string | undefined;

    for (let i = 0; i < args.length; i++) {
      if (args[i] === '--team' && args[i + 1]) {
        team = args[++i];
      } else if (args[i] === '--state' && args[i + 1]) {
        state = args[++i];
      }
    }

    console.log('Fetching issues...\n');

    const sdkListIssues = async () => {
      const client = requireClient();
      const filter: Record<string, unknown> = {};
      if (team) filter.team = { key: { eq: team } };
      if (state) filter.state = { name: { eq: state } };

      const results = await client.issues({
        first: 50,
        ...(Object.keys(filter).length > 0 && { filter })
      });

      if (results.nodes.length === 0) {
        console.log('No issues found.');
        return;
      }

      console.log(`Found ${results.nodes.length} issue(s):\n`);
      for (const issue of results.nodes) {
        const issueState = await issue.state;
        console.log(`  ${issue.identifier}  ${issue.title}`);
        console.log(`    State: ${issueState?.name || 'Unknown'}  Priority: ${issue.priority || 0}`);
      }
    };

    const linArgs = ['issues', 'list'];
    if (team) linArgs.push('--team', team);
    if (state) linArgs.push('--state', state);

    await tryLin(linArgs, sdkListIssues, (data: unknown) => {
      const issues = unwrapLinList(data, 'issues');
      if (issues.length === 0) {
        console.log('No issues found.');
        return;
      }

      console.log(`Found ${issues.length} issue(s):\n`);
      for (const issue of issues) {
        const i = issue as Record<string, unknown>;
        console.log(`  ${i.identifier || i.id}  ${i.title}`);
        const s = typeof i.state === 'object' ? (i.state as Record<string, unknown>).name : i.state;
        console.log(`    State: ${s || 'Unknown'}  Priority: ${i.priority || 0}`);
      }
    });
  },

  async 'help'() {
    console.log(`
Linear High-Level Operations

Usage:
  npx tsx linear-ops.ts <command> [arguments]

Commands:
  create-issue <project-name> <title> [description] [--priority 1-4] [--labels label1,label2]
    Create a new issue in a project
    Priority: 1=urgent, 2=high, 3=medium, 4=low (default: 3)

  create-sub-issue <parent-issue> <title> [description] [--priority 1-4] [--labels label1,label2]
    Create a new issue as a child of an existing issue
    Inherits team and project from parent issue
    Example: create-sub-issue ENG-100 "Add unit tests"

  update-issue <issue-id> <title|description> <value> [--force] [--strict=false]
    Update an issue title or description by full identifier, e.g. ENG-123
    Bare numbers work only when a single issue matches that number
    Description updates use the same Acceptance Criteria validator as create-issue
    Examples:
      update-issue ENG-123 title "Corrected title" --force
      update-issue ENG-123 description --file /tmp/description.md --force
      cat /tmp/description.md | update-issue ENG-123 description --stdin --force

  set-parent <parent-issue> <child-issues...>
    Set parent-child relationships between existing issues
    Useful for organizing issues into hierarchies
    Example: set-parent ENG-100 ENG-101 ENG-102

  list-sub-issues <parent-issue>
    List all sub-issues (children) of a parent issue
    Example: list-sub-issues ENG-100

  create-initiative <name> [description]
    Create a new initiative

  create-project <name> [initiative-name]
    Create a project, optionally linked to an initiative

  project-status <project-name> <state>
    Update project state
    States: backlog, planned, in-progress, paused, completed, canceled

  link-initiative <project-name> <initiative-name>
    Link an existing project to an initiative

  unlink-initiative <project-name> <initiative-name>
    Remove a project from an initiative

  create-project-update <project-name> <body> [--health onTrack|atRisk|offTrack]
    Create a project update with markdown body

  create-initiative-update <initiative-name> <body> [--health onTrack|atRisk|offTrack]
    Create an initiative update with markdown body

  add-link <project-or-initiative-name> <url> <label>
    Add an external resource link to a project or initiative
    Automatically detects whether the target is a project or initiative

  status <state> <issue-numbers...>
    Update issue status (e.g., status Done 123 124 125)
    Accepts both formats: 123 or ENG-123 (prefix stripped automatically)
    States: Backlog, Todo, In Progress, In Review, Done, Canceled

  done <issue-numbers...>
    Shortcut for: status Done <issue-numbers...>
    Example: done ENG-123 ENG-124

  wip <issue-numbers...>
    Shortcut for: status "In Progress" <issue-numbers...>
    Example: wip ENG-123

  list-initiatives
    List all initiatives in the workspace

  list-projects [initiative-name]
    List projects, optionally filtered by initiative

  whoami
    Show current user and organization

  search <query>
    Search issues across workspace
    Example: search "fix login bug"

  list-issues [--team X] [--state Y]
    List issues with optional filters
    Example: list-issues --team SMI --state "In Progress"

  setup
    Check Linear skill setup and configuration

  labels <subcommand> [args]
    Label taxonomy commands:
    - labels taxonomy           Show full label taxonomy
    - labels validate <labels>  Validate comma-separated labels
    - labels suggest <title>    Suggest labels for issue title
    - labels agents <labels>    Show agent recommendations
    - labels set <issue> <labels> [--replace]  Set labels on existing issue

  validate-description <body>
  validate-description --file <path>
  validate-description --stdin
    Validate an issue description against the Acceptance Criteria contract
    (no API calls, no LINEAR_API_KEY required). Pre-flight gate for MCP
    save_issue callers.
    Exit 0 = valid, 5 = invalid + strict, 2 = bad args.
    Use --strict=false to downgrade failures to warnings (exit 0).
    Example: echo "$DRAFT" | npm run ops -- validate-description --stdin

  help
    Show this help message

Examples:
  npx tsx linear-ops.ts create-issue "My Project" "Fix login bug" "Users cannot log in" --priority 2
  npx tsx linear-ops.ts create-sub-issue ENG-100 "Add unit tests" "Unit tests for new feature" --priority 2
  npx tsx linear-ops.ts set-parent ENG-100 ENG-101 ENG-102
  npx tsx linear-ops.ts list-sub-issues ENG-100
  npx tsx linear-ops.ts create-initiative "Q1 2025 Goals" "Key initiatives for Q1"
  npx tsx linear-ops.ts create-project "Phase 1: Foundation" "Q1 2025 Goals"
  npx tsx linear-ops.ts create-project-update "My Project" "## Summary\\n\\nWork completed"
  npx tsx linear-ops.ts create-initiative-update "My Initiative" "## Phase Complete"
  npx tsx linear-ops.ts add-link "Phase 6A" "https://github.com/org/repo/docs/plan.md" "Implementation Plan"
  npx tsx linear-ops.ts status Done 123 124 125
  npx tsx linear-ops.ts done ENG-123 ENG-124
  npx tsx linear-ops.ts wip ENG-125
  npx tsx linear-ops.ts update-issue ENG-123 title "Corrected title" --force
  npx tsx linear-ops.ts update-issue ENG-123 description --file /tmp/description.md --force
  npx tsx linear-ops.ts list-initiatives
  npx tsx linear-ops.ts labels taxonomy
  npx tsx linear-ops.ts labels validate "feature,security,breaking-change"
  npx tsx linear-ops.ts labels suggest "Fix XSS vulnerability in login form"
  npx tsx linear-ops.ts labels agents "security,performance"
  npx tsx linear-ops.ts labels set SMI-1770 mcp,DX,feature
  npx tsx linear-ops.ts labels set ENG-123 bug,security --replace
  echo "$DRAFT_BODY" | npx tsx linear-ops.ts validate-description --stdin
  npx tsx linear-ops.ts validate-description --file /tmp/draft.md
`);
  }
};

// Main
async function main() {
  const [cmd, ...args] = process.argv.slice(2);

  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
    await commands['help']();
    return;
  }

  if (!commands[cmd]) {
    console.error(`Unknown command: ${cmd}\n`);
    console.error('Run with --help to see available commands');
    process.exit(1);
  }

  await commands[cmd](...args);
}

main().catch(error => {
  console.error('\n[ERROR]', error.message);
  process.exit(1);
});
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall