/contract-detection

name: contract-detection
description: Layer 1 skill for parsing machine-readable API contracts. OpenAPI/Swagger, GraphQL, Protobuf/gRPC, and JSON Schema detection, extraction, and behavioral claim generation. Loaded by the analyzer agent during Layer 1.

Contract Detection Methodology

Extract behavioral intelligence from machine-readable API contracts. These are formal, published definitions of system interfaces -- the strongest possible specification source. A contract file is an explicit promise about what the system accepts and returns.

When to Use This Mode

Contract detection activates when:

• The target repository or documentation contains API specification files
• The discovery inventory identifies machine-readable contract files
• Other modes discover machine-readable contracts during analysis

This mode runs independently of all other intelligence sources. All output is **PUBLIC** -- machine-readable contracts are published definitions intended for external consumption. Output goes to `workspace/public/contracts/`.

Why Contracts Are the Strongest Source

Machine-readable contracts are unique among intelligence sources because they are:

• **Formal** -- they use standardized schemas with unambiguous semantics
• **Published** -- they are intended for external consumers to rely on
• **Machine-verifiable** -- they can be validated against implementations automatically
• **Versioned** -- they explicitly track breaking changes through version fields

A single OpenAPI specification can contain more behavioral intelligence than the entire official documentation site, because every endpoint, parameter, response schema, and error code is defined with machine precision.

OpenAPI / Swagger

Detection

# Find OpenAPI/Swagger files
find . -maxdepth 5 -type f \( \
  -name "openapi.*" -o -name "swagger.*" -o \
  -name "api-spec.*" -o -name "api-docs.*" \
  \) \( -name "*.json" -o -name "*.yaml" -o -name "*.yml" \) 2>/dev/null

# Check for OpenAPI version markers in YAML/JSON files
grep -rl '"openapi":\|openapi:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20
grep -rl '"swagger":\|swagger:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20

# Check for hosted spec endpoints (common locations)
# /api-docs, /swagger.json, /openapi.json, /v2/api-docs, /v3/api-docs

Extraction

For each OpenAPI/Swagger specification, extract:

Endpoints

| Field | What It Tells You | |-------|-------------------| | `paths` | Every endpoint the API exposes | | HTTP method | The operation type (GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove) | | `operationId` | The canonical name for the operation | | `summary` / `description` | Behavioral description of what the endpoint does | | `tags` | Logical grouping of endpoints |

Parameters

| Field | What It Tells You | |-------|-------------------| | `parameters` (path, query, header, cookie) | Required inputs and their types | | `required` | Whether the parameter is mandatory | | `schema` with `enum` | Allowed values (behavioral constraint) | | `schema` with `minimum` / `maximum` | Value range (behavioral constraint) | | `schema` with `pattern` | Validation regex (behavioral constraint) | | `schema` with `default` | Default value when omitted |

Request/Response Schemas

| Field | What It Tells You | |-------|-------------------| | `requestBody` | What the endpoint accepts (content type, schema) | | `responses` | Every possible response code and its schema | | `responses.4xx` | Client error conditions and their structure | | `responses.5xx` | Server error conditions | | `components/schemas` | Shared data models with field types, constraints, and relationships |

Authentication

| Field | What It Tells You | |-------|-------------------| | `securityDefinitions` / `components/securitySchemes` | Auth methods (API key, OAuth2, Bearer, Basic) | | `security` (global or per-operation) | Which endpoints require which auth |

Output Format

Write to `workspace/public/contracts/openapi-summary.md`:

## API: {title} v{version}

### Endpoints

| Method | Path | Operation | Auth Required | Description |
|--------|------|-----------|---------------|-------------|
| GET | /users | listUsers | Bearer | List all users with pagination |
| POST | /users | createUser | Bearer | Create a new user |

### Data Models

#### User
| Field | Type | Required | Constraints | Description |
|-------|------|----------|-------------|-------------|
| id | string (uuid) | yes | read-only | Unique identifier |
| email | string | yes | format: email | User's email address |

### Error Responses
| Code | Meaning | Schema |
|------|---------|--------|
| 400 | Validation error | { message: string, errors: [{field, code}] } |
| 401 | Unauthorized | { message: string } |
| 404 | Not found | { message: string } |

GraphQL

Detection

# Find GraphQL schema files
find . -maxdepth 5 -type f \( \
  -name "schema.graphql" -o -name "*.graphqls" -o -name "schema.gql" -o \
  -name "*.graphql" \
  \) 2>/dev/null

# Find GraphQL codegen config (indicates GraphQL usage)
find . -maxdepth 3 -type f \( \
  -name "codegen.*" -o -name ".graphqlrc*" -o -name "apollo.config.*" \
  \) 2>/dev/null

# Check for GraphQL in dependencies
grep -l "graphql\|apollo\|@graphql" package.json requirements.txt Gemfile go.mod 2>/dev/null

# Check for introspection endpoint (if running instance available)
# POST /graphql with { "query": "{ __schema { types { name } } }" }

Extraction

For each GraphQL schema, extract:

Queries (Read Operations)

| Element | What It Tells You | |---------|-------------------| | Query type fields | Every read operation the API exposes | | Arguments | Required and optional parameters with types | | Return types | Shape of the response data | | Directives (`@deprecated`, `@auth`) | Behavioral modifiers |

Mutations (Write Oper