[Extension]: Add linear

[derobiwan]

Extension ID

linear

Extension Name

Linear Storage Backend

Version

1.0.0

Description

Persists Spec-Driven Development artifacts (spec, plan, tasks, research, contracts, checklists, constitution) as Linear issues via the official Linear MCP server. Replaces local file storage; designed to be paired with the 'linear' preset.

Author

speckit-linear (derobiwan)

Repository URL

https://github.com/derobiwan/speckit-linear

Download URL

https://github.com/derobiwan/speckit-linear/archive/refs/tags/v1.0.0.zip

License

MIT

Homepage (optional)

https://github.com/derobiwan/speckit-linear

Documentation URL (optional)

https://github.com/derobiwan/speckit-linear/blob/main/README.md

Changelog URL (optional)

https://github.com/derobiwan/speckit-linear/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.8.0

Required Tools (optional)

• Linear MCP server — configured via claude mcp add -s user --transport http linear https://mcp.linear.app/mcp (required)

Number of Commands

16

Number of Hooks (optional)

18

Tags

linear, mcp, project-management, issue-tracking, spec-driven-development

Key Features

• Linear-as-storage-backend: all Spec-Driven Development artifacts ([CONSTITUTION], [SPEC], [PLAN], [RESEARCH], [DATA-MODEL], [CONTRACT], [QUICKSTART], [CHECKLIST], individual tasks) become Linear issues — no local specs/ directory created
• Dual-label convention: every issue carries one speckit:<type> label plus a feature:NNN-name label, enabling filtering all issues for one feature
• Idempotent on every command: re-running /speckit.specify, /speckit.plan, etc. updates in place rather than creating duplicates (FR-031, non-negotiable)
• Bounded retry: 3 attempts with 1s/2s/4s ±25% jitter on 5xx/429/timeout; 4xx surfaces immediately (FR-032)
• Structured JSON Lines logging: every MCP attempt → .specify/logs/linear-mcp.log with secrets scrubbed (FR-034)
• Backend confirmation banner: [linear] backend=Linear workspace=<name> project=<name> printed once per process on stderr
• Canonical Spec Kit sequence enforcement: every preset command body carries a Workflow Position (MANDATORY) block that aborts if a required predecessor artifact is missing
• 30 supported AI agent integrations via specify init --ai <agent> --extension linear --preset linear
• Namespaced maintenance commands: /speckit.linear.repair, /speckit.linear.baseline, /speckit.linear.migrate, /speckit.linear.upgrade-from-v051

Testing Checklist

• Extension follows extension.yml schema specification
• README.md with installation and usage instructions
• LICENSE file included (MIT)
• GitHub release created with version tag (v1.0.0)
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• macOS 14+ with Spec Kit v0.8.10
• Linux Ubuntu 22.04 with Spec Kit v0.8.10
• Python 3.11+ (matches upstream requires-python)

Test project: github.com/derobiwan/speckit-linear (self-hosted feature: feature:053-community-catalog-publish)

Test scenarios:

1. specify init --ai claude --extension linear --preset linear against a fresh project — completes successfully; .specify/extensions.yml and .specify/config/linear.md both registered
2. /speckit.constitution then /speckit.specify then /speckit.plan then /speckit.tasks then /speckit.implement against a sample feature — full canonical sequence produces 5 plan artifacts + milestone-prefixed task issues in Linear
3. Re-run of /speckit.specify for the same feature — updates the existing [SPEC] issue in place; no duplicate created (idempotency)
4. Force a 429 from the Linear MCP via rate-limiting — extension retries with 1s/2s/4s backoff and eventually succeeds
5. Scan release artifact with gitleaks detect --source . — 0 findings
6. Run full test suite (pytest) on the v1.0.0 tag — 3268 tests pass, 0 fail

Example Usage

# One-time per machine: configure the Linear MCP server
claude mcp add -s user --transport http linear https://mcp.linear.app/mcp

# In any new project:
specify init --ai claude --extension linear --preset linear

# Then follow the canonical Spec Kit sequence:
/speckit.constitution      # one-time per repo
/speckit.specify "Add user authentication"
/speckit.clarify           # optional, before plan
/speckit.plan
/speckit.checklist         # optional, after plan
/speckit.tasks
/speckit.analyze           # optional, after tasks
/speckit.implement

All artifacts persist as Linear issues with dual labels (speckit:spec + feature:NNN-name). No local specs/ directory is created.

Proposed Catalog Entry

{
  "linear": {
    "name": "Linear Storage Backend",
    "id": "linear",
    "description": "Persists Spec-Driven Development artifacts (spec, plan, tasks, research, contracts, checklists, constitution) as Linear issues via the official Linear MCP server. Replaces local file storage; designed to be paired with the 'linear' preset.",
    "author": "speckit-linear",
    "version": "1.0.0",
    "download_url": "https://github.com/derobiwan/speckit-linear/archive/refs/tags/v1.0.0.zip",
    "repository": "https://github.com/derobiwan/speckit-linear",
    "homepage": "https://github.com/derobiwan/speckit-linear",
    "documentation": "https://github.com/derobiwan/speckit-linear/blob/main/README.md",
    "changelog": "https://github.com/derobiwan/speckit-linear/blob/main/CHANGELOG.md",
    "license": "MIT",
    "requires": {
      "speckit_version": ">=0.8.0"
    },
    "provides": {
      "commands": 16,
      "hooks": 18
    },
    "tags": [
      "linear",
      "mcp",
      "project-management",
      "issue-tracking",
      "spec-driven-development"
    ],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-05-16T00:00:00Z",
    "updated_at": "2026-05-16T00:00:00Z"
  }
}

Additional Context

This extension is paired with the linear preset (submitted separately as a PR — see presets/catalog.community.json submission). The pair installs together via specify init --ai <agent> --extension linear --preset linear and replaces local-file storage with Linear-as-storage-backend.

The preset wraps 9 core /speckit.* command templates (speckit.constitution, speckit.specify, speckit.clarify, speckit.plan, speckit.tasks, speckit.checklist, speckit.analyze, speckit.implement, speckit.taskstoissues) so they persist artifacts to Linear instead of local files. The extension adds 16 /speckit.linear.* commands and 18 hooks (one before_* + one after_* per lifecycle phase).

Constitutional invariants observed:

• No patches to src/specify_cli/ (Plugin-P1 — contributions limited to upstream catalog files)
• Linear MCP server is the only credential boundary (Plugin-P8 — no tokens or workspace IDs bundled in the artifact)
• No local-file fallback on MCP failure (Plugin-P2)

Pre-publication scans: gitleaks → 0 findings; grep -ri "derobiwan@" on the v1.0.0 tree → 0 hits; 3268 tests pass.