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`:

```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:

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

Example:
```bash
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:

```json
{
  "passed": true,
  "checks":