Skip to content

v0.1.0 — spec-kit ↔ Linear bridge

Choose a tag to compare

View all tags
@ashbrener ashbrener released this 28 May 15:42
· 54 commits to main since this release
v0.1.0
3f6be46
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Mirror every spec on disk into a Linear Issue — the filesystem stays the single source of truth, Linear is the read-only mirror.

The bridge installs via specify extension add linear and attaches to spec-kit's own after_* hooks plus local git hooks plus a GitHub Actions webhook. Every /speckit.* lifecycle command keeps Linear in sync without re-running anything.

Highlights

  • 🔁 Reconcile-based, never event-push. Every reconcile rebuilds Linear from disk. Re-running on unchanged state produces zero churn (SC-002).
  • 🏷 5 commands: /speckit.linear.install, .seed, .push, .status, .pull. Push fires automatically on every spec-kit hook; the other four are operator escape hatches.
  • 📋 Filesystem ↔ Linear mapping: repo → Project, spec → Issue, task phase → sub-issue, tasks → checklist mirror, clarify sessions → comments, lifecycle phase → workflow state + phase:* label.
  • 🧠 Memory block auto-managed on every spec Issue: current phase / branch / worktree(s) / last-touched / GitHub link, rewritten every reconcile.
  • 🔢 Fibonacci [N] story-point markers on task lines roll up to Linear's estimate field (per-phase + spec rollup).
  • 🤖 Agent identity stamping — agent:claude / agent:codex workspace labels let you filter the kanban by which AI agent did the work. Sticky — once applied, never removed.
  • 👤 Operator captured at install as Linear assigneeId on every issueCreate (single-write-on-create — manual reassignment in Linear's UI persists).
  • 🚧 Write-authority gate: only the worktree on a spec's feature branch may mutate that spec's Linear Issue. Other worktrees' syncs are read-only for that spec.
  • 🚀 Layer D + Layer E: local reconciler + GitHub Action webhook are independently idempotent. Either alone keeps Linear converging.

Architectural posture

  • No daemons, no databases, no filesystem watchers, no crons. Bash + curl + jq + gh + git only.
  • Filesystem wins every conflict. Unidirectional sync — bridge never writes back to disk.
  • Constitution v1.0.0 ratified — 8 principles. Pre-release audit: 7 Conform / 1 caveat / 0 Drift.

Performance

Workload Measured Target Headroom
N=10 specs cold reconcile 0.992s ≤30s (SC-007) ~30×
N=10 specs hot reconcile 0.840s ≤5s (SC-008) ~6×

Install

specify extension add linear

Then /speckit.linear.install (interactive ceremony) → /speckit.linear.seed (one-shot workspace setup) → use spec-kit as normal.

See README.md for the full adopt-in-3-steps walkthrough.

CI matrix

Bats unit + integration suites pass across:

  • ubuntu-latest × bash 4.4
  • ubuntu-latest × bash 5.2
  • macos-latest × bash 5.2

(macOS × bash 4.4 excluded — bash 4.4 source doesn't compile against Xcode 16.4 SDK; documented inline in .github/workflows/ci.yml.)

Acknowledgements

Designed and dogfooded against the OSH-INFRA Linear workspace, alongside the sibling spec-kit-red-team extension.

Assets 2
Loading