Skip to content

Commit 43120f7

Browse files
gjkim42claude
gjkim42
and
claude
committed
Add API contract validation example (example 12)
Add a new example demonstrating an end-to-end API contract validation pipeline using current Kelos primitives. Includes: - PR-triggered validation via /validate-api comment (webhook TaskSpawner) - Weekly cross-service compatibility audit (cron TaskSpawner) - Consumer update pipeline with dependsOn task chaining - AgentConfig with API validation specialist instructions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 9a745d8 commit 43120f7

9 files changed

Lines changed: 322 additions & 0 deletions

File tree

‎examples/12-api-contract-validation/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# 12 — API Contract Validation
2+
3+
An end-to-end API contract validation pipeline that uses PR-triggered
4+
validation, scheduled compatibility audits, and a multi-step consumer
5+
update pipeline to catch and resolve breaking API changes.
6+
7+
## Use Case
8+
9+
Detect breaking changes in API definitions (OpenAPI, protobuf, GraphQL)
10+
when PRs are opened, run weekly audits for unreleased drift, and
11+
coordinate migration across consumer repositories when intentional
12+
breaking changes are approved.
13+
14+
AI agents add value beyond static diff tools by reasoning about semantic
15+
intent, analyzing real consumer impact, proposing backward-compatible
16+
alternatives, and generating targeted migration guides.
17+
18+
## Resources
19+
20+
| File | Kind | Purpose |
21+
|------|------|---------|
22+
| `credentials-secret.yaml` | Secret | Anthropic API key for the agent |
23+
| `github-token-secret.yaml` | Secret | GitHub token for cloning and PR creation |
24+
| `workspace.yaml` | Workspace | Git repository containing API definitions |
25+
| `agentconfig.yaml` | AgentConfig | Shared instructions for the API validator agent |
26+
| `taskspawner-webhook.yaml` | TaskSpawner | PR-triggered validation via `/validate-api` comment |
27+
| `taskspawner-cron.yaml` | TaskSpawner | Weekly cross-service compatibility audit |
28+
| `pipeline.yaml` | Task (x2) | Consumer impact analysis and migration guide pipeline |
29+
30+
## Configurations
31+
32+
### 1. PR-Triggered API Validation (Webhook)
33+
34+
Listens for `/validate-api` comments on PRs. The agent checks out the PR
35+
branch, runs structural diff tools if available, classifies each change,
36+
and posts a review summarizing findings with backward-compatible
37+
alternatives for any breaking changes.
38+
39+
### 2. Scheduled Compatibility Audit (Cron)
40+
41+
Runs every Monday at 8:00 AM UTC. The agent compares the current API
42+
surface against the latest tagged release, identifies unreleased breaking
43+
changes and API hygiene issues, and creates a GitHub issue with findings.
44+
45+
### 3. Consumer Update Pipeline (Task Dependencies)
46+
47+
A two-stage pipeline for coordinating migration after an intentional
48+
breaking change is approved:
49+
50+
```
51+
identify-consumers (Task)
52+
│ analyzes which consumers use the affected endpoints
53+
│ outputs: migration-plan.md
54+
│
55+
▼
56+
generate-migration-guide (Task, dependsOn: [identify-consumers])
57+
│ reads migration-plan.md
58+
│ generates step-by-step migration guide with code examples
59+
│ opens a PR with the guide
60+
```
61+
62+
## Steps
63+
64+
1. **Edit the secrets** — replace placeholders in `credentials-secret.yaml`
65+
and `github-token-secret.yaml`.
66+
67+
2. **Edit `workspace.yaml`** — set your API service repository URL.
68+
69+
3. **Review `agentconfig.yaml`** — customize the agent instructions for your
70+
API format and conventions.
71+
72+
4. **Deploy the webhook-triggered validator:**
73+
74+
```bash
75+
kubectl apply -f credentials-secret.yaml -f github-token-secret.yaml \
76+
-f workspace.yaml -f agentconfig.yaml -f taskspawner-webhook.yaml
77+
```
78+
79+
5. **Deploy the scheduled audit (optional):**
80+
81+
```bash
82+
kubectl apply -f taskspawner-cron.yaml
83+
```
84+
85+
6. **Run the consumer update pipeline (when needed):**
86+
87+
```bash
88+
kubectl apply -f pipeline.yaml
89+
```
90+
91+
7. **Trigger a validation** — comment `/validate-api` on any PR in the
92+
configured repository.
93+
94+
8. **Watch spawned Tasks:**
95+
96+
```bash
97+
kubectl get tasks -w
98+
```
99+
100+
9. **Cleanup:**
101+
102+
```bash
103+
kubectl delete -f examples/12-api-contract-validation/
104+
```
105+
106+
## Complementary Issues
107+
108+
This use case works with current Kelos primitives but would benefit from
109+
proposed API extensions:
110+
111+
| Issue | Enhancement | Benefit |
112+
|-------|-------------|---------|
113+
| #778 | `filePatterns` filter | Auto-trigger on API file changes instead of manual `/validate-api` |
114+
| #884 | Cross-repo propagation | Create migration PRs directly in consumer repos |
115+
| #842 | `readOnlyWorkspaces` | Read consumer repos without full write access |
116+
| #881 | `contextSources` | Inject previous audit results into validation prompts |
117+
118+
## Notes
119+
120+
- The webhook TaskSpawner uses `issue_comment` with `bodyContains` as a
121+
workaround until `filePatterns` filtering (#778) is available.
122+
- The pipeline Tasks share the same `branch` value, which serializes them
123+
automatically in addition to the explicit `dependsOn` ordering.
124+
- Adjust `maxConcurrency` on the webhook TaskSpawner based on your expected
125+
PR volume.

‎examples/12-api-contract-validation/agentconfig.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
apiVersion: kelos.dev/v1alpha1
2+
kind: AgentConfig
3+
metadata:
4+
name: api-validator-config
5+
spec:
6+
agentsMD: |
7+
# API Contract Validator Agent
8+
9+
You are an API contract validation specialist. Your role is to analyze API
10+
definition changes for backward compatibility and consumer impact.
11+
12+
## Key Conventions
13+
- Always classify changes as non-breaking, potentially-breaking, or breaking
14+
- A "breaking change" means any change that could cause existing consumers
15+
to fail without code modifications
16+
- When suggesting alternatives, prefer deprecation over removal
17+
- Reference the specific API versioning strategy used in this project
18+
- Include concrete code examples in migration guides
19+
20+
## Tools Available
21+
- Use `git diff` to compare API definitions between versions
22+
- Use `gh api` to query for dependent repositories or PRs
23+
- Use `gh pr review` to post validation results
24+
- If `oasdiff`, `buf`, or `graphql-inspector` are available, use them first
25+
for structural analysis before adding semantic evaluation

‎examples/12-api-contract-validation/credentials-secret.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
apiVersion: v1
2+
kind: Secret
3+
metadata:
4+
name: anthropic-api-key
5+
type: Opaque
6+
stringData:
7+
# TODO: Replace with your Anthropic API key
8+
ANTHROPIC_API_KEY: "sk-ant-REPLACE-ME"

‎examples/12-api-contract-validation/github-token-secret.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
apiVersion: v1
2+
kind: Secret
3+
metadata:
4+
name: github-token
5+
type: Opaque
6+
stringData:
7+
# TODO: Replace with your GitHub Personal Access Token
8+
# Required permissions: repo (for private repos), workflow (optional)
9+
GITHUB_TOKEN: "ghp_REPLACE-ME"

‎examples/12-api-contract-validation/pipeline.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Stage 1: Identify all affected consumers
2+
apiVersion: kelos.dev/v1alpha1
3+
kind: Task
4+
metadata:
5+
name: identify-consumers
6+
spec:
7+
type: claude-code
8+
workspaceRef:
9+
name: api-service-workspace
10+
credentials:
11+
type: api-key
12+
secretRef:
13+
name: anthropic-api-key
14+
branch: api-migration/v2
15+
prompt: |
16+
A breaking API change has been approved for the user-service API.
17+
18+
1. Read CONSUMERS.md or search the organization for repositories that import
19+
this API's client package or reference its endpoints.
20+
2. For each consumer, identify which breaking fields/endpoints they use.
21+
3. Output a structured summary: consumer repo, affected endpoints, migration effort (low/medium/high).
22+
23+
Commit a file `migration-plan.md` summarizing your findings and push the branch.
24+
---
25+
# Stage 2: Generate migration guide (waits for identify-consumers to succeed)
26+
apiVersion: kelos.dev/v1alpha1
27+
kind: Task
28+
metadata:
29+
name: generate-migration-guide
30+
spec:
31+
type: claude-code
32+
workspaceRef:
33+
name: api-service-workspace
34+
credentials:
35+
type: api-key
36+
secretRef:
37+
name: anthropic-api-key
38+
branch: api-migration/v2
39+
dependsOn:
40+
- identify-consumers
41+
prompt: |
42+
The consumer analysis is complete on branch
43+
{{index .Deps "identify-consumers" "Results" "branch"}}.
44+
45+
Read `migration-plan.md` and generate a comprehensive migration guide:
46+
1. Step-by-step instructions for each breaking change
47+
2. Before/after code examples for each consumer language (Go, Python, TypeScript)
48+
3. A deprecation timeline with recommended milestones
49+
50+
Commit `MIGRATION_GUIDE.md` and open a PR with `gh pr create`.

‎examples/12-api-contract-validation/taskspawner-cron.yaml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
apiVersion: kelos.dev/v1alpha1
2+
kind: TaskSpawner
3+
metadata:
4+
name: weekly-api-compatibility-audit
5+
spec:
6+
when:
7+
cron:
8+
schedule: "0 8 * * 1" # Every Monday at 8:00 AM UTC
9+
taskTemplate:
10+
type: claude-code
11+
workspaceRef:
12+
name: api-service-workspace
13+
agentConfigRef:
14+
name: api-validator-config
15+
credentials:
16+
type: api-key
17+
secretRef:
18+
name: anthropic-api-key
19+
promptTemplate: |
20+
Scheduled weekly API compatibility audit — {{.Time}}
21+
22+
## Instructions
23+
24+
1. Locate all API definition files in this repository (OpenAPI YAML/JSON,
25+
protobuf .proto files, GraphQL .graphql schemas, or typed route definitions).
26+
2. Compare the current API surface against the latest released/tagged version:
27+
- `git diff $(git describe --tags --abbrev=0)..HEAD -- '*.proto' '*.yaml' '*.graphql'`
28+
3. Identify any unreleased breaking changes that have accumulated since the last release.
29+
4. Check for API hygiene issues:
30+
- Deprecated fields without removal timelines
31+
- Undocumented endpoints or parameters
32+
- Inconsistent naming conventions across endpoints
33+
- Missing or outdated API version headers
34+
5. Create a GitHub issue summarizing the audit findings with:
35+
- A table of unreleased breaking changes
36+
- Recommended actions (add deprecation notices, bump API version, etc.)
37+
- Priority classification (critical / warning / info)
38+
39+
Use `gh issue create` with the label `api-audit` for the findings report.
40+
ttlSecondsAfterFinished: 3600

‎examples/12-api-contract-validation/taskspawner-webhook.yaml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
apiVersion: kelos.dev/v1alpha1
2+
kind: TaskSpawner
3+
metadata:
4+
name: api-contract-validator
5+
spec:
6+
when:
7+
githubWebhook:
8+
events:
9+
- "issue_comment"
10+
filters:
11+
- event: "issue_comment"
12+
action: "created"
13+
bodyContains: "/validate-api"
14+
maxConcurrency: 2
15+
taskTemplate:
16+
type: claude-code
17+
workspaceRef:
18+
name: api-service-workspace
19+
agentConfigRef:
20+
name: api-validator-config
21+
credentials:
22+
type: api-key
23+
secretRef:
24+
name: anthropic-api-key
25+
branch: "kelos/api-validation-{{.ID}}"
26+
promptTemplate: |
27+
An API contract validation was requested.
28+
29+
Event: {{.Event}} — {{.Action}}
30+
Triggered by: @{{.Sender}}
31+
PR URL: {{.URL}}
32+
33+
## Instructions
34+
35+
1. Check out the PR branch and identify all changes to API definition files
36+
(OpenAPI specs, protobuf definitions, GraphQL schemas, or typed API routes).
37+
2. Run structural diff tools if available (e.g., `oasdiff diff`, `buf breaking`).
38+
3. For each detected change, classify it:
39+
- **Non-breaking**: additive fields, new optional parameters, new endpoints
40+
- **Potentially breaking**: changed response shapes, renamed fields, type changes
41+
- **Breaking**: removed fields/endpoints, changed required parameters
42+
4. For breaking changes, analyze whether any known consumer actually uses the
43+
affected field/endpoint (check consumer repos if accessible).
44+
5. Post a review comment on the PR summarizing findings:
45+
- List of changes with classification
46+
- Impact assessment for each breaking change
47+
- Suggested backward-compatible alternatives (deprecation, default values, versioning)
48+
6. If all changes are non-breaking, approve with a summary comment.
49+
50+
Use `gh pr review` to post your findings.
51+
metadata:
52+
labels:
53+
kelos.dev/use-case: "api-validation"
54+
ttlSecondsAfterFinished: 3600

‎examples/12-api-contract-validation/workspace.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
apiVersion: kelos.dev/v1alpha1
2+
kind: Workspace
3+
metadata:
4+
name: api-service-workspace
5+
spec:
6+
# TODO: Replace with your API service repository URL
7+
repo: https://github.com/your-org/your-api-service.git
8+
ref: main
9+
secretRef:
10+
name: github-token

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Ready-to-use patterns and YAML manifests for orchestrating AI agents with Kelos.
2222
| [09-bedrock-credentials](09-bedrock-credentials/) | Run an agent using AWS Bedrock with static credentials or IRSA |
2323
| [10-taskspawner-github-webhook](10-taskspawner-github-webhook/) | Respond to GitHub webhook events (issues, PRs, pushes) in real time |
2424
| [11-taskspawner-linear-webhook](11-taskspawner-linear-webhook/) | Respond to Linear webhook events (issues, comments) in real time |
25+
| [12-api-contract-validation](12-api-contract-validation/) | API contract validation pipeline with webhook, cron, and task dependencies |
2526

2627
## How to Use
2728

0 commit comments

Comments
 (0)