workflow-validator

Workflow Validator Skill

Validates JSON artifacts against validation criteria using deterministic script execution.

Automatic Validation via Hook (v0.6.0)

As of v0.6.0, the PostToolUse:Write hook automatically calls this validation script whenever an artifact is written to sandbox/*/outputs/*.json.

You typically don't need to manually invoke this skill - the hook handles it.

When to Manually Use This Skill

Use this skill only in these scenarios:

• Retrying after validation failure - when the hook blocked a write and you need to debug
• Debugging validation issues - to see detailed check results
• Checking artifacts outside the normal workflow - for ad-hoc validation
• Pre-checking before write - to validate data before writing to sandbox

What This Skill Does

• Reads validation criteria from sandbox/{id}/validation.json
• Runs deterministic validation script (no LLM tokens consumed)
• Returns pass/fail status with detailed check results
• Enables workflow completion verification

Validation Process

Step 1: Read Validation Criteria

Read the validation manifest at sandbox/{id}/validation.json:

{
  "workflow": "writing-kit",
  "version": "1.0.0",
  "sandboxId": "article-2025-12-18-xk7m",
  "steps": {
    "summary": {
      "output": "outputs/summary.json",
      "validate": {
        "required_fields": ["contentId", "headline", "tldr", "keyThemes"],
        "min_quotes": 3,
        "min_key_points": 5
      },
      "validated": false
    }
  }
}

Step 2: Run Validation Script

Execute the validation script with artifact path and criteria:

bun scripts/validate.ts <artifact-path> '<criteria-json>'

Example:

bun scripts/validate.ts sandbox/podcast-2024-12-08-ai/outputs/summary.json '{"required_fields":["contentId","headline"],"min_quotes":3}'

Step 3: Parse Results

The script returns JSON with pass/fail and individual checks:

{
  "passed": true,
  "checks": [
    { "name": "has_contentId", "passed": true, "message": "OK" },
    { "name": "has_headline", "passed": true, "message": "OK" },
    { "name": "min_quotes", "passed": true, "message": "Found 5 quotes (min: 3)" }
  ]
}

Step 4: Handle Results

If validation passes:

• Update validation.json to set validated: true for this output
• Continue to next workflow step

If validation fails:

• Review failed checks
• Either retry the subagent with feedback
• Or report the issue to the user

Validation Criteria Reference

required_fields

Array of field names that must exist in the artifact:

"required_fields": ["contentId", "headline", "tldr"]

min_quotes

Minimum number of items in importantQuotes array:

"min_quotes": 3

min_key_points

Minimum number of items in bullets or key points array:

"min_key_points": 5

min_outline_sections

Minimum number of outline sections:

"min_outline_sections": 4

has_hooks

Requires hooks array with at least one item:

"has_hooks": true

Output Format

The validation script returns:

{
  "passed": boolean,
  "checks": [
    {
      "name": "check_name",
      "passed": boolean,
      "message": "Human-readable result"
    }
  ]
}

Important Rules

• Automatic validation via hook - Hook handles validation on write; manual use only for retry/debugging
• Script is deterministic - No LLM context consumed
• Update validation.json - Mark steps validated when passed (v0.6.0 uses .steps not .outputs)
• Retry on failure - Give subagent feedback on what failed
• Check dependencies - Ensure required steps are validated before dependent steps
• Use exact paths - Artifact paths are relative to workspace root

Script Location

The validation script is at:

.claude/skills/workflow-validator/scripts/validate.ts

Run with Bun for TypeScript execution:

bun .claude/skills/workflow-validator/scripts/validate.ts <artifact> '<criteria>'