aiwg/agentic/code/addons/agent-loop/schemas/shared-patterns.yaml

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# Shared Patterns Schema for Cross-Loop Learning
# Based on REF-013 MetaGPT
# Finding: 159% improvement with shared state across agents
# Issue: #269

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/ralph-shared-patterns/v1"
title: "Ralph Shared Patterns Schema"
description: |
  Schema for shared learning patterns across multiple agent loops.
  Enables cross-loop knowledge transfer through error patterns,
  success patterns, and anti-patterns based on MetaGPT's publish-subscribe
  pattern for shared state.

type: object
required:
  - version
  - pattern_registry

properties:
  version:
    type: string
    pattern: "^\\d+\\.\\d+\\.\\d+$"
    default: "1.0.0"

  pattern_registry:
    $ref: "#/$defs/PatternRegistry"

  effectiveness_metrics:
    $ref: "#/$defs/EffectivenessMetrics"

  pruning_policy:
    $ref: "#/$defs/PruningPolicy"

$defs:
  PatternRegistry:
    type: object
    description: "Central registry of all shared patterns"
    properties:
      error_patterns:
        type: array
        items:
          $ref: "#/$defs/ErrorPattern"
        description: "Error → fix patterns discovered across loops"

      success_patterns:
        type: array
        items:
          $ref: "#/$defs/SuccessPattern"
        description: "Successful approaches by task type"

      anti_patterns:
        type: array
        items:
          $ref: "#/$defs/AntiPattern"
        description: "Approaches that consistently fail"

      code_templates:
        type: array
        items:
          $ref: "#/$defs/CodeTemplate"
        description: "Reusable code patterns"

  ErrorPattern:
    type: object
    description: "Pattern linking error signatures to effective fixes"
    required:
      - pattern_id
      - error_signature
      - fix_approach
      - success_rate
      - usage_count
    properties:
      pattern_id:
        type: string
        pattern: "^pat-error-[a-z0-9-]+-\\d{3}$"
        description: "Unique pattern identifier"
        examples:
          - "pat-error-null-check-001"
          - "pat-error-type-mismatch-002"

      error_signature:
        type: object
        required:
          - error_type
          - error_pattern
        properties:
          error_type:
            type: string
            enum:
              - TypeError
              - ReferenceError
              - AssertionError
              - SyntaxError
              - RuntimeError
              - TimeoutError
              - ValidationError
              - Other
          error_pattern:
            type: string
            description: "Regex or exact match pattern for error message"
          error_location_hints:
            type: array
            items:
              type: string
            description: "Common file/function locations for this error"

      fix_approach:
        type: object
        required:
          - description
          - fix_category
        properties:
          description:
            type: string
            minLength: 20
            description: "What to do to fix this error"
          fix_category:
            type: string
            enum:
              - add_null_check
              - add_type_validation
              - add_error_handling
              - fix_logic_error
              - add_import
              - update_dependency
              - refactor_code_structure
              - other
          code_template:
            type: string
            description: "Template code showing fix pattern"
          code_template_language:
            type: string
            description: "Programming language for template"
          diff_pattern:
            type: string
            description: "Example diff showing the fix"

      source_loops:
        type: array
        items:
          type: object
          properties:
            loop_id:
              type: string
            timestamp:
              type: string
              format: date-time
            contributed_by:
              type: string
              description: "Agent or human who discovered this pattern"
        description: "Loops that contributed to this pattern"

      success_rate:
        type: number
        minimum: 0
        maximum: 1
        description: "How often this fix resolves the error (0-1)"

      usage_count:
        type: integer
        minimum: 0
        description: "Number of times this pattern has been applied"

      last_used:
        type: string
        format: date-time

      first_discovered:
        type: string
        format: date-time

      effectiveness_trend:
        type: array
        items:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
            success_rate_snapshot:
              type: number
            sample_size:
              type: integer
        description: "Tracking effectiveness over time"

      related_patterns:
        type: array
        items:
          type: string
        description: "IDs of related error or success patterns"

      tags:
        type: array
        items:
          type: string
        description: "Searchable tags for categorization"
        examples:
          - ["typescript", "null-safety"]
          - ["async", "promise-handling"]

  SuccessPattern:
    type: object
    description: "Successful approaches by task type"
    required:
      - pattern_id
      - task_category
      - approach
      - success_rate
      - usage_count
    properties:
      pattern_id:
        type: string
        pattern: "^pat-success-[a-z0-9-]+-\\d{3}$"
        examples:
          - "pat-success-test-generation-001"
          - "pat-success-refactor-module-002"

      task_category:
        type: string
        enum:
          - implementation
          - debugging
          - refactoring
          - testing
          - documentation
          - architecture
          - migration
          - optimization
        description: "Type of task this pattern applies to"

      task_description_pattern:
        type: string
        description: "Regex pattern matching task descriptions that benefit from this"

      approach:
        type: object
        required:
          - description
          - steps
        properties:
          description:
            type: string
            description: "High-level description of the approach"
          steps:
            type: array
            items:
              type: string
            description: "Ordered steps to execute"
          tools_used:
            type: array
            items:
              type: string
            description: "Tools/commands used in this approach"
          typical_iterations:
            type: object
            properties:
              average:
                type: number
              minimum:
                type: number
              maximum:
                type: number
            description: "Expected iteration counts for this approach"

      source_loops:
        type: array
        items:
          type: object
          properties:
            loop_id:
              type: string
            outcome:
              type: string
              enum: [success, partial, failure]
            iterations_required:
              type: integer
            timestamp:
              type: string
              format: date-time

      success_rate:
        type: number
        minimum: 0
        maximum: 1

      usage_count:
        type: integer
        minimum: 0

      average_iterations:
        type: number
        description: "Average iterations to complete using this pattern"

      preconditions:
        type: array
        items:
          type: string
        description: "Conditions that must be true for this pattern to apply"

      benefits:
        type: array
        items:
          type: string
        description: "Why this approach works well"

      limitations:
        type: array
        items:
          type: string
        description: "When this approach may not work"

      tags:
        type: array
        items:
          type: string

  AntiPattern:
    type: object
    description: "Approaches that consistently fail or degrade quality"
    required:
      - pattern_id
      - approach_description
      - failure_mode
      - failure_rate
      - occurrence_count
    properties:
      pattern_id:
        type: string
        pattern: "^pat-anti-[a-z0-9-]+-\\d{3}$"
        examples:
          - "pat-anti-premature-optimization-001"
          - "pat-anti-over-abstraction-002"

      approach_description:
        type: string
        description: "What was attempted that failed"

      failure_mode:
        type: string
        enum:
          - infinite_loop
          - quality_degradation
          - scope_creep
          - repeated_same_error
          - incorrect_fix
          - breaking_change
          - performance_regression
        description: "How this approach fails"

      failure_symptoms:
        type: array
        items:
          type: string
        description: "Observable symptoms of this anti-pattern"

      why_it_fails:
        type: string
        description: "Root cause of failure"

      better_alternative:
        type: object
        properties:
          description:
            type: string
          success_pattern_id:
            type: string
            description: "Reference to recommended success pattern"
        description: "What to do instead"

      source_loops:
        type: array
        items:
          type: object
          properties:
            loop_id:
              type: string
            failure_iteration:
              type: integer
            timestamp:
              type: string
              format: date-time

      failure_rate:
        type: number
        minimum: 0
        maximum: 1
        description: "How often this approach leads to failure (0-1)"

      occurrence_count:
        type: integer
        minimum: 0
        description: "Number of times this anti-pattern has been observed"

      tags:
        type: array
        items:
          type: string

  CodeTemplate:
    type: object
    description: "Reusable code patterns from successful loops"
    required:
      - template_id
      - language
      - template_code
      - usage_count
    properties:
      template_id:
        type: string
        pattern: "^tmpl-[a-z0-9-]+-\\d{3}$"

      language:
        type: string
        enum:
          - typescript
          - javascript
          - python
          - go
          - rust
          - java
          - other

      template_code:
        type: string
        description: "Template with placeholders like {{variable}}"

      description:
        type: string

      placeholders:
        type: object
        additionalProperties:
          type: string
        description: "Documentation for each placeholder"

      use_case:
        type: string
        description: "When to use this template"

      source_loops:
        type: array
        items:
          type: string
        description: "Loops that successfully used this template"

      usage_count:
        type: integer

      success_rate:
        type: number

      tags:
        type: array
        items:
          type: string

  EffectivenessMetrics:
    type: object
    description: "Track overall effectiveness of pattern sharing"
    properties:
      total_patterns:
        type: integer
        description: "Total patterns in registry"

      patterns_by_type:
        type: object
        properties:
          error_patterns:
            type: integer
          success_patterns:
            type: integer
          anti_patterns:
            type: integer
          code_templates:
            type: integer

      pattern_usage_stats:
        type: object
        properties:
          total_applications:
            type: integer
          successful_applications:
            type: integer
          failed_applications:
            type: integer
          overall_success_rate:
            type: number

      cross_loop_benefit:
        type: object
        properties:
          loops_with_pattern_injection:
            type: integer
          loops_without_pattern_injection:
            type: integer
          average_iterations_with:
            type: number
          average_iterations_without:
            type: number
          improvement_percentage:
            type: number
            description: "Percentage reduction in iterations"
        description: "Measure impact of pattern sharing"

      last_updated:
        type: string
        format: date-time

  PruningPolicy:
    type: object
    description: "Rules for removing stale or ineffective patterns"
    properties:
      min_success_rate:
        type: number
        default: 0.5
        description: "Patterns below this success rate are candidates for removal"

      min_usage_count:
        type: number
        default: 3
        description: "Patterns must be used at least this many times before evaluation"

      max_age_days:
        type: integer
        default: 90
        description: "Patterns unused for this long may be archived"

      archive_instead_of_delete:
        type: boolean
        default: true

      archive_path:
        type: string
        default: ".aiwg/ralph/shared/archive/"

      auto_prune:
        type: boolean
        default: true

      prune_interval_days:
        type: integer
        default: 7

# Pattern extraction protocol
pattern_extraction:
  description: "How patterns are extracted from completed loops"
  triggers:
    - ralph_loop_completion
  steps:
    - analyze_loop_history
    - identify_error_fix_pairs
    - identify_successful_approaches
    - identify_failure_patterns
    - check_for_duplicate_patterns
    - compute_pattern_effectiveness
    - store_in_registry
    - update_effectiveness_metrics

# Pattern injection protocol
pattern_injection:
  description: "How patterns are injected into new loops"
  triggers:
    - ralph_loop_start
  steps:
    - analyze_task_description
    - search_error_patterns_by_similarity
    - search_success_patterns_by_task_category
    - filter_by_min_success_rate
    - sort_by_effectiveness
    - inject_top_k_patterns
    - track_pattern_usage
  configuration:
    top_k_patterns: 5
    min_success_rate: 0.6
    max_patterns_injected: 10

# Storage configuration
storage:
  patterns_path: ".aiwg/ralph/shared/patterns/"
  error_patterns_file: "error-patterns.json"
  success_patterns_file: "success-patterns.json"
  anti_patterns_file: "anti-patterns.json"
  code_templates_file: "code-templates.json"
  metrics_file: "effectiveness-metrics.json"

# Integration with cross-task memory
cross_task_integration:
  enabled: true
  description: |
    Patterns are stored in the cross-task memory alongside
    reflections and task embeddings. This enables semantic
    retrieval of relevant patterns for similar tasks.
  storage:
    memory_path: ".aiwg/ralph/memory/"
    patterns_index: "patterns-index.json"

# CLI integration
cli_support:
  commands:
    list_patterns:
      command: "aiwg ralph-patterns list"
      options:
        - "--type error|success|anti|template"
        - "--min-success-rate 0.7"
        - "--tag typescript"

    show_pattern:
      command: "aiwg ralph-patterns show {pattern_id}"

    prune_patterns:
      command: "aiwg ralph-patterns prune"
      options:
        - "--dry-run"
        - "--min-success-rate 0.6"

    export_patterns:
      command: "aiwg ralph-patterns export --output patterns-backup.json"

# Examples
examples:
  error_pattern_example:
    pattern_id: "pat-error-null-check-001"
    error_signature:
      error_type: "TypeError"
      error_pattern: "Cannot read property '.*' of null"
      error_location_hints:
        - "*.ts:validateInput"
        - "*.ts:processData"
    fix_approach:
      description: "Add null check before property access"
      fix_category: "add_null_check"
      code_template: |
        if ({{variable}} != null) {
          // access property
          const value = {{variable}}.{{property}};
        }
      code_template_language: "typescript"
    source_loops:
      - loop_id: "ralph-fix-auth-a1b2c3d4"
        timestamp: "2026-02-01T10:00:00Z"
        contributed_by: "software-implementer"
      - loop_id: "ralph-fix-validation-b2c3d4e5"
        timestamp: "2026-02-02T14:30:00Z"
        contributed_by: "debugger"
    success_rate: 0.92
    usage_count: 12
    last_used: "2026-02-02T15:00:00Z"
    first_discovered: "2026-02-01T10:00:00Z"
    tags:
      - "typescript"
      - "null-safety"
      - "defensive-programming"

  success_pattern_example:
    pattern_id: "pat-success-test-generation-001"
    task_category: "testing"
    task_description_pattern: "(?i)(add|write|generate).*tests?"
    approach:
      description: "Generate tests using test-driven approach"
      steps:
        - "Analyze function signature and purpose"
        - "Identify edge cases and boundary conditions"
        - "Generate test cases for happy path"
        - "Generate test cases for error conditions"
        - "Run tests to verify they fail appropriately"
        - "Implement/fix code to pass tests"
      tools_used:
        - "Read"
        - "Write"
        - "Bash (npm test)"
      typical_iterations:
        average: 2.5
        minimum: 1
        maximum: 5
    source_loops:
      - loop_id: "ralph-add-auth-tests-c3d4e5f6"
        outcome: "success"
        iterations_required: 3
        timestamp: "2026-02-01T12:00:00Z"
      - loop_id: "ralph-test-api-d4e5f6a7"
        outcome: "success"
        iterations_required: 2
        timestamp: "2026-02-02T09:00:00Z"
    success_rate: 0.88
    usage_count: 8
    average_iterations: 2.5
    preconditions:
      - "Test framework is configured"
      - "Source code exists"
    benefits:
      - "Ensures tests are meaningful before implementation"
      - "Catches edge cases early"
      - "Forces thinking about failure modes"
    tags:
      - "testing"
      - "tdd"
      - "best-practices"

  anti_pattern_example:
    pattern_id: "pat-anti-premature-optimization-001"
    approach_description: "Optimizing code before tests pass or requirements are met"
    failure_mode: "scope_creep"
    failure_symptoms:
      - "Iteration count increases without progress on core task"
      - "Original goal becomes unclear"
      - "Complexity increases without measurable benefit"
    why_it_fails: "Optimization distracts from primary goal and adds complexity"
    better_alternative:
      description: "Complete primary task first, then optimize if needed"
      success_pattern_id: "pat-success-refactor-module-002"
    source_loops:
      - loop_id: "ralph-optimize-early-e5f6a7b8"
        failure_iteration: 12
        timestamp: "2026-02-01T16:00:00Z"
    failure_rate: 0.85
    occurrence_count: 4
    tags:
      - "optimization"
      - "scope-management"
      - "anti-pattern"

# Research targets (from REF-013)
research_targets:
  cross_loop_improvement: "159% improvement with shared state"
  pattern_types:
    - error_fix_pairs
    - successful_approaches
    - anti_patterns
    - code_templates
  publish_subscribe_pattern: "Agents publish learnings, subscribe to relevant patterns"

# References
references:
  research:
    - "@.aiwg/research/paper-analysis/REF-013-aiwg-analysis.md"
    - "@.aiwg/research/quality-assessments/REF-013-metagpt-assessment.yaml"
  implementation:
    - "#269"  # Cross-loop learning
  related:
    - "@agentic/code/addons/ralph/schemas/cross-task-memory.yaml"
    - "@agentic/code/addons/ralph/schemas/debug-memory.yaml"
    - "@agentic/code/addons/ralph/schemas/multi-loop-registry.yaml"