Documentation
Guides
Linear Integration

Linear Integration

SpecWright integrates with Linear (opens in a new tab) to sync your projects and issues. Push specification-backed tasks directly to your Linear workspace so your team can track implementation alongside your existing workflow.

What gets synced

When you push a SpecWright project to Linear, the full specification package is synced:

  • Project — Created in your Linear team with name and description
  • Specification documents — PRD, Design Brief, and Technical Specification attached as Linear documents
  • Issues — All implementation tasks created as Linear issues with full context
  • Dependencies — Blocking relationships between issues are set up in Linear
  • External links — A "SpecWright Resources" document with links to Screen Designs, Technology Choices, Acceptance Criteria, and the full project overview

Setting up

Open Settings

Launch the Web UI (specwright view) and navigate to Settings from the sidebar.

Enter your Linear API key

In the Linear section, enter your personal API key. You can generate one from Linear Settings → API (opens in a new tab).

SpecWright validates your API key before saving. The key needs read/write access to issues, projects, and documents.

Select your team

After validation, SpecWright fetches your available Linear teams. Select the team that should receive your projects and issues.

The sync process

When you click "Sync to Linear" on a project, SpecWright executes a 6-step sync:

  1. Create Linear project — A project in your selected team with the SpecWright project name and description
  2. Sync PRD — Attaches the Product Requirements Document as a Linear document
  3. Sync Design Brief — Attaches the design specification as a Linear document
  4. Sync Technical Specification — Attaches the architecture document as a Linear document
  5. Create issues — Creates a Linear issue for each SpecWright issue with full context
  6. Set up dependencies — Creates blocking relationships between issues that match SpecWright's dependency chain

What issues look like in Linear

Each synced issue includes:

  • Title — The issue title from SpecWright
  • Description — Rich Markdown with all fields: key decisions, acceptance criteria, technical details, testing strategy, dependencies
  • Priority — Mapped from estimated hours (default: Normal)
  • Estimate — Fibonacci story points derived from estimated hours:
Estimated hoursStory points
1-2h1
2-4h2
4-6h3
6-10h5
10-16h8
16-24h13
24h+21

External links

SpecWright creates a "SpecWright Resources" attachment on the Linear project with links to:

  • Screen Designs (visual wireframes in the Web UI)
  • Technology Choices (decision matrix in the Web UI)
  • Acceptance Criteria (testable criteria viewer)
  • Full Project Overview (complete project in the Web UI)

These are localhost links (http://localhost:5174/...) — they work when SpecWright is running locally.

Sync state tracking

After syncing, SpecWright saves a linear_sync.json file in the project directory. This tracks:

  • When the sync happened
  • The Linear project ID and URL
  • Mappings between SpecWright issue IDs and Linear issue IDs
  • Mappings between SpecWright documents and Linear document IDs

This prevents duplicate syncs and enables future re-sync capabilities.

What's next?

Ship to AI ToolsPlaybooks & Standards