Initial commit

commands/api-docs.md

@@ -0,0 +1,132 @@
+---
+description: Analyze API documentation for endpoints, data types, and request/response formats
+allowed-tools: Task, Read, Bash
+---
+
+## Mission
+
+Provide comprehensive API documentation analysis for the Tenant Management Portal API by leveraging the api-analyst agent. Answer questions about endpoints, data structures, authentication, and usage patterns.
+
+## User Query
+
+{{ARGS}}
+
+## Workflow
+
+### STEP 1: Parse User Query
+
+Analyze the user's question to determine what they need:
+
+- **Endpoint information**: Specific API routes, methods, parameters
+- **Data type clarification**: TypeScript interfaces, field types, validation rules
+- **Authentication/Authorization**: How to authenticate requests, required headers
+- **Error handling**: Expected error responses, status codes
+- **Integration guidance**: How to integrate with the API, example requests
+- **General overview**: High-level API structure and available resources
+
+### STEP 2: Launch API Documentation Analyzer
+
+Use the Task tool with `subagent_type: "frontend:api-analyst"` and provide a detailed prompt:
+
+```
+The user is asking: {{ARGS}}
+
+Please analyze the Tenant Management Portal API documentation to answer this query.
+
+Provide:
+1. **Relevant Endpoints**: List all endpoints related to the query with HTTP methods
+2. **Request Format**: Show request body/query parameters with types
+3. **Response Format**: Show response structure with data types
+4. **TypeScript Types**: Generate TypeScript interfaces for request/response
+5. **Authentication**: Specify any auth requirements
+6. **Examples**: Include example requests/responses
+7. **Error Handling**: List possible error responses
+8. **Usage Notes**: Any important considerations or best practices
+
+Context:
+- This is for a React + TypeScript frontend application
+- We use TanStack Query for data fetching
+- We need type-safe API integration
+- Current mock API will be replaced with real API calls
+```
+
+### STEP 3: Format and Present Results
+
+After the agent returns its analysis:
+
+1. **Structure the output clearly** with section headers
+2. **Include code examples** in TypeScript
+3. **Highlight important notes** about authentication, validation, etc.
+4. **Provide actionable guidance** for implementation
+
+## Expected Output Format
+
+The agent should provide documentation analysis structured like:
+
+```markdown
+# API Documentation: [Topic]
+
+## Endpoints
+
+### [HTTP METHOD] /api/[resource]
+- **Purpose**: [Description]
+- **Authentication**: [Required/Optional + method]
+- **Request Parameters**: [Details]
+- **Response**: [Structure]
+
+## TypeScript Types
+
+\`\`\`typescript
+interface [Resource] {
+  id: string;
+  // ... fields with types
+}
+
+interface [ResourceRequest] {
+  // ... request body structure
+}
+\`\`\`
+
+## Example Usage
+
+\`\`\`typescript
+// Example request with TanStack Query
+const { data } = useQuery({
+  queryKey: ['resource', params],
+  queryFn: () => api.getResource(params)
+})
+\`\`\`
+
+## Error Responses
+
+- **400 Bad Request**: [When this occurs]
+- **401 Unauthorized**: [When this occurs]
+- **404 Not Found**: [When this occurs]
+
+## Implementation Notes
+
+- [Important considerations]
+- [Best practices]
+```
+
+## Special Cases
+
+### Vague Query
+If the query is general (e.g., "show me the API"), provide an overview of all major resource groups and suggest specific queries.
+
+### Multiple Endpoints
+If multiple endpoints are relevant, prioritize by:
+1. Exact match to query
+2. Most commonly used
+3. Related operations (CRUD set)
+
+### Missing Documentation
+If documentation is incomplete or unclear, note this explicitly and provide best-effort analysis based on available information.
+
+## Notes
+
+- Always use the latest API documentation from the OpenAPI spec
+- Prefer TypeScript types over generic JSON examples
+- Include practical usage examples with TanStack Query when relevant
+- Highlight any breaking changes or deprecations
+- Consider the frontend context (React + TypeScript) when providing guidance