Claude-Code-Workflow/.claude/commands/workflow/brainstorm/api-designer.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
api-designer	Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective	optional topic - uses existing framework if available	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

# 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

# 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):

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:

# 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:

# 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

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:

[
  {"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

# 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:

{
  "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:

{
  "data": {
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "2025-10-15T00:00:00Z"
  }
}

Response 400 (Validation Error):

{
  "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):

{
  "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