contract-first-design

What this skill does

# Contract-First Design Skill

## When to Use This Skill

Use this skill when:

- **Contract First Design tasks** - Working on design and manage api contracts before implementation using openapi and asyncapi specifications for contract-first development
- **Planning or design** - Need guidance on Contract First Design approaches
- **Best practices** - Want to follow established patterns and standards

## Overview

Apply contract-first development methodology for APIs, ensuring specifications drive implementation.

## Contract-First Methodology

### Core Principles

```yaml
contract_first_principles:
  design_before_code:
    description: "API specification comes before implementation"
    benefits:
      - "Early feedback from consumers"
      - "Parallel development enabled"
      - "Clear contract for testing"
      - "Documentation from day one"

  specification_as_source_of_truth:
    description: "Spec is authoritative, code conforms to it"
    enforcement:
      - "Generate code from spec"
      - "Validate implementation against spec"
      - "CI/CD gates on spec compliance"

  consumer_centric:
    description: "Design for consumer needs, not provider convenience"
    practices:
      - "Involve consumers in design reviews"
      - "Consumer-driven contract testing"
      - "Gather real-world usage patterns"

  evolution_over_revolution:
    description: "Evolve contracts without breaking consumers"
    practices:
      - "Semantic versioning"
      - "Backward compatibility by default"
      - "Deprecation before removal"
```

### Development Workflow

```yaml
contract_first_workflow:
  phases:
    1_design:
      activities:
        - "Identify API consumers and use cases"
        - "Define resources and operations"
        - "Draft specification (OpenAPI/AsyncAPI)"
        - "Review with stakeholders"
      artifacts:
        - "Draft API specification"
        - "Use case documentation"
      gate: "Specification approved by consumers"

    2_validate:
      activities:
        - "Lint specification for style/standards"
        - "Check backward compatibility"
        - "Generate mock server"
        - "Consumer acceptance testing with mocks"
      artifacts:
        - "Lint report"
        - "Compatibility report"
        - "Mock server configuration"
      gate: "Consumers validated against mocks"

    3_implement:
      activities:
        - "Generate server stubs"
        - "Implement business logic"
        - "Contract testing against spec"
        - "Integration testing"
      artifacts:
        - "Generated code"
        - "Contract test results"
      gate: "Implementation passes contract tests"

    4_publish:
      activities:
        - "Publish specification to catalog"
        - "Generate documentation"
        - "Update changelog"
        - "Notify consumers"
      artifacts:
        - "Published specification"
        - "API documentation portal"
        - "Changelog entry"
      gate: "Documentation live, consumers notified"

    5_operate:
      activities:
        - "Monitor API usage"
        - "Collect consumer feedback"
        - "Track breaking change requests"
        - "Plan next version"
      artifacts:
        - "Usage metrics"
        - "Feedback log"
        - "Deprecation schedule"
```

## Contract Management

### Specification Organization

```yaml
specification_organization:
  directory_structure:
    recommended:
      specs/
        openapi/
          order-service.yaml
          customer-service.yaml
          inventory-service.yaml
        asyncapi/
          order-events.yaml
          inventory-events.yaml
        shared/
          schemas/
            common-types.yaml
            error-responses.yaml
          parameters/
            pagination.yaml
          security/
            auth-schemes.yaml

  file_naming:
    pattern: "{service-name}.yaml"
    versioned: "{service-name}-v{major}.yaml"

  modular_specs:
    description: "Split large specs into components"
    approach:
      main_file: "Defines paths, references components"
      components_dir: "Reusable schemas, parameters, responses"
      shared_dir: "Cross-API shared definitions"

    example_main:
      openapi: "3.1.0"
      info:
        title: "Order Service API"
        version: "1.0.0"
      paths:
        $ref: "./paths/orders.yaml"
      components:
        schemas:
          $ref: "./schemas/_index.yaml"
```

### Version Management

```yaml
version_management:
  semantic_versioning:
    major: "Breaking changes"
    minor: "Backward-compatible additions"
    patch: "Backward-compatible fixes"

  version_in_spec:
    location: "info.version"
    format: "MAJOR.MINOR.PATCH"

  api_versioning_strategies:
    url_path:
      spec_example:
        servers:
          - url: "https://api.example.com/v1"
      change_approach: "New spec file for major versions"

    header:
      spec_example:
        parameters:
          API-Version:
            in: header
            required: false
            schema:
              type: string
              default: "2025-01-01"

  changelog_requirements:
    location: "CHANGELOG.md alongside spec"
    format: "Keep a Changelog"
    content:
      - "Version number and date"
      - "Added: new endpoints/fields"
      - "Changed: modified behavior"
      - "Deprecated: marked for removal"
      - "Removed: breaking deletions"
      - "Fixed: bug fixes"
      - "Security: vulnerability patches"
```

### Breaking Change Detection

```yaml
breaking_changes:
  definition: "Changes that can break existing consumers"

  openapi_breaking:
    removals:
      - "Remove endpoint"
      - "Remove required response field"
      - "Remove enum value"
      - "Remove supported content type"

    modifications:
      - "Change field type"
      - "Add required request field"
      - "Narrow validation (smaller max, larger min)"
      - "Change authentication requirements"

    renames:
      - "Rename field (equivalent to remove + add)"
      - "Change endpoint path"

  asyncapi_breaking:
    removals:
      - "Remove channel"
      - "Remove message type"
      - "Remove required payload field"

    modifications:
      - "Change payload schema incompatibly"
      - "Change channel address format"
      - "Modify required headers"

  detection_tools:
    openapi:
      - "openapi-diff"
      - "oasdiff"
      - "speccy"
    asyncapi:
      - "asyncapi/diff"

  ci_integration:
    script: |
      # Compare current spec against main branch
      oasdiff breaking main.yaml current.yaml
      if [ $? -ne 0 ]; then
        echo "Breaking changes detected!"
        exit 1
      fi
```

## C# Models for Contract Management

```csharp
namespace SpecDrivenDevelopment.ContractFirst;

/// <summary>
/// Represents an API contract lifecycle state
/// </summary>
public enum ContractStatus
{
    Draft,
    InReview,
    Approved,
    Implementing,
    Published,
    Deprecated,
    Retired
}

/// <summary>
/// API contract metadata
/// </summary>
public record ApiContract
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public required ContractType Type { get; init; }
    public required ContractStatus Status { get; init; }
    public required string SpecificationPath { get; init; }
    public string? Description { get; init; }
    public List<string> Owners { get; init; } = [];
    public List<string> Consumers { get; init; } = [];
    public DateTimeOffset CreatedAt { get; init; }
    public DateTimeOffset? PublishedAt { get; init; }
    public DateTimeOffset? DeprecatedAt { get; init; }
    public DateTimeOffset? SunsetAt { get; init; }
}

public enum ContractType
{
    OpenApi,
    AsyncApi,
    GraphQL,
    gRPC
}

/// <summary>
/// Tracks changes between contract versions
/// </summary>
public record ContractChange
{
    public required string ContractId { get; init; }
    public required string FromVersion { get; init;