fix(templates): show the main spec format in the sync-specs skill

[clay-good]

Status

Ready for review. Guidance-only change to the sync-specs skill/command templates — no CLI behavior, parser, or schema changes. Rebased onto current main (the golden-hash file had drifted with #1394's archive-template update).

What was wrong

The openspec-sync-specs skill tells the agent to merge delta specs into main specs, but the only markdown example it shows is the delta format (## ADDED/MODIFIED Requirements headers). Weaker agents pattern-match that example and copy the delta file into openspec/specs/<capability>/spec.md as-is. The main-spec parser anchors on a literal ## Requirements section (src/core/parsers/requirement-blocks.ts), so a main spec left with delta headers parses as 0 requirements in openspec view — exactly what #1120 reported with Junie. Since #1394 the archive skill also routes its sync through this skill, so the gap affected every archive-with-sync too.

How it was fixed

In both templates in src/core/templates/workflows/sync-specs.ts (skill + /opsx:sync command):

• Added a Main Spec Format Reference block right after the Delta Spec Format Reference, showing the canonical structure the CLI itself scaffolds (# <capability> Specification → ## Purpose → ## Requirements, per buildSpecSkeleton in src/core/specs-apply.ts), with an explicit rule that main specs never contain delta operation headers.
• Pointed step 4d (create new main spec) at that reference.
• Added a guardrail: never copy a delta file into a main spec as-is.
• Added a matching scenario to openspec/specs/specs-sync-skill/spec.md and regenerated skills/openspec-sync-specs/SKILL.md + the golden hashes.

Proof it works

• npx vitest run on the rebased branch: 2,027 passing; the only failures are the 17 known environment-only zsh-installer failures on machines with a real Oh My Zsh install (ZshInstaller tests fail on machines with a real Oh My Zsh install (17/50 failures) #1321, fix open in test(completion): isolate ZshInstaller tests from a real Oh My Zsh install #1400); CI is unaffected.
• node dist/cli/index.js validate --specs: 36 passed, 0 failed (includes the modified specs-sync-skill).
• npm run build + npm run generate:skills clean after the rebase — zero drift between the committed skills/openspec-sync-specs/SKILL.md and the generator output; no other skill changed.

Notes

• The issue's first half — the sync skill missing from the installed set — is already fixed on main: CORE_WORKFLOWS (src/core/profiles.ts) now includes sync.
• No overlap with open PRs: Clarify archive sync for new specs #1271/Fix greenfield archive sync guidance (#1222) #1241 touch only archive-change.ts; fix: validate artifact content before marking workflow step done #1098 touches done-detection in artifact-graph.

Fixes #1120

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved spec syncing so merged main specs no longer include delta operation headers (e.g., ADDED/MODIFIED/REMOVED/RENAMED), preventing incorrect requirement parsing.
• Documentation
  • Strengthened sync instructions with an explicit “Main Spec Format Reference” and merge guardrails (single ## Requirements section; don’t copy delta files verbatim).
• Tests
  • Updated template parity hash expectations to reflect the revised sync templates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e705dfcd-4276-405f-89a4-02f5d79125f9

📥 Commits

Reviewing files that changed from the base of the PR and between c9d109e and 7740d14.

📒 Files selected for processing (5)

• .changeset/sync-specs-main-spec-format.md
• openspec/specs/specs-sync-skill/spec.md
• skills/openspec-sync-specs/SKILL.md
• src/core/templates/workflows/sync-specs.ts
• test/core/templates/skill-templates-parity.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• openspec/specs/specs-sync-skill/spec.md
• .changeset/sync-specs-main-spec-format.md
• test/core/templates/skill-templates-parity.test.ts
• skills/openspec-sync-specs/SKILL.md
• src/core/templates/workflows/sync-specs.ts

---

📝 Walkthrough

Walkthrough

The sync specification, authored skill, and generated sync templates now define a canonical merged main-spec format with one ## Requirements section and no delta operation headers. Template parity hashes and a patch changeset were updated accordingly.

Changes

Sync main-spec format

Layer / File(s)	Summary
Canonical sync contract openspec/specs/specs-sync-skill/spec.md, skills/openspec-sync-specs/SKILL.md, .changeset/sync-specs-main-spec-format.md	The sync specification and skill now require canonical merged main specs without delta operation headers, with a patch changeset documenting the adjustment.
Generated sync instructions src/core/templates/workflows/sync-specs.ts	The skill and OPSX sync command templates include the main-spec format reference and prohibit copying delta files into main specs verbatim.
Template parity validation test/core/templates/skill-templates-parity.test.ts	Expected hashes were updated for the modified sync templates and generated skill content.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1089: Updates related sync workflow template guidance.
• Fission-AI/OpenSpec#1357: Modifies the same sync-specs workflow templates.
• Fission-AI/OpenSpec#1360: Updates sync templates and their parity test hashes.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding main spec format guidance to the sync-specs skill.
Linked Issues check	✅ Passed	The PR adds main-spec format instructions and guardrails for sync behavior, matching the requirements in #1120.
Out of Scope Changes check	✅ Passed	The changes to docs, templates, and golden hashes are directly tied to the sync-specs update and are in scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sync-specs-main-spec-format

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

The canonical main-spec reference closes the delta-header failure mode in both sync variants, and the checked-in skill remains generator-clean. Exact-head build, 37 focused tests, all 36 spec validations, and the full cross-platform matrix passed.

[alfred-openspec]

The rebase preserves the reviewed main-spec format guidance and cleanly composes with current template changes. Exact-head build, clean skill regeneration, 37 focused tests, all 36 spec validations, and the full CI/CodeQL matrix pass.