feat: Generate AsyncAPI spec for Event Driven Architecture

templates/commands/clarify.md

@@ -46,6 +46,14 @@ Execution steps:
    - Error/empty/loading states
    - Accessibility or localization notes
 
+   Communication Patterns & Real-time Requirements:
+   - Request/response vs event-driven patterns
+   - Synchronous vs asynchronous operations
+   - Real-time update mechanisms (polling, WebSocket, SSE, webhooks)
+   - Message delivery guarantees (at-least-once, exactly-once)
+   - Bidirectional communication needs
+   - Event notification requirements
+
    Non-Functional Quality Attributes:
    - Performance (latency, throughput targets)
    - Scalability (horizontal/vertical, limits)

templates/commands/plan.md

@@ -41,6 +41,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - For each NEEDS CLARIFICATION → research task
    - For each dependency → best practices task
    - For each integration → patterns task
+   - For async communication patterns → protocol/technology evaluation task
 
 2. **Generate and dispatch research agents**:
 
@@ -49,6 +50,9 @@ You **MUST** consider the user input before proceeding (if not empty).
      Task: "Research {unknown} for {feature context}"
    For each technology choice:
      Task: "Find best practices for {tech} in {domain}"
+   For async communication patterns:
+     Task: "Evaluate {WebSocket vs SSE vs Webhooks vs Message Queues} for {feature requirements}"
+     Task: "Research AsyncAPI specification best practices for {identified pattern}"
    ```
 
 3. **Consolidate findings** in `research.md` using format:
@@ -67,12 +71,40 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Validation rules from requirements
    - State transitions if applicable
 
-2. **Generate API contracts** from functional requirements:
+2. **Detect communication patterns** from functional requirements and feature spec:
+   - Scan for **async indicators**: "real-time", "live", "streaming", "push", "event", "notification", "bidirectional", "chat", "feed", "updates", "subscribe", "publish", "webhook", "message"
+   - Scan for **sync indicators**: "request", "query", "fetch", "get", "create", "update", "delete", "CRUD"
+   - **If async indicators found**: Mark as async or hybrid
+   - **If ambiguous**: Add to Technical Context as "NEEDS CLARIFICATION: Does [feature] require synchronous (request-response) or asynchronous (real-time/event-driven) communication?"
+   - Document decision in Technical Context → Communication Patterns field
+
+3. **Generate API contracts** based on detected communication patterns:
+
+   **For Synchronous Operations** (REST/GraphQL):
    - For each user action → endpoint
    - Use standard REST/GraphQL patterns
-   - Output OpenAPI/GraphQL schema to `/contracts/`
-
-3. **Agent context update**:
+   - Generate OpenAPI specification → `/contracts/openapi.yaml` or `/contracts/rest-api.yaml`
+   - Generate GraphQL schema → `/contracts/graphql.schema` (if GraphQL detected)
+
+   **For Asynchronous Operations** (Events/WebSocket/Messaging):
+   - For each real-time feature → channel/event type
+   - Identify: channel names, message payloads, event types
+   - Define: publish/subscribe patterns, message schemas
+   - Generate AsyncAPI specification → `/contracts/asyncapi.yaml` or `/contracts/events-api.yaml`
+   - Document: WebSocket endpoints, event types, message formats
+
+   **For Hybrid APIs** (Both sync and async):
+   - Generate both OpenAPI and AsyncAPI specifications
+   - Document integration points between sync and async operations
+   - Clarify which operations use which pattern and why
+
+   **Contract File Naming**:
+   - `openapi.yaml` or `rest-api.yaml` - REST API specifications
+   - `asyncapi.yaml` or `events-api.yaml` - Event/WebSocket specifications
+   - `graphql.schema` - GraphQL schema definitions
+   - Multiple contracts allowed in `/contracts/` directory
+
+4. **Agent context update**:
    - Run `{AGENT_SCRIPT}`
    - These scripts detect which AI agent is in use
    - Update the appropriate agent-specific context file

templates/plan-template.md

@@ -17,14 +17,16 @@
   the iteration process.
 -->
 
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
 **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [single/web/mobile - determines source structure]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Project Type**: [single/web/mobile - determines source structure]
+**Communication Patterns**: [e.g., REST-only, REST + WebSocket, Event-driven with Kafka, GraphQL + subscriptions or NEEDS CLARIFICATION]
+**Async Operations**: [if applicable, e.g., WebSocket channels for real-time updates, Event types for notifications, Message queues for background jobs or N/A]
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
 **Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
 
 ## Constitution Check