Validate a Harness Configuration

You are helping the user validate a harness.yaml file against the Harness Protocol v1 JSON Schema.

Workflow Order (MANDATORY)

Follow these steps in order. Do not skip any step.

---

Step 1: Find the file

Check for the harness file in this order:

1. A path provided by the user after /harness-validate (e.g., /harness-validate ~/dotfiles/harness.yaml)
2. ./harness.yaml in the current directory

If no file is found at either location, tell the user:

"No harness.yaml found. Specify a path: /harness-validate path/to/harness.yaml"

Read the file contents.

---

Step 2: Run validation

Install the validation tools if not present and run validation:

python3 -m venv /tmp/hk-validate-venv 2>/dev/null || true
/tmp/hk-validate-venv/bin/pip install jsonschema pyyaml -q 2>/dev/null || \
  (python3 -m venv /tmp/hk-validate-venv && /tmp/hk-validate-venv/bin/pip install jsonschema pyyaml -q)

Then run this validation script:

import json, sys, yaml

try:
    from jsonschema import validate, ValidationError, SchemaError
    from jsonschema.validators import validator_for
except ImportError:
    print("ERROR: jsonschema not installed")
    sys.exit(1)

SCHEMA_URL = "https://raw.githubusercontent.com/harnessprotocol/harness-protocol/spec/v1-foundation/schema/draft/harness.schema.json"
HARNESS_FILE = "harness.yaml"  # replace with actual path

# Fetch the schema
import urllib.request
try:
    with urllib.request.urlopen(SCHEMA_URL, timeout=5) as resp:
        schema = json.loads(resp.read())
except Exception as e:
    print(f"WARN: Could not fetch remote schema ({e}). Falling back to basic checks.")
    schema = None

# Load the harness file
try:
    with open(HARNESS_FILE) as f:
        doc = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"FAIL: YAML parse error — {e}")
    sys.exit(1)

if schema is None:
    # Basic offline checks
    errors = []
    if "version" not in doc:
        errors.append("Missing required field: version")
    elif doc["version"] not in ("1", 1):
        errors.append(f"version must be \"1\" (string) or 1 (legacy integer), got: {doc['version']!r}")
    if "metadata" not in doc:
        errors.append("Missing required field: metadata")
    elif "name" not in doc.get("metadata", {}):
        errors.append("metadata.name is required")
    if errors:
        for e in errors:
            print(f"FAIL: {e}")
    else:
        print("PASS (basic checks only — schema fetch failed)")
    sys.exit(0)

# Full schema validation
try:
    validate(instance=doc, schema=schema)
    print("PASS")
except ValidationError as e:
    path = " → ".join(str(p) for p in e.absolute_path) or "(root)"
    print(f"FAIL: {path}: {e.message}")
except SchemaError as e:
    print(f"ERROR: Schema itself is invalid — {e.message}")

Run the script with /tmp/hk-validate-venv/bin/python3 and capture the output.

---

Step 3: Report results

On PASS:

"Your harness.yaml is valid — passes Harness Protocol v1 schema validation."

If the file uses version: 1 (integer, legacy format), add:

"Note: this is in the legacy format (version: 1 integer). Run /harness-export to regenerate in Harness Protocol v1 format (version: \"1\" string)."

On FAIL (validation errors):

Display errors with clear field paths and fix suggestions:

✗ harness.yaml failed validation:

  plugins → 0 → source: 'marketplace' is not a valid property
    Fix: Use source: owner/repo instead of marketplace: key.
    Example: source: harnessprotocol/harness-kit

  env → 0: 'default' is not allowed when sensitive is true
    Fix: Remove the default value — sensitive vars must be set by the user,
    never baked into the harness file.

  (root): version must be "1" (string), got 1 (integer)
    Fix: Change version: 1 to version: "1" (add quotes).

Common errors and their fixes:

Error	Fix
version must be string "1"	Change version: 1 to version: "1"
source is not a valid property	Replace marketplace: key with source: owner/repo
default not allowed when sensitive: true	Remove the default value
metadata.name is required	Add a metadata.name field
Unknown additional property	Check for typos in field names

After listing errors:

"Fix these issues and run /harness-validate again to confirm."

On YAML parse error:

"Your harness.yaml has a YAML syntax error: [error details]

Common causes: wrong indentation, missing quotes around special characters (like : in strings), or a tab used instead of spaces."

---

Common Mistakes

Mistake	Fix
Reporting only the first error	Show all errors, not just the first one
Giving up if schema fetch fails	Fall back to basic checks and tell the user the schema was unavailable
Suggesting marketplace: as a fix	Always recommend source: owner/repo — that's the v1 format