Fission-AI · harikrishnan83 · Jan 11, 2026 · Jan 11, 2026 · Jan 21, 2026 · Jan 21, 2026
@@ -0,0 +1,37 @@
+## Context
+OpenSpec slash-command templates currently describe proposal/apply/archive workflows without any external backlog integration. The request is to wire those workflows to Linear via MCP so backlog selection, state transitions, and epic tracking happen automatically when a Linear MCP connection is present.
+
+## Goals / Non-Goals
+- Goals:
+  - Detect Linear MCP availability and use it only when connected.
+  - Persist a preferred Linear team/project configuration inside `openspec/` and reflect it in `openspec/project.md`.
+  - Keep one Linear epic issue per source-of-truth spec under the preferred Linear project.
+  - Use Linear backlog stories as the starting point for proposals and move story states through the lifecycle.
+- Non-Goals:
+  - Implement a non-MCP Linear API client.
+  - Replace OpenSpec change naming or proposal structure.
+
+## Decisions
+- Decision: Store Linear preferences in `openspec/linear.yml` with `team_id` and `project_id` keys.
+  - Rationale: YAML is concise, easy to hand-edit, and fits alongside existing markdown without frontmatter ambiguity.
+- Decision: Add a new `## Linear MCP` section to `openspec/project.md` containing the preferred team and project IDs.
+  - Rationale: Keeps the preferences visible in the primary project overview while still retaining the canonical config in `openspec/linear.yml`.
+- Decision: Represent epics as regular Linear issues labeled `Epic` in the preferred project.
+  - Rationale: The MCP API exposes issues and labels directly; using a label avoids relying on ambiguous milestone semantics.
+- Decision: Use Linear issue description as the destination for proposal content (proposal body without frontmatter).
+  - Rationale: Keeps the story aligned with the current proposal while avoiding YAML noise.
+- Decision: Order backlog story selection by priority (fall back to recency if priority is unavailable) and show an interactive list.
+  - Rationale: Aligns with the idea of “top stories” while keeping the prompt deterministic.
+
+## Risks / Trade-offs
+- Ambiguity around “epic” semantics in Linear could require adjustment if teams rely on milestones or issue types; the `Epic` label approach is a best-effort default.
+- The Linear MCP may not be connected in all environments; instructions must degrade gracefully.
+
+## Migration Plan
+1. Update slash-command templates to include Linear MCP detection and the new workflow steps.
+2. Add the new `linear-mcp-workflow` spec delta and validate the change.
+3. Ensure any prompt-generation tests that assert template text are updated.
+
+## Open Questions
+- Should the `Epic` label name be configurable (e.g., `Epic`, `Milestone`, `Large Story`) via the Linear config file?
+- Do we want to include Linear project names (in addition to IDs) in `openspec/project.md` for readability?
@@ -0,0 +1,14 @@
+## Why
+Tie OpenSpec proposals and lifecycle updates directly to Linear so teams can pick backlog work, track status changes, and keep source-of-truth specs represented as epics in a single project view.
+
+## What Changes
+- Detect when Linear MCP is available by confirming the MCP is connected and can list teams, and load preferred team/project IDs from an OpenSpec-local config, updating `openspec/project.md` with those preferences.
+- Keep OpenSpec workflows operating as usual when Linear MCP is not available, skipping Linear-specific prompts and updates.
+- Ensure each source-of-truth spec in `openspec/specs/` has a matching Linear epic issue in the preferred project.
+- Proposal workflow lists top backlog stories from the Linear project, prompts for selection, writes the selected story ID into `proposal.md` frontmatter, and moves the story from Backlog to Todo.
+- Apply workflow updates the Linear story with proposal content and moves it to In Progress.
+- Archive workflow updates the Linear story with proposal content, moves it to Done, and refreshes spec epics.
+
+## Impact
+- Affected specs: linear-mcp-workflow (new)
+- Affected code: src/core/templates/slash-command-templates.ts, src/core/templates/slash-command-templates.ts consumers (init/update)
@@ -0,0 +1,54 @@
+## ADDED Requirements
+### Requirement: Linear MCP Detection and Preferences
+The proposal, apply, and archive workflows SHALL detect whether Linear MCP is available and only execute Linear actions when connected. Availability SHALL be confirmed by a successful connection and a successful team list query. When connected, the workflow SHALL load `openspec/linear.yml` to obtain `team_id` and `project_id`, and update `openspec/project.md` with the preferred Linear team and project. If the config file does not exist, the workflow SHALL prompt the user to select a Linear team and project, then persist the selections to `openspec/linear.yml` and `openspec/project.md`.
+
+#### Scenario: Linear MCP connected with stored preferences
+- **WHEN** a workflow starts and Linear MCP is available
+- **AND** `openspec/linear.yml` contains `team_id` and `project_id`
+- **THEN** load those values and update `openspec/project.md` to reflect the preferred team and project
+
+#### Scenario: Linear MCP connected without stored preferences
+- **WHEN** a workflow starts and Linear MCP is available
+- **AND** `openspec/linear.yml` is missing
+- **THEN** prompt for a Linear team and project
+- **AND** persist the selections to `openspec/linear.yml`
+- **AND** update `openspec/project.md` with the preferred team and project
+
+#### Scenario: Linear MCP not available
+- **WHEN** a workflow starts and Linear MCP is not available
+- **THEN** continue the OpenSpec workflow without Linear prompts or updates
+
+### Requirement: Spec Epic Synchronization
+When Linear MCP is available, the workflows SHALL ensure each capability under `openspec/specs/` has a corresponding Linear epic issue in the preferred project. Missing epics SHALL be created and labeled `Epic`, and existing epics SHALL be updated to reflect the spec identifier and path.
+
+#### Scenario: Creating missing epics for specs
+- **WHEN** a workflow runs with Linear MCP connected
+- **AND** a spec does not have a matching epic issue
+- **THEN** create a new Linear issue labeled `Epic` in the preferred project
+- **AND** include the spec identifier and `openspec/specs/<capability>/spec.md` path in the epic description
+
+### Requirement: Proposal Story Selection and State Transition
+When creating a proposal with Linear MCP connected, the workflow SHALL fetch the top backlog stories from the preferred Linear project, present an interactive list for selection, store the selected story ID in `proposal.md` frontmatter, and move the story from Backlog to Todo.
+
+#### Scenario: Selecting a backlog story for a proposal
+- **WHEN** the proposal workflow starts with Linear MCP connected
+- **THEN** list backlog stories from the preferred project in an interactive prompt
+- **AND** store the selected story ID as `linear_story_id` in `proposal.md` frontmatter
+- **AND** move the selected story from Backlog to Todo
+
+### Requirement: Apply Story Update and In Progress Transition
+When applying a change with a `linear_story_id` in `proposal.md`, the workflow SHALL update the Linear story description with the proposal content and move the story to In Progress.
+
+#### Scenario: Applying a change with a Linear story
+- **WHEN** the apply workflow runs and `proposal.md` includes `linear_story_id`
+- **THEN** update the Linear story description using the proposal content
+- **AND** move the story to In Progress
+
+### Requirement: Archive Story Update, Completion, and Epic Refresh
+When archiving a change with a `linear_story_id` in `proposal.md`, the workflow SHALL update the Linear story description with the proposal content, move the story to Done, and refresh spec epics in the preferred project.
+
+#### Scenario: Archiving a change with a Linear story
+- **WHEN** the archive workflow runs and `proposal.md` includes `linear_story_id`
+- **THEN** update the Linear story description using the proposal content
+- **AND** move the story to Done
+- **AND** refresh the spec epic issues for `openspec/specs/`
@@ -0,0 +1,11 @@
+## 1. Specification Updates
+- [x] 1.1 Add the linear MCP workflow requirements in `openspec/changes/add-linear-mcp-workflow/specs/linear-mcp-workflow/spec.md`.
+- [x] 1.2 Capture configuration and epic-mapping decisions in `openspec/changes/add-linear-mcp-workflow/design.md`.
+
+## 2. Template Updates
+- [x] 2.1 Update `src/core/templates/slash-command-templates.ts` to include Linear MCP steps in proposal/apply/archive workflows.
+- [x] 2.2 Update any supporting docs or schema templates that mirror the slash-command content.
+
+## 3. Validation
+- [x] 3.1 Update or add tests that assert the updated slash-command template content.
+- [x] 3.2 Run `openspec validate add-linear-mcp-workflow --strict` and address any issues.
@@ -0,0 +1,75 @@
+# linear-mcp-workflow Specification
+
+## Purpose
+TBD - created by archiving change add-linear-mcp-workflow. Update Purpose after archive.
+## Requirements
+### Requirement: Linear MCP Detection and Preferences
+The proposal, apply, and archive workflows SHALL detect whether Linear MCP is available and only execute Linear actions when connected. Availability SHALL be confirmed by a successful connection and a successful team list query. When connected, the workflow SHALL load `openspec/linear.yml` to obtain `team_id` and `project_id`, and update `openspec/project.md` with the preferred Linear team and project. If the config file does not exist, the workflow SHALL prompt the user to select a Linear team and project, then persist the selections to `openspec/linear.yml` and `openspec/project.md`.
+
+#### Scenario: Linear MCP connected with stored preferences
+- **WHEN** a workflow starts and Linear MCP is available
+- **AND** `openspec/linear.yml` contains `team_id` and `project_id`
+- **THEN** load those values and update `openspec/project.md` to reflect the preferred team and project
+
+#### Scenario: Linear MCP connected without stored preferences
+- **WHEN** a workflow starts and Linear MCP is available
+- **AND** `openspec/linear.yml` is missing
+- **THEN** prompt for a Linear team and project
+- **AND** persist the selections to `openspec/linear.yml`
+- **AND** update `openspec/project.md` with the preferred team and project
+
+#### Scenario: Linear MCP not available
+- **WHEN** a workflow starts and Linear MCP is not available
+- **THEN** continue the OpenSpec workflow without Linear prompts or updates
+
+### Requirement: Spec Epic Synchronization
+When Linear MCP is available, the workflows SHALL ensure each capability under `openspec/specs/` has a corresponding Linear epic issue in the preferred project. Missing epics SHALL be created and labeled `Epic`, and existing epics SHALL be updated to reflect the spec identifier and path.
+
+#### Scenario: Creating missing epics for specs
+- **WHEN** a workflow runs with Linear MCP connected
+- **AND** a spec does not have a matching epic issue
+- **THEN** create a new Linear issue labeled `Epic` in the preferred project
+- **AND** include the spec identifier and `openspec/specs/<capability>/spec.md` path in the epic description
+
+### Requirement: Proposal Story Selection and State Transition
+When creating a proposal with Linear MCP connected, the workflow SHALL fetch the top backlog stories from the preferred Linear project, present an interactive list for selection, store the selected story ID in `proposal.md` frontmatter, and move the story from Backlog to Todo.
+
+#### Scenario: Selecting a backlog story for a proposal
+- **WHEN** the proposal workflow starts with Linear MCP connected
+- **THEN** list backlog stories from the preferred project in an interactive prompt
+- **AND** store the selected story ID as `linear_story_id` in `proposal.md` frontmatter
+- **AND** move the selected story from Backlog to Todo
+
+### Requirement: Apply Story Update and In Progress Transition
+When applying a change with a `linear_story_id` in `proposal.md`, the workflow SHALL update the Linear story description with the proposal content and move the story to In Progress.
+
+#### Scenario: Applying a change with a Linear story
+- **WHEN** the apply workflow runs and `proposal.md` includes `linear_story_id`
+- **THEN** update the Linear story description using the proposal content
+- **AND** move the story to In Progress
+
+### Requirement: Archive Story Update, Completion, and Epic Refresh
+When archiving a change with a `linear_story_id` in `proposal.md`, the workflow SHALL update the Linear story description with the proposal content, move the story to Done, and refresh spec epics in the preferred project.
+
+#### Scenario: Archiving a change with a Linear story
+- **WHEN** the archive workflow runs and `proposal.md` includes `linear_story_id`
+- **THEN** update the Linear story description using the proposal content
+- **AND** move the story to Done
+- **AND** refresh the spec epic issues for `openspec/specs/`
+
+### Requirement: Archived Spec Issue Tracking
+When archiving updates to merged source-of-truth specs with Linear MCP connected, the workflow SHALL ensure each updated spec has a corresponding Linear issue in status `Spec`, and store the issue ID in spec front matter as `linear_spec_issue_id`. If the issue already exists, the workflow SHALL update it with the latest merged spec content.
+
+#### Scenario: Creating missing spec issues after archive
+- **WHEN** the archive workflow runs with Linear MCP connected
+- **AND** the archive updates one or more specs
+- **AND** an updated spec lacks `linear_spec_issue_id` in front matter
+- **THEN** search for an existing Linear issue for the spec and create one if missing
+- **AND** set the issue status to `Spec`
+- **AND** write the resulting issue ID to the spec front matter
+
+#### Scenario: Updating existing spec issues after archive
+- **WHEN** the archive workflow runs with Linear MCP connected
+- **AND** the archive updates one or more specs
+- **AND** an updated spec includes `linear_spec_issue_id` in front matter
+- **THEN** update the linked Linear issue with the latest merged spec content