Add lightweight verification step (implementation vs spec)

[ramarivera]

Problem

Today OpenSpec validates spec structure, but there is no lightweight, built-in way to guide post-implementation verification against an approved change. Teams end up improvising how to verify alignment with change deltas/specs, which can lead to drift or missed requirements.

Proposal

Introduce an optional, lightweight verification workflow that lives with each change:

• Add a per-change openspec/changes/<change-id>/verification.md template that captures:
  • Spec alignment expectations (which deltas/specs apply)
  • Hallucination risks (packages/functions/paths that must/must not exist)
  • Pattern references (files to match)
  • Spec-specific rules (hard constraints)
• Provide a /verify slash command (or guidance in AGENTS.md) that instructs AI to:
  • Load openspec/changes/<change-id>/verification.md
  • Compare implementation to openspec/changes/<change-id>/specs/ and baseline openspec/specs/
  • Flag spec drift, missing acceptance criteria, or hallucinated usage

Benefits

• Lightweight and optional; no automated testing required
• Provides a consistent, repeatable review checklist for implementation-vs-spec
• Complements existing validation instead of replacing it
• Aligns with issue Feature request: Include acceptance verification instructions for each task in AGENTS.md prompts #345 (acceptance verification instructions per task)

Notes / Implementation sketch

• Add template file under OpenSpec assets (or generate on openspec proposal).
• Keep verification guidance separate from spec linting (this is post-implementation review guidance).
• The verification.md format can be markdown-only; no parsing required initially.

---

Disclaimer: This issue was drafted with AI assistance after searching existing OpenSpec issues for related requests.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Feature request: Include acceptance verification instructions for each task in AGENTS.md prompts #345
• Feature request: automatically update project.md during archive #331
• Model tends to cheat around "no deltas found error" #194
• Feature request: option to auto-create feature branch for new proposals #332

🔗 Related PRs

#283 - Fix Cline: use workflows instead of rules for slash commands [merged]
#306 - Enhance proposal guidelines in slash-command-templates.ts [merged]
#310 - Clarify scaffold proposal [merged]
#318 - Add Antigravity workflow support [merged]
#376 - feat(spec): add XDG global config and config command proposals [merged]

👤 Suggested Assignees

• BobbyWang0120
• TabishB
• agladysh
• B2F
• jax-max

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[ramarivera]

I would be more than happy to raise a proposal and iterate on this :)

[TabishB]

@ramarivera I'm pretty aligned on this, I think it's needed and something that should be in the default workflow. Happy for you to create a proposal.

I'm holding off on adding more steps/slash commands for now as I'm doing a bit of a refactor to make OpenSpec more customisable by being able to modify or create your own "workflow"/artifacts generated so to speak.

The goal will be to maintain a default -> This is what we think works best overall workflow but allow users to modify/create your own. This will also help us experiment more and test out different versions of workflows to see what actually works better in practice.

I want to convert the current workflow to this new format as well as make it more granular for better control. I was thinking of adding this step as part of that.

This will hopefully be in by next week. Just giving some rough estimates on timelines here. So yes feel free to go ahead and create the proposal and we can start experimenting this with the new workflow.

[ramarivera]

@ramarivera I'm pretty aligned on this, I think it's needed and something that should be in the default workflow. Happy for you to create a proposal.

I'm holding off on adding more steps/slash commands for now as I'm doing a bit of a refactor to make OpenSpec more customisable by being able to modify or create your own "workflow"/artifacts generated so to speak.

The goal will be to maintain a default -> This is what we think works best overall workflow but allow users to modify/create your own. This will also help us experiment more and test out different versions of workflows to see what actually works better in practice.

I want to convert the current workflow to this new format as well as make it more granular for better control. I was thinking of adding this step as part of that.

This will hopefully be in by next week. Just giving some rough estimates on timelines here. So yes feel free to go ahead and create the proposal and we can start experimenting this with the new workflow.

Hey @TabishB , do you need any help with the workflow engine and so on? Happy to help there as well

[TabishB]

@ramarivera I'm open to collaboration! I'll be create a few changes for this soon. Wold be open to a sanity check and getting your thoughts on it. Maybe dm me on discord or let me know what platform you prefer