005 New plugin: OpenAPI drift detection

.github/plugin/marketplace.json

@@ -19,6 +19,12 @@
       "description": "Detects drift between AsyncAPI spec (version 3.x) and service implementation, prioritises findings in order of severity, and proposes fixes to ensure service implementation is accurately reflected in its documentation.",
       "version": "1.0.0",
       "source": "./plugins/asyncapi-drift-detection"
+    },
+    {
+      "name": "openapi-drift-detection",
+      "description": "Detects drift between OpenAPI spec and service implementation, prioritises findings in order of severity, and proposes fixes to ensure service implementation is accurately reflected in its documentation.",
+      "version": "1.0.0",
+      "source": "./plugins/openapi-drift-detection"
     }
   ]
 }

docs/README.plugins.md

@@ -14,5 +14,6 @@ copilot plugin install <plugin-name>@dev-suq
 
 | Plugin | Description | Install |
 |--------|-------------| ------- |
-| [nodejs-sonarqube-cloud](../plugins/nodejs-sonarqube-cloud/README.md) | Analyses SonarQube Cloud quality gate results from the CI pipeline, triages all issues, and implements fixes automatically. Includes a skill for running local scans via `sonar-scanner-cli`. | `copilot plugin install nodejs-sonarqube-cloud@dev-suq` |
 | [asyncapi-drift-detection](../plugins/asyncapi-drift-detection/README.md) | Detects drift between AsyncAPI spec (version 3.x) and service implementation, prioritises findings in order of severity, and proposes fixes to ensure service implementation is accurately reflected in its documentation. | `copilot plugin install asyncapi-drift-detection@dev-suq` |
+| [nodejs-sonarqube-cloud](../plugins/nodejs-sonarqube-cloud/README.md) | Analyses SonarQube Cloud quality gate results from the CI pipeline, triages all issues, and implements fixes automatically. Includes a skill for running local scans via `sonar-scanner-cli`. | `copilot plugin install nodejs-sonarqube-cloud@dev-suq` |
+| [openapi-drift-detection](../plugins/openapi-drift-detection/README.md) | Detects drift between OpenAPI spec and service implementation, prioritises findings in order of severity, and proposes fixes to ensure service implementation is accurately reflected in its documentation. | `copilot plugin install openapi-drift-detection@dev-suq` |

plugins/openapi-drift-detection/README.md

@@ -0,0 +1,69 @@
+# openapi-drift-detection
+
+An agent that compares OpenAPI spec with service implementation to identify areas of drift, prioritises findings in order of highest severity, and proposes fixes to ensure proper alignment between the service and its documentation.
+
+## What's included
+
+| Component | Path | Description |
+|-----------|------|-------------|
+| Agent | `agents/openapi-drift-detector.agent.md` | Detects drift between OpenAPI 3.x spec and service implementation across 7 dimensions (paths & operations, request schemas, response schemas, authentication & security, error responses, content types, API metadata), prioritises findings by severity (P0-P3), and proposes JSON/YAML fixes |
+| Skill | `skills/openapi-drift-detection/` | Comprehensive 4-step procedure for discovering OpenAPI specs, parsing specifications, analysing service implementation, comparing across all dimensions, and generating detailed drift reports with proposed fixes |
+
+## How it works
+
+### Agent: OpenAPI drift detector
+
+The agent:
+
+1. Discovers OpenAPI specification files in your project
+2. Parses paths, operations, parameters, request bodies, response schemas, security schemes, and servers
+3. Analyzes the service implementation to extract actual routes, validation schemas, response shapes, auth configuration, and error handlers
+4. Compares the spec against the implementation across 7 dimensions:
+   - **Paths & Operations**: Declared vs. actual routes and HTTP methods
+   - **Request Schemas**: Declared vs. actual parameters and request body validation
+   - **Response Schemas**: Declared vs. actual response status codes and body shapes
+   - **Authentication & Security**: Declared vs. actual auth strategies and per-route overrides
+   - **Error Responses**: Declared vs. actual error status codes and shapes
+   - **Content Types**: Declared vs. actual accepted and produced content types
+   - **API Metadata**: Declared vs. actual server URLs, versioning, and info fields
+5. Prioritises findings by severity (P0-P3):
+   - **P0 — Critical**: Contract-breaking differences (missing routes, wrong methods, missing required fields)
+   - **P1 — High**: Schema-level inaccuracies (type mismatches, enum mismatches, auth scheme issues)
+   - **P2 — Medium**: Correctness gaps (optional fields not in spec, default value mismatches)
+   - **P3 — Low**: Documentation quality issues (missing descriptions, cosmetic naming)
+6. Generates a structured drift report with findings grouped by priority
+7. Proposes JSON/YAML fixes to bring the spec into alignment with the implementation
+
+### Skill: OpenAPI drift detection
+
+The skill provides a comprehensive 4-step procedure:
+
+1. **Project Discovery**: Locates OpenAPI specs, detects spec generation method, discovers API-related source code, builds a service inventory
+2. **Parse OpenAPI Spec**: Extracts paths, operations, parameters, request bodies, responses, components, security schemes, and servers
+3. **Analyse Service Implementation**: Discovers actual routes, request validation, response shapes, auth configuration, error handling, and content types
+4. **Compare & Detect Drift**: Checks all 7 dimensions using the priority framework and generates a detailed drift report
+
+Includes reference documentation:
+- `discovery-patterns.md`: Search strategies for finding API infrastructure code
+- `drift-categories.md`: Complete priority framework and decision matrix
+- `report-template.md`: Structured drift report format
+
+## Usage
+
+Ask the agent to detect drift in your OpenAPI specifications:
+
+> "Check for drift between my OpenAPI spec and service implementation"
+
+> "Audit my OpenAPI 3.x documentation against the actual service"
+
+> "Review my routes, schemas, and responses in OpenAPI against the code"
+
+The agent will:
+1. Generate a comprehensive drift report
+2. Prioritise findings by severity
+3. Propose specific JSON/YAML changes to fix the drift
+4. Apply fixes with your approval
+
+## License
+
+[MIT](../../LICENSE)

plugins/openapi-drift-detection/agents/openapi-drift-detector.agent.md

@@ -0,0 +1,36 @@
+---
+description: "Detect OpenAPI contract drift between an OpenAPI 3.x spec and the service implementation. Use when: checking OpenAPI drift, auditing REST API documentation, validating request/response schemas match code, reviewing API contract accuracy, comparing spec vs implementation, onboarding documentation review, verifying routes operations and schemas match implementation."
+tools: [read, search, edit]
+model: Claude Sonnet 4.6 (copilot)
+---
+
+You are an OpenAPI contract drift detective. Your job is to find discrepancies between a project's OpenAPI 3.x specification and its actual HTTP API implementation, then report them in a structured, prioritised format and offer to fix the spec.
+
+## Constraints
+
+- DO NOT edit application source code — only OpenAPI spec files (e.g. `openapi*.json`, `openapi*.yaml`, `openapi*.yml`, `swagger*.json`, `swagger*.yaml`)
+- DO NOT guess or fabricate information about the service — only report what you can verify by reading the code
+- DO NOT modify the service's behaviour — if the code is "wrong", flag it in the report for the developer to fix manually
+- ONLY propose spec changes that bring documentation in line with the actual implementation
+- ALWAYS use the `openapi-drift-detection` skill procedure for a thorough, repeatable analysis
+- When the spec is auto-generated (e.g. via hapi-swagger, swagger-jsdoc, NestJS decorators), note this in the report — drift may indicate the spec needs regeneration rather than manual editing
+
+## Approach
+
+1. **Discover** — Find the OpenAPI spec(s) and all API-related source code in the workspace using the `openapi-drift-detection` skill's discovery procedure
+2. **Parse** — Extract the contract surface from the spec: paths, operations, parameters, request bodies, response schemas, security schemes, servers, metadata
+3. **Analyse** — Extract the actual implementation surface from source code: route registrations, validation schemas, response builders, auth configuration, error handlers, content types
+4. **Compare** — Detect drift across 7 dimensions: Paths & Operations, Request Schemas, Response Schemas, Authentication & Security, Error Responses, Content Types, API Metadata
+5. **Report** — Generate a prioritised drift report (P0 Critical → P3 Low) using the standardised report template
+6. **Fix** — After presenting the report, offer to apply proposed changes to the OpenAPI spec. Apply fixes only with user approval, one at a time
+
+## Output Format
+
+Always output a structured drift report following the report template from the `openapi-drift-detection` skill. If no drift is detected, confirm alignment with a brief summary of what was checked.
+
+## When Offering Fixes
+
+- Show the exact JSON/YAML path and proposed change before applying
+- Apply one fix at a time so the user can review each change
+- After all fixes are applied, re-run the comparison to confirm zero remaining drift
+- If the spec is auto-generated, recommend regeneration commands instead of manual edits where appropriate

plugins/openapi-drift-detection/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "openapi-drift-detection",
+  "description": "Detects drift between OpenAPI spec and service implementation, prioritises findings in order of severity, and proposes fixes to ensure service implementation is accurately reflected in its documentation.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Rana Salem"
+  },
+  "license": "MIT",
+  "keywords": [
+    "openapi",
+    "documentation"
+  ],
+  "agents": "agents/",
+  "skills": "skills/"
+}