diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 9a62dfa74..8519ea1cc 100644 --- a/templates/commands/clarify.md +++ b/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) diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 7dfe63a2f..6dac1dd3f 100644 --- a/templates/commands/plan.md +++ b/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 diff --git a/templates/plan-template.md b/templates/plan-template.md index 6a8bfc6c8..3a332cc5c 100644 --- a/templates/plan-template.md +++ b/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