x-execute-contract-tests
Stack-aware contract breaking-change detection: openapi-diff (REST), buf breaking (gRPC/proto3), Spring Cloud Contract (Java/Spring), schema registry compat (events). Pact opt-in via quality.contract.pact=true.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-execute-contract-tests
- model
- sonnet
- visibility
- public
- description
- Stack-aware contract breaking-change detection: openapi-diff (REST), buf breaking (gRPC/proto3), Spring Cloud Contract (Java/Spring), schema registry compat (events). Pact opt-in via quality.contract.pact=true.
- requires-any
- [ "quality.contract.openapi-diff", "quality.contract.pact", "quality.contract.buf", "quality.contract.scc" ]
- allowed-tools
- Read, Write, Edit, Bash, Grep, Glob
- argument-hint
- [--story-id STORY-XXXX-YYYY] [--base-ref HEAD~1]
- context-budget
- medium
- requires-capabilities
- []
02 资源文件 1
- 参考文档README.md1.3 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Contract Breaking-Change Detection (x-execute-contract-tests)
Purpose
Detect breaking changes in API contracts before they reach production. Stack-aware dispatch:
| Contract artifact | Tool | Activation |
|---|---|---|
openapi.yaml / openapi.json |
openapi-diff | capability quality.contract.openapi-diff |
**/*.proto |
buf breaking | capability quality.contract.buf |
| Spring Boot + SCC stubs | Spring Cloud Contract | capability quality.contract.scc |
**/*.avsc / schema registry |
Schema registry compat | capability quality.contract.scc + schema-registry-url set |
| Consumer-driven contracts | Pact | capability quality.contract.pact (opt-in only) |
Triggers
/x-execute-contract-tests— auto-detect contracts, run all applicable tools/x-execute-contract-tests --story-id story-XXXX-YYYY— scope report to story/x-execute-contract-tests --base-ref HEAD~1— compare against specific base ref
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
--story-id |
String | — | Story ID for report path |
--base-ref |
String | HEAD~1 |
Base ref for comparison |
Exit Codes
| Exit | Code | Condition |
|---|---|---|
| 0 | SUCCESS |
No breaking changes, or breaking change documented in CHANGELOG |
| 1 | CONTRACT_BREAKING_CHANGE |
Breaking change detected without CHANGELOG documentation |
| 2 | OPERATIONAL_ERROR |
Tool not found, invalid config, file read failure |
| 3 | CONTRACT_ARTIFACT_INVALID |
Contract file exists but is malformed |
Step 1 — Detect Contract Artifacts
Scan project for contract artifacts:
# OpenAPI
find . -name "openapi.yaml" -o -name "openapi.json" | grep -v target/ | head -5
# gRPC proto
find . -name "*.proto" | grep -v target/ | head -10
# Avro schemas
find . -name "*.avsc" | grep -v target/ | head -5
# Spring Cloud Contract stubs
find . -path "*/contractTest/*.groovy" -o -path "*/contractTest/*.yml" | grep -v target/
When NO contract artifact found AND quality.contract.enabled=true:
- Emit
WARN: no contract artifact found — skipping - Exit 0 (non-blocking)
Step 2 — Run Stack-Appropriate Tool
REST (openapi-diff)
# Validate tool available
openapi-diff --version 2>&1 || { echo "OPERATIONAL_ERROR: openapi-diff not on PATH"; exit 2; }
# Compare base vs current
openapi-diff \
--fail-on-incompatible \
--output-markdown \
<(git show ${BASE_REF}:openapi.yaml 2>/dev/null || echo "{}") \
openapi.yaml \
> /tmp/openapi-diff-result.md 2>&1
OPENAPI_EXIT=$?
Classify changes:
ADDEDfield/path/method → NON_BREAKINGREMOVEDfield/path/method → BREAKINGTYPE_CHANGED→ BREAKINGENUM_VALUE_REMOVED→ BREAKINGNULLABLE_CHANGED(required→optional = NON_BREAKING; optional→required = BREAKING)DEFAULT_CHANGED→ NON_BREAKING (advisory warn)
gRPC/proto (buf breaking)
buf --version 2>&1 || { echo "OPERATIONAL_ERROR: buf not on PATH"; exit 2; }
buf breaking \
--against ".git#branch=${BASE_REF},subdir=." \
--config buf.yaml \
2>&1 | tee /tmp/buf-result.txt
BUF_EXIT=$?
Classify:
- Field removed → BREAKING
- Field type changed → BREAKING
- Message removed → BREAKING
- Field renamed (proto3 wire-compat preserved) → NON_BREAKING (warn)
Spring Cloud Contract (SCC)
# Skip when scc.stub-repository-url absent or unreachable
if [ -z "${SCC_STUB_REPO_URL}" ]; then
echo "WARN: SCC stub repository not configured — skipping Spring Cloud Contract verification"
SCC_EXIT=0
else
mvn spring-cloud-contract:verify --no-transfer-progress -q 2>&1
SCC_EXIT=$?
fi
Pact (opt-in)
Runs only when quality.contract.pact=true:
if [ "${PACT_ENABLED}" = "true" ]; then
mvn pact:verify --no-transfer-progress -q 2>&1
PACT_EXIT=$?
fi
Schema Registry (events)
if [ -n "${SCHEMA_REGISTRY_URL}" ]; then
curl -u "${SCHEMA_REGISTRY_USER}:${SCHEMA_REGISTRY_PASSWORD}" \
"${SCHEMA_REGISTRY_URL}/compatibility/subjects/${SUBJECT}/versions/latest" \
-d @schema.avsc --fail-with-body 2>&1
SCHEMA_EXIT=$?
if [ $SCHEMA_EXIT -ne 0 ]; then
echo "WARN: schema registry auth failed — skipping event contract check"
SCHEMA_EXIT=0
fi
fi
Step 3 — CHANGELOG Integration
When breaking change detected, check if PR documents it:
# CHANGELOG detection regex — matches ## Breaking, ## Breaking Change(s), ## BREAKING
git diff ${BASE_REF} -- CHANGELOG.md 2>/dev/null \
| grep -E '^\+##\s+(Breaking(\s+Changes?)?|BREAKING)\s*$' \
| head -1
Breaking change + CHANGELOG entry → exit 0 with WARN: breaking change detected — documented migration path accepted
Breaking change + NO CHANGELOG entry → exit 1 CONTRACT_BREAKING_CHANGE
Step 4 — Produce Report
Output: ai/epics/epic-XXXX/reports/contract-report-${STORY_ID}.md
## Summary
- **Verdict:** PASS | FAIL | WARN
- **Tool(s):** openapi-diff 2.x | buf 1.30+ | Spring Cloud Contract | Pact
- **Execution time:** Xs
## Changes Detected
| Field / Path | Change Type | Severity | Location |
|--------------|-------------|----------|----------|
...
## CHANGELOG Integration
- **Breaking entry found:** yes / no
- **Accepted:** yes / no (reason)
## Recommendations
...
Recovery
# When tool is not on PATH
OPERATIONAL_ERROR: openapi-diff not on PATH
→ Install: brew install openapitools/openapi-generator/openapi-diff (v2.x)
→ Or use Docker: docker run openapitools/openapi-diff:latest
# When SCC stub repo missing
WARN: SCC stub repository not configured — skipping Spring Cloud Contract verification
→ Set quality.contract.scc.stub-repository-url in project YAML to enable
# When schema registry auth fails
WARN: schema registry auth failed — skipping event contract check
→ Set SCHEMA_REGISTRY_USER and SCHEMA_REGISTRY_PASSWORD env vars
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.