Plan iOS implementation work from Linear boards, projects, or issues by fetching task details (title, description, attachments, design links, comments) via the Linear API, saving workspace context for reuse, and producing a Markdown implementation plan for developers.
Plan iOS implementation from Linear tasks with repeatable data collection and a consistent Markdown plan output.
Example invocation:
$linear-task-planner SKI-1
In this mode, use the API token flow by default and map the issue key to --identifier.
--identifier expects the Linear key format TEAM-123 and is resolved via the team key + issue number filter.
Collect these once per workspace/board and save them for future use:
token or mcp)raw for personal API key or bearer for OAuth)Save to a local config file (repo root): .linear-task-planner.json.
Add it to .gitignore to avoid committing workspace details.
Use the helper script to initialize or update it:
python3 skills/linear-task-planner/scripts/linear_fetch.py init \
--workspace "your-workspace" \
--team-key "ENG" \
--team-id "team-id" \
--project-id "project-id" \
--board-url "https://linear.app/your-workspace/team/ENG" \
--env ".env.local" \
--auth-mode token \
--auth-scheme raw
When starting a plan, ask the developer which auth mode they prefer:
LINEAR_API_TOKEN from the env file.authMode=mcp + mcpServer.If authMode=mcp, do not use linear_fetch.py. Instead, call the MCP server for Linear and request the same fields as the GraphQL queries in references/issue.graphql, references/project.graphql, and references/team.graphql.
Expect LINEAR_API_TOKEN in a local env file (e.g., .env.local, .env).
Use .env.local.example as a template.
--env on commands when the env file is not .env.local or .env.--env before or after the subcommand.Use the helper script to pull issue or project data into JSON.
Issue data (include comments and attachments):
python3 skills/linear-task-planner/scripts/linear_fetch.py issue \
--identifier "ENG-123" \
--env .env.local \
--details \
--out plans/ENG-123.json
If you are using OAuth tokens, set the auth scheme:
python3 skills/linear-task-planner/scripts/linear_fetch.py issue \
--identifier "ENG-123" \
--details \
--auth-scheme bearer \
--out plans/ENG-123.json
Project data (list issues, then pick the target issue):
python3 skills/linear-task-planner/scripts/linear_fetch.py project \
--id "project-id" \
--first 50 \
--out plans/project.json
Team data (board view / backlog):
python3 skills/linear-task-planner/scripts/linear_fetch.py team \
--id "team-id" \
--first 50 \
--out plans/team.json
If a query fails due to schema changes, use the custom query path and adjust fields via the GraphQL explorer:
python3 skills/linear-task-planner/scripts/linear_fetch.py custom \
--query skills/linear-task-planner/references/issue.graphql \
--variables '{"issueId": "..."}'
Use the template in references/plan-template.md. Populate it with:
Save the plan in plans/{issue-identifier}.md (create plans/ if missing).
Always attempt to collect these fields before planning:
When you write the plan, explicitly map decisions to the existing skills:
swiftui-guidelines for state management, async patterns, and view organizationswift-concurrency-expert for actor isolation, Sendable, and data-race safetyswiftui-performance-audit for avoiding heavy work in body and identity stabilityswiftui-ui-patterns for NavigationStack, lists/grids, sheets, and app wiringswiftui-view-refactor for consistent view structure and MV-first patternsswiftui-liquid-glass if iOS 26+ glass UI is in scope (include fallbacks)If any of these introduce constraints or tradeoffs, capture them in the plan under “Risks & Dependencies” or “Open Questions.”
Read the source skills as needed for detailed guidance:
skills/swift-concurrency-expert/SKILL.mdskills/swiftui-guidelines/SKILL.mdskills/swiftui-liquid-glass/SKILL.mdskills/swiftui-performance-audit/SKILL.mdskills/swiftui-ui-patterns/SKILL.mdskills/swiftui-view-refactor/SKILL.mdreferences/linear-queries.md for query templates and field suggestionsreferences/auth.md for API token guidance and auth-mode notesreferences/issue.graphql, references/project.graphql, references/team.graphql for runnable queriesreferences/plan-template.md for the Markdown plan skeletonskills/swift-concurrency-expert/SKILL.md for concurrency best practicesskills/swiftui-guidelines/SKILL.md for SwiftUI state/data flow and async patternsskills/swiftui-liquid-glass/SKILL.md for iOS 26+ glass UI guidanceskills/swiftui-performance-audit/SKILL.md for performance checklistsskills/swiftui-ui-patterns/SKILL.md for UI scaffolding patternsskills/swiftui-view-refactor/SKILL.md for view structure conventions