Linear Plan Mode

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)

1. ALL issues (parent and sub-issues) MUST have status "Todo" - Never use "Triage", "Backlog", or any other status for new issues
2. Parent issues MUST have the "Feature Root" label - NOT "Feature", always "Feature Root"
3. Never modify "Done" issues - They represent completed work
4. Check Linear teams first - If multiple teams exist, ALWAYS ask the user which team to use before creating issues
5. 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:

1. Ask the user if this plan should be tracked in Linear
2. If yes, load Linear tools directly:

   ToolSearch: "+linear create issue"
   

3. Check for existing parent issue using mcp__linear__get_issue (if issue ID is known) or mcp__linear__search_issues
4. 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:

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:

1. Ensure all plan sections have corresponding Linear sub-issues
2. Parent issue has high-level overview with Mermaid diagram
3. All sub-issues are in "Todo" status ready for execution
4. 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:

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.