validate-pipeline

Validate Pipeline

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. validate-pipeline vX.Y — recent: <summary>. Then proceed.

Read-only linter. Verify a pipeline.yaml is structurally sound. Surfaces errors and warnings; writes no files.

Run this:

• After any manual edit to pipeline.yaml
• Automatically at the end of /add-pipeline and /add-pipeline-stage
• Before deploying the agent to a new environment

The heartbeat (pipeline-tick) reads pipeline.yaml directly each tick. It does not require this skill to have run. If you ship a broken pipeline.yaml, the heartbeat will fail loudly on the next tick — running the linter just gets you that feedback sooner.

Process

Step 1: Resolve target

Expect <pipeline-slug> as the single positional argument. If missing, list pipelines and prompt.

Validate projects/<slug>/pipeline.yaml exists.

Step 2: Schema check

Required top-level keys: schema_version, pipeline_id, name, stages, heartbeat.

PIPELINE_FILE="projects/$SLUG/pipeline.yaml"

SCHEMA=$(yq '.schema_version // 0' "$PIPELINE_FILE")
[ "$SCHEMA" = "1" ] || error "schema_version must be 1 (got: $SCHEMA)"

ID=$(yq '.pipeline_id // ""' "$PIPELINE_FILE")
[ "$ID" = "$SLUG" ] || error "pipeline_id ($ID) doesn't match directory slug ($SLUG)"

STAGE_COUNT=$(yq '.stages | length' "$PIPELINE_FILE")
[ "$STAGE_COUNT" -gt 0 ] || error "No stages defined"

yq '.heartbeat.cron' "$PIPELINE_FILE" >/dev/null || error "heartbeat.cron is required"
yq '.heartbeat.message' "$PIPELINE_FILE" >/dev/null || error "heartbeat.message is required"
yq '.heartbeat.name' "$PIPELINE_FILE" >/dev/null || error "heartbeat.name is required"

Collect all errors and report at the end — don't stop on the first one.

Step 3: Stage-level checks

For each stage in .stages[]:

yq '.stages[] | [.id, .skill, .timeout_seconds, (.retry.max_attempts // 1), (.on_failure // "escalate")] | @tsv' "$PIPELINE_FILE"