cy-issue-to-spec
Publishes a Compozy spec set to compozy-specs and mirrors it into a GitHub + Linear issue pair — or starts from a bare issue and authors the spec first.
- License 许可
- MIT
- 所属仓库
- compozy/compozy
- 最近更新
- 2026-11-15
- Stars
- ★ 2.9k
- Forks
- 187
01 前言 Front Matter
- name
- cy-issue-to-spec
- description
- Publishes a Compozy spec set to compozy-specs and mirrors it into a GitHub + Linear issue pair — or starts from a bare issue and authors the spec first.
- argument-hint
- [spec slug or issue number]
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/issue-body.md3.3 KB
- 脚本scripts/check-tracker-sync.py3.8 KB
- 脚本scripts/publish-spec.py6.3 KB
03 SKILL.md 正文
Issue ↔ Spec
One feature lives in three places: the working spec set under .compozy/tasks/<slug>/, its published folder in the compozy/compozy-specs repo, and its mirror — a GitHub issue and a Linear issue that read identically. This skill moves a feature between those places and leaves all three agreeing.
Branches
| Starting point | Enter at |
|---|---|
A spec set already exists under .compozy/tasks/<slug>/ |
Step 1 |
| A GitHub issue exists carrying no spec behind it | Step 0 |
Step 0 — Author the spec
Only when starting from a bare issue.
Read the issue and restate its scope in one sentence. When it bundles separable features, split it first: retitle the original to the narrower scope, open a second issue for the remainder, and cross-link both — then spec one of them.
Activate cy-create-spec with docs/_memory/spec-authoring-playbook.md. It writes _slices.md and offers peer review after the user approves the spec.
Done when: .compozy/tasks/<slug>/ holds _spec.md (or _prd.md + _techspec.md), its companions, adrs/, and _slices.md, and the user has approved the spec.
Step 1 — Stage the spec set
Run the staging helper (mutating — writes into the specs repo working tree):
python3 .agents/skills/cy-issue-to-spec/scripts/publish-spec.py \
--spec-dir .compozy/tasks/<slug> \
--specs-repo <specs-repo-checkout> \
--repo-root "$(pwd)"
It publishes _*.md, task_NN.md, and adrs/*.md; it leaves analysis/, qa/, memory/, evidence/, reviews-*/, state.yaml, and handoff notes in the workspace. Pass --include '<glob>' for a document that carries spec content under a name outside those patterns, and --archived when the workstream is already closed.
The folder is named YYYY-MM-DD-<slug>, dated by when the work began: the source folder's own date prefix when it carries one, else state.yaml's created_at, else the earliest document. Active specs sit at the repo root; closed ones under _archived/.
Done when: the helper exits 0, reporting the staged path, file count, and a clean scan.
Step 2 — Resolve the report
The helper scrubs machine-local paths and repairs ../adrs/ links itself. Two findings need a decision:
- A surviving local path or a possible secret exits the helper non-zero. Edit the staged document, then re-run the scan.
- A broken relative link points at something the filter left behind. Either publish that material too, or accept the dangling reference — the repo README already tells readers that older documents point at files they will not find.
Done when: every reported path, secret, and link is fixed or consciously accepted.
Step 3 — Index and push
Add one row to the specs repo README.md, in the Active or Archived table: the folder link, one sentence on what the spec covers, the tracking-issue link, and the Documents column naming its shape (spec, prd + techspec, brief + techspec, …). Newest first.
Commit as docs: add <slug> spec set and push.
Done when: every relative link in the README resolves and the commit is on main.
Step 4 — Write the issue body
Read .agents/skills/cy-issue-to-spec/references/issue-body.md in full and build the body against it.
Done when: the body opens with the spec-set link block and every section of the skeleton is either written or deliberately absent.
Step 5 — Open the mirror
Create or update the GitHub issue: title matching the spec's subject, labels roadmap + planned (removing needs-plan), the Step 4 body, and a closing Roadmap item tracked in Linear: [CY-NNN](…) line.
Create or update the Linear issue with the same title and the same body, swapping the footer for Tracked on GitHub: <url>. Linear renders GitHub callout syntax as plain text — convert a > [!NOTE] block to a bold sentence.
Verify with the audit helper (read-only):
python3 .agents/skills/cy-issue-to-spec/scripts/check-tracker-sync.py --linear-json <export>
Save the Linear MCP list_issues result to a file first; without --linear-json the helper audits only the GitHub half.
Done when: the helper exits 0 with no defects, and both issues carry a link to each other.
Reference
- Publishing an already-archived spec skips Step 0 and Step 4's tracking link when no issue exists — the README row is then the only index entry.
- Renaming a published folder breaks the links already sitting in both trackers; update the issue bodies in the same change.
references/issue-body.md— the issue-body skeleton and where each part comes from in the spec.scripts/publish-spec.py— mutating; stages, scrubs, scans, and link-checks a spec set.scripts/check-tracker-sync.py— read-only; audits titles, states, and links across the mirror.
04 同仓库更多 Skills
security-review
Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review", or review code for injection, XSS, authentication, authorization, cryptography issues. Provides systematic review with confidence-based reporting.
lesson-learned
Extract evidence-backed engineering lessons from recent changes or incidents. Use for requested reflection, lesson updates, or retiring an obsolete workflow rule.
compozy
Operate CompozyOS. Use when working with CompozyOS sessions, agents, native tools, skills, tasks, Loops, Goals, Terminal, desktops and windows, automation, extensions, or configuration. Don't use for unrelated projects.
remotion-upgrade
Upgrade Remotion, and related packages
remotion-studio
Preview a Remotion video
remotion-saas
Build an app with Remotion