Add API contract validation example (example 12)

[kelos-bot]

What type of PR is this?

/kind docs

What this PR does / why we need it:

Adds a new example (examples/12-api-contract-validation/) demonstrating an end-to-end API contract validation pipeline using current Kelos primitives. The example includes:

• PR-triggered validation — A webhook TaskSpawner that listens for /validate-api comments on PRs, runs structural diff tools, classifies changes (non-breaking/potentially breaking/breaking), and posts review findings.
• Scheduled compatibility audit — A cron TaskSpawner that runs weekly to detect unreleased API drift and creates GitHub issues with findings.
• Consumer update pipeline — A two-stage task pipeline using dependsOn that identifies affected consumers and generates migration guides when intentional breaking changes are approved.
• AgentConfig — Shared instructions for the API validator agent with classification conventions and tool guidance.

Also updates the examples README index with the new entry.

Which issue(s) this PR is related to:

Fixes #972

Special notes for your reviewer:

This is a documentation-only PR — all files are YAML configs, Markdown, or Kubernetes Secret templates. No Go code changes. The YAML files pass yamlfmt -lint formatting checks.

The configurations use existing Kelos API primitives (githubWebhook, cron, dependsOn, AgentConfig, bodyContains). The README notes complementary issues (#778, #884, #842, #881) that would enhance the workflow.

Does this PR introduce a user-facing change?

NONE

---

Summary by cubic

Adds example 12: an end-to-end API contract validation pipeline with PR-triggered checks, a weekly audit, and a consumer migration flow. Improves coverage for JSON OpenAPI files and simplifies setup.

• New Features

  • New example at examples/12-api-contract-validation/ with README and manifests
  • Webhook TaskSpawner listens for /validate-api PR comments and posts validation results
  • Cron TaskSpawner runs a weekly compatibility audit and files GitHub issues
  • Two-stage migration pipeline (identify-consumers → generate-migration-guide) using dependsOn
  • Shared AgentConfig with tool guidance (oasdiff, buf, graphql-inspector, gh); includes secrets and workspace templates, plus examples index update

• Refinements

  • Cron audit diff includes *.json to cover JSON OpenAPI specs
  • Removed manual PR branch checkout step; Kelos handles checkout automatically

^{Written for commit 1a41397. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 9 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="examples/12-api-contract-validation/taskspawner-cron.yaml">

<violation number="1" location="examples/12-api-contract-validation/taskspawner-cron.yaml:27">
P2: Include `*.json` in the diff command; the current command skips JSON OpenAPI files despite the stated scope.</violation>
</file>

<file name="examples/12-api-contract-validation/taskspawner-webhook.yaml">

<violation number="1" location="examples/12-api-contract-validation/taskspawner-webhook.yaml:35">
P2: Remove the manual PR branch checkout instruction; Kelos already handles PR branch checkout automatically.

(Based on your team's feedback about avoiding manual git checkout steps in Kelos prompts.) [FEEDBACK_USED]</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}