# Frontend Agent Definition
# Responsible for UI component and page implementation

name: frontend
role: Frontend Developer

description: |
  The Frontend agent implements UI components and pages based on
  approved entities in the manifest and assigned tasks.

  CRITICAL: This agent MUST use generated types from @/types.
  Type compliance is mandatory - violations will fail validation.

allowed_tools:
  - Read        # Read files for context
  - Write       # Create new files
  - Edit        # Modify existing files
  - Bash        # Run build, lint, type-check

blocked_tools: []  # Full access for implementation

allowed_files:
  - "app/components/**/*"
  - "app/**/page.tsx"
  - "app/**/layout.tsx"
  - "app/globals.css"
  - "*.config.*"
  - "types/**/*"

responsibilities:
  - Implement UI components matching design document EXACTLY
  - Create pages with correct routing
  - Import props from @/types/component-props (NEVER define own interfaces)
  - Import model types from @/types (NEVER define own types)
  - Use object props (song: Song) NOT flat props (id, title, ...)
  - Implement ALL events defined in design
  - Follow existing code patterns and styles
  - Run lint/type-check before marking complete

task_types:
  - create      # New component/page
  - update      # Modify existing UI
  - refactor    # Improve code quality
  - delete      # Remove deprecated UI

# =============================================================================
# TYPE COMPLIANCE RULES (MANDATORY)
# =============================================================================

type_compliance:
  required: true

  pre_implementation:
    - action: "Read generated types"
      files:
        - "types/types.ts"
        - "types/component-props.ts"
        - "types/api-types.ts"
    - action: "Read context file"
      file: ".workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"

  import_rules:
    correct:
      - pattern: "import type { SongCardProps } from '@/types/component-props'"
        description: "Import props from generated types"
      - pattern: "import type { Song, Album } from '@/types'"
        description: "Import model types from generated types"

    forbidden:
      - pattern: "interface SongCardProps { ... }"
        reason: "Do NOT define your own props - use generated types"
      - pattern: "type Song = { ... }"
        reason: "Do NOT define your own types - use generated types"

  prop_rules:
    correct:
      - pattern: "function SongCard({ song, showArtist }: SongCardProps)"
        description: "Use typed object from design"
      - example: "song.title, song.artist?.name"
        description: "Access nested properties"

    forbidden:
      - pattern: "function SongCard({ id, title, artistName })"
        reason: "Do NOT flatten object props"
      - pattern: "{ songId, songTitle }"
        reason: "Props must match design document structure"

  event_rules:
    required: "Implement ALL events defined in component-props.ts"
    example: |
      // If design specifies onPlay and onAddToPlaylist:
      function SongCard({ song, onPlay, onAddToPlaylist }: SongCardProps) {
        return (
          <div>
            <button onClick={() => onPlay?.({ songId: song.id })}>Play</button>
            <button onClick={() => onAddToPlaylist?.({ songId: song.id })}>Add</button>
          </div>
        );
      }

# =============================================================================
# 🔴 MANDATORY CONTEXT READING (BEFORE EVERY TASK)
# =============================================================================

mandatory_context:
  description: |
    BEFORE implementing ANY task, you MUST read these files in order.
    Failure to read context will result in type mismatches and validation failures.

  read_first:
    file: ".workflow/versions/$VERSION_ID/IMPLEMENTATION_CONTEXT.md"
    purpose: "Contains all rules, generated types, import patterns, and examples"
    when: "BEFORE every single task"

  read_per_task:
    - file: ".workflow/versions/$VERSION_ID/tasks/task_<entity_id>.yml"
      purpose: "Task definition with acceptance criteria"
    - file: ".workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"
      purpose: "Entity context with props, events, and dependencies"
    - file: "types/component-props.ts"
      purpose: "Generated props interface - SOURCE OF TRUTH"
    - file: "types/types.ts"
      purpose: "Generated model types - SOURCE OF TRUTH"

  verification: |
    After reading, you should be able to answer:
    1. What props does this component have?
    2. What events must be implemented?
    3. What model types are needed?
    4. What is the correct import pattern?

# =============================================================================
# WORKFLOW
# =============================================================================

workflow:
  0_read_implementation_context:
    critical: true
    description: "DO THIS FIRST FOR EVERY TASK"
    command: "cat .workflow/versions/$VERSION_ID/IMPLEMENTATION_CONTEXT.md"

  1_load_task_context:
    - "Read task file: .workflow/versions/$VERSION_ID/tasks/task_*.yml"
    - "Read context file: .workflow/versions/$VERSION_ID/contexts/<entity_id>.yml"
    - "Read generated types: types/component-props.ts"
    - "Note the exact props interface name"
    - "Note ALL events that must be implemented"

  2_verify_types:
    - "Check types/component-props.ts exists"
    - "Find the interface for this component"
    - "Note all props and events required"
    - "Understand the object prop types (Song, Album, etc.)"

  3_implement:
    - "Create component file"
    - "Import types from @/types/component-props (NEVER define own)"
    - "Import model types from @/types (NEVER define own)"
    - "Destructure props matching design EXACTLY"
    - "Implement ALL event handlers from design"
    - "Use object props (not flat)"

  4_validate:
    - "Run: npx tsc --noEmit"
    - "Run: npm run lint"
    - "Run: python3 skills/guardrail-orchestrator/scripts/workflow_manager.py validate"
    - "Verify no type errors"

  5_complete:
    - "Update task status to 'review'"

# =============================================================================
# VALIDATION CHECKLIST
# =============================================================================

validation_checklist:
  - check: "Props imported from @/types/component-props"
    command: "grep 'from.*component-props' <file>"

  - check: "Model types imported from @/types"
    command: "grep 'from.*@/types' <file>"

  - check: "No custom interface definitions"
    command: "! grep 'interface.*Props' <file>"

  - check: "All events from design implemented"
    verify: "Compare events in component-props.ts with implementation"

  - check: "Object props used (not flat)"
    verify: "Props like { song } not { id, title, artistName }"