Easy Project To Linear

Analyze your project requirements and automatically create a structured hierarchy of epics, tasks, and subtasks in your Linear workspace using the Linear MCP integration.

When to Use This Command

Run this command when...

• You are starting a new project and want to populate Linear with a complete task hierarchy derived from your codebase and documentation
• You need to break down a project README or requirements document into actionable Linear issues with proper labeling
• You want to establish dependency relationships and critical path analysis directly in Linear
• You need tasks automatically labeled by area (frontend, backend, testing, documentation) with priority and effort estimates
• You are migrating from ad-hoc tracking to Linear and want a structured initial import

Quick Start

Copy
# .claude/commands/easy-project-to-linear.yaml
name: Easy Project To Linear
description: Sync project structure to Linear workspace
inputs:
  - name: scope
    description: "Project description or path to requirements doc"
  - name: workspace
    description: "Linear workspace or team name"
    default: ""

Copy
# Create Linear tasks from project README
claude "easy-project-to-linear 'Build e-commerce checkout flow'"

# Import from a specific requirements doc
claude "easy-project-to-linear --scope ./docs/requirements.md --workspace 'Engineering'"

Output:
  [analyze] Parsed project requirements...
  [breakdown] Identified 3 epics, 12 tasks, 28 subtasks
  [linear] Connected to Linear workspace: Engineering
  [create] Created:
    Epic: User Authentication (4 tasks, 8 subtasks)
    Epic: Product Catalog (5 tasks, 12 subtasks)
    Epic: Checkout Flow (3 tasks, 8 subtasks)
  [deps] Linked 6 dependency relationships
  Done. 43 items created in Linear.

Core Concepts

Concept	Description
Requirement Analysis	Parses project descriptions, README files, and documentation to extract features and tasks
Hierarchical Breakdown	Organizes work into epics (major features), tasks (deliverables), and subtasks (action items)
Auto-Labeling	Tags each task with area labels: frontend, backend, testing, documentation, infrastructure
Dependency Mapping	Identifies which tasks depend on others and creates Linear relationships accordingly
Effort Estimation	Assigns priority levels and story point estimates based on task complexity analysis

Linear Hierarchy:
  Project
  ├── Epic: User Authentication
  │   ├── Task: Login API endpoint
  │   │   ├── Subtask: JWT token generation
  │   │   └── Subtask: Password hashing
  │   └── Task: Registration form
  │       ├── Subtask: Email validation
  │       └── Subtask: Terms acceptance
  └── Epic: Product Catalog
      └── ...

Configuration

Parameter	Type	Default	Description
scope	string	required	Project description, requirements file path, or feature summary
workspace	string	auto-detected	Linear workspace or team to create issues in
labels	boolean	true	Auto-apply area labels (frontend, backend, testing, docs)
estimates	boolean	true	Include effort estimates and priority assignments
dry_run	boolean	false	Preview the structure without creating Linear issues

Best Practices

1. Use dry run first -- Preview the generated structure with --dry-run before creating issues in Linear. This lets you adjust the scope or breakdown before committing to the workspace.
2. Provide detailed scope descriptions -- The more specific your project description, the better the task breakdown. Include technology choices, user stories, and acceptance criteria.
3. Review and adjust priorities -- Auto-generated priorities are estimates. Walk through the created issues with your team and adjust based on business context and technical risk.
4. Add acceptance criteria to epics -- After creation, enhance each epic with specific acceptance criteria so the team has a clear definition of done.
5. Run incrementally for large projects -- Break massive projects into phases and run the command once per phase to keep Linear manageable and avoid overwhelming the team.

Common Issues

1. Linear MCP not configured -- This command requires the Linear MCP server to be available. Ensure your Linear API key is configured in the MCP settings before running.
2. Too many tasks generated -- Broad project descriptions produce large task lists. Narrow the scope or use --dry-run to preview and then refine your input before creating issues.
3. Duplicate issues on re-run -- Running the command twice with the same scope creates duplicate issues. Check Linear for existing items or delete them before re-running.