Validate Workflow Skill

Validate Workflow

Validate AI Developer Workflow step outputs and ensure contract compliance.

Arguments

$ARGUMENTS: <step-type> [spec-path]
- step-type: One of plan, build, review, fix
- spec-path: Optional path to spec file (auto-detected if not provided)

Step Contracts

| Step | Output Type | Key Requirements | | --- | --- | --- | | plan | Spec file | Summary, requirements, criteria, approach | | build | Code changes | Commits with prefix, tests pass | | review | Report | PASS/FAIL status, severity-rated issues | | fix | Resolutions | Issues addressed, no new issues |

Instructions

Step 1: Identify Step Type

Parse the step type from arguments:

Valid types: plan, build, review, fix

Step 2: Load Step Contract

Plan Contract:

[ ] Spec file exists at specs/*.md
[ ] Contains Summary section
[ ] Contains Requirements list
[ ] Contains Acceptance Criteria
[ ] Contains Technical Approach
[ ] Scope is bounded and achievable

Build Contract:

[ ] Files modified or created
[ ] Commits exist with build: prefix
[ ] No build/lint errors
[ ] Tests pass (if exist)
[ ] All spec requirements addressed

Review Contract:

[ ] Report generated with structured format
[ ] STATUS is clearly PASS or FAIL
[ ] Issues have severity levels (CRITICAL/HIGH/MEDIUM/LOW)
[ ] Issue descriptions are actionable
[ ] All code reviewed against spec

Fix Contract:

[ ] All flagged issues addressed
[ ] Commits exist with fix: prefix
[ ] No new issues introduced
[ ] Verification confirms resolution

Step 3: Validate Outputs

For Plan Step:

# Find latest spec file
ls -t specs/*.md | head -1

# Check required sections
grep -c "## Summary\|## Requirements\|## Acceptance\|## Technical" specs/latest.md

For Build Step:

# Check for build commits
git log --oneline -5 | grep "^[a-f0-9]* build:"

# Check build status
npm run build 2>&1 | tail -5
# or: dotnet build 2>&1 | tail -5

# Check tests
npm test 2>&1 | tail -10
# or: dotnet test 2>&1 | tail -10

For Review Step:

# Check for review report
ls -t .claude/temp/*review*.md 2>/dev/null | head -1

# Verify PASS/FAIL status
grep -E "STATUS:|Result:" review_report.md

For Fix Step:

# Check for fix commits
git log --oneline -5 | grep "^[a-f0-9]* fix:"

# Verify no new issues
# (re-run review step)

Step 4: Check Success Criteria

For each criterion in the contract:

Execute verification command/check
Record pass/fail status
Capture evidence (file path, command output, etc.)

Step 5: Report Results

Generate validation report.

Output

## Workflow Validation Report

### Step Validated

**Step:** {plan|build|review|fix}
**Spec Path:** {path if applicable}
**Timestamp:** {ISO-8601}

### Contract Check

| Requirement | Status | Evidence |
| --- | --- | --- |
| {requirement} | ✅/❌ | {details} |
| {requirement} | ✅/❌ | {details} |
| {requirement} | ✅/❌ | {details} |

### Output Validation

#### {Output Name}

- **Path:** {path}
- **Exists:** ✅/❌
- **Format Valid:** ✅/❌
- **Issues:** {if any}

### Success Criteria

| Criterion | Met | Evidence |
| --- | --- | --- |
| {criterion} | ✅/❌ | {evidence} |
| {criterion} | ✅/❌ | {evidence} |

### Overall Status

**Result:** VALID | INVALID

**Summary:** {brief summary of validation result}

### Issues Found

1. **{Severity}:** {description}
   - **Location:** {where}
   - **Expected:** {what should be}
   - **Actual:** {what was found}
   - **Recommendation:** {how to fix}

### Next Steps

- {Recommended action if invalid}
- {Continue to next step if valid}

Validation Quick Reference

Plan Validation Commands

# Check spec exists
test -f specs/*.md && echo "Spec exists"

# Check sections
for section in "Summary" "Requirements" "Acceptance" "Technical"; do
  grep -q "## $section" specs/*.md && echo "$section: OK"
done

Build Validation Commands

# Check commits
git log --oneline -10 | grep "build:"

# Check tests
npm test --if-present || echo "No npm tests"
dotnet test 2>/dev/null || echo "No dotnet tests"

Review Validation Commands

# Check report format
grep -E "^STATUS:|^Result:" review_output.md

# Check severity levels
grep -cE "CRITICAL|HIGH|MEDIUM|LOW" review_output.md

Anti-Patterns

| Avoid | Why | Instead | | --- | --- | --- | | Skipping validation | Proceeding with incomplete work | Always validate before next step | | Partial checks | Missing critical issues | Complete all contract checks | | Auto-fixing during validation | Scope creep | Validate only, fix separately | | Ignoring warnings | Technical debt | Address all severity levels |

Cross-References

@composable-steps.md - Step contracts
@adw-framework.md - ADW architecture
workflow-validator agent - Automated validation
composable-step-design skill - Step design patterns

Agent Skills: Validate Workflow

Install this agent skill to your local

Skill Files