fix(explore): require explicit confirmation before writing files

[aymanxdev]

Status

LGTM. The write-confirmation contract is scope-bound, generated output is in parity, and CI is green.

What was wrong

Explore allowed OpenSpec artifacts “if the user asks,” which could let an agent mistake answers to its own design questions for consent to write. Workflow configuration such as schemas, templates, and openspec/config.yaml was also not clearly classified as implementation work.

How it was fixed

Both Explore delivery surfaces now:

• allow read-only commands and tools without confirmation;
• require a direct yes/no question before the first write-capable action;
• name the artifacts or files and proposed changes before asking;
• accept confirmation only in a separate user message;
• limit confirmation to the described scope and ask again before expanding it;
• allow creating or updating OpenSpec change artifacts only within that confirmed scope;
• keep workflow configuration and application-code changes outside Explore mode.

The committed openspec-explore skill was regenerated from the source template and parity hashes were refreshed.

Replication / proof

• Explore template and generated-skill tests: 40/40 passed.
• Build and lint pass.
• GitHub checks are green.
• Regression assertions cover read-only access, separate confirmation, named scope, scope expansion, workflow configuration, and source/generated parity.

Notes / nits

This changes prompt behavior only. It does not alter CLI write paths or grant Explore permission to implement application code.

Closes #1715

[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: e8d67a48-7315-4125-8976-8ea9826cc039

📥 Commits

Reviewing files that changed from the base of the PR and between 4d2435e and 62ef54f.

📒 Files selected for processing (5)

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

🚧 Files skipped from review as they are similar to previous changes (1)

• test/core/templates/skill-templates-parity.test.ts

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

---

📝 Walkthrough

Walkthrough

Explore mode now distinguishes read-only actions from write-capable actions. Write-capable actions require named files or artifacts and separate, scope-limited confirmation. Tests cover the updated templates and generated skill content.

Changes

Explore write policy

Layer / File(s)	Summary
Explore guardrails skills/openspec-explore/SKILL.md, src/core/templates/workflows/explore.ts, test/core/templates/explore.test.ts	Explore guidance permits read-only actions without confirmation. It requires separate confirmation before write-capable actions, names the affected scope, and allows OpenSpec artifact changes only within that scope.
Release metadata and parity validation .changeset/explore-explicit-write-confirmation.md, test/core/templates/skill-templates-parity.test.ts	The changeset records the confirmation contract. Parity hashes now match the updated templates and generated skill content.

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

Merge Risk: ⚪ Minimal · up to 62ef5

This localized wording change adds explicit confirmation before explore writes files without changing other workflow capabilities. No actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: tabishb, clay-good

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes require separate yes/no confirmation before writes, exclude clarifying answers as consent, and cover scoped workflow and OpenSpec artifact changes.
Out of Scope Changes check	✅ Passed	All changes update explore guidance, templates, parity hashes, tests, and the related changeset; no unrelated code or skills are modified.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: requiring explicit confirmation before file-writing actions.

✨ 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.}