refactor(templates): share one apply instruction body across skill and command by clay-good · Pull Request #1515 · Fission-AI/OpenSpec

clay-good · 2026-08-05T14:35:35Z

Status: Ready. Internal refactor plus one small drift fix — no change to the generated skill; the generated command gains a more informative note.

What was wrong
The apply skill and command templates each held a full ~150-line copy of the same instruction body. They differed in exactly one line — the contextFiles note (skill spelled out example artifact sets; command said only "varies by schema"). Two near-identical copies drift over time, and that one line was itself long-standing accidental drift between the copies.

What it does

Shared core. The body is authored once in getApplyInstructions() and rendered by both surfaces.
Drift resolved. The surfaces are meant to differ only in how they are invoked — the generation transformers already handle that downstream, rewriting the canonical /opsx:<id> tokens per surface (/openspec-* for skills, /opsx:* for commands, etc.). The contextFiles wording was never an intentional surface difference, so both now use the more informative note.
Contract test. A new test asserts both surfaces render the shared core, so they can't silently drift at the template level; the per-surface invocation rendering stays covered by the existing tests in test/utils/command-references.test.ts.

Proof it's safe

Generated skill output (skills/openspec-apply-change/SKILL.md) is byte-identical to before.
Only change to generated output: the apply command's contextFiles line now reads (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) instead of (varies by schema). One parity hash regenerated to match.
Full template + generation + init/update/migration suites green (645 tests); typecheck and lint clean.

Scope
apply-change.ts (the shared core), a one-line re-export in skill-templates.ts, and the contract test. No other workflow file touched.

Summary by CodeRabbit

Documentation
- Standardized instructions across the apply skill and apply command for a more consistent experience.
- Unified guidance for context files across both workflow surfaces.
Tests
- Added coverage to verify that both apply experiences use the same core instructions.
- Updated validation to preserve consistent template content.

…d command The apply skill and command templates each carried a full ~150-line copy of the same instruction body, differing in exactly one line (the `contextFiles` note). Two near-identical copies invite silent drift. Author the body once in `getApplyInstructions(contextFilesNote)` and render it per surface, passing each surface's own note. The single intentional wording difference stays explicit as a named constant, and further per-surface parameters can be added here as the surfaces evolve — the skill and command remain distinct templates. Pure refactor: the generated skill and command output is byte-identical to before (SKILL.md and all parity hashes unchanged). Added a contract test that fails both if the shared body drifts between surfaces and if the intentional contextFiles difference is flattened away. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

coderabbitai · 2026-08-05T14:35:59Z

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: d3061be7-6201-4b78-ab0f-89ec35e3ad8f

📥 Commits

Reviewing files that changed from the base of the PR and between efc5f3e and bcb1131.

📒 Files selected for processing (3)

src/core/templates/skill-templates.ts
src/core/templates/workflows/apply-change.ts
test/core/templates/skill-templates-parity.test.ts

📝 Walkthrough

Walkthrough

The apply workflow now generates its instructions through one exported helper. Skill and command templates use the helper, and parity tests verify that both surfaces render the shared instruction core.

Changes

Apply template parity

Layer / File(s)	Summary
Centralize apply instructions `src/core/templates/workflows/apply-change.ts`, `src/core/templates/skill-templates.ts`	`getApplyInstructions()` contains the canonical apply workflow instructions. The skill and command templates use it. The compatibility facade re-exports it.
Validate template parity `test/core/templates/skill-templates-parity.test.ts`	The tests update the command template hash and verify that both apply surfaces match the shared instruction core.

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

Possibly related PRs

Fission-AI/OpenSpec#513: Modifies the apply instruction flow that this PR centralizes.
Fission-AI/OpenSpec#1153: Updates the same apply templates and parity tests.
Fission-AI/OpenSpec#1514: Revises the same apply templates and parity tests.

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: sharing one apply instruction body across the 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/apply-template-shared-core

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

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

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

alfred-openspec

Approved at efc5f3e. The shared instruction body preserves the one intentional contextFiles wording difference, the contract test pins both parity and that exception, and the full hosted matrix is green.

Builds on the shared-core extraction: the apply skill and command still each carried a slightly different `contextFiles` note (skill spelled out example artifact sets, command said only "varies by schema"). That difference was long-standing accidental drift between the two copies, not an intentional surface distinction — the surfaces are meant to differ only in how they are invoked, which the generation transformers already handle downstream by rewriting `/opsx:<id>` tokens per surface. Resolve the drift by unifying on the more informative note, so both surfaces render one shared `getApplyInstructions()` body with no per-surface text. Skill output is unchanged; the command's contextFiles note gains the example artifact sets. Updated the contract test to assert both surfaces render the shared core (no silent template-level drift), and regenerated the command function hash accordingly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

alfred-openspec

Re-reviewed at bcb1131 after the follow-up. The generated skill remains unchanged, the command gains only the clearer contextFiles examples, and both now render one shared instruction body. A fresh frozen install, build, lint, 365 focused template/reference/init/update/migration tests, static-skill regeneration, and the full hosted matrix pass.

cloudflare-workers-and-pages · 2026-08-05T15:36:59Z

Deploying openspec-docs with Cloudflare Pages

Latest commit:	`7a81745`
Status:	✅ Deploy successful!
Preview URL:	https://d1c26a02.openspec-docs.pages.dev
Branch Preview URL:	https://claude-apply-template-shared.openspec-docs.pages.dev

View logs

clay-good requested a review from a team as a code owner August 5, 2026 14:35

clay-good requested review from TabishB and removed request for a team August 5, 2026 14:35

clay-good mentioned this pull request Aug 5, 2026

Commands and Skills are nearly duplicated after init — maintenance drift risk in team workflows #1139

Closed

alfred-openspec previously approved these changes Aug 5, 2026

View reviewed changes

clay-good dismissed alfred-openspec’s stale review via bcb1131 August 5, 2026 14:47

clay-good mentioned this pull request Aug 5, 2026

fix(templates): deduplicate apply skill and command instructions #1153

Merged

alfred-openspec approved these changes Aug 5, 2026

View reviewed changes

Merge branch 'main' into claude/apply-template-shared-core

7a81745

clay-good added this pull request to the merge queue Aug 5, 2026

Merged via the queue into main with commit 96a6548 Aug 5, 2026
18 checks passed

clay-good deleted the claude/apply-template-shared-core branch August 5, 2026 15:57

coderabbitai Bot mentioned this pull request Aug 7, 2026

fix(apply): surface deferred scope instead of silently simplifying tasks #1530

Open

Navigation Menu

Uh oh!

refactor(templates): share one apply instruction body across skill and command - #1515

refactor(templates): share one apply instruction body across skill and command#1515
clay-good merged 3 commits into
mainfrom
claude/apply-template-shared-core

clay-good commented Aug 5, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

Walkthrough

Changes

Review ran into problems

Uh oh!

alfred-openspec left a comment

Uh oh!

alfred-openspec left a comment

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

clay-good commented Aug 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Review ran into problems

Uh oh!

alfred-openspec left a comment

Choose a reason for hiding this comment

Uh oh!

alfred-openspec left a comment

Choose a reason for hiding this comment

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying openspec-docs with Cloudflare Pages

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clay-good commented Aug 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Aug 5, 2026 •

edited

Loading