linear-core-workflow-b

name	linear-core-workflow-b
description	Project and cycle management workflows with Linear. Use when implementing sprint planning, managing projects and roadmaps, or organizing work into cycles. Trigger with phrases like "linear project", "linear cycle", "linear sprint", "linear roadmap", "linear planning", "organize linear work".
allowed-tools	Read, Write, Edit, Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Linear Core Workflow B: Projects & Cycles

Overview

Manage projects, cycles (sprints), and roadmaps using the Linear API.

Prerequisites

• Linear SDK configured
• Understanding of Linear's project hierarchy
• Team access with project permissions

Instructions

Step 1: Project Management

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

// List all projects
async function getProjects(teamKey?: string) {
  const filter = teamKey
    ? { accessibleTeams: { some: { key: { eq: teamKey } } } }
    : undefined;

  const projects = await client.projects({ filter });
  return projects.nodes;
}

// Create a project
async function createProject(options: {
  name: string;
  description?: string;
  teamIds: string[];
  targetDate?: Date;
  state?: "planned" | "started" | "paused" | "completed" | "canceled";
}) {
  const result = await client.createProject({
    name: options.name,
    description: options.description,
    teamIds: options.teamIds,
    targetDate: options.targetDate?.toISOString(),
    state: options.state ?? "planned",
  });

  return result.project;
}

// Update project status
async function updateProjectStatus(
  projectId: string,
  status: "planned" | "started" | "paused" | "completed" | "canceled"
) {
  return client.updateProject(projectId, { state: status });
}

Step 2: Cycle (Sprint) Management

// Get current and upcoming cycles
async function getActiveCycles(teamKey: string) {
  const teams = await client.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];

  const now = new Date().toISOString();
  const cycles = await team.cycles({
    filter: {
      or: [
        { endsAt: { gte: now } }, // Current or future
        { startsAt: { gte: now } }, // Future
      ],
    },
    orderBy: "startsAt",
  });

  return cycles.nodes;
}

// Create a new cycle
async function createCycle(options: {
  teamId: string;
  name?: string;
  startsAt: Date;
  endsAt: Date;
}) {
  const result = await client.createCycle({
    teamId: options.teamId,
    name: options.name,
    : options..(),
    : options..(),
  });

   result.;
}


  () {
   results =  .(
    issueIds.(
      client.(issueId, { cycleId })
    )
  );

   results.( r.).;
}


  () {
   cycle =  client.(cycleId);
   issues =  cycle.();

   states =  <, >();
   totalEstimate = ;
   completedEstimate = ;

   ( issue  issues.) {
     state =  issue.;
     stateName = state?. ?? ;
    states.(stateName, (states.(stateName) ?? ) + );

    totalEstimate += issue. ?? ;
     (state?. === ) {
      completedEstimate += issue. ?? ;
    }
  }

   {
    : issues..,
    : .(states),
    totalEstimate,
    completedEstimate,
    : totalEstimate ? completedEstimate / totalEstimate : ,
  };
}

Step 3: Roadmap Operations

// Get roadmap items (projects with milestones)
async function getRoadmap(options?: {
  includeCompleted?: boolean;
  monthsAhead?: number;
}) {
  const futureDate = new Date();
  futureDate.setMonth(futureDate.getMonth() + (options?.monthsAhead ?? 6));

  const filter: Record<string, unknown> = {
    targetDate: { lte: futureDate.toISOString() },
  };

  if (!options?.includeCompleted) {
    filter.state = { neq: "completed" };
  }

  const projects = await client.projects({
    filter,
    orderBy: "targetDate",
  });

  return projects.nodes.map(p => ({
    id: p.id,
    name: p.name,
    state: p.state,
    targetDate: p.targetDate,
    progress: p.progress,
  }));
}

// Create project milestone
async function () {
   client.({
    : options.,
    : options.,
    : options..(),
  });
}

Step 4: Planning Utilities

// Move unfinished issues to next cycle
async function rolloverCycle(fromCycleId: string, toCycleId: string) {
  const fromCycle = await client.cycle(fromCycleId);
  const issues = await fromCycle.issues({
    filter: {
      state: { type: { nin: ["completed", "canceled"] } },
    },
  });

  const movedCount = await addIssuesToCycle(
    issues.nodes.map(i => i.id),
    toCycleId
  );

  return { movedCount, totalUnfinished: issues.nodes.length };
}

// Calculate team velocity
async function calculateVelocity(teamKey: string, cycleCount = 3) {
  const teams = await client.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];

  const cycles = await team.({
    : {
      : { :  }
    },
    : ,
    : cycleCount,
  });

   velocities =  .(
    cycles..( cycle => {
       issues =  cycle.({
        : { : { : { :  } } },
      });
       issues..( sum + (i. ?? ), );
    })
  );

   avgVelocity = velocities.( a + b, ) / velocities.;

   {
    velocities,
    : .(avgVelocity * ) / ,
  };
}

Output

• Project CRUD operations
• Cycle planning and management
• Roadmap visualization data
• Sprint rollover automation
• Velocity calculations

Error Handling

Error	Cause	Solution
Project not found	Invalid project ID	Verify project exists
Cycle overlap	Dates conflict with existing	Check existing cycles
Permission denied	No project access	Verify team membership
Invalid date range	End before start	Validate date order

Examples

Sprint Planning Flow

async function setupSprint(options: {
  teamKey: string;
  name: string;
  durationDays: number;
  issueIdentifiers: string[];
}) {
  const teams = await client.teams({ filter: { key: { eq: options.teamKey } } });
  const team = teams.nodes[0];

  const startsAt = new Date();
  const endsAt = new Date();
  endsAt.setDate(endsAt.getDate() + options.durationDays);

  // Create cycle
  const cycleResult = await client.createCycle({
    teamId: team.id,
    name: options.name,
    startsAt: startsAt.toISOString(),
    endsAt: endsAt.toISOString(),
  });

  const cycle = await cycleResult.cycle;

  // Add issues
  for (const identifier of options.issueIdentifiers) {
    const issue = await client.issue(identifier);
     client.(issue., { : cycle!. });
  }

   cycle;
}

Resources

• Project Object Reference
• Cycle Object Reference
• Linear Roadmaps

Next Steps

Handle errors effectively with linear-common-errors.