plan

SpecForge Planning Agent

Analyze feature requirements and propose coordinated changes to both OpenAPI spec and database schema.

Overview

SpecForge's core innovation is the dual-spec approach: both OpenAPI and database schemas drive development. This planning command helps you:

1. Analyze feature requirements
2. Propose OpenAPI spec changes
3. Propose database schema changes
4. Generate implementation plan
5. Estimate complexity and agent requirements

Planning Process

Step 1: Gather Feature Requirements

Ask the user what feature they want to implement. Use AskUserQuestion to collect:

1. Feature description: What functionality should this add?
2. User-facing behavior: What does the user see/experience?
3. Data requirements: What data needs to be stored/retrieved?
4. Integration points: Does this interact with existing features?

Step 2: Analyze Current State

Read and analyze existing specifications:

# Read current OpenAPI spec
cat spec/openapi.yaml

# Read existing database migrations
ls -la migrations/
cat migrations/*.sql

# Check existing backend code structure
find backend -type f -name "*.rs" -o -name "*.ts" -o -name "*.py" -o -name "*.go" | head -20

Understand:

• Current API endpoints
• Existing database schema
• Current data models
• Existing patterns and conventions

Step 3: Propose OpenAPI Spec Changes

Based on the feature requirements, draft new OpenAPI endpoints with:

Detailed Endpoint Specifications

paths:
  /api/users/{id}/orders:
    get:
      summary: Get user's orders
      description: |
        Retrieve all orders for a specific user.

        Business Logic:
        1. Authenticate the requesting user
        2. Verify user has permission to view these orders
        3. Fetch user from database by ID
        4. Query orders with user_id foreign key
        5. Include order items with product details via JOIN
        6. Calculate order totals (sum of item prices)
        7. Sort by created_at DESC (most recent first)
        8. Return paginated results

        Edge Cases:
        - User not found: Return 404
        - No orders: Return empty array with 200
        - Permission denied: Return 403
        - Invalid pagination params: Return 400

        Performance Considerations:
        - Use database indexes on user_id and created_at
        - Limit JOIN depth to avoid N+1 queries
        - Default page size: 20, max: 100
        - Consider caching for frequently accessed users

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: User ID
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of orders per page

      responses:
        "200":
          description: User's orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Order"
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      totalPages:
                        type: integer
              examples:
                success:
                  value:
                    data:
                      - id: 1
                        userId: 123
                        total: 4999
                        status: completed
                        createdAt: "2025-01-15T10:30:00Z"
                        items:
                          - productId: 456
                            quantity: 2
                            price: 2499
                    pagination:
                      page: 1
                      limit: 20
                      total: 45
                      totalPages: 3
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - userId
        - total
        - status
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          description: Unique order identifier
        userId:
          type: integer
          format: int64
          description: ID of user who placed the order
        total:
          type: integer
          description: Total price in cents
          example: 4999
        status:
          type: string
          enum: [pending, completed, cancelled]
          description: Current order status
        createdAt:
          type: string
          format: date-time
          description: When order was created
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderItem"