claude-code-workflow 6.1.4 → 6.2.2

package/.claude/commands/workflow/brainstorm/api-designer.md

@@ -1,585 +1,587 @@
----
-name: api-designer
-description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective
-argument-hint: "optional topic - uses existing framework if available"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
----
-
-## 🔌 **API Designer Analysis Generator**
-
-### Purpose
-**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
-
-### Core Function
-- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
-- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
-- **Update Mechanism**: Create new or update existing analysis.md
-- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
-
-### Analysis Scope
-- **API Architecture**: RESTful/GraphQL design patterns and best practices
-- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection
-- **Data Contracts**: Request/response schemas, validation rules, and data transformation
-- **API Documentation**: OpenAPI/Swagger specifications and developer experience
-
-### Role Boundaries & Responsibilities
-
-#### **What This Role OWNS (API Contract Within Architectural Framework)**
-- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes
-- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types
-- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats
-- **API Versioning Strategy**: Version management, deprecation policies, and migration paths
-- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs
-
-#### **What This Role DOES NOT Own (Defers to Other Roles)**
-- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect**
-- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect**
-- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer**
-
-#### **Handoff Points**
-- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space
-- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view)
-- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides
-
-## ⚙️ **Execution Protocol**
-
-### Phase 1: Session & Framework Detection
-```bash
-# Check active session and framework
-CHECK: find .workflow/active/ -name "WFS-*" -type d
-IF active_session EXISTS:
-    session_id = get_active_session()
-    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
-
-    CHECK: brainstorm_dir/guidance-specification.md
-    IF EXISTS:
-        framework_mode = true
-        load_framework = true
-    ELSE:
-        IF topic_provided:
-            framework_mode = false  # Create analysis without framework
-        ELSE:
-            ERROR: "No framework found and no topic provided"
-```
-
-### Phase 2: Analysis Mode Detection
-```bash
-# Check existing analysis
-CHECK: brainstorm_dir/api-designer/analysis.md
-IF EXISTS:
-    SHOW existing analysis summary
-    ASK: "Analysis exists. Do you want to:"
-    OPTIONS:
-      1. "Update with new insights" → Update existing
-      2. "Replace completely" → Generate new
-      3. "Cancel" → Exit without changes
-ELSE:
-    CREATE new analysis
-```
-
-### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when guidance-specification.md exists):
-```bash
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Generate API designer analysis addressing topic framework
-
-     ## Framework Integration Required
-     **MANDATORY**: Load and address guidance-specification.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
-     **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
-
-     ## Analysis Requirements
-     1. **Load Topic Framework**: Read guidance-specification.md completely
-     2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
-     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
-     4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
-     5. **Structured Response**: Use framework structure for analysis organization
-
-     ## Framework Sections to Address
-     - Core Requirements (from API design perspective)
-     - Technical Considerations (detailed API architecture analysis)
-     - User Experience Factors (developer experience and API usability)
-     - Implementation Challenges (API design risks and solutions)
-     - Success Metrics (API performance metrics and adoption tracking)
-
-     ## Output Structure Required
-     ```markdown
-     # API Designer Analysis: [Topic]
-
-     **Framework Reference**: @../guidance-specification.md
-     **Role Focus**: Backend API Design and Contract Definition
-
-     ## Core Requirements Analysis
-     [Address framework requirements from API design perspective]
-
-     ## Technical Considerations
-     [Detailed API architecture and endpoint design analysis]
-
-     ## Developer Experience Factors
-     [API usability, documentation, and integration ease]
-
-     ## Implementation Challenges
-     [API design risks and mitigation strategies]
-
-     ## Success Metrics
-     [API performance metrics, adoption rates, and developer satisfaction]
-
-     ## API Design-Specific Recommendations
-     [Detailed API design recommendations and best practices]
-     ```",
-     description="Generate API designer framework-based analysis")
-```
-
-### Phase 4: Update Mechanism
-**Analysis Update Process**:
-```bash
-# For existing analysis updates
-IF update_mode = "incremental":
-    Task(subagent_type="conceptual-planning-agent",
-         prompt="Update existing API designer analysis
-
-         ## Current Analysis Context
-         **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
-
-         ## Update Requirements
-         1. **Preserve Structure**: Maintain existing analysis structure
-         2. **Add New Insights**: Integrate new API design insights and recommendations
-         3. **Framework Alignment**: Ensure continued alignment with topic framework
-         4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
-         5. **Maintain References**: Keep @../guidance-specification.md reference
-
-         ## Update Instructions
-         - Read existing analysis completely
-         - Identify areas for enhancement or new insights
-         - Add API design depth while preserving original structure
-         - Update recommendations with new API design patterns and approaches
-         - Maintain framework discussion point addressing",
-         description="Update API designer analysis incrementally")
-```
-
-## Document Structure
-
-### Output Files
-```
-.workflow/active/WFS-[topic]/.brainstorming/
-├── guidance-specification.md          # Input: Framework (if exists)
-└── api-designer/
-    └── analysis.md            # ★ OUTPUT: Framework-based analysis
-```
-
-### Analysis Structure
-**Required Elements**:
-- **Framework Reference**: @../guidance-specification.md (if framework exists)
-- **Role Focus**: Backend API Design and Contract Definition perspective
-- **5 Framework Sections**: Address each framework discussion point
-- **API Design Recommendations**: Endpoint-specific insights and solutions
-
-## ⚡ **Two-Step Execution Flow**
-
-### ⚠️ Session Management - FIRST STEP
-Session detection and selection:
-```bash
-# Check for active sessions
-active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
-if [ multiple_sessions ]; then
-  prompt_user_to_select_session()
-else
-  use_existing_or_create_new()
-fi
-```
-
-### Step 1: Context Gathering Phase
-**API Designer Perspective Questioning**
-
-Before agent assignment, gather comprehensive API design context:
-
-#### 📋 Role-Specific Questions
-1. **API Type & Architecture**
-   - RESTful, GraphQL, or hybrid API approach?
-   - Synchronous vs asynchronous communication patterns?
-   - Real-time requirements (WebSocket, Server-Sent Events)?
-
-2. **Resource Modeling & Endpoints**
-   - What are the core domain resources/entities?
-   - Expected CRUD operations for each resource?
-   - Complex query requirements (filtering, sorting, pagination)?
-
-3. **Data Contracts & Validation**
-   - Request/response data format requirements (JSON, XML, Protocol Buffers)?
-   - Input validation and sanitization requirements?
-   - Data transformation and mapping needs?
-
-4. **API Management & Governance**
-   - API versioning strategy requirements?
-   - Authentication and authorization mechanisms?
-   - Rate limiting and throttling requirements?
-   - API documentation and developer portal needs?
-
-5. **Integration & Compatibility**
-   - Client platforms consuming the API (web, mobile, third-party)?
-   - Backward compatibility requirements?
-   - External API integrations needed?
-
-#### Context Validation
-- **Minimum Response**: Each answer must be ≥50 characters
-- **Re-prompting**: Insufficient detail triggers follow-up questions
-- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md`
-
-### Step 2: Agent Assignment with Flow Control
-**Dedicated Agent Execution**
-
-```bash
-Task(conceptual-planning-agent): "
-[FLOW_CONTROL]
-
-Execute dedicated api-designer conceptual analysis for: {topic}
-
-ASSIGNED_ROLE: api-designer
-OUTPUT_LOCATION: .brainstorming/api-designer/
-USER_CONTEXT: {validated_responses_from_context_gathering}
-
-Flow Control Steps:
-[
-  {
-    \"step\": \"load_role_template\",
-    \"action\": \"Load api-designer planning template\",
-    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\",
-    \"output_to\": \"role_template\"
-  }
-]
-
-Conceptual Analysis Requirements:
-- Apply api-designer perspective to topic analysis
-- Focus on endpoint design, data contracts, and API governance
-- Use loaded role template framework for analysis structure
-- Generate role-specific deliverables in designated output location
-- Address all user context from questioning phase
-
-Deliverables:
-- analysis.md: Main API design analysis
-- api-specification.md: Detailed endpoint specifications
-- data-contracts.md: Request/response schemas and validation rules
-- api-documentation.md: API documentation strategy and templates
-
-Embody api-designer role expertise for comprehensive conceptual planning."
-```
-
-### Progress Tracking
-TodoWrite tracking for two-step process:
-```json
-[
-  {"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
-  {"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"},
-  {"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"},
-  {"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"}
-]
-```
-
-## 📊 **Output Specification**
-
-### Output Location
-```
-.workflow/active/WFS-{topic-slug}/.brainstorming/api-designer/
-├── analysis.md                 # Primary API design analysis
-├── api-specification.md        # Detailed endpoint specifications (OpenAPI/Swagger)
-├── data-contracts.md           # Request/response schemas and validation rules
-├── versioning-strategy.md      # API versioning and backward compatibility plan
-└── developer-guide.md          # API usage documentation and integration examples
-```
-
-### Document Templates
-
-#### analysis.md Structure
-```markdown
-# API Design Analysis: {Topic}
-*Generated: {timestamp}*
-
-## Executive Summary
-[Key API design findings and recommendations overview]
-
-## API Architecture Overview
-### API Type Selection (REST/GraphQL/Hybrid)
-### Communication Patterns
-### Authentication & Authorization Strategy
-
-## Resource Modeling
-### Core Domain Resources
-### Resource Relationships
-### URL Structure and Naming Conventions
-
-## Endpoint Design
-### Resource Endpoints
-- GET /api/v1/resources
-- POST /api/v1/resources
-- GET /api/v1/resources/{id}
-- PUT /api/v1/resources/{id}
-- DELETE /api/v1/resources/{id}
-
-### Query Parameters
-- Filtering: ?filter[field]=value
-- Sorting: ?sort=field,-field2
-- Pagination: ?page=1&limit=20
-
-### HTTP Methods and Status Codes
-- Success responses (2xx)
-- Client errors (4xx)
-- Server errors (5xx)
-
-## Data Contracts
-### Request Schemas
-[JSON Schema or OpenAPI definitions]
-
-### Response Schemas
-[JSON Schema or OpenAPI definitions]
-
-### Validation Rules
-- Required fields
-- Data types and formats
-- Business logic constraints
-
-## API Versioning Strategy
-### Versioning Approach (URL/Header/Accept)
-### Version Lifecycle Management
-### Deprecation Policy
-### Migration Paths
-
-## Security & Governance
-### Authentication Mechanisms
-- OAuth 2.0 / JWT / API Keys
-### Authorization Patterns
-- RBAC / ABAC / Resource-based
-### Rate Limiting & Throttling
-### CORS and Security Headers
-
-## Error Handling
-### Standard Error Response Format
-```json
-{
-  "error": {
-    "code": "ERROR_CODE",
-    "message": "Human-readable error message",
-    "details": [],
-    "trace_id": "uuid"
-  }
-}
-```
-
-### Error Code Taxonomy
-### Validation Error Responses
-
-## API Documentation
-### OpenAPI/Swagger Specification
-### Developer Portal Requirements
-### Code Examples and SDKs
-### Changelog and Migration Guides
-
-## Performance Optimization
-### Response Caching Strategies
-### Compression (gzip, brotli)
-### Field Selection (sparse fieldsets)
-### Bulk Operations and Batch Endpoints
-
-## Monitoring & Observability
-### API Metrics
-- Request count, latency, error rates
-- Endpoint usage analytics
-### Logging Strategy
-### Distributed Tracing
-
-## Developer Experience
-### API Usability Assessment
-### Integration Complexity
-### SDK and Client Library Needs
-### Sandbox and Testing Environments
-```
-
-#### api-specification.md Structure
-```markdown
-# API Specification: {Topic}
-*OpenAPI 3.0 Specification*
-
-## API Information
-- **Title**: {API Name}
-- **Version**: 1.0.0
-- **Base URL**: https://api.example.com/v1
-- **Contact**: api-team@example.com
-
-## Endpoints
-
-### Users API
-
-#### GET /users
-**Description**: Retrieve a list of users
-
-**Parameters**:
-- `page` (query, integer): Page number (default: 1)
-- `limit` (query, integer): Items per page (default: 20, max: 100)
-- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at")
-- `filter[status]` (query, string): Filter by user status
-
-**Response 200**:
-```json
-{
-  "data": [
-    {
-      "id": "uuid",
-      "username": "string",
-      "email": "string",
-      "created_at": "2025-10-15T00:00:00Z"
-    }
-  ],
-  "meta": {
-    "page": 1,
-    "limit": 20,
-    "total": 100
-  },
-  "links": {
-    "self": "/users?page=1",
-    "next": "/users?page=2",
-    "prev": null
-  }
-}
-```
-
-#### POST /users
-**Description**: Create a new user
-
-**Request Body**:
-```json
-{
-  "username": "string (required, 3-50 chars)",
-  "email": "string (required, valid email)",
-  "password": "string (required, min 8 chars)",
-  "profile": {
-    "first_name": "string (optional)",
-    "last_name": "string (optional)"
-  }
-}
-```
-
-**Response 201**:
-```json
-{
-  "data": {
-    "id": "uuid",
-    "username": "string",
-    "email": "string",
-    "created_at": "2025-10-15T00:00:00Z"
-  }
-}
-```
-
-**Response 400** (Validation Error):
-```json
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Request validation failed",
-    "details": [
-      {
-        "field": "email",
-        "message": "Invalid email format"
-      }
-    ]
-  }
-}
-```
-
-[Continue for all endpoints...]
-
-## Authentication
-
-### OAuth 2.0 Flow
-1. Client requests authorization
-2. User grants permission
-3. Client receives access token
-4. Client uses token in requests
-
-**Header Format**:
-```
-Authorization: Bearer {access_token}
-```
-
-## Rate Limiting
-
-**Headers**:
-- `X-RateLimit-Limit`: 1000
-- `X-RateLimit-Remaining`: 999
-- `X-RateLimit-Reset`: 1634270400
-
-**Response 429** (Too Many Requests):
-```json
-{
-  "error": {
-    "code": "RATE_LIMIT_EXCEEDED",
-    "message": "API rate limit exceeded",
-    "retry_after": 3600
-  }
-}
-```
-```
-
-## 🔄 **Session Integration**
-
-### Status Synchronization
-Upon completion, update `workflow-session.json`:
-```json
-{
-  "phases": {
-    "BRAINSTORM": {
-      "api_designer": {
-        "status": "completed",
-        "completed_at": "timestamp",
-        "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/api-designer/",
-        "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
-      }
-    }
-  }
-}
-```
-
-### Cross-Role Collaboration
-API designer perspective provides:
-- **API Contract Specifications** → Frontend Developer
-- **Data Schema Requirements** → Data Architect
-- **Security Requirements** → Security Expert
-- **Integration Endpoints** → System Architect
-- **Performance Constraints** → DevOps Engineer
-
-## ✅ **Quality Assurance**
-
-### Required Analysis Elements
-- [ ] Complete endpoint inventory with HTTP methods and paths
-- [ ] Detailed request/response schemas with validation rules
-- [ ] Clear versioning strategy and backward compatibility plan
-- [ ] Comprehensive error handling and status code usage
-- [ ] API documentation strategy (OpenAPI/Swagger)
-
-### API Design Principles
-- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints
-- [ ] **Simplicity**: Intuitive resource modeling and URL structures
-- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection
-- [ ] **Security**: Proper authentication, authorization, and input validation
-- [ ] **Performance**: Caching strategies, compression, and efficient data structures
-
-### Developer Experience Validation
-- [ ] API is self-documenting with clear endpoint descriptions
-- [ ] Error messages are actionable and helpful for debugging
-- [ ] Response formats are consistent and predictable
-- [ ] Code examples and integration guides are provided
-- [ ] Sandbox environment available for testing
-
-### Technical Completeness
-- [ ] **Resource Modeling**: All domain entities mapped to API resources
-- [ ] **CRUD Coverage**: Complete create, read, update, delete operations
-- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality
-- [ ] **Versioning**: Clear version management and migration paths
-- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined
-
-### Integration Readiness
-- [ ] **Client Compatibility**: API works with all target client platforms
-- [ ] **External Integration**: Third-party API dependencies identified
-- [ ] **Backward Compatibility**: Changes don't break existing clients
-- [ ] **Migration Path**: Clear upgrade paths for API consumers
-- [ ] **SDK Support**: Client libraries and code generation considered
+---
+name: api-designer
+description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective
+argument-hint: "optional topic - uses existing framework if available"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
+---
+
+## 🔌 **API Designer Analysis Generator**
+
+### Purpose
+**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
+
+### Core Function
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
+- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
+- **Update Mechanism**: Create new or update existing analysis.md
+- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
+
+### Analysis Scope
+- **API Architecture**: RESTful/GraphQL design patterns and best practices
+- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection
+- **Data Contracts**: Request/response schemas, validation rules, and data transformation
+- **API Documentation**: OpenAPI/Swagger specifications and developer experience
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (API Contract Within Architectural Framework)**
+- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes
+- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types
+- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats
+- **API Versioning Strategy**: Version management, deprecation policies, and migration paths
+- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect**
+- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect**
+- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space
+- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view)
+- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides
+
+## ⚙️ **Execution Protocol**
+
+### Phase 1: Session & Framework Detection
+```bash
+# Check active session and framework
+CHECK: find .workflow/active/ -name "WFS-*" -type d
+IF active_session EXISTS:
+    session_id = get_active_session()
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
+
+    CHECK: brainstorm_dir/guidance-specification.md
+    IF EXISTS:
+        framework_mode = true
+        load_framework = true
+    ELSE:
+        IF topic_provided:
+            framework_mode = false  # Create analysis without framework
+        ELSE:
+            ERROR: "No framework found and no topic provided"
+```
+
+### Phase 2: Analysis Mode Detection
+```bash
+# Check existing analysis
+CHECK: brainstorm_dir/api-designer/analysis.md
+IF EXISTS:
+    SHOW existing analysis summary
+    ASK: "Analysis exists. Do you want to:"
+    OPTIONS:
+      1. "Update with new insights" → Update existing
+      2. "Replace completely" → Generate new
+      3. "Cancel" → Exit without changes
+ELSE:
+    CREATE new analysis
+```
+
+### Phase 3: Agent Task Generation
+**Framework-Based Analysis** (when guidance-specification.md exists):
+```bash
+Task(subagent_type="conceptual-planning-agent",
+     run_in_background=false,
+     prompt="Generate API designer analysis addressing topic framework
+
+     ## Framework Integration Required
+     **MANDATORY**: Load and address guidance-specification.md discussion points
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
+     **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
+
+     ## Analysis Requirements
+     1. **Load Topic Framework**: Read guidance-specification.md completely
+     2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
+     4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
+     5. **Structured Response**: Use framework structure for analysis organization
+
+     ## Framework Sections to Address
+     - Core Requirements (from API design perspective)
+     - Technical Considerations (detailed API architecture analysis)
+     - User Experience Factors (developer experience and API usability)
+     - Implementation Challenges (API design risks and solutions)
+     - Success Metrics (API performance metrics and adoption tracking)
+
+     ## Output Structure Required
+     ```markdown
+     # API Designer Analysis: [Topic]
+
+     **Framework Reference**: @../guidance-specification.md
+     **Role Focus**: Backend API Design and Contract Definition
+
+     ## Core Requirements Analysis
+     [Address framework requirements from API design perspective]
+
+     ## Technical Considerations
+     [Detailed API architecture and endpoint design analysis]
+
+     ## Developer Experience Factors
+     [API usability, documentation, and integration ease]
+
+     ## Implementation Challenges
+     [API design risks and mitigation strategies]
+
+     ## Success Metrics
+     [API performance metrics, adoption rates, and developer satisfaction]
+
+     ## API Design-Specific Recommendations
+     [Detailed API design recommendations and best practices]
+     ```",
+     description="Generate API designer framework-based analysis")
+```
+
+### Phase 4: Update Mechanism
+**Analysis Update Process**:
+```bash
+# For existing analysis updates
+IF update_mode = "incremental":
+    Task(subagent_type="conceptual-planning-agent",
+         run_in_background=false,
+         prompt="Update existing API designer analysis
+
+         ## Current Analysis Context
+         **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
+
+         ## Update Requirements
+         1. **Preserve Structure**: Maintain existing analysis structure
+         2. **Add New Insights**: Integrate new API design insights and recommendations
+         3. **Framework Alignment**: Ensure continued alignment with topic framework
+         4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
+         5. **Maintain References**: Keep @../guidance-specification.md reference
+
+         ## Update Instructions
+         - Read existing analysis completely
+         - Identify areas for enhancement or new insights
+         - Add API design depth while preserving original structure
+         - Update recommendations with new API design patterns and approaches
+         - Maintain framework discussion point addressing",
+         description="Update API designer analysis incrementally")
+```
+
+## Document Structure
+
+### Output Files
+```
+.workflow/active/WFS-[topic]/.brainstorming/
+├── guidance-specification.md          # Input: Framework (if exists)
+└── api-designer/
+    └── analysis.md            # ★ OUTPUT: Framework-based analysis
+```
+
+### Analysis Structure
+**Required Elements**:
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
+- **Role Focus**: Backend API Design and Contract Definition perspective
+- **5 Framework Sections**: Address each framework discussion point
+- **API Design Recommendations**: Endpoint-specific insights and solutions
+
+## ⚡ **Two-Step Execution Flow**
+
+### ⚠️ Session Management - FIRST STEP
+Session detection and selection:
+```bash
+# Check for active sessions
+active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
+if [ multiple_sessions ]; then
+  prompt_user_to_select_session()
+else
+  use_existing_or_create_new()
+fi
+```
+
+### Step 1: Context Gathering Phase
+**API Designer Perspective Questioning**
+
+Before agent assignment, gather comprehensive API design context:
+
+#### 📋 Role-Specific Questions
+1. **API Type & Architecture**
+   - RESTful, GraphQL, or hybrid API approach?
+   - Synchronous vs asynchronous communication patterns?
+   - Real-time requirements (WebSocket, Server-Sent Events)?
+
+2. **Resource Modeling & Endpoints**
+   - What are the core domain resources/entities?
+   - Expected CRUD operations for each resource?
+   - Complex query requirements (filtering, sorting, pagination)?
+
+3. **Data Contracts & Validation**
+   - Request/response data format requirements (JSON, XML, Protocol Buffers)?
+   - Input validation and sanitization requirements?
+   - Data transformation and mapping needs?
+
+4. **API Management & Governance**
+   - API versioning strategy requirements?
+   - Authentication and authorization mechanisms?
+   - Rate limiting and throttling requirements?
+   - API documentation and developer portal needs?
+
+5. **Integration & Compatibility**
+   - Client platforms consuming the API (web, mobile, third-party)?
+   - Backward compatibility requirements?
+   - External API integrations needed?
+
+#### Context Validation
+- **Minimum Response**: Each answer must be ≥50 characters
+- **Re-prompting**: Insufficient detail triggers follow-up questions
+- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md`
+
+### Step 2: Agent Assignment with Flow Control
+**Dedicated Agent Execution**
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute dedicated api-designer conceptual analysis for: {topic}
+
+ASSIGNED_ROLE: api-designer
+OUTPUT_LOCATION: .brainstorming/api-designer/
+USER_CONTEXT: {validated_responses_from_context_gathering}
+
+Flow Control Steps:
+[
+  {
+    \"step\": \"load_role_template\",
+    \"action\": \"Load api-designer planning template\",
+    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\",
+    \"output_to\": \"role_template\"
+  }
+]
+
+Conceptual Analysis Requirements:
+- Apply api-designer perspective to topic analysis
+- Focus on endpoint design, data contracts, and API governance
+- Use loaded role template framework for analysis structure
+- Generate role-specific deliverables in designated output location
+- Address all user context from questioning phase
+
+Deliverables:
+- analysis.md: Main API design analysis
+- api-specification.md: Detailed endpoint specifications
+- data-contracts.md: Request/response schemas and validation rules
+- api-documentation.md: API documentation strategy and templates
+
+Embody api-designer role expertise for comprehensive conceptual planning."
+```
+
+### Progress Tracking
+TodoWrite tracking for two-step process:
+```json
+[
+  {"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
+  {"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"},
+  {"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"},
+  {"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"}
+]
+```
+
+## 📊 **Output Specification**
+
+### Output Location
+```
+.workflow/active/WFS-{topic-slug}/.brainstorming/api-designer/
+├── analysis.md                 # Primary API design analysis
+├── api-specification.md        # Detailed endpoint specifications (OpenAPI/Swagger)
+├── data-contracts.md           # Request/response schemas and validation rules
+├── versioning-strategy.md      # API versioning and backward compatibility plan
+└── developer-guide.md          # API usage documentation and integration examples
+```
+
+### Document Templates
+
+#### analysis.md Structure
+```markdown
+# API Design Analysis: {Topic}
+*Generated: {timestamp}*
+
+## Executive Summary
+[Key API design findings and recommendations overview]
+
+## API Architecture Overview
+### API Type Selection (REST/GraphQL/Hybrid)
+### Communication Patterns
+### Authentication & Authorization Strategy
+
+## Resource Modeling
+### Core Domain Resources
+### Resource Relationships
+### URL Structure and Naming Conventions
+
+## Endpoint Design
+### Resource Endpoints
+- GET /api/v1/resources
+- POST /api/v1/resources
+- GET /api/v1/resources/{id}
+- PUT /api/v1/resources/{id}
+- DELETE /api/v1/resources/{id}
+
+### Query Parameters
+- Filtering: ?filter[field]=value
+- Sorting: ?sort=field,-field2
+- Pagination: ?page=1&limit=20
+
+### HTTP Methods and Status Codes
+- Success responses (2xx)
+- Client errors (4xx)
+- Server errors (5xx)
+
+## Data Contracts
+### Request Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Response Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Validation Rules
+- Required fields
+- Data types and formats
+- Business logic constraints
+
+## API Versioning Strategy
+### Versioning Approach (URL/Header/Accept)
+### Version Lifecycle Management
+### Deprecation Policy
+### Migration Paths
+
+## Security & Governance
+### Authentication Mechanisms
+- OAuth 2.0 / JWT / API Keys
+### Authorization Patterns
+- RBAC / ABAC / Resource-based
+### Rate Limiting & Throttling
+### CORS and Security Headers
+
+## Error Handling
+### Standard Error Response Format
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "details": [],
+    "trace_id": "uuid"
+  }
+}
+```
+
+### Error Code Taxonomy
+### Validation Error Responses
+
+## API Documentation
+### OpenAPI/Swagger Specification
+### Developer Portal Requirements
+### Code Examples and SDKs
+### Changelog and Migration Guides
+
+## Performance Optimization
+### Response Caching Strategies
+### Compression (gzip, brotli)
+### Field Selection (sparse fieldsets)
+### Bulk Operations and Batch Endpoints
+
+## Monitoring & Observability
+### API Metrics
+- Request count, latency, error rates
+- Endpoint usage analytics
+### Logging Strategy
+### Distributed Tracing
+
+## Developer Experience
+### API Usability Assessment
+### Integration Complexity
+### SDK and Client Library Needs
+### Sandbox and Testing Environments
+```
+
+#### api-specification.md Structure
+```markdown
+# API Specification: {Topic}
+*OpenAPI 3.0 Specification*
+
+## API Information
+- **Title**: {API Name}
+- **Version**: 1.0.0
+- **Base URL**: https://api.example.com/v1
+- **Contact**: api-team@example.com
+
+## Endpoints
+
+### Users API
+
+#### GET /users
+**Description**: Retrieve a list of users
+
+**Parameters**:
+- `page` (query, integer): Page number (default: 1)
+- `limit` (query, integer): Items per page (default: 20, max: 100)
+- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at")
+- `filter[status]` (query, string): Filter by user status
+
+**Response 200**:
+```json
+{
+  "data": [
+    {
+      "id": "uuid",
+      "username": "string",
+      "email": "string",
+      "created_at": "2025-10-15T00:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "prev": null
+  }
+}
+```
+
+#### POST /users
+**Description**: Create a new user
+
+**Request Body**:
+```json
+{
+  "username": "string (required, 3-50 chars)",
+  "email": "string (required, valid email)",
+  "password": "string (required, min 8 chars)",
+  "profile": {
+    "first_name": "string (optional)",
+    "last_name": "string (optional)"
+  }
+}
+```
+
+**Response 201**:
+```json
+{
+  "data": {
+    "id": "uuid",
+    "username": "string",
+    "email": "string",
+    "created_at": "2025-10-15T00:00:00Z"
+  }
+}
+```
+
+**Response 400** (Validation Error):
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+[Continue for all endpoints...]
+
+## Authentication
+
+### OAuth 2.0 Flow
+1. Client requests authorization
+2. User grants permission
+3. Client receives access token
+4. Client uses token in requests
+
+**Header Format**:
+```
+Authorization: Bearer {access_token}
+```
+
+## Rate Limiting
+
+**Headers**:
+- `X-RateLimit-Limit`: 1000
+- `X-RateLimit-Remaining`: 999
+- `X-RateLimit-Reset`: 1634270400
+
+**Response 429** (Too Many Requests):
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "API rate limit exceeded",
+    "retry_after": 3600
+  }
+}
+```
+```
+
+## 🔄 **Session Integration**
+
+### Status Synchronization
+Upon completion, update `workflow-session.json`:
+```json
+{
+  "phases": {
+    "BRAINSTORM": {
+      "api_designer": {
+        "status": "completed",
+        "completed_at": "timestamp",
+        "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/api-designer/",
+        "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
+      }
+    }
+  }
+}
+```
+
+### Cross-Role Collaboration
+API designer perspective provides:
+- **API Contract Specifications** → Frontend Developer
+- **Data Schema Requirements** → Data Architect
+- **Security Requirements** → Security Expert
+- **Integration Endpoints** → System Architect
+- **Performance Constraints** → DevOps Engineer
+
+## ✅ **Quality Assurance**
+
+### Required Analysis Elements
+- [ ] Complete endpoint inventory with HTTP methods and paths
+- [ ] Detailed request/response schemas with validation rules
+- [ ] Clear versioning strategy and backward compatibility plan
+- [ ] Comprehensive error handling and status code usage
+- [ ] API documentation strategy (OpenAPI/Swagger)
+
+### API Design Principles
+- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints
+- [ ] **Simplicity**: Intuitive resource modeling and URL structures
+- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection
+- [ ] **Security**: Proper authentication, authorization, and input validation
+- [ ] **Performance**: Caching strategies, compression, and efficient data structures
+
+### Developer Experience Validation
+- [ ] API is self-documenting with clear endpoint descriptions
+- [ ] Error messages are actionable and helpful for debugging
+- [ ] Response formats are consistent and predictable
+- [ ] Code examples and integration guides are provided
+- [ ] Sandbox environment available for testing
+
+### Technical Completeness
+- [ ] **Resource Modeling**: All domain entities mapped to API resources
+- [ ] **CRUD Coverage**: Complete create, read, update, delete operations
+- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality
+- [ ] **Versioning**: Clear version management and migration paths
+- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined
+
+### Integration Readiness
+- [ ] **Client Compatibility**: API works with all target client platforms
+- [ ] **External Integration**: Third-party API dependencies identified
+- [ ] **Backward Compatibility**: Changes don't break existing clients
+- [ ] **Migration Path**: Clear upgrade paths for API consumers
+- [ ] **SDK Support**: Client libraries and code generation considered