# Implementation Task Template Schema
# Used by the Architect agent to create implementation tasks
# Tasks are generated from design_document.yml with full context

# ============================================================================
# TASK DEFINITION
# ============================================================================
task:
  # Required fields
  id: task_<type>_<entity>        # e.g., task_create_model_user, task_create_api_users
  type: create | update | delete | refactor | test | review
  title: string                   # Human-readable title
  agent: frontend | backend       # Which agent implements this
  entity_id: string               # Primary entity ID from design_document
  entity_ids: [string]            # All entity IDs this task covers (for multi-entity tasks)
  status: pending | in_progress | review | approved | completed | blocked

  # Execution layer (from dependency_graph)
  layer: integer                  # Which layer this task belongs to (1, 2, 3...)
  parallel_group: string          # Group ID for parallel execution

  # Optional fields
  description: string             # Detailed implementation notes
  file_paths: [string]            # Files to create/modify
  dependencies: [string]          # Task IDs that must complete first
  acceptance_criteria: [string]   # Checklist for completion
  priority: low | medium | high   # Task priority
  complexity: low | medium | high # Estimated complexity

  # Tracking (set by system)
  created_at: datetime
  assigned_at: datetime
  completed_at: datetime
  reviewed_by: string
  review_notes: string

# ============================================================================
# CONTEXT SECTION (Passed to subagent)
# ============================================================================
# This is the critical section that provides full context to subagents
# Generated from design_document.yml during task creation

context:
  # Source reference
  design_version: string          # design_document revision
  workflow_version: string        # Workflow version (v001, etc.)
  context_snapshot_path: string   # Path to full context file

  # TARGET: What this task implements
  target:
    entity_id: string             # model_user, api_create_user, etc.
    entity_type: model | api | page | component
    definition: object            # Full definition from design_document

    # For models
    model:
      name: string
      table_name: string
      fields: [field_definition]
      relations: [relation_definition]
      validations: [validation_rule]
      indexes: [index_definition]

    # For APIs
    api:
      method: string
      path: string
      summary: string
      path_params: [param_definition]
      query_params: [param_definition]
      request_body: object
      responses: [response_definition]
      auth: object

    # For pages
    page:
      path: string
      layout: string
      data_needs: [data_requirement]
      components: [string]
      seo: object
      auth: object

    # For components
    component:
      name: string
      props: [prop_definition]
      events: [event_definition]
      uses_apis: [string]
      uses_components: [string]
      variants: [string]

  # DEPENDENCIES: What this task needs
  dependencies:
    # Models this task interacts with
    models:
      - id: string                # model_user
        definition:
          name: string
          fields: [field_definition]
          relations: [relation_definition]

    # APIs this task needs
    apis:
      - id: string                # api_get_user
        definition:
          method: string
          path: string
          request_body: object
          responses: [object]

    # Components this task uses
    components:
      - id: string                # component_button
        definition:
          props: [prop_definition]
          events: [event_definition]

  # CONTRACTS: Input/Output specifications
  contracts:
    # What this task receives from previous tasks
    inputs:
      - from_task: string         # task_create_model_user
        provides: string          # model_user
        type: model | api | component | file

    # What this task provides to later tasks
    outputs:
      - entity_id: string         # api_create_user
        type: model | api | component | file
        consumers: [string]       # [page_user_create, component_user_form]

  # FILES: File operations
  files:
    # Files to create
    create: [string]

    # Files to modify
    modify: [string]

    # Files to read for patterns/context
    reference:
      - path: string
        purpose: string           # "Similar component pattern", "API route pattern"

  # VALIDATION: How to verify completion
  validation:
    # Required checks
    checks:
      - type: file_exists | lint | typecheck | test | build
        target: string            # File or test pattern
        required: boolean

    # Acceptance criteria (human-readable)
    criteria:
      - criterion: string
        verification: string      # How to verify this

  # HINTS: Implementation guidance
  hints:
    # Patterns to follow
    patterns:
      - pattern: string           # "Use existing API route pattern"
        reference: string         # "app/api/health/route.ts"

    # Things to avoid
    avoid:
      - issue: string
        reason: string

    # Code examples
    examples:
      - description: string
        file: string

# ============================================================================
# TASK GENERATION RULES
# ============================================================================
generation_rules:
  from_model:
    task_id: "task_create_model_{model_name}"
    type: create
    agent: backend
    file_paths:
      - "prisma/schema.prisma"    # Add model to schema
      - "app/models/{model_name}.ts"  # TypeScript types
    acceptance_criteria:
      - "Model defined in Prisma schema"
      - "TypeScript types exported"
      - "Relations properly configured"
      - "Migrations generated"

  from_api:
    task_id: "task_create_api_{endpoint_name}"
    type: create
    agent: backend
    file_paths:
      - "app/api/{path}/route.ts"
    acceptance_criteria:
      - "Endpoint responds to {method} requests"
      - "Request validation implemented"
      - "Response matches contract"
      - "Auth requirements enforced"
      - "Error handling complete"

  from_page:
    task_id: "task_create_page_{page_name}"
    type: create
    agent: frontend
    file_paths:
      - "app/{path}/page.tsx"
    acceptance_criteria:
      - "Page renders at {path}"
      - "Data fetching implemented"
      - "Components integrated"
      - "Auth protection active"
      - "SEO metadata set"

  from_component:
    task_id: "task_create_component_{component_name}"
    type: create
    agent: frontend
    file_paths:
      - "app/components/{ComponentName}.tsx"
    acceptance_criteria:
      - "Component renders correctly"
      - "Props typed and documented"
      - "Events emitted properly"
      - "Variants implemented"
      - "Accessible (a11y)"

# ============================================================================
# VALID STATUS TRANSITIONS
# ============================================================================
status_transitions:
  pending:
    - in_progress               # Start work
    - blocked                   # Dependencies not met
  in_progress:
    - review                    # Ready for review
    - blocked                   # Hit blocker
  review:
    - approved                  # Review passed
    - in_progress               # Changes requested
  approved:
    - completed                 # Final completion
  blocked:
    - pending                   # Blocker resolved
    - in_progress               # Resume after unblock

# ============================================================================
# EXAMPLE: Complete Task with Context
# ============================================================================
example_task:
  id: task_create_api_create_user
  type: create
  title: "Create User API Endpoint"
  agent: backend
  entity_id: api_create_user
  entity_ids: [api_create_user]
  status: pending
  layer: 2
  parallel_group: "layer_2_apis"
  description: "Implement POST /api/users endpoint for user registration"
  file_paths:
    - app/api/users/route.ts
  dependencies:
    - task_create_model_user
  acceptance_criteria:
    - "POST /api/users returns 201 on success"
    - "Validates email format"
    - "Returns 409 if email exists"
    - "Hashes password before storage"
    - "Returns user object without password"
  priority: high
  complexity: medium

  context:
    design_version: "rev_3"
    workflow_version: "v001"
    context_snapshot_path: ".workflow/versions/v001/contexts/api_create_user.yml"

    target:
      entity_id: api_create_user
      entity_type: api
      api:
        method: POST
        path: /api/users
        summary: "Create a new user"
        request_body:
          type: object
          properties:
            email: { type: string, required: true, validation: email }
            name: { type: string, required: true, validation: "min:1,max:100" }
            password: { type: string, required: true, validation: "min:8" }
        responses:
          - status: 201
            schema: { id: uuid, email: string, name: string, created_at: datetime }
          - status: 400
            schema: { error: string, details: array }
          - status: 409
            schema: { error: string }
        auth:
          required: false

    dependencies:
      models:
        - id: model_user
          definition:
            name: User
            table_name: users
            fields:
              - { name: id, type: uuid, constraints: [primary_key] }
              - { name: email, type: string, constraints: [unique, not_null] }
              - { name: name, type: string, constraints: [not_null] }
              - { name: password_hash, type: string, constraints: [not_null] }
              - { name: created_at, type: datetime, constraints: [not_null] }

    contracts:
      inputs:
        - from_task: task_create_model_user
          provides: model_user
          type: model
      outputs:
        - entity_id: api_create_user
          type: api
          consumers: [page_signup, component_signup_form]

    files:
      create:
        - app/api/users/route.ts
      reference:
        - path: app/api/health/route.ts
          purpose: "API route pattern"
        - path: app/lib/db.ts
          purpose: "Database connection"
        - path: app/lib/auth.ts
          purpose: "Password hashing"

    validation:
      checks:
        - { type: typecheck, target: "app/api/users/route.ts", required: true }
        - { type: lint, target: "app/api/users/route.ts", required: true }
        - { type: test, target: "app/api/users/*.test.ts", required: false }
      criteria:
        - criterion: "Returns 201 with user object on success"
          verification: "curl -X POST /api/users with valid data"
        - criterion: "Returns 409 if email exists"
          verification: "curl -X POST /api/users with duplicate email"

    hints:
      patterns:
        - pattern: "Use NextResponse for responses"
          reference: "app/api/health/route.ts"
        - pattern: "Use Prisma for database operations"
          reference: "app/lib/db.ts"
      avoid:
        - issue: "Don't store plain text passwords"
          reason: "Security vulnerability - always hash with bcrypt"
        - issue: "Don't return password_hash in response"
          reason: "Sensitive data exposure"
      examples:
        - description: "Similar API endpoint"
          file: "app/api/health/route.ts"