Refactor skill packaging so optional workflows do not break default experiences

[alfred-openspec]

Problem

Some default workflows can reference optional skills that are not installed in core/default profiles. This creates user-facing command paths that fail at runtime in core installs.

Context

Use #913 as a concrete acceptance case: /opsx-archive can surface a sync path that depends on openspec-sync-specs, but core profile does not include that workflow.

Scope

• Define packaging policy for default profile composition.
• Ensure default profiles never expose optional-skill-only paths.
• Provide explicit fallback/guard behavior where optional workflows are referenced.
• Add regression coverage for default vs custom profile behavior.

Success criteria

• Default profile workflows are self-sufficient.
• No required flow can call missing skills in default mode.
• Existing users can still opt into richer profiles explicitly.

[21st-connector]

🤖 Automation triggered: Enrich Github Issue

I'm starting to work on this automatically.

---

View live progress

Powered by 1Code

[21st-connector]

Issue Analysis

Root Cause

The core problem is in src/core/templates/workflows/archive-change.ts (lines 67 and 276). The openspec-archive-change skill (part of the core profile) unconditionally instructs the AI agent to invoke openspec-sync-specs via the Skill tool when the user selects "Sync now":

If user chooses sync, use Task tool (subagent_type: "general-purpose",
prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'...")

However, openspec-sync-specs maps to the sync workflow (src/core/profile-sync-drift.ts:20), which is not in CORE_WORKFLOWS:

// src/core/profiles.ts:14
export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive'] as const;

The sync workflow is only available when users explicitly opt into a custom profile. So on core profile installs, the openspec-sync-specs skill file is never generated, and the Skill tool invocation fails at runtime.

Scope of the Problem

This is not limited to the archive/sync case. The broader pattern is: skill template content is static and does not adapt to which workflows are actually installed. Any skill that cross-references another skill in its instructions will break if the referenced skill is outside the active profile.

Currently, the archive skill is the only confirmed case, but the architecture has no guardrail preventing future templates from introducing similar cross-references.

Relevant Files

File	Role
src/core/templates/workflows/archive-change.ts:67,276	Archive skill references openspec-sync-specs
src/core/profiles.ts:14	Defines CORE_WORKFLOWS (no sync)
src/core/profile-sync-drift.ts:14-26	WORKFLOW_TO_SKILL_DIR mapping
src/core/shared/skill-generation.ts	Skill template filtering by profile workflows
src/core/init.ts:512-522	Init filters templates by profile but not template content

Existing Infrastructure

The codebase already has profile-aware filtering at the file level — getSkillTemplates(workflows) in src/core/shared/skill-generation.ts only generates skills for active workflows. The gap is that template content is not profile-aware. A skill's instructions can reference any other skill regardless of whether it will be installed.

The drift detection system (src/core/profile-sync-drift.ts:88-161) validates that the right files exist on disk, but does not validate that cross-skill references within those files are satisfiable.

Potential Approaches

1. Conditional template content (recommended for the archive/sync case)
Make the archive template profile-aware: omit the "Sync now" prompt option and the openspec-sync-specs invocation when the sync workflow is not in the active profile. The CLI already has a deterministic sync path via openspec archive (as noted in #863), which could serve as the fallback.

2. Guard at the Skill tool invocation layer
Add runtime detection: before the agent invokes a skill, check if the skill file exists. If not, either fall back to a CLI equivalent or inform the user that the workflow requires a profile upgrade. This is harder since skill invocation happens in the AI agent, not in OpenSpec code.

3. Add sync to core profile
Move sync into CORE_WORKFLOWS. This is the simplest fix for this specific case but doesn't address the general architectural problem of cross-skill references. It also increases the core profile footprint, which was deliberately kept minimal.

4. Template content transformation (general solution)
Extend the skill generation pipeline to post-process template content based on the active profile — stripping or replacing cross-references to unavailable skills. This pairs with the existing transformInstructions parameter in generateSkillContent() (src/core/shared/skill-generation.ts).

Related Issues

• /opsx-archive can offer 'Sync now' even when openspec-sync-specs is not installed (core profile) #913 — The concrete acceptance case: /opsx-archive offers "Sync now" on core profile where openspec-sync-specs is missing. Directly blocked by this issue.
• AI commands and skills for /opsx:archive do not invoke openspec archive CLI, unlike official docs and tutorials #863 — Archive skill doesn't use openspec archive CLI. The CLI already handles sync deterministically, making it a natural fallback for core profile.
• [Bug] Skills-only delivery emits /opsx:* command references #879 — Skills-only delivery emits /opsx:* command references that don't exist. Same class of problem (generated content references unavailable artifacts).
• [Fix] Add transformToSkillReferences for skills-only delivery mode #881 — Fix for [Bug] Skills-only delivery emits /opsx:* command references #879, adding transformToSkillReferences for skills-only delivery. Demonstrates the content-transformation pattern that could generalize to profile-aware transforms.
• [Question/Bug] archive without syncing #764 — "Archive without syncing" — user confusion about the sync/archive coupling.
• Are skills even necessary? why bloat context with 10 openspec skills? #611 — "Are skills even necessary?" — context on why the core profile was trimmed.

Regression Coverage

The issue calls for regression tests on default vs custom profile behavior. The existing test infrastructure in this repo validates drift detection. New tests should cover:

1. Core profile skill content does not reference any skill outside CORE_WORKFLOWS
2. Custom profile skill content only references skills within the selected workflow set
3. openspec init --profile core followed by archive workflow execution does not attempt to invoke missing skills
4. Profile switching from custom→core correctly removes optional skill references from generated content

A static analysis test that parses all generated skill content for openspec-* skill name references and validates them against the active workflow set would catch this class of issue generically.

[clay-good]

Partially addressed by #1775, which takes the update-change instance (#1734).

Against the success criteria here, for the default profile:

• packaging policy: optional-workflow references are now resolved at generation time against the installed workflow set, not left to a runtime availability check;
• explicit fallback: every such reference is authored with a CLI fallback (openspec status / openspec instructions);
• regression coverage: a test generates the whole core skill and command set and fails if any body names one of the six uninstalled workflows;
• richer profiles are unaffected — with every workflow installed the handoffs stay.

Not yet covered: a hand-built custom profile can still omit a workflow another one references (onboard names eight, propose names apply, new names continue). The mechanism is in place for those; authoring the remaining fallbacks is a follow-up. Leaving this open for that reason.