SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsopenspec-linearized

openspec-linearized

General & other

View repository

Updated 10-15 22:38

About this skill

OpenSpec Linearized

Use this skill to run an OpenSpec change lifecycle while preserving a clear handoff boundary:

  • Linear issue/card owns the business "what": business goal, use cases, personas/workflows, scope, acceptance criteria, and stakeholder-facing status. Keep its description synchronized from the business-facing content in proposal.md.
  • The repo owns the technical "how": OpenSpec design decisions, tasks, implementation details, migrations, tests, and code.
  • Canonical specs live under openspec/specs/. After archive succeeds, mirror those specs into Linear Project Documents for stakeholder visibility.

Linear updates are best effort once project setup exists.

Invocation Contract

  • If the user asks to operate on an OpenSpec change, use this skill as the Linear lifecycle overlay.
  • Also use the base OpenSpec skill that matches the request, such as openspec-propose, openspec-apply-change, openspec-archive-change, or openspec-sync-specs.
  • If openspec/linear.yaml exists, run the relevant Linear hook for the current phase when possible.
  • If openspec/linear.yaml is missing during proposal/setup, create it before issue hunting, story selection, or other Linear lifecycle work.
  • If openspec/linear.yaml is missing outside proposal/setup, no-op the Linear hook and continue normal OpenSpec work.
  • For status, validate, sync, continue, and artifact-editing work, preserve Linear binding awareness but do not move a Linear story to Done.

Start

  • Read references/lifecycle.md before doing lifecycle work.
  • Run openspec list --json to understand active changes.
  • Determine the phase from the request:
    • Proposal: create or continue an OpenSpec change and bind a Linear story.
    • Apply: implement tasks.md while updating the bound Linear story.
    • Archive: archive the OpenSpec change, then mirror canonical specs and close the story.
    • Sync/status/validate/continue/artifact work: keep the Linear binding in view, preserve the ownership boundary, and avoid Done transitions.
  • If another OpenSpec skill also applies, use this skill as the Linear lifecycle overlay and follow the base OpenSpec skill for normal artifact generation, task execution, or archive mechanics.

Linear Rules

  • Prefer Linear MCP tools when available: list_teams, list_projects, list_issue_labels, list_issues, list_comments, list_documents, save_issue, save_comment, and save_document.
  • If openspec/linear.yaml is missing during proposal/setup, perform setup before proposal discovery: list only Linear setup data, choose team/project/optional issue label filter, then write the config.
  • During missing-config setup, call only list_teams, list_projects, and list_issue_labels. Do not call list_issues until after openspec/linear.yaml exists and the configured lifecycle flow requires story selection.
  • Ask setup choices one question at a time: first Linear team, then Linear project, then issue label filter. The label question must include an explicit "no label filter" option.
  • Never infer or auto-select team, project, or label from names, ordering, previous results, or seemingly obvious matches.
  • After openspec/linear.yaml exists, Linear unavailability is non-blocking. Continue local OpenSpec work and skip Linear updates silently.
  • Keep Linear comments short, at most two sentences.
  • Do not make Linear the specification source of truth. Canonical specs live under openspec/specs/.
  • Do not transition the bound Linear story to Done before OpenSpec archive succeeds.
  • Keep detailed technical design out of Linear issue descriptions and comments; keep business context out of repo design/tasks except where needed to make technical decisions traceable.
  • When proposal.md is created or materially updated, update the bound Linear issue description with the current business-facing proposal details when possible. Exclude frontmatter, Linear metadata, detailed technical design, task lists, and implementation notes.

Phase Hooks

Proposal:

  • Load openspec/linear.yaml; if it is missing, create it first using the missing-config setup rules above.
  • After openspec/linear.yaml exists, select a configured-project Backlog issue, applying the optional label filter only to candidate selection.
  • Read the selected issue title, description, labels, comments, links, and related context when available.
  • Treat the Linear issue as the business brief. If proposal discovery produces new or corrected business details, update the Linear issue/card when possible instead of making proposal.md the long-form business record.
  • Ask clarifying questions before writing artifacts.
  • Keep proposal.md lean: record Linear metadata in frontmatter, include capability impact and a concise repo-facing summary, and link back to the Linear issue for business details.
  • After writing or updating proposal.md, refresh the bound Linear issue description from the proposal's business-facing sections when possible.
  • Transition the issue to Todo when possible and add a short comment that proposal discovery started.

Apply:

  • Read linear_story_id from openspec/changes/<change>/proposal.md before implementation.
  • Before implementation, sync useful business/context changes from proposal.md to the Linear issue description when possible, but do not copy technical design details from design.md into Linear.
  • Transition Todo to In Progress when possible and add a short comment that implementation began from the OpenSpec change.
  • Work through tasks.md, marking checkboxes complete as tasks finish.
  • Leave Done transition for archive.

Archive:

  • Complete the normal OpenSpec archive flow first, including delta spec sync when applicable.
  • Only after archive succeeds, mirror canonical openspec/specs/<capability>/spec.md content into Linear Project Documents.
  • Use deterministic titles: OpenSpec: <capability-name>.
  • Persist created or discovered document IDs in openspec/linear.yaml when possible.
  • Transition the bound Linear issue to Done when possible and add a short archive-complete comment.

Guardrails

  • Keep post-archive Linear Project Document sync guidance out of tasks.md; it belongs to archive behavior.
  • Only Linear Project Documents are in scope for spec mirrors. Do not create generic project resources for specs.
  • Linear Project Documents are archive-time mirrors of finalized specs, not a place for draft design notes or implementation tasks.
  • If the active schema is already linearized, honor OpenSpec CLI instructions and avoid duplicating conflicting guidance.
  • If the active schema is local-only, layer this skill's Linear hooks around the normal proposal/apply/archive workflow.