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/phase-complete.ts

View on GitHub
#!/usr/bin/env npx tsx

/**
 * Phase Completion Workflow
 *
 * Automates the complete phase/project completion process:
 * 1. Looks up project by name (fuzzy matching)
 * 2. Verifies all issues are completed
 * 3. Updates project status to Completed
 * 4. Creates a completion summary project update
 * 5. Optionally archives the project
 *
 * Usage:
 *   LINEAR_API_KEY=lin_api_xxx npx tsx phase-complete.ts "Phase 1: Foundation"
 *   LINEAR_API_KEY=lin_api_xxx npx tsx phase-complete.ts "Phase 1" --archive
 *   LINEAR_API_KEY=lin_api_xxx npx tsx phase-complete.ts "Phase 1" --force
 *   LINEAR_API_KEY=lin_api_xxx npx tsx phase-complete.ts "Phase 1" --dry-run
 */

import { LinearClient } from '@linear/sdk';
import { EXIT_CODES } from './lib/exit-codes.js';
import { getLinearClient, findProjectByName as findProjectByNameBase } from './lib/linear-utils.js';

interface ProjectStatus {
  id: string;
  name: string;
  type: string;
}

interface IssueState {
  name: string;
  type: string;
}

interface Issue {
  identifier: string;
  title: string;
  state: IssueState;
}

interface Project {
  id: string;
  name: string;
  slugId: string;
  status: ProjectStatus | null;
  issues: {
    nodes: Issue[];
  };
}

interface Options {
  projectName: string;
  archive: boolean;
  force: boolean;
  dryRun: boolean;
}

function parseArgs(): Options {
  const args = process.argv.slice(2);
  const options: Options = {
    projectName: '',
    archive: false,
    force: false,
    dryRun: false,
  };

  for (const arg of args) {
    if (arg === '--archive') {
      options.archive = true;
    } else if (arg === '--force') {
      options.force = true;
    } else if (arg === '--dry-run') {
      options.dryRun = true;
    } else if (!arg.startsWith('-')) {
      options.projectName = arg;
    }
  }

  return options;
}

function printUsage(): void {
  console.error(`
Phase Completion Workflow - Automate project/phase completion

Usage:
  LINEAR_API_KEY=xxx npx tsx phase-complete.ts "<project-name>" [options]

Options:
  --archive    Archive the project after completion
  --force      Complete even if some issues aren't done
  --dry-run    Show what would happen without making changes

Examples:
  # Complete a phase
  npx tsx phase-complete.ts "Phase 1: Foundation"

  # Complete and archive
  npx tsx phase-complete.ts "Phase 1" --archive

  # Force complete with incomplete issues
  npx tsx phase-complete.ts "Phase 1" --force

  # Preview what would happen
  npx tsx phase-complete.ts "Phase 1" --dry-run
`);
}

async function findProjectByName(
  client: LinearClient,
  searchName: string
): Promise<Project | null> {
  // Use shared utility for case-insensitive lookup with exact match preference
  const projectInfo = await findProjectByNameBase(client, searchName);

  if (!projectInfo) {
    return null;
  }

  // Fetch full project details with issues
  return fetchProjectDetails(client, projectInfo.id);
}

async function fetchProjectDetailsOptimized(
  client: LinearClient,
  projectId: string
): Promise<Project> {
  // Single GraphQL query to fetch project + status + issues with states
  const result = await client.client.rawRequest<{
    project: {
      id: string;
      name: string;
      slugId: string;
      status: { id: string; name: string; type: string } | null;
      issues: {
        nodes: Array<{
          identifier: string;
          title: string;
          state: { name: string; type: string } | null;
        }>;
      };
    };
  }, { projectId: string }>(
    `
    query GetProjectDetails($projectId: String!) {
      project(id: $projectId) {
        id
        name
        slugId
        status {
          id
          name
          type
        }
        issues {
          nodes {
            identifier
            title
            state {
              name
              type
            }
          }
        }
      }
    }
  `,
    { projectId }
  );

  const project = result.data?.project;
  if (!project) {
    throw new Error(`Project not found: ${projectId}`);
  }

  return {
    id: project.id,
    name: project.name,
    slugId: project.slugId,
    status: project.status
      ? {
          id: project.status.id,
          name: project.status.name,
          type: project.status.type,
        }
      : null,
    issues: {
      nodes: project.issues.nodes.map((issue) => ({
        identifier: issue.identifier,
        title: issue.title,
        state: issue.state
          ? { name: issue.state.name, type: issue.state.type }
          : { name: 'Unknown', type: 'unknown' },
      })),
    },
  };
}

async function fetchProjectDetails(
  client: LinearClient,
  projectId: string
): Promise<Project> {
  return fetchProjectDetailsOptimized(client, projectId);
}

async function getCompletedStatus(
  client: LinearClient
): Promise<ProjectStatus | null> {
  // Fetch all project statuses and find "Completed"
  const result = await client.client.rawRequest<{
    projectStatuses: { nodes: ProjectStatus[] };
  }, Record<string, never>>(`
    query {
      projectStatuses {
        nodes {
          id
          name
          type
        }
      }
    }
  `);

  const statuses = result.data?.projectStatuses?.nodes || [];
  return statuses.find((s) => s.type === 'completed') || null;
}

async function updateProjectStatus(
  client: LinearClient,
  projectId: string,
  statusId: string
): Promise<boolean> {
  const result = await client.client.rawRequest<{
    projectUpdate: { success: boolean };
  }, { id: string; statusId: string }>(
    `
    mutation UpdateProjectStatus($id: String!, $statusId: String!) {
      projectUpdate(id: $id, input: { statusId: $statusId }) {
        success
        project {
          name
          status { name }
        }
      }
    }
  `,
    { id: projectId, statusId }
  );

  return result.data?.projectUpdate?.success || false;
}

async function createProjectUpdate(
  client: LinearClient,
  projectId: string,
  body: string
): Promise<string | null> {
  const result = await client.client.rawRequest<{
    projectUpdateCreate: {
      success: boolean;
      projectUpdate: { id: string; url: string };
    };
  }, { projectId: string; body: string }>(
    `
    mutation CreateProjectUpdate($projectId: String!, $body: String!) {
      projectUpdateCreate(input: {
        projectId: $projectId,
        body: $body,
        health: onTrack
      }) {
        success
        projectUpdate {
          id
          url
        }
      }
    }
  `,
    { projectId, body }
  );

  return result.data?.projectUpdateCreate?.projectUpdate?.url || null;
}

async function archiveProject(
  client: LinearClient,
  projectId: string
): Promise<boolean> {
  const result = await client.client.rawRequest<{
    projectArchive: { success: boolean };
  }, { id: string }>(
    `
    mutation ArchiveProject($id: String!) {
      projectArchive(id: $id) {
        success
      }
    }
  `,
    { id: projectId }
  );

  return result.data?.projectArchive?.success || false;
}

function generateCompletionSummary(project: Project): string {
  const issues = project.issues.nodes;
  const completed = issues.filter((i) => i.state.type === 'completed');
  const cancelled = issues.filter((i) => i.state.type === 'canceled');
  const remaining = issues.filter(
    (i) => i.state.type !== 'completed' && i.state.type !== 'canceled'
  );

  const completedList = completed
    .map((i) => `- ${i.identifier}: ${i.title}`)
    .join('\n');

  const cancelledList =
    cancelled.length > 0
      ? `\n\n### Cancelled\n${cancelled.map((i) => `- ${i.identifier}: ${i.title}`).join('\n')}`
      : '';

  const remainingList =
    remaining.length > 0
      ? `\n\n### Not Completed\n${remaining.map((i) => `- ${i.identifier}: ${i.title} [${i.state.name}]`).join('\n')}`
      : '';

  return `## Phase Completed

**${project.name}** has been marked as completed.

### Summary
- **Total Issues**: ${issues.length}
- **Completed**: ${completed.length}
- **Cancelled**: ${cancelled.length}
${remaining.length > 0 ? `- **Remaining**: ${remaining.length} (force-completed)` : ''}

### Completed Issues
${completedList || '_No issues_'}${cancelledList}${remainingList}

---
_Completed on ${new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}_`;
}

async function main(): Promise<void> {
  const options = parseArgs();

  if (!options.projectName) {
    console.error('Error: Project name is required');
    printUsage();
    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
  }

  let client: LinearClient;
  try {
    client = getLinearClient();
  } catch (error) {
    console.error(`Error: ${(error as Error).message}`);
    printUsage();
    process.exit(EXIT_CODES.MISSING_API_KEY);
  }

  console.log(`\nSearching for project: "${options.projectName}"...`);

  // Step 1: Find project by name
  const project = await findProjectByName(client, options.projectName);

  if (!project) {
    console.error(`\nError: No project found matching "${options.projectName}"`);
    console.error('\nTip: Use partial name matching, e.g., "Phase 1" instead of full name');
    process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
  }

  console.log(`\nFound project: ${project.name}`);
  console.log(`  ID: ${project.id}`);
  console.log(`  Current status: ${project.status?.name || 'None'}`);
  console.log(`  Issues: ${project.issues.nodes.length}`);

  // Step 2: Check issue completion status
  const issues = project.issues.nodes;
  const completedIssues = issues.filter(
    (i) => i.state.type === 'completed' || i.state.type === 'canceled'
  );
  const incompleteIssues = issues.filter(
    (i) => i.state.type !== 'completed' && i.state.type !== 'canceled'
  );

  console.log(`\nIssue Status:`);
  console.log(`  Completed/Cancelled: ${completedIssues.length}/${issues.length}`);

  if (incompleteIssues.length > 0) {
    console.log(`\n  Incomplete issues:`);
    for (const issue of incompleteIssues) {
      console.log(`    - ${issue.identifier}: ${issue.title} [${issue.state.name}]`);
    }

    if (!options.force) {
      console.error(
        `\nError: ${incompleteIssues.length} issues are not completed.`
      );
      console.error('Use --force to complete anyway, or finish the issues first.');
      process.exit(EXIT_CODES.VALIDATION_ERROR);
    }

    console.log('\n  --force flag set, continuing with incomplete issues...');
  }

  // Step 3: Get Completed status
  const completedStatus = await getCompletedStatus(client);

  if (!completedStatus) {
    console.error('\nError: Could not find "Completed" status in workspace');
    process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
  }

  console.log(`\nCompleted status ID: ${completedStatus.id}`);

  // Step 4: Generate completion summary
  const summary = generateCompletionSummary(project);

  if (options.dryRun) {
    console.log('\n--- DRY RUN MODE ---');
    console.log('\nWould perform:');
    console.log(`  1. Update project status to "${completedStatus.name}"`);
    console.log('  2. Create project update with summary:');
    console.log('\n' + summary.split('\n').map((l) => '     ' + l).join('\n'));
    if (options.archive) {
      console.log('  3. Archive the project');
    }
    console.log('\nNo changes made.');
    process.exit(0);
  }

  // Step 5: Update project status
  console.log(`\nUpdating project status to "${completedStatus.name}"...`);
  const statusUpdated = await updateProjectStatus(
    client,
    project.id,
    completedStatus.id
  );

  if (!statusUpdated) {
    console.error('Error: Failed to update project status');
    process.exit(EXIT_CODES.API_ERROR);
  }
  console.log('  Status updated successfully');

  // Step 6: Create project update
  console.log('\nCreating completion summary...');
  const updateUrl = await createProjectUpdate(client, project.id, summary);

  if (updateUrl) {
    console.log(`  Project update created: ${updateUrl}`);
  } else {
    console.log('  Project update created (no URL returned)');
  }

  // Step 7: Archive if requested
  if (options.archive) {
    console.log('\nArchiving project...');
    const archived = await archiveProject(client, project.id);

    if (archived) {
      console.log('  Project archived successfully');
    } else {
      console.error('  Warning: Failed to archive project');
    }
  }

  console.log('\n--- Phase Completion Successful ---');
  console.log(`Project "${project.name}" is now marked as Completed.`);
}

main().catch((error) => {
  console.error('Error:', error.message);
  if (error.errors) {
    console.error('GraphQL Errors:', JSON.stringify(error.errors, null, 2));
  }
  process.exit(EXIT_CODES.API_ERROR);
});
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