project-standalo-sonic-cloud/skills/guardrail-orchestrator/schemas/dependency_graph.yml

# Dependency Graph Schema
# Auto-generated from design_document.yml
# Determines execution order for parallel task distribution

# ============================================================================
# GRAPH METADATA
# ============================================================================
dependency_graph:
  # Links to design document
  design_version: string    # design_document revision this was generated from
  workflow_version: string  # v001, v002, etc.

  # Generation info
  generated_at: timestamp
  generator: string         # Script that generated this

  # Statistics
  stats:
    total_entities: integer
    total_layers: integer
    max_parallelism: integer  # Max items that can run in parallel
    critical_path_length: integer  # Longest dependency chain

# ============================================================================
# EXECUTION LAYERS
# ============================================================================
layers:
  description: "Ordered layers for parallel execution within each layer"

  layer_schema:
    layer: integer          # 1, 2, 3...
    name: string            # Human-readable name
    description: string     # What this layer contains

    # Items in this layer (can run in parallel)
    items:
      - id: string          # Entity ID (model_*, api_*, page_*, component_*)
        type: enum          # model | api | page | component
        name: string        # Human-readable name

        # Dependencies (all must be in lower layers)
        depends_on: [string]  # Entity IDs this depends on

        # Task mapping
        task_id: string     # task_* ID for implementation
        agent: enum         # frontend | backend

        # Estimated complexity
        complexity: enum    # low | medium | high

    # Layer constraints
    requires_layers: [integer]  # Layer numbers that must complete first
    parallel_count: integer     # Number of items that can run in parallel

  # Example layers
  example:
    - layer: 1
      name: "Data Layer"
      description: "Database models - no external dependencies"
      items:
        - id: model_user
          type: model
          name: User
          depends_on: []
          task_id: task_create_model_user
          agent: backend
          complexity: medium
        - id: model_post
          type: model
          name: Post
          depends_on: []
          task_id: task_create_model_post
          agent: backend
          complexity: low
      requires_layers: []
      parallel_count: 2

    - layer: 2
      name: "API Layer"
      description: "REST endpoints - depend on models"
      items:
        - id: api_create_user
          type: api
          name: "Create User"
          depends_on: [model_user]
          task_id: task_create_api_create_user
          agent: backend
          complexity: medium
        - id: api_list_users
          type: api
          name: "List Users"
          depends_on: [model_user]
          task_id: task_create_api_list_users
          agent: backend
          complexity: low
      requires_layers: [1]
      parallel_count: 2

    - layer: 3
      name: "UI Layer"
      description: "Pages and components - depend on APIs"
      items:
        - id: component_user_card
          type: component
          name: UserCard
          depends_on: []
          task_id: task_create_component_user_card
          agent: frontend
          complexity: low
        - id: page_users
          type: page
          name: "Users Page"
          depends_on: [api_list_users, component_user_card]
          task_id: task_create_page_users
          agent: frontend
          complexity: medium
      requires_layers: [2]
      parallel_count: 2

# ============================================================================
# FULL DEPENDENCY MAP
# ============================================================================
dependency_map:
  description: "Complete dependency relationships for visualization"

  entry_schema:
    entity_id:
      type: enum            # model | api | page | component
      layer: integer        # Which layer this belongs to
      depends_on: [string]  # What this entity needs
      depended_by: [string] # What entities need this

  # Example
  example:
    model_user:
      type: model
      layer: 1
      depends_on: []
      depended_by: [model_post, api_create_user, api_list_users, api_get_user]

    api_create_user:
      type: api
      layer: 2
      depends_on: [model_user]
      depended_by: [page_user_create, component_user_form]

    page_users:
      type: page
      layer: 3
      depends_on: [api_list_users, component_user_card]
      depended_by: []

# ============================================================================
# TASK GENERATION MAP
# ============================================================================
task_map:
  description: "Maps entities to implementation tasks with context"

  task_entry_schema:
    entity_id: string       # model_user, api_create_user, etc.
    task_id: string         # task_create_model_user
    layer: integer          # Execution layer
    agent: enum             # frontend | backend

    # Context to pass to subagent (snapshot from design_document)
    context:
      # For models
      model_definition:
        fields: [object]
        relations: [object]
        validations: [object]

      # For APIs
      api_contract:
        method: string
        path: string
        request_body: object
        responses: [object]
        auth: object

      # For pages
      page_definition:
        path: string
        data_needs: [object]
        components: [string]
        auth: object

      # For components
      component_definition:
        props: [object]
        events: [object]
        uses_apis: [string]

      # Shared context
      related_models: [object]    # Models this entity interacts with
      related_apis: [object]      # APIs this entity needs/provides

    # Dependencies as task IDs
    depends_on_tasks: [string]    # Task IDs that must complete first

    # Output definition
    outputs:
      files: [string]             # Files this task will create
      provides: [string]          # Entity IDs this task provides

# ============================================================================
# EXECUTION PLAN
# ============================================================================
execution_plan:
  description: "Concrete execution order for workflow orchestrator"

  phase_schema:
    phase: integer          # 1, 2, 3... (maps to layers)

    # Parallel batch within phase
    parallel_batch:
      - task_id: string
        entity_id: string
        agent: enum

        # Full context blob for subagent
        context_file: string  # Path to context snapshot file

        # Expected outputs
        expected_files: [string]

        # Validation to run after completion
        validation:
          - type: enum      # file_exists | lint | typecheck | test
            target: string

  # Example
  example:
    - phase: 1
      parallel_batch:
        - task_id: task_create_model_user
          entity_id: model_user
          agent: backend
          context_file: .workflow/versions/v001/contexts/model_user.yml
          expected_files: [prisma/schema.prisma, app/models/user.ts]
          validation:
            - type: typecheck
              target: app/models/user.ts

        - task_id: task_create_model_post
          entity_id: model_post
          agent: backend
          context_file: .workflow/versions/v001/contexts/model_post.yml
          expected_files: [prisma/schema.prisma, app/models/post.ts]
          validation:
            - type: typecheck
              target: app/models/post.ts

    - phase: 2
      parallel_batch:
        - task_id: task_create_api_create_user
          entity_id: api_create_user
          agent: backend
          context_file: .workflow/versions/v001/contexts/api_create_user.yml
          expected_files: [app/api/users/route.ts]
          validation:
            - type: lint
              target: app/api/users/route.ts
            - type: typecheck
              target: app/api/users/route.ts

# ============================================================================
# CONTEXT SNAPSHOT SCHEMA
# ============================================================================
context_snapshot:
  description: "Schema for per-task context files passed to subagents"

  snapshot_schema:
    # Metadata
    task_id: string
    entity_id: string
    generated_at: timestamp
    workflow_version: string

    # The entity being implemented
    target:
      type: enum            # model | api | page | component
      definition: object    # Full definition from design_document

    # Related entities (for reference)
    related:
      models: [object]      # Model definitions this task needs to know about
      apis: [object]        # API contracts this task needs to know about
      components: [object]  # Component definitions this task needs

    # Dependency chain
    dependencies:
      completed: [string]   # Entity IDs already implemented
      pending: [string]     # Entity IDs not yet implemented (shouldn't depend on)

    # File context
    files:
      to_create: [string]   # Files this task should create
      to_modify: [string]   # Files this task may modify
      reference: [string]   # Files to read for context

    # Acceptance criteria
    acceptance:
      - criterion: string   # What must be true
        validation: string  # How to verify

    # Implementation hints
    hints:
      patterns: [string]    # Patterns to follow (from existing codebase)
      avoid: [string]       # Anti-patterns to avoid
      examples: [string]    # Example file paths to reference

# ============================================================================
# GRAPH GENERATION RULES
# ============================================================================
generation_rules:
  layer_assignment:
    - "Models with no relations → Layer 1"
    - "Models with relations to Layer 1 models → Layer 1 (parallel)"
    - "APIs depending only on models → Layer 2"
    - "Components with no API deps → Layer 3 (parallel with pages)"
    - "Pages and components with API deps → Layer 3+"
    - "Recursive: if all deps in Layer N, assign to Layer N+1"

  parallelism:
    - "Items in same layer with no inter-dependencies can run in parallel"
    - "Max parallelism = min(layer_item_count, configured_max_agents)"
    - "Group by agent type for efficient batching"

  context_generation:
    - "Include full definition of target entity"
    - "Include definitions of all direct dependencies"
    - "Include one-level of indirect dependencies for context"
    - "Exclude unrelated entities to minimize context size"

  validation:
    - "No circular dependencies (would prevent layer assignment)"
    - "All dependency targets must exist in design_document"
    - "Each entity must be in exactly one layer"
    - "Layer numbers must be consecutive starting from 1"