fix(propose): wait for explicit implementation request

[clay-good]

Status

LGTM.

What was wrong

The generated propose workflow could finish the planning artifacts and continue directly into implementation. Its handoff suggested apply but did not explicitly require the workflow to stop, it did not clearly limit the triggering request to planning, and it could resolve material ambiguity without asking the user. This is the behavior reported across Factory, Cursor, Kilo, Pi, and Codex.

How it was fixed

• Put a planning-only boundary before the workflow steps and repeat the explicit stop at the final handoff.
• Clarify that any request selecting or triggering propose authorizes planning only, even when it asks to build or fix something.
• Ask the user before creating the change when ambiguity would materially change scope, externally observable behavior, compatibility, or acceptance criteria. Minor details still use recorded assumptions.
• Make implementation and apply instructions in the triggering request expire with the propose workflow. Applying requires a new user request after the artifacts are presented.
• Hand command-only tools exclusively to their generated apply command. Skill surfaces may also accept an explicit request to apply the change.
• Verify the boundary and apply handoff survive every registered command adapter and the affected tools' real initialization paths.

This is prompt hardening only. It does not add an approval state, change the artifact workflow, or alter any CLI/API behavior.

Replication / proof

• Regression tests cover the skill and command templates, boundary placement, material clarification, and the final stop.
• Adapter tests verify both boundaries and the correctly transformed apply invocation in every registered command format.
• End-to-end initialization generated and verified propose instructions for Factory, Cursor, Kilo, Pi, and Codex.
• npm test -- --run: 119 files, 3,480 tests passed.
• npm run lint: passed.
• npm run build: passed.

Closes #232.
Closes #258.
Closes #262.

Notes / nits

OpenSpec controls the generated command and skill instructions, not the host model's compliance. This PR fully addresses the repository-controlled prompt surfaces without claiming a formal enforcement gate.

The propose workflow remains one-step for clear requests. Users who want open-ended discovery can still use /opsx:explore; propose asks only about ambiguity that could materially change the result.

#1500 touches the same checked-in skill and parity hashes for unrelated guidance. Whichever PR lands second may need a mechanical rebase and hash refresh.

Summary by CodeRabbit

• New Features

  • Proposal workflows now stop after creating planning artifacts.
  • Prevented proposal workflows from implementing changes or editing project code before a separate implementation request.
  • Added clarification prompts when ambiguity may affect scope or behavior.
  • Prompted users to review planning artifacts before implementation.

• Tests

  • Added coverage across supported tool integrations.
  • Updated template consistency checks.

• Documentation

  • Documented the planning-only proposal behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 2daf8072-4d61-41da-9bc9-6842cb3cda93

📥 Commits

Reviewing files that changed from the base of the PR and between d150e57 and 9101e8a.

📒 Files selected for processing (6)

• .changeset/quiet-proposals-stop.md
• skills/openspec-propose/SKILL.md
• src/core/templates/workflows/propose.ts
• test/core/init.test.ts
• test/core/templates/propose.test.ts
• test/core/templates/skill-templates-parity.test.ts

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

• test/core/templates/skill-templates-parity.test.ts
• src/core/templates/workflows/propose.ts
• .changeset/quiet-proposals-stop.md
• test/core/templates/propose.test.ts

---

📝 Walkthrough

Walkthrough

The propose workflow now stops after creating planning artifacts. It prohibits implementation and project-code edits until a separate implementation request. Tests, initialization coverage, parity hashes, and a patch Changeset cover the updated instructions.

Changes

Propose planning boundary

Layer / File(s)	Summary
Enforce planning-only behavior skills/openspec-propose/SKILL.md, src/core/templates/workflows/propose.ts	The propose skill and command templates prohibit implementation and project-code edits. They require clarification for material ambiguity and artifact review before implementation.
Validate and publish the guardrail test/core/templates/propose.test.ts, test/core/init.test.ts, test/core/templates/skill-templates-parity.test.ts, .changeset/quiet-proposals-stop.md	Tests verify the guardrail across command adapters and tool targets. Parity hashes track generated content. A patch Changeset records the release.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#306: Updates proposal workflow templates with planning-only boundaries.
• Fission-AI/OpenSpec#1089: Updates the same propose workflow templates and generated skill behavior.
• Fission-AI/OpenSpec#1464: Updates propose workflow guidance around user clarification.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: require an explicit implementation request after the propose workflow.
Linked Issues check	✅ Passed	The changes address issues [#232], [#258], and [#262] by enforcing planning-only behavior, clarification, and deferred implementation.
Out of Scope Changes check	✅ Passed	The changes remain within scope and include related templates, generated artifacts, tests, and validation updates.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/stop-propose-before-implementation

---

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

[alfred-openspec]

Reviewed at exact head f36897a. Focused template, parity, and initialization coverage passes; the generated guidance now preserves selected stores, validates syncs before success, and keeps propose planning-only until a separate apply request.

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	d150e57
Status:	✅  Deploy successful!
Preview URL:	https://19758cf7.openspec-docs.pages.dev
Branch Preview URL:	https://codex-stop-propose-before-im.openspec-docs.pages.dev

View logs

[alfred-openspec]

Re-reviewed the rebased head. The planning-only propose boundary and explicit apply handoff are unchanged, parity hashes match current main, 116 focused propose/init/parity tests pass locally, and the full hosted matrix is green.