Skip to content

fix(skills): avoid activation outside OpenSpec projects - #1658

Open
clay-good wants to merge 2 commits into
mainfrom
codex/scope-skills-to-openspec-projects
Open

fix(skills): avoid activation outside OpenSpec projects#1658
clay-good wants to merge 2 commits into
mainfrom
codex/scope-skills-to-openspec-projects

Conversation

@clay-good

@clay-good clay-good commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Status: LGTM.

What was wrong

Generated OpenSpec skills advertised broad actions such as exploring ideas and proposing features. Tools that discover skills globally could therefore select an OpenSpec workflow for an ordinary request in a repository that does not use OpenSpec.

How it was fixed

Every generated workflow skill now leads with an OpenSpec-only selection boundary. It still supports all existing OpenSpec contexts: a local openspec/ root, a configured or user-selected store, or an explicit skill invocation or OpenSpec request. Each original workflow-specific routing description remains intact.

As defense in depth, skill bodies now perform the same check before applying a workflow and return to normal assistance if no OpenSpec context exists. Explicit /opsx:* commands remain unchanged.

Replication / proof

  • Confirmed that current main emits broad global descriptions for all 12 workflow skills, including explore and propose.
  • Confirmed from OpenCode and Agent Skills behavior that descriptions are the model-facing skill-selection signal.
  • Added registry-level coverage for the description boundary, body fallback, and unchanged explicit commands.
  • Regenerated and parity-checked the committed skills.sh distribution.
  • Parsed all 12 generated frontmatters as YAML and verified description lengths of 289–453 characters, below the 1,024-character limit.
  • Build and lint pass.
  • 1,137 focused generation, adapter, parity, and CLI end-to-end tests pass.
  • Three independent adversarial reviews covering semantics, compatibility, and test gaps found no remaining actionable risk.

Notes / nits

This changes skill-selection metadata and adds a read-only skill preflight. It does not change CLI behavior, command syntax, schemas, file formats, workflow architecture, or explicit slash-command behavior. No changeset is included because routine bug fixes follow the normal release cadence.

Closes #1645

Summary by CodeRabbit

  • Behavior Updates

    • OpenSpec workflows now activate only when an OpenSpec project or applicable OpenSpec store is detected, or when explicitly requested.
    • Requests without valid OpenSpec context continue through normal handling.
    • Bulk archiving now synchronizes specifications through the updated workflow command.
  • Tests

    • Added coverage to verify consistent activation rules and behavior across deployed workflows.

@clay-good
clay-good requested a review from a team as a code owner August 14, 2026 21:04
@clay-good
clay-good requested review from TabishB and removed request for a team August 14, 2026 21:04
@coderabbitai

coderabbitai Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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: c085eae9-15d9-4e95-ae9a-4f14295657ba

📥 Commits

Reviewing files that changed from the base of the PR and between 3270917 and 5dcd1c2.

📒 Files selected for processing (26)
  • skills/openspec-apply-change/SKILL.md
  • skills/openspec-archive-change/SKILL.md
  • skills/openspec-bulk-archive-change/SKILL.md
  • skills/openspec-continue-change/SKILL.md
  • skills/openspec-explore/SKILL.md
  • skills/openspec-ff-change/SKILL.md
  • skills/openspec-new-change/SKILL.md
  • skills/openspec-onboard/SKILL.md
  • skills/openspec-propose/SKILL.md
  • skills/openspec-sync-specs/SKILL.md
  • skills/openspec-update-change/SKILL.md
  • skills/openspec-verify-change/SKILL.md
  • src/core/templates/workflows/apply-change.ts
  • src/core/templates/workflows/archive-change.ts
  • src/core/templates/workflows/bulk-archive-change.ts
  • src/core/templates/workflows/continue-change.ts
  • src/core/templates/workflows/explore.ts
  • src/core/templates/workflows/ff-change.ts
  • src/core/templates/workflows/new-change.ts
  • src/core/templates/workflows/onboard.ts
  • src/core/templates/workflows/propose.ts
  • src/core/templates/workflows/skill-activation.ts
  • src/core/templates/workflows/sync-specs.ts
  • src/core/templates/workflows/update-change.ts
  • src/core/templates/workflows/verify-change.ts
  • test/core/templates/skill-templates-parity.test.ts
🚧 Files skipped from review as they are similar to previous changes (8)
  • skills/openspec-new-change/SKILL.md
  • src/core/templates/workflows/update-change.ts
  • skills/openspec-verify-change/SKILL.md
  • skills/openspec-continue-change/SKILL.md
  • src/core/templates/workflows/ff-change.ts
  • src/core/templates/workflows/onboard.ts
  • skills/openspec-onboard/SKILL.md
  • src/core/templates/workflows/bulk-archive-change.ts

📝 Walkthrough

Walkthrough

OpenSpec skill descriptions and workflow templates now require an OpenSpec directory, applicable store, or explicit OpenSpec request. A shared activation guard is prepended to generated workflows. Parity tests validate the generated content.

Changes

OpenSpec skill activation

Layer / File(s) Summary
Shared activation guard and workflow templates
src/core/templates/workflows/skill-activation.ts, src/core/templates/workflows/*
Workflow templates now use SKILL_ACTIVATION_GUARD and describe OpenSpec activation requirements. Bulk archiving invokes /opsx:sync.
Generated skill activation requirements
skills/openspec-*/SKILL.md
Generated skills now check for an OpenSpec directory, applicable store, or explicit OpenSpec request before continuing.
Activation parity validation
test/core/templates/skill-templates-parity.test.ts
Parity tests update generated-content hashes and verify activation guards and apply-surface ordering.

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

Merge Risk: ⚪ Minimal · up to 5dcd1

The change limits automatic skill activation to OpenSpec projects or explicitly named OpenSpec requests while preserving explicit commands and workflow behavior. No actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

Suggested reviewers: tabishb, alfred-openspec

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The bulk archive template also changes synchronization from openspec-sync-specs to /opsx:sync, which is unrelated to the activation guardrails. Remove or separately justify the synchronization-command change, or link an issue that requires it.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The changes add activation guardrails that address issue #1645 by requiring OpenSpec context or an explicit OpenSpec request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: preventing skill activation outside OpenSpec projects.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/scope-skills-to-openspec-projects

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant