[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C2ATRQEF9ABTRPWNDJSQ98":3,"skill-same:01M6C2ATRQEF9ABTRPWNDJSQ98":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":34,"publishedAt":51,"linkOnly":52,"markdownContent":53,"markdownBody":54,"frontMatter":55,"refName":59,"commitSha":60,"skillDirectory":61,"forksCount":62,"repositoryHtmlUrl":63,"repositoryHomepageUrl":64,"ownerHtmlUrl":65,"ownerBlogUrl":66,"ownerDescription":67,"updatedAt":68,"install":69,"resources":82},"01M6C2ATRQEF9ABTRPWNDJSQ98","regression-api-contract",null,"Detect breaking changes in API contracts across REST, GraphQL, and gRPC interfaces with semver enforcement","jmagly\u002Faiwg","jmagly","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1159087?v=4","01M6C10AK8N2WCSQN11FYGTJWN","Joseph Magly","01M6C10AQ8A2RMED1Y1BSVY7NF",229,"MIT","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-api-contract\u002FSKILL.md",[18,23,26,31],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000037","律师与法务",[35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50],"api","regression","regression api contract","api contract","contract","semver","grpc","REST","GraphQL","enforcement","contracts","across","detect","with","changes","api contracts","2026-11-10 10:12:30",false,"---\nnamespace: aiwg\nname: regression-api-contract\nplatforms: [all]\ndescription: Detect breaking changes in API contracts across REST, GraphQL, and gRPC interfaces with semver enforcement\n\n---\n\n# regression-api-contract\n\nDetect breaking changes in API contracts across REST, GraphQL, and gRPC interfaces.\n\n## Triggers\n\n\nAlternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):\n\n- \"breaking change\" → API contract regression\n- \"schema compatibility\" → contract validation\n- \"Pact\" \u002F \"Swagger diff\" → contract testing tool names\n\n## Purpose\n\nThis skill detects API contract regressions by:\n- Identifying breaking changes in REST API endpoints\n- Detecting schema changes in request\u002Fresponse contracts\n- Validating GraphQL schema compatibility\n- Checking gRPC\u002Fprotobuf definition changes\n- Enforcing semantic versioning compliance\n- Integrating consumer contract testing (Pact, Spring Cloud Contract)\n\n## Behavior\n\nWhen triggered, this skill:\n\n1. **Identifies API contract scope**:\n   - Discover API definition files (OpenAPI, GraphQL, protobuf)\n   - Identify baseline version for comparison\n   - Determine API type (REST, GraphQL, gRPC)\n   - Locate consumer contract tests\n\n2. **Compares contracts to baseline**:\n   - Load current API definition\n   - Load baseline API definition\n   - Run compatibility analysis using appropriate tools\n   - Generate detailed diff of changes\n\n3. **Classifies changes by severity**:\n   - **BREAKING**: Removed endpoints, fields, or enum values; type changes; new required fields\n   - **NON-BREAKING**: New optional fields, new endpoints, extended enums\n   - **DEPRECATED**: Marked for future removal\n   - **INTERNAL**: Implementation changes with no contract impact\n\n4. **Validates semantic versioning**:\n   - Check if version increment matches change type\n   - Ensure breaking changes trigger major version bump\n   - Verify non-breaking changes use minor\u002Fpatch versions\n   - Flag version mismatches\n\n5. **Runs consumer contract tests**:\n   - Execute Pact or Spring Cloud Contract tests\n   - Validate against consumer expectations\n   - Identify consumers affected by changes\n   - Generate compatibility matrix\n\n6. **Generates compatibility report**:\n   - List all breaking changes with locations\n   - Document affected consumers\n   - Recommend version bump strategy\n   - Suggest migration paths for consumers\n\n## Breaking Change Categories\n\n### REST API Breaking Changes\n\n```yaml\nrest_breaking_changes:\n  removed:\n    - endpoint: \"DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\"\n      severity: BREAKING\n      reason: \"Endpoint removed entirely\"\n\n    - field: \"email\" from \"User\" response\n      severity: BREAKING\n      reason: \"Required field removed from response\"\n\n    - enum_value: \"PENDING\" from \"OrderStatus\"\n      severity: BREAKING\n      reason: \"Enum value removed\"\n\n  modified:\n    - field: \"created_at\"\n      from_type: \"string\"\n      to_type: \"integer\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"email\"\n      from_required: false\n      to_required: true\n      severity: BREAKING\n      reason: \"Optional field made required in request\"\n\n    - constraint: \"password\"\n      from: \"minLength: 6\"\n      to: \"minLength: 12\"\n      severity: BREAKING\n      reason: \"Stricter validation on request field\"\n\n  renamed:\n    - endpoint: \"GET \u002Fapi\u002Fv1\u002Fuser\u002F{id}\"\n      to: \"GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}\"\n      severity: BREAKING\n      reason: \"Path renamed without redirect\u002Falias\"\n\n    - parameter: \"userId\"\n      to: \"user_id\"\n      severity: BREAKING\n      reason: \"Parameter renamed without backward compatibility\"\n```\n\n### GraphQL Schema Breaking Changes\n\n```yaml\ngraphql_breaking_changes:\n  removed:\n    - field: \"User.email\"\n      severity: BREAKING\n      reason: \"Field removed from type\"\n\n    - argument: \"Query.users(filter: UserFilter)\"\n      severity: BREAKING\n      reason: \"Required argument removed\"\n\n    - type: \"Address\"\n      severity: BREAKING\n      reason: \"Type removed from schema\"\n\n  modified:\n    - field: \"User.age\"\n      from_type: \"Int\"\n      to_type: \"String\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"User.email\"\n      from_nullable: true\n      to_nullable: false\n      severity: BREAKING\n      reason: \"Field made non-nullable\"\n\n    - argument: \"Query.user(id: ID)\"\n      from_optional: true\n      to_optional: false\n      severity: BREAKING\n      reason: \"Argument made required\"\n\n  interface_changes:\n    - interface: \"Node\"\n      removed_implementation: \"User\"\n      severity: BREAKING\n      reason: \"Type no longer implements interface\"\n```\n\n### gRPC\u002FProtobuf Breaking Changes\n\n```yaml\ngrpc_breaking_changes:\n  removed:\n    - field: \"UserMessage.email\"\n      field_number: 3\n      severity: BREAKING\n      reason: \"Field removed from message\"\n\n    - service: \"UserService\"\n      severity: BREAKING\n      reason: \"Service removed\"\n\n    - rpc: \"UserService.GetUser\"\n      severity: BREAKING\n      reason: \"RPC method removed\"\n\n  modified:\n    - field: \"UserMessage.age\"\n      from_type: \"int32\"\n      to_type: \"string\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"UserMessage.name\"\n      from_label: \"optional\"\n      to_label: \"required\"\n      severity: BREAKING\n      reason: \"Field made required\"\n\n    - field_number: 5\n      from_reserved: false\n      to_reserved: true\n      severity: BREAKING\n      reason: \"Field number reserved (deletion)\"\n\n  renamed:\n    - message: \"User\"\n      to: \"UserAccount\"\n      severity: BREAKING\n      reason: \"Message type renamed\"\n\n    - enum: \"Status\"\n      to: \"OrderStatus\"\n      severity: BREAKING\n      reason: \"Enum renamed\"\n```\n\n## API Contract Tools Integration\n\n### OpenAPI\u002FREST\n\n```yaml\nopenapi_tools:\n  primary: openapi-diff\n  alternatives:\n    - oasdiff\n    - swagger-diff\n    - api-diff\n\n  usage:\n    install: \"npm install -g openapi-diff\"\n    compare: |\n      openapi-diff \\\n        .aiwg\u002Fapi\u002Fbaselines\u002Fopenapi-v1.yaml \\\n        .aiwg\u002Fapi\u002Fcurrent\u002Fopenapi.yaml \\\n        --format markdown \\\n        --breaking-only\n    output: \".aiwg\u002Fapi\u002Fcompatibility\u002Fopenapi-diff.md\"\n\n  configuration:\n    strict_mode: true\n    ignore_descriptions: true\n    treat_as_breaking:\n      - removed_endpoints\n      - removed_fields\n      - type_changes\n      - required_field_additions\n      - enum_value_removals\n```\n\n### GraphQL\n\n```yaml\ngraphql_tools:\n  primary: graphql-inspector\n  alternatives:\n    - apollo-cli (schema:check)\n    - graphql-schema-diff\n\n  usage:\n    install: \"npm install -g @graphql-inspector\u002Fcli\"\n    compare: |\n      graphql-inspector diff \\\n        .aiwg\u002Fapi\u002Fbaselines\u002Fschema-v1.graphql \\\n        .aiwg\u002Fapi\u002Fcurrent\u002Fschema.graphql \\\n        --onComplete report.json\n    output: \".aiwg\u002Fapi\u002Fcompatibility\u002Fgraphql-diff.json\"\n\n  configuration:\n    fail_on_breaking: true\n    include_dangerous: true\n    schema_extensions: true\n```\n\n### gRPC\u002FProtobuf\n\n```yaml\nprotobuf_tools:\n  primary: buf\n  alternatives:\n    - prototool\n    - protoc-gen-validate\n\n  usage:\n    install: \"brew install buf\" # or \"go install github.com\u002Fbufbuild\u002Fbuf\u002Fcmd\u002Fbuf@latest\"\n    setup: |\n      # Create buf.yaml\n      version: v1\n      breaking:\n        use:\n          - FILE\n      lint:\n        use:\n          - DEFAULT\n    compare: |\n      buf breaking \\\n        .aiwg\u002Fapi\u002Fcurrent \\\n        --against .aiwg\u002Fapi\u002Fbaselines\u002Fv1\n    output: \"Breaking change detection via buf CLI\"\n\n  configuration:\n    breaking_rules:\n      - FIELD_SAME_TYPE\n      - FIELD_NO_DELETE\n      - ENUM_VALUE_NO_DELETE\n      - RPC_NO_DELETE\n      - MESSAGE_NO_DELETE\n```\n\n## Semantic Versioning Compliance\n\n```yaml\nsemver_validation:\n  rules:\n    breaking_change:\n      requires: major_version_bump\n      examples:\n        - \"v1.2.3 → v2.0.0\"\n      violations:\n        - detected: breaking_change\n          version_change: \"v1.2.3 → v1.3.0\"\n          verdict: VIOLATION\n          message: \"Breaking change detected but only minor version bumped\"\n\n    non_breaking_addition:\n      requires: minor_version_bump\n      examples:\n        - \"v1.2.3 → v1.3.0\"\n      acceptable:\n        - \"v1.2.3 → v2.0.0\"  # Major bump also acceptable\n\n    bug_fix:\n      requires: patch_version_bump\n      examples:\n        - \"v1.2.3 → v1.2.4\"\n      acceptable:\n        - \"v1.2.3 → v1.3.0\"  # Minor\u002Fmajor also acceptable\n\n  enforcement:\n    block_deployment: true  # Block if version mismatch\n    require_override: true  # Allow manual override with justification\n```\n\n## Consumer Contract Testing\n\n### Pact Integration\n\n```yaml\npact_integration:\n  provider: api-service\n  consumers:\n    - name: web-frontend\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fweb-frontend.json\"\n      criticality: high\n\n    - name: mobile-app\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fmobile-app.json\"\n      criticality: high\n\n    - name: partner-api\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fpartner-api.json\"\n      criticality: medium\n\n  verification:\n    run: |\n      npm run test:pact\n      # Verifies provider meets all consumer contracts\n    on_failure:\n      action: block_deployment\n      notification: consumers_affected\n\n  compatibility_matrix:\n    provider_version: v2.0.0\n    consumers:\n      - consumer: web-frontend\n        version: v1.5.0\n        compatible: true\n        tests_passing: 45\u002F45\n\n      - consumer: mobile-app\n        version: v2.1.0\n        compatible: false\n        tests_passing: 38\u002F42\n        failing_tests:\n          - \"POST \u002Fapi\u002Fusers - email field type mismatch\"\n          - \"GET \u002Fapi\u002Fusers\u002F{id} - missing 'phone' field\"\n\n      - consumer: partner-api\n        version: v1.0.0\n        compatible: true\n        tests_passing: 12\u002F12\n```\n\n### Spring Cloud Contract\n\n```yaml\nspring_cloud_contract:\n  contracts_location: \".aiwg\u002Fapi\u002Fcontracts\u002F\"\n  consumers:\n    - name: order-service\n      contracts: \"contracts\u002Forder-service\u002F**\u002F*.groovy\"\n\n    - name: payment-service\n      contracts: \"contracts\u002Fpayment-service\u002F**\u002F*.groovy\"\n\n  verification:\n    run: \".\u002Fmvnw clean test\"\n    stub_generation: true\n    publish_stubs: true\n\n  compatibility_check:\n    baseline: v1.0.0\n    current: v2.0.0\n    results:\n      - consumer: order-service\n        compatible: true\n        contracts_verified: 8\u002F8\n\n      - consumer: payment-service\n        compatible: false\n        contracts_verified: 5\u002F7\n        failures:\n          - \"User schema missing 'email' field\"\n          - \"Order status enum missing 'PENDING'\"\n```\n\n## API Compatibility Report\n\n```markdown\n# API Compatibility Report\n\n**Date**: 2026-01-28\n**Baseline**: v1.5.0 (OpenAPI)\n**Current**: v2.0.0\n**API Type**: REST (OpenAPI 3.0)\n\n## Executive Summary\n\n**Status**: ⚠️ BREAKING CHANGES DETECTED\n**Severity**: HIGH\n**Breaking Changes**: 5\n**Non-Breaking Changes**: 12\n**Version Compliance**: ✅ CORRECT (major bump)\n**Consumer Impact**: 2 of 4 consumers affected\n\n## Version Validation\n\n| Aspect | Baseline | Current | Required | Status |\n|--------|----------|---------|----------|--------|\n| Version | v1.5.0 | v2.0.0 | v2.x.x | ✅ CORRECT |\n| Reason | - | Breaking changes detected | Major bump | ✅ VALID |\n\n## Breaking Changes\n\n### 1. Removed Endpoint\n\n**Endpoint**: `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}`\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Endpoint removed entirely from API\n- No replacement or redirect provided\n- Used by 2 consumers: `web-frontend`, `admin-panel`\n\n**Consumer Impact**:\n- web-frontend: 3 call sites affected\n- admin-panel: 1 call site affected\n\n**Recommendation**:\n- Provide migration path: Use `POST \u002Fapi\u002Fv1\u002Fusers\u002F{id}\u002Fdeactivate` instead\n- Update consumer documentation\n- Consider deprecation period instead of immediate removal\n\n### 2. Field Removed: `User.email`\n\n**Resource**: `User` (GET \u002Fapi\u002Fv1\u002Fusers\u002F{id} response)\n**Field**: `email`\n**Severity**: BREAKING\n**Impact**: CRITICAL\n\n**Details**:\n- Required field `email` removed from User response\n- Breaking for consumers expecting this field\n- No alternative field provided\n\n**Consumer Impact**:\n- web-frontend: AFFECTED (displays user email in profile)\n- mobile-app: AFFECTED (uses email for contact)\n- partner-api: NOT AFFECTED (does not use email)\n\n**Recommendation**:\n- DO NOT REMOVE - Add deprecation warning instead\n- Or provide migration: Add `contactInfo.email` as replacement\n- Document migration path clearly\n\n### 3. Field Type Changed: `created_at`\n\n**Field**: `created_at`\n**From**: `string` (ISO-8601)\n**To**: `integer` (Unix timestamp)\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Field type incompatible change\n- All consumers parsing as ISO-8601 will break\n- No backward compatibility layer\n\n**Consumer Impact**:\n- ALL CONSUMERS AFFECTED (4\u002F4)\n- Requires code changes in all consumers\n\n**Recommendation**:\n- Add `created_at_unix` as new field (non-breaking)\n- Deprecate `created_at` string format\n- Maintain both for 2 versions before removing string format\n\n### 4. New Required Field: `password_policy`\n\n**Endpoint**: `POST \u002Fapi\u002Fv1\u002Fusers`\n**Field**: `password_policy`\n**Severity**: BREAKING\n**Impact**: MEDIUM\n\n**Details**:\n- New field added as required in request body\n- Consumers not sending this field will get 400 errors\n- Breaking for existing integrations\n\n**Consumer Impact**:\n- web-frontend: AFFECTED (user registration form)\n- mobile-app: AFFECTED (sign-up flow)\n\n**Recommendation**:\n- Make field optional with sensible default\n- Or add default value if not provided\n- Document new requirement clearly\n\n### 5. Enum Value Removed: `OrderStatus.PENDING`\n\n**Enum**: `OrderStatus`\n**Value**: `PENDING`\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Enum value removed without replacement\n- Consumers comparing against `PENDING` will break\n- Orders in `PENDING` state require migration\n\n**Consumer Impact**:\n- order-service: CRITICAL (manages pending orders)\n- payment-service: AFFECTED (checks pending status)\n\n**Recommendation**:\n- DO NOT REMOVE - Deprecate instead\n- Or provide mapping: `PENDING` → `AWAITING_CONFIRMATION`\n- Migrate existing data before API deployment\n\n## Non-Breaking Changes\n\n### Safe Additions\n\n| Change | Type | Impact |\n|--------|------|--------|\n| New endpoint: `GET \u002Fapi\u002Fv2\u002Fusers\u002Fsearch` | Addition | None |\n| New optional field: `User.avatar_url` | Addition | None |\n| New enum value: `OrderStatus.CANCELLED` | Addition | None |\n| New query parameter: `?include_inactive` | Addition | None |\n\n### Deprecations\n\n| Item | Deprecated In | Remove In | Replacement |\n|------|---------------|-----------|-------------|\n| `GET \u002Fapi\u002Fv1\u002Fusers\u002Flist` | v2.0.0 | v3.0.0 | `GET \u002Fapi\u002Fv2\u002Fusers` |\n| Field `User.phone` | v2.0.0 | v3.0.0 | `User.contactInfo.phone` |\n\n## Consumer Contract Test Results\n\n### Pact Verification\n\n| Consumer | Version | Compatible | Tests | Failures |\n|----------|---------|------------|-------|----------|\n| web-frontend | v1.5.0 | ❌ NO | 38\u002F45 | 7 |\n| mobile-app | v2.1.0 | ❌ NO | 40\u002F42 | 2 |\n| partner-api | v1.0.0 | ✅ YES | 12\u002F12 | 0 |\n| admin-panel | v0.9.0 | ❌ NO | 15\u002F18 | 3 |\n\n### Failing Contract Tests\n\n**web-frontend failures**:\n1. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Missing `email` field in response\n2. `POST \u002Fapi\u002Fv1\u002Fusers` - Missing required field `password_policy`\n3. `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Endpoint not found (404)\n\n**mobile-app failures**:\n1. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Field type mismatch: `created_at`\n2. `POST \u002Fapi\u002Fv1\u002Fusers` - Validation error: `password_policy` required\n\n**admin-panel failures**:\n1. `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Endpoint removed\n2. `GET \u002Fapi\u002Fv1\u002Forders` - Enum value `PENDING` not recognized\n3. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Missing `email` field\n\n## Backward Compatibility Analysis\n\n```yaml\ncompatibility_assessment:\n  backward_compatible: false\n  reason: \"5 breaking changes detected\"\n\n  migration_effort:\n    web-frontend: HIGH (7 changes required)\n    mobile-app: MEDIUM (2 changes required)\n    partner-api: NONE (no changes needed)\n    admin-panel: HIGH (3 changes required)\n\n  recommended_strategy:\n    option_1:\n      name: \"Parallel API versions\"\n      description: \"Maintain v1 and v2 simultaneously\"\n      effort: HIGH\n      timeline: \"6 months dual support\"\n\n    option_2:\n      name: \"Phased migration\"\n      description: \"Reduce breaking changes, migrate in phases\"\n      effort: MEDIUM\n      timeline: \"3 months migration window\"\n      preferred: true\n\n    option_3:\n      name: \"Hard cutover\"\n      description: \"Deploy v2, deprecate v1 immediately\"\n      effort: LOW\n      timeline: \"1 month notice\"\n      risk: HIGH\n```\n\n## Recommendations\n\n### Immediate Actions\n\n- [ ] Revert breaking changes or provide backward compatibility layer\n- [ ] Make `password_policy` field optional with default value\n- [ ] Add `created_at_unix` alongside `created_at` string\n- [ ] Do not remove `email` field - deprecate with timeline instead\n- [ ] Provide `PENDING` → `AWAITING_CONFIRMATION` enum mapping\n\n### Consumer Migration\n\n- [ ] Notify all consumers of breaking changes\n- [ ] Provide migration guide with code examples\n- [ ] Offer migration support timeline (3 months)\n- [ ] Update consumer contract tests\n- [ ] Coordinate deployment across consumers\n\n### Process Improvements\n\n- [ ] Add contract testing to CI\u002FCD pipeline\n- [ ] Require compatibility report in PR template\n- [ ] Enforce semantic versioning in release process\n- [ ] Implement API deprecation policy (6-month notice)\n- [ ] Add breaking change review gate\n\n## Migration Guide\n\n### For web-frontend\n\n```diff\n\u002F\u002F User profile display\n- const email = user.email;\n+ const email = user.contactInfo?.email || user.email;\n\n\u002F\u002F User registration\n  const userData = {\n    username: form.username,\n    password: form.password,\n+   password_policy: 'default',\n  };\n\n\u002F\u002F Delete user\n- await api.delete(`\u002Fapi\u002Fv1\u002Fusers\u002F${id}`);\n+ await api.post(`\u002Fapi\u002Fv1\u002Fusers\u002F${id}\u002Fdeactivate`);\n```\n\n### For mobile-app\n\n```diff\n\u002F\u002F Timestamp parsing\n- const createdAt = new Date(user.created_at); \u002F\u002F ISO string\n+ const createdAt = user.created_at_unix\n+   ? new Date(user.created_at_unix * 1000)\n+   : new Date(user.created_at);\n\n\u002F\u002F User registration\n  const userData = {\n    ...\n+   password_policy: 'default',\n  };\n```\n\n## Tool Output\n\n### OpenAPI Diff\n\n```bash\n$ openapi-diff baseline.yaml current.yaml --breaking-only\n\nBREAKING CHANGES DETECTED (5):\n\n1. DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n   - Endpoint removed\n\n2. GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n   - Response schema changed\n   - Field 'email' removed\n\n3. POST \u002Fapi\u002Fv1\u002Fusers\n   - Request schema changed\n   - Field 'password_policy' now required\n\n4. OrderStatus enum\n   - Value 'PENDING' removed\n\n5. Multiple endpoints\n   - Field 'created_at' type changed: string → integer\n\nSee full report: openapi-diff-report.md\n```\n```\n\n## Usage Examples\n\n### Detect REST API Regression\n\n```\nUser: \"Check API contract for breaking changes\"\n\nSkill executes:\n1. Locate OpenAPI spec files\n2. Load baseline (v1.5.0)\n3. Load current (v2.0.0)\n4. Run openapi-diff\n5. Classify changes\n6. Check semantic versioning\n7. Run Pact tests\n\nOutput:\n\"API Compatibility Report\n\nStatus: BREAKING CHANGES DETECTED\nBreaking: 5\nNon-Breaking: 12\nVersion: v1.5.0 → v2.0.0 (CORRECT major bump)\nConsumer Impact: 3 of 4 consumers affected\n\nCritical Issues:\n1. Field removed: User.email (affects web-frontend, mobile-app)\n2. Endpoint removed: DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n3. Type change: created_at string → integer\n\nSee full report: .aiwg\u002Fapi\u002Fcompatibility\u002Freport-2026-01-28.md\n\nRecommendation: Revert breaking changes or add compatibility layer\"\n```\n\n### Detect GraphQL Schema Regression\n\n```\nUser: \"API breaking change check for GraphQL\"\n\nSkill executes:\n1. Locate GraphQL schema files\n2. Load baseline schema\n3. Load current schema\n4. Run graphql-inspector diff\n5. Identify breaking vs safe changes\n\nOutput:\n\"GraphQL Schema Compatibility\n\nStatus: BREAKING CHANGES DETECTED\nBreaking: 2\nDangerous: 3\nSafe: 8\n\nBreaking Changes:\n1. Field 'User.email' removed\n2. Type 'Address' removed\n\nDangerous Changes:\n1. Field 'User.age' type changed: Int → String\n2. Argument 'Query.users(limit)' default changed: 10 → 100\n3. Enum 'Status' value 'ACTIVE' description changed\n\nRecommendation: Review breaking changes before deployment\"\n```\n\n### Consumer Contract Verification\n\n```\nUser: \"Run consumer contract tests\"\n\nSkill executes:\n1. Locate Pact contracts\n2. Run provider verification tests\n3. Generate compatibility matrix\n\nOutput:\n\"Consumer Contract Verification\n\nStatus: INCOMPATIBLE CONSUMERS DETECTED\nCompatible: 1\u002F4\nFailing: 3\u002F4\n\nResults:\n✅ partner-api (12\u002F12 tests passing)\n❌ web-frontend (38\u002F45 passing, 7 failures)\n❌ mobile-app (40\u002F42 passing, 2 failures)\n❌ admin-panel (15\u002F18 passing, 3 failures)\n\nCommon Failures:\n- Missing field: User.email (3 consumers)\n- Endpoint not found: DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id} (2 consumers)\n\nAction Required: Update consumers or revert breaking changes\"\n```\n\n## Integration\n\nThis skill uses:\n- `regression-baseline`: Store API contract baselines\n- `regression-bisect`: Find commit that introduced breaking change\n- `regression-report`: Generate comprehensive regression report\n- `project-awareness`: Detect API framework (OpenAPI, GraphQL, gRPC)\n\n## Agent Orchestration\n\n```yaml\nagents:\n  detection:\n    agent: api-designer\n    focus: Identify and classify API changes\n\n  analysis:\n    agent: architecture-designer\n    focus: Assess impact and recommend migration\n\n  testing:\n    agent: test-engineer\n    focus: Run consumer contract tests\n\n  approval:\n    agent: tech-lead\n    focus: Approve breaking changes or require fixes\n```\n\n## Configuration\n\n### Detection Settings\n\n```yaml\napi_contract_detection:\n  api_types:\n    - rest_openapi\n    - graphql\n    - grpc_protobuf\n\n  tools:\n    rest: openapi-diff\n    graphql: graphql-inspector\n    grpc: buf\n\n  baselines:\n    storage: .aiwg\u002Fapi\u002Fbaselines\u002F\n    naming: \"{api-name}-{version}.{ext}\"\n\n  strict_mode: true  # Fail on any breaking change\n  semver_enforcement: true\n```\n\n### Breaking Change Rules\n\n```yaml\nbreaking_rules:\n  rest:\n    - removed_endpoints\n    - removed_fields\n    - type_changes\n    - new_required_fields\n    - enum_value_removals\n    - stricter_validations\n\n  graphql:\n    - removed_fields\n    - removed_types\n    - type_changes\n    - non_nullable_additions\n    - argument_removals\n\n  grpc:\n    - removed_services\n    - removed_rpcs\n    - removed_fields\n    - type_changes\n    - required_field_additions\n```\n\n### Consumer Contract Testing\n\n```yaml\nconsumer_contracts:\n  enabled: true\n  framework: pact  # or spring-cloud-contract\n\n  pact:\n    broker_url: https:\u002F\u002Fpact-broker.example.com\n    publish_verification: true\n\n  contracts_location: .aiwg\u002Fapi\u002Fcontracts\u002F\n  fail_on_incompatibility: true\n```\n\n## Output Locations\n\n- Baselines: `.aiwg\u002Fapi\u002Fbaselines\u002F{api-name}-{version}.{yaml|graphql|proto}`\n- Reports: `.aiwg\u002Fapi\u002Fcompatibility\u002Freport-{date}.md`\n- Diffs: `.aiwg\u002Fapi\u002Fcompatibility\u002Fdiff-{baseline}-to-{current}.md`\n- Pact Results: `.aiwg\u002Fapi\u002Fpact-results\u002F`\n- Migration Guides: `.aiwg\u002Fapi\u002Fmigration\u002F{version}\u002FMIGRATION.md`\n\n## References\n\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fschemas\u002Ftesting\u002Fregression.yaml\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fagents\u002Fapi-designer.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-baseline\u002FSKILL.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-bisect\u002FSKILL.md\n- @.aiwg\u002Fresearch\u002Ffindings\u002FREF-013-metagpt.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Frules\u002Fexecutable-feedback.md\n","# regression-api-contract\n\nDetect breaking changes in API contracts across REST, GraphQL, and gRPC interfaces.\n\n## Triggers\n\n\nAlternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):\n\n- \"breaking change\" → API contract regression\n- \"schema compatibility\" → contract validation\n- \"Pact\" \u002F \"Swagger diff\" → contract testing tool names\n\n## Purpose\n\nThis skill detects API contract regressions by:\n- Identifying breaking changes in REST API endpoints\n- Detecting schema changes in request\u002Fresponse contracts\n- Validating GraphQL schema compatibility\n- Checking gRPC\u002Fprotobuf definition changes\n- Enforcing semantic versioning compliance\n- Integrating consumer contract testing (Pact, Spring Cloud Contract)\n\n## Behavior\n\nWhen triggered, this skill:\n\n1. **Identifies API contract scope**:\n   - Discover API definition files (OpenAPI, GraphQL, protobuf)\n   - Identify baseline version for comparison\n   - Determine API type (REST, GraphQL, gRPC)\n   - Locate consumer contract tests\n\n2. **Compares contracts to baseline**:\n   - Load current API definition\n   - Load baseline API definition\n   - Run compatibility analysis using appropriate tools\n   - Generate detailed diff of changes\n\n3. **Classifies changes by severity**:\n   - **BREAKING**: Removed endpoints, fields, or enum values; type changes; new required fields\n   - **NON-BREAKING**: New optional fields, new endpoints, extended enums\n   - **DEPRECATED**: Marked for future removal\n   - **INTERNAL**: Implementation changes with no contract impact\n\n4. **Validates semantic versioning**:\n   - Check if version increment matches change type\n   - Ensure breaking changes trigger major version bump\n   - Verify non-breaking changes use minor\u002Fpatch versions\n   - Flag version mismatches\n\n5. **Runs consumer contract tests**:\n   - Execute Pact or Spring Cloud Contract tests\n   - Validate against consumer expectations\n   - Identify consumers affected by changes\n   - Generate compatibility matrix\n\n6. **Generates compatibility report**:\n   - List all breaking changes with locations\n   - Document affected consumers\n   - Recommend version bump strategy\n   - Suggest migration paths for consumers\n\n## Breaking Change Categories\n\n### REST API Breaking Changes\n\n```yaml\nrest_breaking_changes:\n  removed:\n    - endpoint: \"DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\"\n      severity: BREAKING\n      reason: \"Endpoint removed entirely\"\n\n    - field: \"email\" from \"User\" response\n      severity: BREAKING\n      reason: \"Required field removed from response\"\n\n    - enum_value: \"PENDING\" from \"OrderStatus\"\n      severity: BREAKING\n      reason: \"Enum value removed\"\n\n  modified:\n    - field: \"created_at\"\n      from_type: \"string\"\n      to_type: \"integer\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"email\"\n      from_required: false\n      to_required: true\n      severity: BREAKING\n      reason: \"Optional field made required in request\"\n\n    - constraint: \"password\"\n      from: \"minLength: 6\"\n      to: \"minLength: 12\"\n      severity: BREAKING\n      reason: \"Stricter validation on request field\"\n\n  renamed:\n    - endpoint: \"GET \u002Fapi\u002Fv1\u002Fuser\u002F{id}\"\n      to: \"GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}\"\n      severity: BREAKING\n      reason: \"Path renamed without redirect\u002Falias\"\n\n    - parameter: \"userId\"\n      to: \"user_id\"\n      severity: BREAKING\n      reason: \"Parameter renamed without backward compatibility\"\n```\n\n### GraphQL Schema Breaking Changes\n\n```yaml\ngraphql_breaking_changes:\n  removed:\n    - field: \"User.email\"\n      severity: BREAKING\n      reason: \"Field removed from type\"\n\n    - argument: \"Query.users(filter: UserFilter)\"\n      severity: BREAKING\n      reason: \"Required argument removed\"\n\n    - type: \"Address\"\n      severity: BREAKING\n      reason: \"Type removed from schema\"\n\n  modified:\n    - field: \"User.age\"\n      from_type: \"Int\"\n      to_type: \"String\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"User.email\"\n      from_nullable: true\n      to_nullable: false\n      severity: BREAKING\n      reason: \"Field made non-nullable\"\n\n    - argument: \"Query.user(id: ID)\"\n      from_optional: true\n      to_optional: false\n      severity: BREAKING\n      reason: \"Argument made required\"\n\n  interface_changes:\n    - interface: \"Node\"\n      removed_implementation: \"User\"\n      severity: BREAKING\n      reason: \"Type no longer implements interface\"\n```\n\n### gRPC\u002FProtobuf Breaking Changes\n\n```yaml\ngrpc_breaking_changes:\n  removed:\n    - field: \"UserMessage.email\"\n      field_number: 3\n      severity: BREAKING\n      reason: \"Field removed from message\"\n\n    - service: \"UserService\"\n      severity: BREAKING\n      reason: \"Service removed\"\n\n    - rpc: \"UserService.GetUser\"\n      severity: BREAKING\n      reason: \"RPC method removed\"\n\n  modified:\n    - field: \"UserMessage.age\"\n      from_type: \"int32\"\n      to_type: \"string\"\n      severity: BREAKING\n      reason: \"Field type changed\"\n\n    - field: \"UserMessage.name\"\n      from_label: \"optional\"\n      to_label: \"required\"\n      severity: BREAKING\n      reason: \"Field made required\"\n\n    - field_number: 5\n      from_reserved: false\n      to_reserved: true\n      severity: BREAKING\n      reason: \"Field number reserved (deletion)\"\n\n  renamed:\n    - message: \"User\"\n      to: \"UserAccount\"\n      severity: BREAKING\n      reason: \"Message type renamed\"\n\n    - enum: \"Status\"\n      to: \"OrderStatus\"\n      severity: BREAKING\n      reason: \"Enum renamed\"\n```\n\n## API Contract Tools Integration\n\n### OpenAPI\u002FREST\n\n```yaml\nopenapi_tools:\n  primary: openapi-diff\n  alternatives:\n    - oasdiff\n    - swagger-diff\n    - api-diff\n\n  usage:\n    install: \"npm install -g openapi-diff\"\n    compare: |\n      openapi-diff \\\n        .aiwg\u002Fapi\u002Fbaselines\u002Fopenapi-v1.yaml \\\n        .aiwg\u002Fapi\u002Fcurrent\u002Fopenapi.yaml \\\n        --format markdown \\\n        --breaking-only\n    output: \".aiwg\u002Fapi\u002Fcompatibility\u002Fopenapi-diff.md\"\n\n  configuration:\n    strict_mode: true\n    ignore_descriptions: true\n    treat_as_breaking:\n      - removed_endpoints\n      - removed_fields\n      - type_changes\n      - required_field_additions\n      - enum_value_removals\n```\n\n### GraphQL\n\n```yaml\ngraphql_tools:\n  primary: graphql-inspector\n  alternatives:\n    - apollo-cli (schema:check)\n    - graphql-schema-diff\n\n  usage:\n    install: \"npm install -g @graphql-inspector\u002Fcli\"\n    compare: |\n      graphql-inspector diff \\\n        .aiwg\u002Fapi\u002Fbaselines\u002Fschema-v1.graphql \\\n        .aiwg\u002Fapi\u002Fcurrent\u002Fschema.graphql \\\n        --onComplete report.json\n    output: \".aiwg\u002Fapi\u002Fcompatibility\u002Fgraphql-diff.json\"\n\n  configuration:\n    fail_on_breaking: true\n    include_dangerous: true\n    schema_extensions: true\n```\n\n### gRPC\u002FProtobuf\n\n```yaml\nprotobuf_tools:\n  primary: buf\n  alternatives:\n    - prototool\n    - protoc-gen-validate\n\n  usage:\n    install: \"brew install buf\" # or \"go install github.com\u002Fbufbuild\u002Fbuf\u002Fcmd\u002Fbuf@latest\"\n    setup: |\n      # Create buf.yaml\n      version: v1\n      breaking:\n        use:\n          - FILE\n      lint:\n        use:\n          - DEFAULT\n    compare: |\n      buf breaking \\\n        .aiwg\u002Fapi\u002Fcurrent \\\n        --against .aiwg\u002Fapi\u002Fbaselines\u002Fv1\n    output: \"Breaking change detection via buf CLI\"\n\n  configuration:\n    breaking_rules:\n      - FIELD_SAME_TYPE\n      - FIELD_NO_DELETE\n      - ENUM_VALUE_NO_DELETE\n      - RPC_NO_DELETE\n      - MESSAGE_NO_DELETE\n```\n\n## Semantic Versioning Compliance\n\n```yaml\nsemver_validation:\n  rules:\n    breaking_change:\n      requires: major_version_bump\n      examples:\n        - \"v1.2.3 → v2.0.0\"\n      violations:\n        - detected: breaking_change\n          version_change: \"v1.2.3 → v1.3.0\"\n          verdict: VIOLATION\n          message: \"Breaking change detected but only minor version bumped\"\n\n    non_breaking_addition:\n      requires: minor_version_bump\n      examples:\n        - \"v1.2.3 → v1.3.0\"\n      acceptable:\n        - \"v1.2.3 → v2.0.0\"  # Major bump also acceptable\n\n    bug_fix:\n      requires: patch_version_bump\n      examples:\n        - \"v1.2.3 → v1.2.4\"\n      acceptable:\n        - \"v1.2.3 → v1.3.0\"  # Minor\u002Fmajor also acceptable\n\n  enforcement:\n    block_deployment: true  # Block if version mismatch\n    require_override: true  # Allow manual override with justification\n```\n\n## Consumer Contract Testing\n\n### Pact Integration\n\n```yaml\npact_integration:\n  provider: api-service\n  consumers:\n    - name: web-frontend\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fweb-frontend.json\"\n      criticality: high\n\n    - name: mobile-app\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fmobile-app.json\"\n      criticality: high\n\n    - name: partner-api\n      pact_file: \".aiwg\u002Fapi\u002Fpacts\u002Fpartner-api.json\"\n      criticality: medium\n\n  verification:\n    run: |\n      npm run test:pact\n      # Verifies provider meets all consumer contracts\n    on_failure:\n      action: block_deployment\n      notification: consumers_affected\n\n  compatibility_matrix:\n    provider_version: v2.0.0\n    consumers:\n      - consumer: web-frontend\n        version: v1.5.0\n        compatible: true\n        tests_passing: 45\u002F45\n\n      - consumer: mobile-app\n        version: v2.1.0\n        compatible: false\n        tests_passing: 38\u002F42\n        failing_tests:\n          - \"POST \u002Fapi\u002Fusers - email field type mismatch\"\n          - \"GET \u002Fapi\u002Fusers\u002F{id} - missing 'phone' field\"\n\n      - consumer: partner-api\n        version: v1.0.0\n        compatible: true\n        tests_passing: 12\u002F12\n```\n\n### Spring Cloud Contract\n\n```yaml\nspring_cloud_contract:\n  contracts_location: \".aiwg\u002Fapi\u002Fcontracts\u002F\"\n  consumers:\n    - name: order-service\n      contracts: \"contracts\u002Forder-service\u002F**\u002F*.groovy\"\n\n    - name: payment-service\n      contracts: \"contracts\u002Fpayment-service\u002F**\u002F*.groovy\"\n\n  verification:\n    run: \".\u002Fmvnw clean test\"\n    stub_generation: true\n    publish_stubs: true\n\n  compatibility_check:\n    baseline: v1.0.0\n    current: v2.0.0\n    results:\n      - consumer: order-service\n        compatible: true\n        contracts_verified: 8\u002F8\n\n      - consumer: payment-service\n        compatible: false\n        contracts_verified: 5\u002F7\n        failures:\n          - \"User schema missing 'email' field\"\n          - \"Order status enum missing 'PENDING'\"\n```\n\n## API Compatibility Report\n\n```markdown\n# API Compatibility Report\n\n**Date**: 2026-01-28\n**Baseline**: v1.5.0 (OpenAPI)\n**Current**: v2.0.0\n**API Type**: REST (OpenAPI 3.0)\n\n## Executive Summary\n\n**Status**: ⚠️ BREAKING CHANGES DETECTED\n**Severity**: HIGH\n**Breaking Changes**: 5\n**Non-Breaking Changes**: 12\n**Version Compliance**: ✅ CORRECT (major bump)\n**Consumer Impact**: 2 of 4 consumers affected\n\n## Version Validation\n\n| Aspect | Baseline | Current | Required | Status |\n|--------|----------|---------|----------|--------|\n| Version | v1.5.0 | v2.0.0 | v2.x.x | ✅ CORRECT |\n| Reason | - | Breaking changes detected | Major bump | ✅ VALID |\n\n## Breaking Changes\n\n### 1. Removed Endpoint\n\n**Endpoint**: `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}`\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Endpoint removed entirely from API\n- No replacement or redirect provided\n- Used by 2 consumers: `web-frontend`, `admin-panel`\n\n**Consumer Impact**:\n- web-frontend: 3 call sites affected\n- admin-panel: 1 call site affected\n\n**Recommendation**:\n- Provide migration path: Use `POST \u002Fapi\u002Fv1\u002Fusers\u002F{id}\u002Fdeactivate` instead\n- Update consumer documentation\n- Consider deprecation period instead of immediate removal\n\n### 2. Field Removed: `User.email`\n\n**Resource**: `User` (GET \u002Fapi\u002Fv1\u002Fusers\u002F{id} response)\n**Field**: `email`\n**Severity**: BREAKING\n**Impact**: CRITICAL\n\n**Details**:\n- Required field `email` removed from User response\n- Breaking for consumers expecting this field\n- No alternative field provided\n\n**Consumer Impact**:\n- web-frontend: AFFECTED (displays user email in profile)\n- mobile-app: AFFECTED (uses email for contact)\n- partner-api: NOT AFFECTED (does not use email)\n\n**Recommendation**:\n- DO NOT REMOVE - Add deprecation warning instead\n- Or provide migration: Add `contactInfo.email` as replacement\n- Document migration path clearly\n\n### 3. Field Type Changed: `created_at`\n\n**Field**: `created_at`\n**From**: `string` (ISO-8601)\n**To**: `integer` (Unix timestamp)\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Field type incompatible change\n- All consumers parsing as ISO-8601 will break\n- No backward compatibility layer\n\n**Consumer Impact**:\n- ALL CONSUMERS AFFECTED (4\u002F4)\n- Requires code changes in all consumers\n\n**Recommendation**:\n- Add `created_at_unix` as new field (non-breaking)\n- Deprecate `created_at` string format\n- Maintain both for 2 versions before removing string format\n\n### 4. New Required Field: `password_policy`\n\n**Endpoint**: `POST \u002Fapi\u002Fv1\u002Fusers`\n**Field**: `password_policy`\n**Severity**: BREAKING\n**Impact**: MEDIUM\n\n**Details**:\n- New field added as required in request body\n- Consumers not sending this field will get 400 errors\n- Breaking for existing integrations\n\n**Consumer Impact**:\n- web-frontend: AFFECTED (user registration form)\n- mobile-app: AFFECTED (sign-up flow)\n\n**Recommendation**:\n- Make field optional with sensible default\n- Or add default value if not provided\n- Document new requirement clearly\n\n### 5. Enum Value Removed: `OrderStatus.PENDING`\n\n**Enum**: `OrderStatus`\n**Value**: `PENDING`\n**Severity**: BREAKING\n**Impact**: HIGH\n\n**Details**:\n- Enum value removed without replacement\n- Consumers comparing against `PENDING` will break\n- Orders in `PENDING` state require migration\n\n**Consumer Impact**:\n- order-service: CRITICAL (manages pending orders)\n- payment-service: AFFECTED (checks pending status)\n\n**Recommendation**:\n- DO NOT REMOVE - Deprecate instead\n- Or provide mapping: `PENDING` → `AWAITING_CONFIRMATION`\n- Migrate existing data before API deployment\n\n## Non-Breaking Changes\n\n### Safe Additions\n\n| Change | Type | Impact |\n|--------|------|--------|\n| New endpoint: `GET \u002Fapi\u002Fv2\u002Fusers\u002Fsearch` | Addition | None |\n| New optional field: `User.avatar_url` | Addition | None |\n| New enum value: `OrderStatus.CANCELLED` | Addition | None |\n| New query parameter: `?include_inactive` | Addition | None |\n\n### Deprecations\n\n| Item | Deprecated In | Remove In | Replacement |\n|------|---------------|-----------|-------------|\n| `GET \u002Fapi\u002Fv1\u002Fusers\u002Flist` | v2.0.0 | v3.0.0 | `GET \u002Fapi\u002Fv2\u002Fusers` |\n| Field `User.phone` | v2.0.0 | v3.0.0 | `User.contactInfo.phone` |\n\n## Consumer Contract Test Results\n\n### Pact Verification\n\n| Consumer | Version | Compatible | Tests | Failures |\n|----------|---------|------------|-------|----------|\n| web-frontend | v1.5.0 | ❌ NO | 38\u002F45 | 7 |\n| mobile-app | v2.1.0 | ❌ NO | 40\u002F42 | 2 |\n| partner-api | v1.0.0 | ✅ YES | 12\u002F12 | 0 |\n| admin-panel | v0.9.0 | ❌ NO | 15\u002F18 | 3 |\n\n### Failing Contract Tests\n\n**web-frontend failures**:\n1. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Missing `email` field in response\n2. `POST \u002Fapi\u002Fv1\u002Fusers` - Missing required field `password_policy`\n3. `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Endpoint not found (404)\n\n**mobile-app failures**:\n1. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Field type mismatch: `created_at`\n2. `POST \u002Fapi\u002Fv1\u002Fusers` - Validation error: `password_policy` required\n\n**admin-panel failures**:\n1. `DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Endpoint removed\n2. `GET \u002Fapi\u002Fv1\u002Forders` - Enum value `PENDING` not recognized\n3. `GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}` - Missing `email` field\n\n## Backward Compatibility Analysis\n\n```yaml\ncompatibility_assessment:\n  backward_compatible: false\n  reason: \"5 breaking changes detected\"\n\n  migration_effort:\n    web-frontend: HIGH (7 changes required)\n    mobile-app: MEDIUM (2 changes required)\n    partner-api: NONE (no changes needed)\n    admin-panel: HIGH (3 changes required)\n\n  recommended_strategy:\n    option_1:\n      name: \"Parallel API versions\"\n      description: \"Maintain v1 and v2 simultaneously\"\n      effort: HIGH\n      timeline: \"6 months dual support\"\n\n    option_2:\n      name: \"Phased migration\"\n      description: \"Reduce breaking changes, migrate in phases\"\n      effort: MEDIUM\n      timeline: \"3 months migration window\"\n      preferred: true\n\n    option_3:\n      name: \"Hard cutover\"\n      description: \"Deploy v2, deprecate v1 immediately\"\n      effort: LOW\n      timeline: \"1 month notice\"\n      risk: HIGH\n```\n\n## Recommendations\n\n### Immediate Actions\n\n- [ ] Revert breaking changes or provide backward compatibility layer\n- [ ] Make `password_policy` field optional with default value\n- [ ] Add `created_at_unix` alongside `created_at` string\n- [ ] Do not remove `email` field - deprecate with timeline instead\n- [ ] Provide `PENDING` → `AWAITING_CONFIRMATION` enum mapping\n\n### Consumer Migration\n\n- [ ] Notify all consumers of breaking changes\n- [ ] Provide migration guide with code examples\n- [ ] Offer migration support timeline (3 months)\n- [ ] Update consumer contract tests\n- [ ] Coordinate deployment across consumers\n\n### Process Improvements\n\n- [ ] Add contract testing to CI\u002FCD pipeline\n- [ ] Require compatibility report in PR template\n- [ ] Enforce semantic versioning in release process\n- [ ] Implement API deprecation policy (6-month notice)\n- [ ] Add breaking change review gate\n\n## Migration Guide\n\n### For web-frontend\n\n```diff\n\u002F\u002F User profile display\n- const email = user.email;\n+ const email = user.contactInfo?.email || user.email;\n\n\u002F\u002F User registration\n  const userData = {\n    username: form.username,\n    password: form.password,\n+   password_policy: 'default',\n  };\n\n\u002F\u002F Delete user\n- await api.delete(`\u002Fapi\u002Fv1\u002Fusers\u002F${id}`);\n+ await api.post(`\u002Fapi\u002Fv1\u002Fusers\u002F${id}\u002Fdeactivate`);\n```\n\n### For mobile-app\n\n```diff\n\u002F\u002F Timestamp parsing\n- const createdAt = new Date(user.created_at); \u002F\u002F ISO string\n+ const createdAt = user.created_at_unix\n+   ? new Date(user.created_at_unix * 1000)\n+   : new Date(user.created_at);\n\n\u002F\u002F User registration\n  const userData = {\n    ...\n+   password_policy: 'default',\n  };\n```\n\n## Tool Output\n\n### OpenAPI Diff\n\n```bash\n$ openapi-diff baseline.yaml current.yaml --breaking-only\n\nBREAKING CHANGES DETECTED (5):\n\n1. DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n   - Endpoint removed\n\n2. GET \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n   - Response schema changed\n   - Field 'email' removed\n\n3. POST \u002Fapi\u002Fv1\u002Fusers\n   - Request schema changed\n   - Field 'password_policy' now required\n\n4. OrderStatus enum\n   - Value 'PENDING' removed\n\n5. Multiple endpoints\n   - Field 'created_at' type changed: string → integer\n\nSee full report: openapi-diff-report.md\n```\n```\n\n## Usage Examples\n\n### Detect REST API Regression\n\n```\nUser: \"Check API contract for breaking changes\"\n\nSkill executes:\n1. Locate OpenAPI spec files\n2. Load baseline (v1.5.0)\n3. Load current (v2.0.0)\n4. Run openapi-diff\n5. Classify changes\n6. Check semantic versioning\n7. Run Pact tests\n\nOutput:\n\"API Compatibility Report\n\nStatus: BREAKING CHANGES DETECTED\nBreaking: 5\nNon-Breaking: 12\nVersion: v1.5.0 → v2.0.0 (CORRECT major bump)\nConsumer Impact: 3 of 4 consumers affected\n\nCritical Issues:\n1. Field removed: User.email (affects web-frontend, mobile-app)\n2. Endpoint removed: DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id}\n3. Type change: created_at string → integer\n\nSee full report: .aiwg\u002Fapi\u002Fcompatibility\u002Freport-2026-01-28.md\n\nRecommendation: Revert breaking changes or add compatibility layer\"\n```\n\n### Detect GraphQL Schema Regression\n\n```\nUser: \"API breaking change check for GraphQL\"\n\nSkill executes:\n1. Locate GraphQL schema files\n2. Load baseline schema\n3. Load current schema\n4. Run graphql-inspector diff\n5. Identify breaking vs safe changes\n\nOutput:\n\"GraphQL Schema Compatibility\n\nStatus: BREAKING CHANGES DETECTED\nBreaking: 2\nDangerous: 3\nSafe: 8\n\nBreaking Changes:\n1. Field 'User.email' removed\n2. Type 'Address' removed\n\nDangerous Changes:\n1. Field 'User.age' type changed: Int → String\n2. Argument 'Query.users(limit)' default changed: 10 → 100\n3. Enum 'Status' value 'ACTIVE' description changed\n\nRecommendation: Review breaking changes before deployment\"\n```\n\n### Consumer Contract Verification\n\n```\nUser: \"Run consumer contract tests\"\n\nSkill executes:\n1. Locate Pact contracts\n2. Run provider verification tests\n3. Generate compatibility matrix\n\nOutput:\n\"Consumer Contract Verification\n\nStatus: INCOMPATIBLE CONSUMERS DETECTED\nCompatible: 1\u002F4\nFailing: 3\u002F4\n\nResults:\n✅ partner-api (12\u002F12 tests passing)\n❌ web-frontend (38\u002F45 passing, 7 failures)\n❌ mobile-app (40\u002F42 passing, 2 failures)\n❌ admin-panel (15\u002F18 passing, 3 failures)\n\nCommon Failures:\n- Missing field: User.email (3 consumers)\n- Endpoint not found: DELETE \u002Fapi\u002Fv1\u002Fusers\u002F{id} (2 consumers)\n\nAction Required: Update consumers or revert breaking changes\"\n```\n\n## Integration\n\nThis skill uses:\n- `regression-baseline`: Store API contract baselines\n- `regression-bisect`: Find commit that introduced breaking change\n- `regression-report`: Generate comprehensive regression report\n- `project-awareness`: Detect API framework (OpenAPI, GraphQL, gRPC)\n\n## Agent Orchestration\n\n```yaml\nagents:\n  detection:\n    agent: api-designer\n    focus: Identify and classify API changes\n\n  analysis:\n    agent: architecture-designer\n    focus: Assess impact and recommend migration\n\n  testing:\n    agent: test-engineer\n    focus: Run consumer contract tests\n\n  approval:\n    agent: tech-lead\n    focus: Approve breaking changes or require fixes\n```\n\n## Configuration\n\n### Detection Settings\n\n```yaml\napi_contract_detection:\n  api_types:\n    - rest_openapi\n    - graphql\n    - grpc_protobuf\n\n  tools:\n    rest: openapi-diff\n    graphql: graphql-inspector\n    grpc: buf\n\n  baselines:\n    storage: .aiwg\u002Fapi\u002Fbaselines\u002F\n    naming: \"{api-name}-{version}.{ext}\"\n\n  strict_mode: true  # Fail on any breaking change\n  semver_enforcement: true\n```\n\n### Breaking Change Rules\n\n```yaml\nbreaking_rules:\n  rest:\n    - removed_endpoints\n    - removed_fields\n    - type_changes\n    - new_required_fields\n    - enum_value_removals\n    - stricter_validations\n\n  graphql:\n    - removed_fields\n    - removed_types\n    - type_changes\n    - non_nullable_additions\n    - argument_removals\n\n  grpc:\n    - removed_services\n    - removed_rpcs\n    - removed_fields\n    - type_changes\n    - required_field_additions\n```\n\n### Consumer Contract Testing\n\n```yaml\nconsumer_contracts:\n  enabled: true\n  framework: pact  # or spring-cloud-contract\n\n  pact:\n    broker_url: https:\u002F\u002Fpact-broker.example.com\n    publish_verification: true\n\n  contracts_location: .aiwg\u002Fapi\u002Fcontracts\u002F\n  fail_on_incompatibility: true\n```\n\n## Output Locations\n\n- Baselines: `.aiwg\u002Fapi\u002Fbaselines\u002F{api-name}-{version}.{yaml|graphql|proto}`\n- Reports: `.aiwg\u002Fapi\u002Fcompatibility\u002Freport-{date}.md`\n- Diffs: `.aiwg\u002Fapi\u002Fcompatibility\u002Fdiff-{baseline}-to-{current}.md`\n- Pact Results: `.aiwg\u002Fapi\u002Fpact-results\u002F`\n- Migration Guides: `.aiwg\u002Fapi\u002Fmigration\u002F{version}\u002FMIGRATION.md`\n\n## References\n\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fschemas\u002Ftesting\u002Fregression.yaml\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fagents\u002Fapi-designer.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-baseline\u002FSKILL.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-bisect\u002FSKILL.md\n- @.aiwg\u002Fresearch\u002Ffindings\u002FREF-013-metagpt.md\n- @$AIWG_ROOT\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Frules\u002Fexecutable-feedback.md\n",{"name":5,"namespace":56,"platforms":57,"description":7},"aiwg",[58],"all","main","6754967c344ccb087a8de06972f55a41067b291b","agentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-api-contract",36,"https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg","https:\u002F\u002Faiwg.io","https:\u002F\u002Fgithub.com\u002Fjmagly","https:\u002F\u002Fintegrolabs.io","ml\u002Fai, industrial automation, safety\u002Fsecurity, ssi\r\n\r\nmagly.net\r\nintegrolabs.io\r\naiwg.io\r\nfortemi.com\r\npagenary.com\r\nbytecask.com","2026-11-12 00:33:10",{"source":8,"skillName":5,"commands":70,"prompt":80,"zipAvailable":81},[71,74,77],{"tool":72,"command":73},"npx","npx skills add jmagly\u002Faiwg --skill regression-api-contract",{"tool":75,"command":76},"bunx","bunx skills add jmagly\u002Faiwg --skill regression-api-contract",{"tool":78,"command":79},"pnpm","pnpm dlx skills add jmagly\u002Faiwg --skill regression-api-contract","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsdlc-complete\u002Fskills\u002Fregression-api-contract\u002FSKILL.md",true,[],[84,112,136,142,149,163],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":91,"publishedAt":51},"01M70QA0BSYJ49EES9V4RE8QH1","host-hardening","Read-only system hardening baseline and plan-first host hardening recommendations for SSH, Docker bind addresses, firewall persistence, datastores, exporters and audit retention.","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fplugins\u002Fsecurity-engineering\u002Fskills\u002Fhost-hardening\u002FSKILL.md",[90],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111],"host","host hardening","hardening","read","re","recommendations","remediation","plan","port","verification","Bash","access","only","retention","audit","never","firewall","bind","secrets","request",{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":122,"publishedAt":51},"01M70PNT2Z4HMZPRBTAF6073NN","exposure-analysis","Read-only firewall analysis and effective host exposure reconstruction for Docker published ports, UFW bypass, stale rules, CDN scope, IPv6 asymmetry and external probe allowlists.","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fplugins\u002Fforensics\u002Fskills\u002Fexposure-analysis\u002FSKILL.md",[118,121],{"categoryNo":119,"categoryName":120,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[123,124,125,95,126,100,127,128,102,129,92,130,104,131,132,107,108,133,134,135],"exposure analysis","analysis","unknown","credentials","collection","ufw","ports","internet","local","scope","reconstruction","operator","write",{"skillNo":137,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":141,"publishedAt":51},"01M70P8QATMPKA78E4FT5D2TNA","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fframeworks\u002Fsecurity-engineering\u002Fskills\u002Fhost-hardening\u002FSKILL.md",[140],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[94,92,93,103,95,111,98,97,106,99,100,101,102,110,104,105,96,107,108,109],{"skillNo":143,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":148,"publishedAt":51},"01M70NMPVJ5H0JH131P60FW4R8","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Fagentic\u002Fcode\u002Fframeworks\u002Fforensics-complete\u002Fskills\u002Fexposure-analysis\u002FSKILL.md",[146,147],{"categoryNo":119,"categoryName":120,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[124,123,107,126,100,127,102,125,92,130,104,131,132,95,108,129,128,133,134,135],{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":156,"publishedAt":51},"01M6CB4DDR0B4NNCFK7ZK7449H","fixture-skill","Exercise rule delivery.","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Frule-delivery\u002Fskills\u002Ffixture-skill\u002FSKILL.md",[155],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[157,158,159,160,161,162],"fixture skill","fixture","rule","delivery","true","exercise",{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":170,"publishedAt":51},"01M6CB4AVK1W76MFMPP0JP32CJ","pi-local","Pi-local duplicate-precedence fixture.","https:\u002F\u002Fgithub.com\u002Fjmagly\u002Faiwg\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fproviders\u002Fpi\u002Fproject\u002F.pi\u002Fskills\u002Fpi-local\u002FSKILL.md",[169],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[171,172,131,173,158],"pi","pi local","duplicate"]