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

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.

Author: TabishB

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

@@ -0,0 +1,96 @@
+# Design: Add /opsx:verify Skill
+
+## Architecture Decision: Dynamic Generation via Setup Command
+
+### Context
+
+All existing opsx experimental skills (explore, new, continue, apply, ff, sync, archive) are dynamically generated when users run `openspec artifact-experimental-setup`. They are not manually created files checked into the repository.
+
+### Decision
+
+**Integrate verify into the existing artifact-experimental-setup system rather than creating static skill files.**
+
+### Rationale
+
+1. **Consistency**: All 7 existing opsx skills follow this pattern. Adding verify as the 8th skill should follow the same architecture.
+
+2. **Maintainability**: Template functions in `skill-templates.ts` are the single source of truth. Changes to skill definitions automatically propagate to all users when they re-run setup.
+
+3. **Distribution**: Users get the verify skill automatically when running `openspec artifact-experimental-setup`, just like all other opsx skills. No special installation steps needed.
+
+4. **Versioning**: Skills are generated from the installed npm package version, ensuring consistency between CLI version and skill behavior.
+
+### Implementation Approach
+
+#### 1. Template Functions
+
+Add two template functions to `src/core/templates/skill-templates.ts`:
+
+```typescript
+export function getVerifyChangeSkillTemplate(): SkillTemplate
+export function getOpsxVerifyCommandTemplate(): CommandTemplate
+```
+
+These return the skill definition (for Agent Skills) and slash command definition (for explicit invocation).
+
+#### 2. Setup Integration
+
+Update `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts`:
+
+- Import both template functions
+- Add verify to the `skills` array (position 8)
+- Add verify to the `commands` array (position 8)
+- Update help text to list `/opsx:verify`
+
+#### 3. Generated Artifacts
+
+When users run `openspec artifact-experimental-setup`, the command creates:
+
+- `.claude/skills/openspec-verify-change/SKILL.md` - Agent Skills format
+- `.claude/commands/opsx/verify.md` - Slash command format
+
+Both are generated from the template functions, with YAML frontmatter automatically added.
+
+### Alternatives Considered
+
+**Alternative 1: Static skill files in repository**
+
+Create `.claude/skills/openspec-verify-change/SKILL.md` as a static file in the OpenSpec repository.
+
+**Rejected because:**
+- Inconsistent with all other opsx skills
+- Requires users to manually copy/update files
+- Versioning becomes complicated (repo version vs installed package version)
+- Breaks the established pattern
+
+**Alternative 2: Separate verify setup command**
+
+Add `openspec setup-verify` as a separate command.
+
+**Rejected because:**
+- Fragments the setup experience
+- Users would need to run multiple commands
+- Doesn't scale if we add more skills in the future
+- Goes against the "setup once, get everything" philosophy
+
+### Trade-offs
+
+**Advantages:**
+- Consistent with existing architecture
+- Zero additional setup burden for users
+- Easy to update and maintain
+- Automatic version compatibility
+
+**Disadvantages:**
+- Slightly more complex initial implementation (template functions + integration)
+- Requires understanding the setup system (but that's already documented)
+
+### Verification
+
+The implementation correctly follows this design if:
+
+1. Both template functions exist in `skill-templates.ts`
+2. Verify appears in both skills and commands arrays in `artifact-workflow.ts`
+3. Help text mentions `/opsx:verify`
+4. Running `openspec artifact-experimental-setup` generates both skill and command files
+5. Build succeeds with no TypeScript errors

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

@@ -12,9 +12,12 @@ A user requested: "Can we get a :verify that will ensure that the implementation
 
 ## What Changes
 
-- Add new `/opsx:verify` slash command skill
+- Add `getVerifyChangeSkillTemplate()` function to `skill-templates.ts`
+- Add `getOpsxVerifyCommandTemplate()` function to `skill-templates.ts`
+- Integrate verify skill into `artifactExperimentalSetupCommand` in `artifact-workflow.ts`
+- Add verify to the skills and commands arrays in the setup command
+- Update help text to include `/opsx:verify` in the list of available commands
 - Create `opsx-verify-skill` capability spec
-- Create `SKILL.md` file at `.claude/skills/openspec-verify-change/`
 
 ## Verification Dimensions
 
@@ -36,5 +39,10 @@ Produces a prioritized report with:
 ## Impact
 
 - Affected specs: New `opsx-verify-skill` spec
-- Affected code: New skill file at `.claude/skills/openspec-verify-change/SKILL.md`
+- Affected code:
+  - `src/core/templates/skill-templates.ts` - Added 2 new template functions
+  - `src/commands/artifact-workflow.ts` - Integrated verify into experimental setup
+- Generated artifacts: When users run `openspec artifact-experimental-setup`:
+  - Creates `.claude/skills/openspec-verify-change/SKILL.md`
+  - Creates `.claude/commands/opsx/verify.md`
 - Related skills: Works alongside `/opsx:apply` and before `/opsx:archive`

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

@@ -1,28 +1,15 @@
 # Tasks: Add /opsx:verify Skill
 
-## 1. Skill Implementation
-- [ ] 1.1 Create `.claude/skills/openspec-verify-change/SKILL.md` with skill definition
-
-## 2. Completeness Verification Logic
-- [ ] 2.1 Implement task completion parsing (read tasks.md, count checkboxes)
-- [ ] 2.2 Implement spec coverage detection (extract requirements, search codebase)
-
-## 3. Correctness Verification Logic
-- [ ] 3.1 Implement requirement-to-code mapping logic
-- [ ] 3.2 Implement scenario coverage assessment
-- [ ] 3.3 Implement divergence detection heuristics
-
-## 4. Coherence Verification Logic
-- [ ] 4.1 Implement design.md decision extraction
-- [ ] 4.2 Implement design adherence checking
-- [ ] 4.3 Implement project pattern consistency checking
-
-## 5. Report Generation
-- [ ] 5.1 Implement summary scorecard generation
-- [ ] 5.2 Implement issue prioritization (CRITICAL/WARNING/SUGGESTION)
-- [ ] 5.3 Implement actionable recommendation generation
-
-## 6. Integration
-- [ ] 6.1 Add opsx:verify alias registration
-- [ ] 6.2 Test skill invocation end-to-end
-- [ ] 6.3 Update documentation/help text if applicable
+## 1. Skill Template Functions
+- [x] 1.1 Add `getVerifyChangeSkillTemplate()` to skill-templates.ts
+- [x] 1.2 Add `getOpsxVerifyCommandTemplate()` to skill-templates.ts
+
+## 2. Integration with artifact-experimental-setup
+- [x] 2.1 Import verify template functions in artifact-workflow.ts
+- [x] 2.2 Add verify to skills array in artifactExperimentalSetupCommand
+- [x] 2.3 Add verify to commands array in artifactExperimentalSetupCommand
+- [x] 2.4 Add verify to help text output
+
+## 3. Verification (Build & Test)
+- [x] 3.1 Verify TypeScript compilation succeeds
+- [x] 3.2 Verify all 8 skills are now included (was 7, now 8)

src/commands/artifact-workflow.ts

@@ -28,7 +28,7 @@ import {
   type SchemaInfo,
 } from '../core/artifact-graph/index.js';
 import { createChange, validateChangeName } from '../utils/change-utils.js';
-import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate } from '../core/templates/skill-templates.js';
+import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxVerifyCommandTemplate } from '../core/templates/skill-templates.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 
 // -----------------------------------------------------------------------------
@@ -800,6 +800,7 @@ async function artifactExperimentalSetupCommand(): Promise<void> {
     const ffChangeSkill = getFfChangeSkillTemplate();
     const syncSpecsSkill = getSyncSpecsSkillTemplate();
     const archiveChangeSkill = getArchiveChangeSkillTemplate();
+    const verifyChangeSkill = getVerifyChangeSkillTemplate();
 
     // Get command templates
     const exploreCommand = getOpsxExploreCommandTemplate();
@@ -809,6 +810,7 @@ async function artifactExperimentalSetupCommand(): Promise<void> {
     const ffCommand = getOpsxFfCommandTemplate();
     const syncCommand = getOpsxSyncCommandTemplate();
     const archiveCommand = getOpsxArchiveCommandTemplate();
+    const verifyCommand = getOpsxVerifyCommandTemplate();
 
     // Create skill directories and SKILL.md files
     const skills = [
@@ -819,6 +821,7 @@ async function artifactExperimentalSetupCommand(): Promise<void> {
       { template: ffChangeSkill, dirName: 'openspec-ff-change' },
       { template: syncSpecsSkill, dirName: 'openspec-sync-specs' },
       { template: archiveChangeSkill, dirName: 'openspec-archive-change' },
+      { template: verifyChangeSkill, dirName: 'openspec-verify-change' },
     ];
 
     const createdSkillFiles: string[] = [];
@@ -850,6 +853,7 @@ ${template.instructions}
       { template: ffCommand, fileName: 'ff.md' },
       { template: syncCommand, fileName: 'sync.md' },
       { template: archiveCommand, fileName: 'archive.md' },
+      { template: verifyCommand, fileName: 'verify.md' },
     ];
 
     const createdCommandFiles: string[] = [];
@@ -908,6 +912,7 @@ ${template.content}
     console.log('  • /opsx:apply - Implement tasks');
     console.log('  • /opsx:ff - Fast-forward: create all artifacts at once');
     console.log('  • /opsx:sync - Sync delta specs to main specs');
+    console.log('  • /opsx:verify - Verify implementation matches artifacts');
     console.log('  • /opsx:archive - Archive a completed change');
     console.log();
     console.log(chalk.yellow('💡 This is an experimental feature.'));