Improve explore → change transition guidance in skills #720

Activity

1. 21st-connector commented on Feb 18, 2026

   

   21st-connectorBot

   on Feb 18, 2026 – with 21st - Connector

   Last edited by 21st-connector

   Contributor

   More actions

   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
2. 21st-connector commented on Feb 18, 2026

   

   21st-connectorBot

   on Feb 18, 2026 – with 21st - Connector

   Contributor

   More actions

   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
3. clay-good

   closed this as completedin #1503on Aug 4, 2026
4. clay-good

   added a commit that references this issue on Sep 10, 2026

   docs(explore): stop claiming explore never writes files

   ...

   922aa1a
5. pull

   added a commit that references this issue on Sep 16, 2026

   docs(explore): stop claiming explore never writes files (Fission-AI#1838

   ...

   b928165