feat: Generate AsyncAPI spec for Event Driven Architecture

[harikrishnan83]

Fixes #944

Summary

This PR adds generation of AsyncAPI specification support to spec-kit templates, enabling the toolkit to detect, document, and generate a standardised spec for event-driven and asynchronous communication patterns alongside traditional synchronous REST/GraphQL APIs.

Key Changes

Communication Patterns Detection

• Added Communication Patterns taxonomy to the clarify command (templates/commands/clarify.md)
• Detects request/response vs event-driven patterns
• Identifies synchronous vs asynchronous operations
• Captures real-time update mechanisms (polling, WebSocket, webhooks, etc.)
• Documents message delivery guarantees and bidirectional communication needs

AsyncAPI Specification Generation

• Enhanced plan command (templates/commands/plan.md) to generate AsyncAPI specifications
• Automatic detection of async indicators (real-time, streaming, events, notifications, etc.)
• Generates asyncapi.yaml or events-api.yaml alongside OpenAPI specs
• Supports hybrid APIs with both synchronous and asynchronous patterns
• Added research tasks for protocol/technology evaluation (WebSocket vs Webhooks vs Message Queues)

Template Enhancements

• Updated plan template (templates/plan-template.md) with new fields:
  • Communication Patterns: Documents the API communication model
  • Async Operations: Specifies event types, channels, and messaging patterns
• Clear separation between sync operations (REST/GraphQL) and async operations (Events/WebSocket)

Files Modified

• templates/commands/clarify.md (+8 lines)
• templates/commands/plan.md (+38 lines, -3 lines)
• templates/plan-template.md (+7 lines, -7 lines)

Benefits

• Better Requirements Gathering: Clarify command now captures async communication requirements upfront
• Complete API Documentation: Supports both OpenAPI and AsyncAPI specifications
• Technology Guidance: Helps teams choose appropriate protocols for their use cases
• Hybrid API Support: Handles modern applications that use both sync and async patterns

Manual Testing Details

Click here to expand

Spec Kit interactions

/speckit.specify delivery status tracking
  - Allow clients to subscribe to status changes of a package based on the tracking reference number
  - The status involves two fields, status (Dispatched, InTransit, Delayed, OnTime, OutForDelivery, Delivered) and time at which this status was known

/speckit.plan Build a Java and Springboot application
  - Exposes a REST endpoint which accepts status subcription requests through HTTP POST for tracking ref number
  - In response it return a Kafka topic on which clients can get their updates
  - Exposes another REST endpoint where it receives delivery status in bulk for multiple tracking ref numbers and stores those in an in memory map
  - This service just has to look at the in memory map every 15 min and let the clients who registered for tracking status know about the current status of their delivery on the respective Kafka topics
  - No need to handle retries etc. this is a low risk service

Generated AsyncAPI Spec

asyncapi: 3.0.0
info:
  title: Delivery Status Tracking Event API
  version: 1.0.0
  description: |
    Event-driven API for real-time delivery status notifications via Apache Kafka.

    ## Overview

    This API defines the asynchronous communication pattern for delivery status updates.
    Clients subscribe to tracking updates via REST API (see OpenAPI spec) and receive
    notifications on dedicated Kafka topics.

    ## Workflow

    1. Client calls REST endpoint `POST /api/v1/subscriptions` with tracking reference
    2. Service creates a unique Kafka topic and returns topic name
    3. Client consumes from the assigned Kafka topic
    4. Service publishes status updates to the topic every 15 minutes
    5. Client receives `DeliveryStatusUpdate` messages

    ## Message Delivery

    - **Frequency**: Updates published every 15 minutes via scheduled job
    - **Reliability**: At-least-once delivery (Kafka guarantees)
    - **Ordering**: Messages for same tracking reference are ordered by timestamp
    - **Retention**: Kafka topic retention configurable (default: 7 days)
  contact:
    name: API Support
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  development:
    host: localhost:9092
    protocol: kafka
    description: Local Kafka broker for development
    tags:
      - name: env:development
  production:
    host: kafka.example.com:9092
    protocol: kafka
    description: Production Kafka cluster
    tags:
      - name: env:production
    security:
      - $ref: '#/components/securitySchemes/saslScram'

channels:
  deliveryStatusUpdate:
    address: 'delivery-status-{subscriptionId}'
    description: |
      Dedicated topic for delivery status updates.

      Each subscription gets a unique topic with format: `delivery-status-{UUID}`

      **Topic Lifecycle**:
      - Created when client subscribes via REST API
      - Receives status updates every 15 minutes
      - Persists until manual cleanup or retention period expires
    messages:
      statusUpdate:
        $ref: '#/components/messages/DeliveryStatusUpdate'
    parameters:
      subscriptionId:
        description: Unique identifier for the subscription (UUID v4)
        examples:
          - '123e4567-e89b-12d3-a456-426614174000'

operations:
  receiveDeliveryStatusUpdate:
    action: receive
    channel:
      $ref: '#/channels/deliveryStatusUpdate'
    summary: Receive delivery status updates
    description: |
      Clients consume from their assigned Kafka topic to receive status updates.

      **Consumer Configuration**:
      - Group ID: Client-specific (allows multiple consumers)
      - Auto-commit: Recommended (true)
      - Offset reset: earliest (to receive all messages)
    messages:
      - $ref: '#/components/messages/DeliveryStatusUpdate'

components:
  messages:
    DeliveryStatusUpdate:
      name: DeliveryStatusUpdate
      title: Delivery Status Update
      summary: Notification of delivery status change
      description: |
        Published when a package's delivery status changes.

        Contains the tracking reference, new status, and timestamp of the status change.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeliveryStatusPayload'
      examples:
        - name: packageDispatched
          summary: Package dispatched
          payload:
            trackingReferenceNumber: "TRK-2025-10-18-001"
            status: "Dispatched"
            timestamp: "2025-10-18T09:00:00Z"
        - name: packageInTransit
          summary: Package in transit
          payload:
            trackingReferenceNumber: "TRK-2025-10-18-001"
            status: "InTransit"
            timestamp: "2025-10-18T12:30:00Z"
        - name: packageDelayed
          summary: Package delayed
          payload:
            trackingReferenceNumber: "TRK-2025-10-18-001"
            status: "Delayed"
            timestamp: "2025-10-18T14:00:00Z"
        - name: packageOutForDelivery
          summary: Package out for delivery
          payload:
            trackingReferenceNumber: "TRK-2025-10-18-001"
            status: "OutForDelivery"
            timestamp: "2025-10-18T16:00:00Z"
        - name: packageDelivered
          summary: Package delivered (final status)
          payload:
            trackingReferenceNumber: "TRK-2025-10-18-001"
            status: "Delivered"
            timestamp: "2025-10-18T17:45:00Z"

  schemas:
    DeliveryStatusPayload:
      type: object
      required:
        - trackingReferenceNumber
        - status
        - timestamp
      properties:
        trackingReferenceNumber:
          type: string
          description: Unique identifier for the package being tracked
          examples:
            - "TRK-2025-10-18-001"
            - "PKG-ABC-12345"
        status:
          type: string
          enum:
            - Dispatched
            - InTransit
            - Delayed
            - OnTime
            - OutForDelivery
            - Delivered
          description: |
            Current delivery status:
            - **Dispatched**: Package has been picked up and is in the logistics network
            - **InTransit**: Package is moving between facilities
            - **Delayed**: Package is behind schedule
            - **OnTime**: Package is on schedule (or recovered from delay)
            - **OutForDelivery**: Package is on the delivery vehicle
            - **Delivered**: Package has been delivered to recipient (final state)
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this status was recorded in the logistics system
          examples:
            - "2025-10-18T14:30:00Z"
            - "2025-10-18T09:15:30.123Z"

  securitySchemes:
    saslScram:
      type: scramSha256
      description: SASL/SCRAM-SHA-256 authentication for production Kafka cluster

AI Assistance Disclosure

This PR was created with assistance from Claude Code (Anthropic). The solution was discussed, implemented, and tested with AI assistance for code generation and documentation. All changes have been reviewed and validated.

🤖 Generated with Claude Code

[Copilot]

Pull Request Overview

This PR enhances the spec-kit toolkit to support AsyncAPI specification generation for event-driven and asynchronous communication patterns. The changes enable the detection and documentation of both synchronous REST/GraphQL APIs and asynchronous messaging patterns within a unified workflow.

Key changes include:

• Added communication patterns taxonomy to requirements gathering in the clarify command
• Enhanced the plan command with AsyncAPI specification generation capabilities
• Updated the plan template to capture async operation details and communication patterns

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
templates/commands/clarify.md	Adds communication patterns section to capture async requirements during clarification
templates/commands/plan.md	Implements AsyncAPI detection, generation logic, and hybrid API support
templates/plan-template.md	Adds fields for communication patterns and async operations documentation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[poelzi]

LGTM