Improve explore → change transition guidance in skills

[TabishB]

Problem

When transitioning from /opsx:explore to creating a change proposal, the agent may manually create files in openspec/changes/ without running openspec new change, which skips scaffolding and misses the .openspec.yaml metadata file.

What happened:

1. Ran /opsx:explore to explore an idea
2. User said "capture this in a proposal"
3. Agent created proposal.md directly instead of running openspec new change first
4. .openspec.yaml was missing from the change directory

Proposed Fix

1. Add to explore skill: Explicit guidance for transitioning to change creation

   To capture as a change, run `openspec new change "<name>"` or `/opsx:new`
   

2. Add project rule to openspec/config.yaml:

   rules:
     design:
       - Never manually create files in openspec/changes/ - always use `openspec new change` first

3. Add guardrail to ff skill: Verify .openspec.yaml exists after openspec new change

Context

Discovered during creation of simplify-skill-installation change in PR #719.

[21st-connector]

Task completed.

Posted an enrichment comment on issue #720. Here's a summary of what was included:

Not a duplicate — no existing issues cover this specific explore → change transition gap.

Key finding: The proposed rules.design config approach has a scoping limitation. The rules-injection system (openspec/specs/rules-injection/spec.md) is per-artifact — a design rule only applies when generating the design artifact, not during explore mode. This means the config rule alone won't prevent the problem.

Recommended approach:

1. Explore skill template (src/core/templates/workflows/explore.ts) — Add an explicit guardrail against manual file creation in openspec/changes/ and strengthen the "When no change exists" transition guidance. This is the highest-impact, simplest fix.
2. FF skill guardrail (src/core/templates/workflows/ff-change.ts) — Add .openspec.yaml verification after openspec new change runs.
3. Config rule — Only effective if a global/non-artifact-scoped rule mechanism is added to the rules system (currently unsupported).

The comment includes specific file paths, line numbers, and suggested text for each change.

---

View full conversation

Powered by 1Code

[21st-connector]

Issue Analysis

Not a duplicate

No existing issues cover this specific explore → change transition guidance gap. The closest related issue is #16847 (auto-load openspec/ directory), which touches the OpenSpec ecosystem but addresses a different concern.

---

Relevant Files

1. Explore skill — where transition guidance lives today

• src/core/templates/workflows/explore.ts:15 — The IMPORTANT block already says to remind users about /opsx:new or /opsx:ff, but only when the user asks to implement. It doesn't cover the case where the user says "capture this as a proposal" (which isn't implementation, so the guardrail doesn't trigger).
• src/core/templates/workflows/explore.ts:95-101 — "When no change exists" section suggests transitioning to /opsx:new or /opsx:ff, but only as something to offer, not a hard constraint.
• src/core/templates/workflows/explore.ts:256 and :273-274 — "Ending Discovery" section mentions /opsx:new and /opsx:ff but doesn't explicitly warn against manual file creation.
• src/core/templates/workflows/explore.ts:282-291 — Guardrails section. Currently includes "Don't implement" and "Don't auto-capture" but nothing about how to capture (i.e., always via CLI, never manually).

2. /opsx:new skill — the correct scaffolding path

• src/core/templates/workflows/new-change.ts:38-43 — Step 3 runs openspec new change "<name>" which creates the scaffolded directory including .openspec.yaml.
• src/core/templates/workflows/new-change.ts:70-74 — Guardrails for /opsx:new itself (don't create artifacts yet, just show instructions).

3. /opsx:ff skill — fast-forward path

• src/core/templates/workflows/ff-change.ts:28-32 — Also runs openspec new change "<name>" as step 2 before creating artifacts.
• src/core/templates/workflows/ff-change.ts:97-102 — Guardrails section. The proposed .openspec.yaml existence check would go here.

4. Project config — where the proposed rule would go

• openspec/config.yaml:15-24 — Existing rules section with per-artifact rules for specs, tasks, and design. The proposed design rule about never manually creating files in openspec/changes/ would be added here.

5. Rules injection spec

• openspec/specs/rules-injection/spec.md — Defines how per-artifact rules from config are injected into instructions. Important: rules are keyed by artifact ID (e.g., proposal, specs, design, tasks), not by arbitrary categories. A rule under design: would only apply when creating the design artifact, not globally.

---

Key Observation: Rules Scoping Limitation

The proposed fix suggests adding a rule under rules.design in openspec/config.yaml:

rules:
  design:
    - Never manually create files in openspec/changes/ - always use `openspec new change` first

However, per the rules-injection spec (openspec/specs/rules-injection/spec.md:9-17), rules are per-artifact — a design rule is only injected when generating the design artifact, not during explore mode or other contexts. For this guardrail to be effective during the explore → change transition, it would need to be either:

• Added directly to the explore skill template instructions (proposal fix feat: initialize typescript project #1), or
• Added as a global project-level constraint (not currently supported by the rules system — would require a new feature like a top-level rules.global key)

The explore skill template approach (fix #1) is the most straightforward path.

---

Suggested Implementation Approach

Fix 1 — Explore skill transition guidance (highest impact, simplest change):

In src/core/templates/workflows/explore.ts, add explicit guidance to both the skill template and command template. Two places to modify:

1. In the "When no change exists" section (~line 97), strengthen the transition guidance:

   **IMPORTANT**: To capture insights as a change, ALWAYS use `openspec new change "<name>"` 
   (or `/opsx:new` / `/opsx:ff`). Never manually create files in `openspec/changes/` — 
   the CLI scaffolds required metadata (`.openspec.yaml`) that manual creation misses.
   

2. Add a new guardrail to the Guardrails section (~line 282):

   - **Don't manually scaffold changes** - Never create files directly in `openspec/changes/`. 
     Always use `openspec new change` to ensure `.openspec.yaml` and proper directory structure.
   

These same changes should be mirrored in the command template starting at line 298.

Fix 2 — Config rule (limited effectiveness due to scoping):

If still desired, add to openspec/config.yaml under a new artifact-agnostic key. However, this requires extending the rules-injection system to support non-artifact-scoped rules, which is a larger change.

Fix 3 — FF skill guardrail (defensive check):

In src/core/templates/workflows/ff-change.ts:97-102, add a verification step:

- After running `openspec new change`, verify `.openspec.yaml` exists at 
  `openspec/changes/<name>/.openspec.yaml` before proceeding with artifact creation

This is already partially covered by the existing guardrail at line 102: "Verify each artifact file exists after writing before proceeding to next" — but adding an explicit .openspec.yaml check after scaffolding would catch failures earlier.

---

Files to Modify (Summary)

File	Change
src/core/templates/workflows/explore.ts	Add transition guardrail + strengthen "When no change exists" section
src/core/templates/workflows/ff-change.ts	Add .openspec.yaml verification after openspec new change
openspec/config.yaml	Optional: add rule if global rule support is added