fix(templates): restore intentional apply skill/command separation

[clay-good]

Status: Ready. This reverts #1153, which we merged by mistake.

What was wrong
#1153 deduplicated the apply skill and command templates into one shared body (getApplyInstructions()) and added a test asserting the two are byte-identical. But skills and commands are intentionally different ways to invoke the workflow:

• Commands reference /opsx:* (e.g. /opsx:continue, /opsx:archive).
• Skills reference other skills by name and avoid /opsx: — a skill can be installed without the commands.

Teams choose skills-only, commands-only, or both via delivery mode, so generating both is a deliberate choice, not drift. The merge erased four intentional skill→command differences:

Location	Skill	Command
Input example	(none)	/opsx:apply add-auth
contextFiles note	full schema list	(varies by schema)
blocked state	openspec-continue-change	/opsx:continue
completion	Ready to archive this change.	…archive with /opsx:archive

How it's fixed
Restored apply-change.ts to two separate template functions, regenerated the static skills/openspec-apply-change/SKILL.md, and removed the identical-body parity assertion from the test. No other workflow file used this dedup pattern, so the change is self-contained.

Proof it works
Working tree matches the exact pre-#1153 state (empty diff vs 0b233efb^). npm run build, then all 86 test/core/templates/ tests pass — including the generated-SKILL.md content-hash checks, which confirm the static file matches the reverted template.

Notes
The underlying report #1139 ("commands and skills are nearly duplicated") is answered separately by delivery mode: openspec config → Delivery only → Skills only / Commands only. Closing that issue with the guidance.

Summary by CodeRabbit

• Documentation

  • Expanded apply guidance to cover additional implementation and documentation context files.
  • Updated blocked-state instructions to use the newer continue command.
  • Clarified completion messaging with archive-ready guidance.

• Refactor

  • Refined apply workflow instructions and context-handling guidance for more consistent generated commands and skills.

• Tests

  • Added coverage to verify workflow command references are correctly formatted across supported skill formats.

[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 Plus

Run ID: 6864a378-b13f-435c-8e07-7337771cba69

📥 Commits

Reviewing files that changed from the base of the PR and between 3db3381 and c953444.

📒 Files selected for processing (4)

• skills/openspec-apply-change/SKILL.md
• src/core/templates/workflows/apply-change.ts
• test/core/templates/skill-templates-parity.test.ts
• test/utils/command-references.test.ts

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

• test/core/templates/skill-templates-parity.test.ts
• skills/openspec-apply-change/SKILL.md

---

📝 Walkthrough

Walkthrough

The apply skill and command templates now use separate instruction bodies. The skill updates context-file and workflow guidance. The command embeds its own workflow. Tests update hashes and validate transformed command references.

Changes

Apply workflow templates

Layer / File(s)	Summary
Skill workflow instructions skills/openspec-apply-change/SKILL.md, src/core/templates/workflows/apply-change.ts	The skill template inlines its workflow, omits the input example, and expands schema-aware contextFiles guidance.
Command workflow instructions src/core/templates/workflows/apply-change.ts	The OPSX: Apply command embeds separate instructions for change selection, status inspection, task execution, pausing, progress output, guardrails, and completion.
Template and reference validation test/core/templates/skill-templates-parity.test.ts, test/utils/command-references.test.ts	The tests update template hashes, remove the shared-content assertion, and validate default, Codex, and Kimi command-reference transformations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1153: Modified the same apply templates and parity tests through shared instruction logic.
• Fission-AI/OpenSpec#1437: Modified apply workflow and blocked-state guidance.
• Fission-AI/OpenSpec#1357: Modified the openspec-apply-change skill and generated template content.

Suggested reviewers: tabishb, alfred-openspec

🚥 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 and concisely describes the main change: restoring separate apply skill and command templates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 claude/pr-1153-design-issues-f5489a

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/templates/workflows/apply-change.ts`:
- Line 55: Update the blocked-state guidance in
src/core/templates/workflows/apply-change.ts at line 55 to invoke
/openspec-continue-change instead of the bare command name, then regenerate
skills/openspec-apply-change/SKILL.md at line 53 so the committed generated
artifact reflects the corrected invocation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: cc048a4c-3be8-4c4a-8827-bdee655b14c2

📥 Commits

Reviewing files that changed from the base of the PR and between 59bfb27 and 3db3381.

📒 Files selected for processing (3)

• skills/openspec-apply-change/SKILL.md
• src/core/templates/workflows/apply-change.ts
• test/core/templates/skill-templates-parity.test.ts

[alfred-openspec]

Requesting changes because this revert removes the canonical /opsx:* tokens that generation rewrites for skills-only targets. At 3db3381, skills.sh, Codex, and Kimi all receive bare openspec-continue-change text and lose valid input/archive invocations; main correctly emits /openspec-*, $openspec-*, and /skill:openspec-*. Please preserve transformable tokens in the skill template (shared or split) and add default/Codex/Kimi generation regressions. The focused tests pass but miss this break.

[clay-good]

Thanks @alfred-openspec — you're right, and I verified the break: for every skill target the plain revert emitted bare openspec-continue-change prose and dropped the archive/input invocations, because the transformers only rewrite canonical /opsx:<id> tokens.

Fixed in c953444, keeping both concerns satisfied:

• Templates stay split — no shared constant, no identical-body assertion. The design separation fix(templates): deduplicate apply skill and command instructions #1153 erased remains reverted; skill and command are still two distinct bodies.
• Skill invocations are transformable again — the skill's three references (continue, apply example, archive) are now authored as /opsx:* tokens, so generation spells them per target: /openspec-continue-change (default/skills.sh), $openspec-continue-change (Codex), /skill:openspec-continue-change (Kimi). That's still "invoked as skills," just spelled correctly for each tool instead of dead prose.
• Regressions added — test/utils/command-references.test.ts now pins the apply skill's default/Codex/Kimi invocations (continue + apply + archive) and asserts no canonical token survives the rewrite, so this can't recur silently.

Regenerated the static SKILL.md and parity hashes. Full template + generation + init/update/migration suites green.

[alfred-openspec]

Re-reviewed c953444. The canonical references are restored and now rewrite correctly for skills.sh, Codex's shared .agents form, and Kimi; static skills regenerate cleanly. A fresh frozen install, build, lint, 364 focused template/reference/init/update/migration tests, and the full hosted matrix pass.