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
  • Fixed spec sync output to ensure merged main specs don’t contain delta operation headers (e.g., ADDED/MODIFIED/REMOVED/RENAMED), preventing incorrect requirement parsing.
• Documentation
  • Strengthened guidance for spec synchronization, including an explicit “Main Spec Format” reference and clear merge guardrails (single ## Requirements section).
• Tests
  • Updated template parity checks to match the revised synchronization guidance.

[coderabbitai]

📝 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#450: Updates the sync workflow templates and main-spec reconciliation format.
• Fission-AI/OpenSpec#1089: Modifies sync-specs template instructions with formatting guardrails.
• Fission-AI/OpenSpec#1357: Updates the same sync templates and parity test hashes.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	[#1120] The PR adds main-spec instructions and a format reference so syncs merge delta specs into valid main specs instead of copying headers.
Out of Scope Changes check	✅ Passed	The extra changeset, generated docs, and hash updates support the same sync-spec template change and appear in scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: surfacing the main spec format in the sync-specs skill templates.

✨ 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.