aiwg/agentic/code/addons/ralph/schemas/mcp-task.yaml

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

# Ralph MCP Task Schema
# Based on REF-066 MCP Specification 2024-11-05
# Issue: #123

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/ralph-mcp-task/v1"
title: "Ralph MCP Task Resource Schema"
description: |
  Schema for Ralph iterative loops as MCP Task resources.
  Enables standardized async operation management per MCP specification.

type: object
required:
  - uri
  - name
  - completion_criteria
  - state

properties:
  uri:
    type: string
    pattern: "^aiwg://tasks/ralph/[a-zA-Z0-9-]+$"
    description: "Task resource URI"
    examples:
      - "aiwg://tasks/ralph/fix-tests-001"
      - "aiwg://tasks/ralph/refactor-auth-002"

  name:
    type: string
    minLength: 1
    maxLength: 200
    description: "Human-readable task name (objective)"
    examples:
      - "Fix all failing tests"
      - "Implement authentication module"

  description:
    type: string
    description: "Detailed task description"

  completion_criteria:
    type: string
    description: "Criteria that define when the task is complete"
    examples:
      - "npm test passes with 0 failures"
      - "All TODOs in codebase resolved"
      - "Security audit passes with no critical findings"

  state:
    $ref: "#/$defs/TaskState"

  progress:
    $ref: "#/$defs/Progress"

  created_at:
    type: string
    format: date-time

  updated_at:
    type: string
    format: date-time

  metadata:
    type: object
    properties:
      created_by:
        type: string
        description: "User or agent that created task"
      priority:
        type: string
        enum: [low, normal, high, critical]
        default: normal
      tags:
        type: array
        items:
          type: string
      execution_mode:
        type: string
        enum: [strict, seeded, logged, default]
        default: default
    additionalProperties: true

$defs:
  TaskState:
    type: object
    required:
      - iteration
      - max_iterations
      - status
    properties:
      iteration:
        type: integer
        minimum: 0
        description: "Current iteration number"
      max_iterations:
        type: integer
        minimum: 1
        default: 200
        description: "Maximum iterations before stopping"
      status:
        type: string
        enum:
          - pending       # Not yet started
          - running       # Currently executing
          - paused        # Temporarily stopped
          - completed     # Successfully finished
          - failed        # Failed with error
          - cancelled     # Manually cancelled
        description: "Current task status"
      last_action:
        type: string
        description: "Description of last action taken"
      next_steps:
        type: array
        items:
          type: string
        description: "Planned next steps"
      error:
        type: object
        properties:
          message:
            type: string
          code:
            type: string
          recoverable:
            type: boolean
        description: "Error details if failed"

  Progress:
    type: object
    properties:
      percentage:
        type: number
        minimum: 0
        maximum: 100
        description: "Progress percentage"
      message:
        type: string
        description: "Current progress message"
      artifacts_created:
        type: integer
        minimum: 0
      artifacts_modified:
        type: integer
        minimum: 0
      checkpoints:
        type: integer
        minimum: 0
        description: "Number of checkpoints saved"

# MCP Task Operations
operations:
  list:
    description: "List all Ralph tasks"
    request:
      method: "tasks/list"
      params:
        status:
          type: string
          description: "Filter by status"
    response:
      type: array
      items:
        $ref: "#"

  start:
    description: "Start a new Ralph task"
    request:
      method: "tasks/start"
      params:
        objective:
          type: string
          required: true
        completion_criteria:
          type: string
          required: true
        max_iterations:
          type: integer
          default: 200
        execution_mode:
          type: string
          enum: [strict, seeded, logged, default]
          default: default
    response:
      $ref: "#"

  cancel:
    description: "Cancel a running task"
    request:
      method: "tasks/cancel"
      params:
        task_id:
          type: string
          required: true
    response:
      type: object
      properties:
        success:
          type: boolean

  resume:
    description: "Resume a paused task"
    request:
      method: "tasks/resume"
      params:
        task_id:
          type: string
          required: true
        from_checkpoint:
          type: string
          description: "Resume from specific checkpoint ID"
    response:
      $ref: "#"

  pause:
    description: "Pause a running task"
    request:
      method: "tasks/pause"
      params:
        task_id:
          type: string
          required: true
    response:
      $ref: "#"

  get_status:
    description: "Get task status"
    request:
      method: "tasks/status"
      params:
        task_id:
          type: string
          required: true
    response:
      $ref: "#"

# Agent protocol for task management
agent_protocol:
  task_lifecycle:
    description: "How agents manage task lifecycle"
    phases:
      - name: creation
        actions:
          - validate_objective
          - parse_completion_criteria
          - set_initial_state
          - create_checkpoint
      - name: execution
        actions:
          - evaluate_state
          - plan_next_action
          - execute_action
          - update_progress
          - check_completion
          - checkpoint_if_needed
      - name: completion
        actions:
          - verify_criteria_met
          - final_checkpoint
          - update_status
          - report_results

  progress_reporting:
    frequency: "every_iteration"
    fields:
      - percentage
      - message
      - artifacts_created

  error_handling:
    on_transient_error:
      action: retry
      max_retries: 3
      backoff: exponential
    on_permanent_error:
      action: fail
      preserve_checkpoint: true

# Storage
storage:
  location: ".aiwg/ralph/tasks/"
  format: json
  index: ".aiwg/ralph/tasks/index.json"
  checkpoint_dir: ".aiwg/ralph/checkpoints/"

# Integration with existing Ralph
migration:
  strategy: parallel
  feature_flag: "AIWG_RALPH_MCP_TASKS"
  phases:
    - name: parallel_operation
      description: "Run MCP tasks alongside legacy Ralph"
    - name: internal_migration
      description: "Migrate internal Ralph to use MCP tasks"
    - name: external_migration
      description: "Migrate ralph-external to use MCP tasks"
    - name: deprecate_legacy
      description: "Remove legacy implementation"

# Examples
examples:
  - uri: "aiwg://tasks/ralph/fix-tests-001"
    name: "Fix all failing tests"
    completion_criteria: "npm test passes with 0 failures"
    state:
      iteration: 5
      max_iterations: 200
      status: running
      last_action: "Fixed type error in auth.ts"
      next_steps:
        - "Run tests to check remaining failures"
        - "Fix import path issue"
    progress:
      percentage: 25
      message: "Fixed 5 of 20 test failures"
      artifacts_modified: 3
      checkpoints: 2
    created_at: "2026-01-25T10:00:00Z"
    updated_at: "2026-01-25T10:30:00Z"

# References
references:
  research:
    - "@.aiwg/research/findings/REF-066-mcp-spec.md"
  implementation:
    - "#123"
  related:
    - "@agentic/code/addons/ralph/schemas/checkpoint.yaml"
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/execution-mode.yaml"
    - "@.claude/commands/ralph.md"