validate

Validate Task Harness YAML

Pre-validates a task harness YAML file to catch configuration errors before starting execution.

Overview

The validate skill performs comprehensive checks on a YAML task file including:

• YAML syntax validation
• Schema structure verification (required fields)
• Task ID uniqueness validation
• Dependency graph validation (circular dependencies, invalid references)
• Quality gate configuration summary

This allows catching errors early before starting a potentially long-running harness session.

Prerequisites

• YAML file - A task harness configuration file to validate
• yq - Recommended for proper YAML parsing
• jq - For JSON processing

Instructions

Step 1: Check File Exists

Verify the provided YAML file path is valid:

[[ -f "$YAML_FILE" ]] || echo "ERROR: File not found"

Step 2: Parse and Validate YAML Syntax

Use yq to verify the YAML is parseable:

yq eval '.' "$YAML_FILE" > /dev/null 2>&1

Step 3: Validate Schema Structure

Check required fields:

• harness.metadata.name - Harness identifier
• harness.tasks - Non-empty array of tasks
• Each task has id, name, and objective or prompt

Step 4: Check Task ID Uniqueness

Ensure no duplicate task IDs exist:

yq -r '.harness.tasks[].id' "$YAML_FILE" | sort | uniq -d

Step 5: Validate Dependency Graph

Check all depends_on references point to existing task IDs and detect circular dependencies.

Step 6: Generate Report

Display comprehensive validation results with status and recommendations.

Output

Valid YAML

YAML Validation Report
======================
File: tasks/auth-implementation.yaml
Status: VALID ✓

Metadata:
  Name: implement-auth-feature
  Tasks: 5

Task Summary:
  ✓ plan-auth - Design Authentication System
  ✓ implement-model - Implement User Model
  ✓ implement-routes - Implement Routes
  ✓ write-tests - Write Tests
  ✓ update-docs - Update Documentation

Dependency Graph: Valid (no cycles)

Ready to start: /task-harness:start tasks/auth-implementation.yaml

Invalid YAML

YAML Validation Report
======================
File: tasks/broken.yaml
Status: INVALID ✗

Errors:
  - Task 'implement' references non-existent dependency: 'design'
  - Duplicate task ID: 'test'
  - Circular dependency detected: A → B → A

Fix these errors before starting.

Error Handling

Error	Cause	Resolution
File not found	Invalid path	Check file path spelling
YAML syntax error	Malformed YAML	Fix indentation/syntax
Duplicate task ID	Same ID used twice	Make IDs unique
Invalid dependency	Reference to non-existent task	Check depends_on spelling
Circular dependency	A depends on B depends on A	Restructure dependencies

Examples

Example 1: Validate a Working File

User: /task-harness:validate tasks/auth-feature.yaml

Skill: Parses YAML, validates all checks pass

Result:
YAML Validation Report
======================
File: tasks/auth-feature.yaml
Status: VALID ✓
Tasks: 5
Dependencies: Valid
Ready to start!

Example 2: Validate with Errors

User: /task-harness:validate tasks/broken.yaml

Skill: Finds multiple validation errors

Result:
YAML Validation Report
======================
Status: INVALID ✗

Errors:
  - Missing 'id' in task 2
  - Circular dependency: plan → implement → plan

Example 3: Validate with Warnings

User: /task-harness:validate tasks/minimal.yaml

Skill: Valid but with suggestions

Result:
YAML Validation Report
======================
Status: VALID (with warnings)

Warnings:
  - No test commands configured
  - No lint commands configured

Consider adding quality gates.

Resources

• {baseDir}/docs/yaml-schema.md - Complete YAML schema documentation
• {baseDir}/scripts/validate-yaml.sh - Validation script
• {baseDir}/examples/feature-complete.yaml - Example valid YAML