skills.rest
compozy
compozyOFFICIAL
Explore all skills by this author →
Website𝕏@compozyaiGitHub

cy-issue-to-spec

Publishes Compozy spec sets to compozy-specs and mirrors them into GitHub and Linear issues.

2.7k|171|Updated Mar 28, 2026
Search Tags:#linear#Python#issue mirroring#gitHub issues#spec publishing#roadmap tracking#spec-Driven Development
One-click install
npx skills add https://github.com/compozy/compozy --skill cy-issue-to-spec
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cy-issue-to-spec
Source: https://github.com/compozy/compozy/tree/main/.agents/skills/cy-issue-to-spec
Command: npx skills add https://github.com/compozy/compozy --skill cy-issue-to-spec

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Keeping a feature's spec set, its published copy in the compozy-specs repository, and its GitHub and Linear tracking issues in agreement requires manual copying, link fixing, and cross-tracker auditing that is easy to get wrong.

Core Features & Use Cases

  • Spec staging and publishing: Copies publishable spec documents and ADRs into the specs repo, scrubs machine-local paths, scans for secrets, and checks relative links.
  • Issue body authoring: Builds a structured GitHub/Linear issue body from the spec's own sections using a documented skeleton.
  • Mirror auditing: Verifies titles, states, and cross-links between GitHub issues and Linear issues with a read-only sync checker.
  • Use Case: After finishing a spec under .compozy/tasks/<slug>/, run the skill to publish the spec set, index it in the specs repo README, and open matching GitHub and Linear issues that link to each other.

Quick Start

Publish the spec set in .compozy/tasks/my-feature to the specs repo and create mirrored GitHub and Linear issues for it.

Frequently Asked Questions about cy-issue-to-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I publish a spec set to the compozy-specs repository?▼

Run the publish-spec.py script with --spec-dir pointing at .compozy/tasks/<slug>, --specs-repo pointing at a specs repo checkout, and --repo-root for path scrubbing. It copies _*.md, task_NN.md, and adrs/*.md files into a dated folder and reports staged files and scan results.

How do I keep GitHub and Linear issues in sync?▼

Create both issues with identical titles and bodies, each linking to the other, then run check-tracker-sync.py with a Linear issues JSON export. The script audits titles, states, and cross-links, exiting non-zero when defects are found.

What files get published from a spec directory?▼

The publisher copies files matching _*.md and task_NN.md plus everything under adrs/. Working files like analysis/, qa/, memory/, evidence/, state.yaml, and handoff notes stay in the workspace, and --include adds extra glob patterns.

Why does the publish script fail with a non-zero exit?▼

The script exits non-zero when it finds a surviving machine-local path or a possible secret such as an API key or private key in the staged documents. Edit the flagged document to remove the finding, then re-run the staging step.

Can I publish a spec for work that is already finished?▼

Yes, pass --archived to place the folder under _archived/ in the specs repo and add its README row to the Archived table. When no tracking issue exists, the README row becomes the only index entry.

Related Skills

Explore More Software Engineering Skills→
DarkCodePEDarkCodePE

new-feature

Generate linked PRD, SPEC, ADR, and TASK artifacts for new features.

Community
Advanced
MaelwalserMaelwalser

project-flow-ops

Triage GitHub issues and pull requests into Linear execution flows.

Community
Intermediate
MajesteitBartMajesteitBart
7

sync-skill

Reconcile local task contracts with Linear and GitHub state.

Community
Advanced
EllevatedAIEllevatedAI

reflect

Analyze diary entries to generate a CLAUDE.md improvement spec.

Official
Advanced