fix(explore): require explicit confirmation before writing files

[aymanxdev]

Risk: low — prompt text only; no code paths change. Touches the explore skill template, its generated /opsx:explore command twin, the committed skills.sh copy, and the pinned parity hashes.

What was wrong

In explore mode, the guardrail "You MAY create OpenSpec artifacts … if the user asks" let an agent read answers to its own clarifying questions as an implicit go-ahead. In the reported case the agent created a project schema under openspec/schemas/ and switched schema: in openspec/config.yaml while the user was still discussing a possible design. Workflow configuration was also uncovered ground: neither "Don't implement" (scoped to application code) nor "Don't auto-capture" (scoped to change artifacts) claimed it.

What changes

Both explore templates (skill and /opsx:explore command — their guardrail text is byte-identical) now instruct the agent to:

• ask a direct yes/no question and wait for explicit confirmation in a separate user message before the first write of any file, with wording that answers to design or clarifying questions are never consent to write;
• treat workflow configuration — schemas, templates, openspec/config.yaml — as changes, not thinking, under "Don't implement".

Why it's safe

Explore stays exactly as capable: reading, searching, diagramming, and creating artifacts on request are all unchanged. The only new behaviour is one confirmation question before the first write. Non-explore skills and commands are untouched.

Proof

• skills/openspec-explore/SKILL.md regenerated with pnpm build && pnpm generate:skills; parity hashes updated with pnpm regen:parity-hashes.
• Full suite: 4,076 tests across 140 files pass.
• Verified end-to-end in a scratch project: openspec init --tools claude from this branch installs the new text in both .claude/skills/openspec-explore/SKILL.md and .claude/commands/opsx/explore.md.
• Behavioural repro of the issue scenario against the fixed skill: entered explore mode, discussed adding a custom artifact, answered the agent's clarifying questions without ever saying "create it" — the agent sketched the design in chat and explicitly waited ("just say so and I'll scaffold it"); git status confirmed zero files written.

No OpenSpec change proposal is included since no main spec covers the explore skill and precedent (#1658) shipped skill-text fixes directly — happy to add one if you'd prefer.

Generated with Claude Code using claude-fable-5. Tested and verified as above.

Closes #1715

Summary by CodeRabbit

• New Features

  • Explore mode now requires explicit yes/no confirmation in a separate message before creating or modifying files.
  • OpenSpec artifacts can be created after confirmation, while implementation files and workflow configuration remain excluded.

• Documentation

  • Clarified Explore mode’s file-writing restrictions and confirmation requirements.

[openspec-cloud]

Fork pull request not scanned

Fork pull requests are not scanned. Open the branch in this repository, then create a new pull request.
View the OpenSpec Cloud check · A same-repository pull request is required.

[coderabbitai]

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: 382340c8-cf72-4e18-892b-9ac92c1cfefa

📥 Commits

Reviewing files that changed from the base of the PR and between f1b521d and f5ff932.

📒 Files selected for processing (4)

• .changeset/explore-explicit-write-confirmation.md
• skills/openspec-explore/SKILL.md
• src/core/templates/workflows/explore.ts
• test/core/templates/skill-templates-parity.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Explore mode now requires a separate direct yes/no confirmation before writing files. It prohibits implementation-related changes, including workflow configuration, schemas, templates, and openspec/config.yaml. Template parity hashes and a patch changeset were updated.

Changes

Explore write policy

Layer / File(s)	Summary
Explore guardrails skills/openspec-explore/SKILL.md, src/core/templates/workflows/explore.ts	Explore guidance requires explicit confirmation before file writes. It treats workflow configuration, schemas, templates, and project configuration as implementation changes.
Release metadata and parity validation .changeset/explore-explicit-write-confirmation.md, test/core/templates/skill-templates-parity.test.ts	The changeset documents the policy update. Parity baselines now match the updated explore skill content.

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

Merge Risk: ⚪ Minimal · up to f5ff9

This localized change adds explicit confirmation before explore mode writes files while preserving existing requested-write behavior. It is merge-ready after normal checks and review, with no actionable merge-blocking risk remaining.

Suggested reviewers: tabishb, clay-good

🚥 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 identifies the main change: requiring explicit confirmation before explore mode writes files.
Linked Issues check	✅ Passed	The changes address issue #1715 by requiring separate yes/no confirmation and covering workflow configuration under explore guardrails.
Out of Scope Changes check	✅ Passed	The changes are limited to explore guidance, generated templates, documentation, and related parity hashes.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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