create-plan-linear

name	create-plan-linear
description	Create detailed implementation plans with codebase research and, after explicit user approval, publish the approved phased plan to Linear by creating a project under a chosen initiative plus phase and subphase issues assigned to a user chosen at runtime.
argument-hint	[ticket-or-file-path]

Create Plan Linear

Create a detailed implementation plan first. Only after explicit user approval, create a matching Linear project and issues.

Intake

• Read any provided ticket, plan, or file paths fully before planning.
• If key inputs are missing, ask for them: objective, constraints, references, preferred project name, target assignee, and plan file path.
• Capture initiative and team context early when available.
• Ask only questions that cannot be answered from the codebase or provided context.

Research

• Read all mentioned files completely; avoid partial reads.
• Use Grep/Glob for quick targeted lookups.
• Spawn parallel sub-agents via the Task tool for deeper investigation:
  • codebase-analyzer — understand how specific components work (data flow, logic, patterns)
  • codebase-pattern-finder — find similar implementations or conventions to model after
  • thoughts-analyzer — deep-dive on research docs in thoughts/ for prior decisions
  • thoughts-locator — discover relevant documents in thoughts/ directory
  • web-search-researcher — research external APIs, libraries, or technologies
• Gather MCP context before planning:
  • Call list_mcp_resources and list_mcp_resource_templates.
  • Read relevant resources such as tickets, docs, and runbooks.
• Spawn multiple sub-agents in parallel for efficiency; wait for all to complete before synthesizing.

Plan Development

• Build a phased implementation plan with clear top-level phases and explicit subphases where needed.
• Use file:line references for current-state analysis and proposed edits.
• Keep automated and manual verification sections separate.
• Use project-standard commands for build/test/lint/docs.
• Save the plan to <repo_root>/thoughts/shared/plans/<YYYY-MM-DD>-<name>.md.

Plan Template

# [Feature/Task Name] Implementation Plan

## Overview
[What we are implementing and why]

## Current State Analysis
[What exists now, what is missing, constraints; include file:line references]

## Desired End State
[What "done" looks like and how to verify it]

## What We Are Not Doing
[Explicit out-of-scope list]

## Implementation Approach
[High-level strategy and rationale]

## Phase 1: [Descriptive Name]
[What this phase accomplishes]

### Changes Required
- File: `path/to/file.ext` (file:line)
- Summary of edits

### Success Criteria

#### Automated Verification
- [ ] Command or test that must pass

#### Manual Verification
- [ ] Human validation steps

**Implementation Note**: After completing this phase and automated verification, pause for manual confirmation before proceeding.

---

## Phase 2: [Descriptive Name]
[Repeat structure]

---

## Testing Strategy
- Unit tests
- Integration tests
- Manual testing steps

## Performance Considerations
[Implications and mitigations]

## Migration Notes
[If applicable]

## References
- Ticket or request reference
- Related research docs
- Similar implementations (file:line)

Approval Gate (Mandatory)

• After drafting the plan, stop and request explicit approval.
• Use a direct approval question, for example:
  • I created the plan at <path>. Approve syncing this plan to Linear?
• Do not create or modify Linear projects, issues, labels, or comments before approval.
• If the user requests edits, revise the plan and request approval again.

Linear Sync Workflow (Run Only After Approval)

1. Resolve initiative

• If the initiative name is missing, ask the user for it.
• Use mcp__linear__get_initiative (or list/search equivalents) to resolve it.
• If multiple initiatives match, ask the user to choose.

2. Resolve team

• Prefer a team provided by the user.
• If missing, infer from initiative context when possible.
• If still unclear, ask the user for the target Linear team before creating anything.

3. Create project (epic)

• Use mcp__linear__create_project.
• Set name to the project name.
• Set initiative to the resolved initiative.
• Set team to the resolved team.
• Set description to the full approved plan markdown.
• Set summary to a concise one-line overview from the plan.

4. Resolve assignee

• Ask the user which assignee to use if not already provided.
• Resolve the provided assignee via mcp__linear__get_user.
• If no exact match is found, ask the user to confirm the intended user before creating issues.

5. Prepare labels and severity

• Derive labels from phase scope (for example: consensus, execution, networking, docs, testing).
• For each required label:
  • Check existing labels via mcp__linear__list_issue_labels.
  • Create missing labels via mcp__linear__create_issue_label.
• Apply severity to each issue using both priority and a severity label.
• Default severity mapping:
  • critical -> priority 1, label severity:critical
  • high -> priority 2, label severity:high
  • medium -> priority 3, label severity:medium
  • low -> priority 4, label severity:low
• If severity is unclear from the plan, default to medium.

6. Create phase issues

• Create one Linear issue per top-level phase under the created project.
• Set issue title to the phase title.
• Set issue description to the phase plan content (scope, changes, and success criteria).
• Assign each issue to the resolved assignee.
• Add derived labels, severity label, and priority.

7. Create subphase sub-issues

• For each subphase under a phase, create a child issue with parentId set to the parent phase issue.
• Use subphase title for the child issue title.
• Use subphase details for description.
• Apply the same assignment, labels, and severity policy unless subphase context implies a different severity.

8. Return sync summary

• Report created project identifier/name.
• Report each created phase issue and sub-issue with identifiers.
• Report the plan file path used for sync.
• Call out any assumptions made (team inference, severity defaults, inferred labels).

Execution Rules

• Never skip the user approval gate.
• Never proceed with ambiguous initiative/team/assignee without clarifying.
• Keep issue text grounded in the approved plan; do not invent new scope.
• Prefer deterministic, auditable mappings from plan phase to Linear issue.