In my earlier article, I walked through keeping a Linear backlog in sync with OpenSpec as an agent moved a change through Propose, Apply, and Archive. That workflow worked, but it relied on modifying OpenSpec itself.

This revisit achieves the same workflow without touching OpenSpec at all. The Linear sync now lives entirely in a skill — openspec-linearized — that runs on stock OpenSpec.

What the Skill Does

The skill overlays Linear issue management onto the OpenSpec change lifecycle while keeping a clear ownership boundary:

  • Linear owns the business context — goals, acceptance criteria, and stakeholder-facing status.
  • The repository owns the technical design and implementation.

Initial Configuration

In order to let the coding agent know about which Linear project, team and label we want to associate this repository with, the skill asks us for the details and stores them in openspec/linear.yaml. Once this file is created when we subsequently ask the coding agent to pick up an issue from Linear, it exactly knows where to look.

Mapping Linear issue status with OpenSpec change proposal phases

  • Propose — Binds a Linear Backlog issue as the business brief, and moves it to Todo. proposal.md stays lean, with Linear metadata in its frontmatter.
  • Apply — Moves the story to In Progress while the tasks are implemented.
  • Archive — Completes the OpenSpec archive first, then mirrors the finalized specs into Linear Project Documents (titled OpenSpec: <capability>) and moves the issue to Done.

Video Walkthrough

References