Instructions
You are creating Linear issues from a refined project plan.
Input
- The refined plan file path is passed as $ARGUMENTS
- If no argument provided, look for
docs/project-plan-refined.md
Process
Step 0: Linear Project Setup
Before creating any issues, you must determine the target team and project.
- Detect team:
- Call list_teams to get all teams in the workspace - If exactly 1 team exists, auto-select it and inform the user: "I'll create issues in team '[name]'." - If multiple teams exist, ask the user to pick one using AskUserQuestion with the team names as options - If 0 teams exist, stop and tell the user to create a team in Linear first
- Find or create project:
- Extract the project name from the plan file heading (the # [Project Name] at the top of the refined plan) - Search for existing projects in the selected team using list_projects with that name as a query - Exact match found: Ask the user — "I found an existing project called '[name]'. Should I add issues there, or create a new project?" - Multiple partial matches: Show the matches and ask the user to pick one or create a new project - No match found: Tell the user — "I'll create a new Linear project called '[name]'. Want a different name?" Wait for confirmation, then create the project using create_project
- Confirm and proceed: Summarize the setup — "Creating issues in team '[team]', project '[project]'." Then continue to issue creation below.
Step 1: Create Issues
- Read the refined plan and parse all tasks
- For each task, create a Linear issue with:
- Team: The team selected in Step 0 - Project: The project confirmed/created in Step 0 - Title: From the task title - Description: Combine the Context, Steps, and Validation sections into a well-structured issue body. Format it so that an AI agent receiving this issue has everything it needs: - "## Context" — background and architectural decisions - "## Implementation Steps" — the numbered steps - "## Validation Criteria" — how to verify completion - "## Dependencies" — links to dependent issues (add after all issues are created) - Labels: Add complexity label (S/M/L) - Priority: Derive from dependency order (earlier = higher)
- After all issues are created:
- Go back and update dependency references to use actual Linear issue IDs/links - Set parent/sub-issue relationships where appropriate
- Update the refined plan file:
- Add the Linear issue ID next to each task title - Add a "Linear Project" link at the top of the document
Output
- Linear issues created and linked
- Updated
docs/project-plan-refined.mdwith issue IDs - Write a summary to
docs/linear-issues-created.mdcontaining:
- Total issues created - Issue ID → Task title mapping - Any issues that needed special handling
Validation Criteria
Read .claude/skills/_shared/validation-pattern.md and apply it. Specific criteria for this skill:
- Every task in the refined plan has a corresponding Linear issue
- Each issue's description contains Context, Implementation Steps, and Validation Criteria sections
- Read each issue back from Linear via MCP and verify the content matches what was intended
- Dependencies are correctly linked between issues
- An agent picking up any single issue would have enough context to: understand the task, complete the work, and validate the result
- The refined plan file has been updated with issue IDs