feat(skills): implement /opsx:verify skill for validating change implementations #501

TabishB · 2026-01-14T06:25:33Z

Summary

Implements the /opsx:verify skill to validate that implementations match their change artifacts (specs, tasks, design) before archiving. This addresses the user request for a verification step to ensure implementation completeness, correctness, and coherence.

Changes

Added getVerifyChangeSkillTemplate() to src/core/templates/skill-templates.ts
- Comprehensive verification logic covering three dimensions:
  - Completeness: Task completion + spec coverage
  - Correctness: Requirement implementation + scenario coverage
  - Coherence: Design adherence + code pattern consistency
- Generates prioritized reports (CRITICAL/WARNING/SUGGESTION)
Added getOpsxVerifyCommandTemplate() to src/core/templates/skill-templates.ts
- Slash command variant for explicit invocation
Integrated verify into artifactExperimentalSetupCommand in src/commands/artifact-workflow.ts
- Added to skills array (8th skill)
- Added to commands array
- Updated help text
Created design.md documenting the architectural decision to use dynamic generation via the existing setup system rather than static skill files

Verification Dimensions

The skill validates three aspects:

Completeness: Are all tasks done? Are all spec requirements implemented?
Correctness: Do implementations match requirement intent? Are scenarios covered?
Coherence: Does implementation follow design decisions? Does it match project patterns?

Usage

After running openspec artifact-experimental-setup, users can invoke:

/opsx:verify - Interactive prompt to select a change
/opsx:verify --change <name> - Verify specific change

The skill generates a report with actionable recommendations for any issues found.

Test Plan

TypeScript compilation succeeds
Verify skill integrated into setup (8 skills total, was 7)
All tasks marked complete
End-to-end test: Run openspec artifact-experimental-setup and verify files generated
End-to-end test: Invoke /opsx:verify on a change and validate report output

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

New Features
- Added a new verify skill for validating completeness, correctness, and coherence of change artifacts
- New /opsx:verify slash command providing access to the verification workflow
- Verification reports now categorize issues by severity level (CRITICAL, WARNING, SUGGESTION) for clearer feedback

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…ementations Add comprehensive verification skill that checks implementation completeness, correctness, and coherence against change artifacts. The skill validates task completion, spec coverage, requirement implementation, and design adherence.

coderabbitai · 2026-01-14T06:25:42Z

📝 Walkthrough

Walkthrough

Adds a verify skill to the OpenSpec artifact workflow, introducing two new exported template functions (getVerifyChangeSkillTemplate and getOpsxVerifyCommandTemplate) in skill-templates.ts and integrating them into the artifact-experimental-setup command by importing, instantiating, and registering them with skills, commands arrays, and help text.

Changes

Cohort / File(s)	Summary
Design & Specification `openspec/changes/add-verify-skill/design.md`, `proposal.md`, `tasks.md`	Detailed design documentation specifying verify skill integration: template function signatures, artifact-workflow integration points, generated artifacts structure (SKILL.md and command definitions with YAML frontmatter), verification steps, and rationale.
Verify Skill & Command Templates `src/core/templates/skill-templates.ts`	Added two exported template functions totaling 337 lines: `getVerifyChangeSkillTemplate()` defining multi-step verification workflow (artifact loading, validation, coherence checks, structured report with CRITICAL/WARNING/SUGGESTION levels) and `getOpsxVerifyCommandTemplate()` providing equivalent OPSX slash command workflow.
Artifact Workflow Integration `src/commands/artifact-workflow.ts`	Imported new template functions and integrated verify into `artifactExperimentalSetupCommand`: instantiated verifyChangeSkill and verifyCommand, added to skills and commands generation arrays, and updated help text output to include `/opsx:verify`.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

feat(skills): add /opsx:verify change proposal #497 — Provides proposal/specs for the verify skill that this PR implements with template functions and artifact-workflow integration.
feat: add /opsx:explore command for exploratory thinking #467 — Demonstrates the same pattern of adding new OPSX skill and slash-command templates and wiring them into artifact-experimental-setup across identical files.
feat: add Agent Skills for experimental artifact workflow #424 — Shows related modifications to skill template surfaces and artifact-experimental-setup wiring using the same affected source files.

Poem

🐰✨ A verify skill hops into place,
Templates defined with methodical grace,
Workflows check artifacts with care,
Warnings and fixes float in the air,
OpenSpec's toolkit grows complete and fair! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: implementing a new /opsx:verify skill for validating change implementations, which is the core objective of this pull request.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧹 Recent nitpick comments

openspec/changes/add-verify-skill/proposal.md (1)
15-20: Consider adding line number references for clarity.

Per coding guidelines, use direct file references in format file.ts:42. Consider adding specific line numbers:
-- Add `getVerifyChangeSkillTemplate()` function to `skill-templates.ts`
-- Add `getOpsxVerifyCommandTemplate()` function to `skill-templates.ts`
-- Integrate verify skill into `artifactExperimentalSetupCommand` in `artifact-workflow.ts`
+- Add `getVerifyChangeSkillTemplate()` function to `skill-templates.ts:1792`
+- Add `getOpsxVerifyCommandTemplate()` function to `skill-templates.ts:2139`
+- Integrate verify skill into `artifactExperimentalSetupCommand` in `artifact-workflow.ts:787`
As per coding guidelines, this helps maintainers quickly locate the relevant code.

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 322bfd4 and 7478532.

📒 Files selected for processing (5)

openspec/changes/add-verify-skill/design.md
openspec/changes/add-verify-skill/proposal.md
openspec/changes/add-verify-skill/tasks.md
src/commands/artifact-workflow.ts
src/core/templates/skill-templates.ts

🧰 Additional context used

📓 Path-based instructions (3)

openspec/changes/*/{proposal,design,tasks}.md

📄 CodeRabbit inference engine (openspec/AGENTS.md)

Use direct file references in format file.ts:42 and reference specs as specs/auth/spec.md for clarity

Files:

openspec/changes/add-verify-skill/design.md
openspec/changes/add-verify-skill/tasks.md
openspec/changes/add-verify-skill/proposal.md

openspec/changes/*/tasks.md

📄 CodeRabbit inference engine (openspec/AGENTS.md)

Create tasks.md with numbered implementation sections and checkboxes in format - [ ] X.Y Task description

Files:

openspec/changes/add-verify-skill/tasks.md

openspec/changes/*/proposal.md

📄 CodeRabbit inference engine (openspec/AGENTS.md)

Create proposal.md with Why, What Changes (with BREAKING markers), and Impact sections

Files:

openspec/changes/add-verify-skill/proposal.md

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2026-01-13T22:51:14.330Z
Learning: Applies to openspec/changes/*/tasks.md : Create `tasks.md` with numbered implementation sections and checkboxes in format `- [ ] X.Y Task description`

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2026-01-13T22:51:14.330Z
Learning: Run `openspec validate [change] --strict --no-interactive` before sharing a proposal to resolve validation issues