Linear Plan Mode Integration Skill

Linear Plan Mode Integration

When in plan mode, maintain the plan in Linear alongside the plan file. The orchestrator handles all Linear operations directly — never delegate to sub-agents for issue creation or updates.

CRITICAL RULES (ALWAYS FOLLOW)

ALL issues (parent and sub-issues) MUST have status "Todo" - Never use "Triage", "Backlog", or any other status for new issues
Parent issues MUST have the "Feature Root" label - NOT "Feature", always "Feature Root"
Never modify "Done" issues - They represent completed work
Check Linear teams first - If multiple teams exist, ALWAYS ask the user which team to use before creating issues
Orchestrator does ALL Linear work directly - Do NOT spawn sub-agents for Linear operations. ToolSearch and MCP tools work in plan mode.

Key Principle

All Linear MCP tools work in plan mode. The orchestrator can call ToolSearch, mcp__linear__create_issue, mcp__linear__update_issue, and mcp__linear__get_issue directly. No delegation needed.

Workflow

Phase 1: Plan Mode Entry

When entering plan mode for any task:

Ask the user if this plan should be tracked in Linear
If yes, load Linear tools directly:
```
ToolSearch: "+linear create issue"
```
Check for existing parent issue using mcp__linear__get_issue (if issue ID is known) or mcp__linear__search_issues

If no existing issue, create one directly:

mcp__linear__create_issue(
  title: "[feature title]",
  team: "LaserFocused",
  state: "Todo",
  labels: ["Feature Root"],
  description: "[plan overview]"
)

Phase 2: Plan Development (Sync as You Go)

As you write/edit the plan file, keep Linear in sync by calling MCP tools directly:

| Plan File Change | Linear Action | |------------------|---------------| | New section added | mcp__linear__create_issue with parentId | | Section modified | mcp__linear__update_issue with updated description | | Section removed | mcp__linear__update_issue to set state "Canceled" (with user confirmation) |

Example — creating a sub-issue directly:

mcp__linear__create_issue(
  title: "[Backend] Add student results API endpoint",
  team: "LaserFocused",
  parentId: "<parent-uuid>",
  state: "Todo",
  description: "## Acceptance Criteria\n- [ ] GET endpoint returns student answers\n- [ ] Includes audio URLs\n\n## Depends on\nLAS-XXX (migration)"
)

Phase 3: Plan Finalization

Before calling ExitPlanMode:

Ensure all plan sections have corresponding Linear sub-issues
Parent issue has high-level overview with Mermaid diagram
All sub-issues are in "Todo" status ready for execution
Sub-issue IDs are recorded in the plan file

Linear Issue Structure

Parent Issue (Feature Root)

Parent issues MUST have the "Feature Root" label and follow this structure:

## IMPORTANT
This feature is tracked in Linear. Before starting work:
- Find your assigned sub-issue
- Mark it "In Progress" before coding
- Mark it "Done" when complete

## Problem
[What problem we're solving]

## Solution Overview
[High-level approach - 2-3 paragraphs max]

## High-Level Flow
```mermaid
flowchart TD
    A[User Action] --> B[System Response]
    B --> C[Result]

MVP Scope

In Scope:

[Essential item 1]
[Essential item 2]

Out of Scope (Deferred):

[Nice-to-have 1]
[Nice-to-have 2]

Sub-Issues

[Auto-generated list of child issues]


### Sub-Issues (Tagged by Layer)

Each sub-issue title is prefixed with its layer tag:

| Tag | Meaning |
|-----|---------|
| `[Backend]` | Express API, services, repositories |
| `[Frontend]` | React components, pages, hooks |
| `[Migration]` | Database schema changes |
| `[Both]` | Spans backend and frontend |

Sub-issue description format:
```markdown
## Context
[Brief context linking to parent feature]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes
[Implementation hints, patterns to follow]

## Dependencies
Depends on: LAS-XXX (if applicable)

Mermaid Diagrams

Use diagrams to visualize flows and relationships:

| Context | Diagram Type | When to Use | |---------|--------------|-------------| | Parent issue | flowchart TD | Main user/data flow (REQUIRED) | | API endpoints | sequenceDiagram | Service interactions | | State machines | stateDiagram-v2 | Status workflows | | Data models | erDiagram | Entity relationships |

For detailed templates, see mermaid-templates.md.

Key Constraints

Orchestrator does ALL Linear work — never delegate to sub-agents or linear-manager for issue creation
Never modify "Done" issues — They represent completed work
Confirm before canceling — Ask user before canceling "In Progress" issues
Todo status only — ALL new issues MUST start as "Todo"
"Feature Root" label (not "Feature") — Parent issues ALWAYS get the "Feature Root" label
linear-manager is for implementation only — It tracks status during Phase 5, not during planning

Quick Reference

Load Linear tools:

ToolSearch: "+linear create issue"

Create parent issue:

mcp__linear__create_issue(
  title: "Feature title",
  team: "LaserFocused",
  state: "Todo",
  labels: ["Feature Root"],
  description: "[plan overview with mermaid diagram]"
)

Create sub-issue:

mcp__linear__create_issue(
  title: "[Backend] Step description",
  team: "LaserFocused",
  parentId: "<parent-uuid>",
  state: "Todo",
  description: "[acceptance criteria + dependencies]"
)

Update issue:

mcp__linear__update_issue(
  issueId: "<uuid>",
  description: "[updated content]"
)

For detailed sync patterns, see sync-patterns.md.

Agent Skills: Linear Plan Mode Integration

Install this agent skill to your local

Skill Files