{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/nissen-consulting/agentic-patterns/schema.json",
  "title": "Agentic Design Pattern",
  "description": "GoF/POSA-style description of a single agentic design pattern. Each pattern names a recurring problem in agent design, the forces that make it hard, and a reusable solution. The schema is intentionally close to Buschmann/POSA (Pattern-Oriented Software Architecture) so existing pattern literacy carries over.",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "name", "category", "intent", "context", "problem", "solution", "status_in_practice"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]*$",
      "description": "Stable kebab-case identifier. Used as the filename for the per-pattern markdown page."
    },
    "name": {
      "type": "string",
      "description": "Canonical human-readable name."
    },
    "aliases": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Synonyms and Also-Known-As names from the literature."
    },
    "category": {
      "type": "string",
      "enum": [
        "planning-control-flow",
        "tool-use-environment",
        "memory",
        "multi-agent",
        "verification-reflection",
        "safety-control",
        "routing-composition",
        "governance-observability",
        "structure-data",
        "streaming-ux",
        "reasoning",
        "retrieval",
        "anti-patterns"
      ],
      "description": "Top-level taxonomy bucket. See taxonomy.md for definitions."
    },
    "intent": {
      "type": "string",
      "description": "One sentence stating what the pattern accomplishes. The Intent slot from GoF."
    },
    "context": {
      "type": "string",
      "description": "The situation in which the problem recurs."
    },
    "problem": {
      "type": "string",
      "description": "The recurring problem the pattern solves."
    },
    "forces": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Competing constraints that make the problem hard. Each force is an independently checkable tension."
    },
    "solution": {
      "type": "string",
      "description": "How the pattern resolves the forces. Recipe-level, not framework-specific."
    },
    "structure": {
      "type": "string",
      "description": "Optional sketch of participants and collaborations. Plain text or ascii diagram."
    },
    "consequences": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "benefits": {
          "type": "array",
          "items": {"type": "string"}
        },
        "liabilities": {
          "type": "array",
          "items": {"type": "string"}
        }
      }
    },
    "constrains": {
      "type": "string",
      "description": "What this pattern *forbids* the LLM from doing. The constraint-first framing: every agent pattern is ultimately a constraint on the model's freedom."
    },
    "known_uses": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["system"],
        "properties": {
          "system": {"type": "string"},
          "note": {"type": "string"},
          "status": {
            "type": "string",
            "enum": ["available", "planned", "pure-future", "not-pursued", "deprecated"],
            "description": "Status in this system. Available = running in production. Planned = on the immediate roadmap. Pure-future = on paper only. Not-pursued = deliberate non-choice. Deprecated = was available, now retired."
          },
          "url": {"type": "string", "format": "uri"}
        }
      }
    },
    "related": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["pattern", "relation"],
        "properties": {
          "pattern": {
            "type": "string",
            "description": "The id of a related pattern."
          },
          "relation": {
            "type": "string",
            "enum": [
              "complements",
              "alternative-to",
              "specialises",
              "generalises",
              "uses",
              "used-by",
              "composes-with",
              "conflicts-with"
            ]
          },
          "note": {"type": "string"}
        }
      }
    },
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "title"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["paper", "blog", "doc", "talk", "repo", "book", "spec"]
          },
          "title": {"type": "string"},
          "authors": {"type": "string"},
          "year": {"type": "integer"},
          "url": {"type": "string", "format": "uri"}
        }
      }
    },
    "status_in_practice": {
      "type": "string",
      "enum": ["mature", "emerging", "experimental", "deprecated"],
      "description": "Maturity in the field as of the version date. Mature = production-ready, settled vocabulary. Emerging = stabilising, still evolving. Experimental = research-grade. Deprecated = superseded."
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    },
    "example_scenario": {
      "type": "string",
      "minLength": 30,
      "description": "Plain-English narrative example, 2-4 sentences, of a concrete situation where this pattern is applied. Avoids jargon where possible; explains in everyday terms what is happening and why this pattern fits. Optional; backfilled over time."
    },
    "applicability": {
      "type": "object",
      "additionalProperties": false,
      "description": "Decision-style bullets that help a reader judge whether to use this pattern in their situation. Optional; backfilled over time.",
      "properties": {
        "use_when": {
          "type": "array",
          "items": {"type": "string", "minLength": 1},
          "description": "Conditions under which this pattern is the right choice."
        },
        "do_not_use_when": {
          "type": "array",
          "items": {"type": "string", "minLength": 1},
          "description": "Conditions under which a different pattern (or no pattern) fits better. Often pairs with related.alternative-to edges."
        }
      }
    },
    "variants": {
      "type": "array",
      "description": "POSA-style Variants slot: named implementation shapes of this pattern that share its problem and forces but differ in tactics. Variants are subordinate to the parent pattern; promote to a first-class pattern only when the intent itself changes (per GoF, intent is what distinguishes patterns of identical structure such as Strategy vs State).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "summary"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "summary": {
            "type": "string",
            "minLength": 10,
            "description": "One-paragraph description of how this variant differs in implementation."
          },
          "distinguishing_factor": {
            "type": "string",
            "description": "What makes this variant different from the others — typically a single tactical dimension (transport, encoding, scheduling, etc.)."
          },
          "when_to_use": {
            "type": "string",
            "description": "Conditions under which this variant is the right shape."
          },
          "see_also": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]*$",
            "description": "Optional pattern id of a related first-class pattern that fully realises this variant's tactic."
          }
        }
      }
    },
    "diagram": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "mermaid"],
      "description": "Mermaid diagram source. Rendered by the Pages workflow into the per-pattern HTML page; GitHub also renders Mermaid in markdown natively.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["sequence", "flow", "class", "state", "graph"],
          "description": "Diagram kind. Drives the expected leading Mermaid keyword: sequenceDiagram | flowchart | classDiagram | stateDiagram-v2 | graph."
        },
        "mermaid": {
          "type": "string",
          "minLength": 10,
          "description": "Raw Mermaid source. Must begin with the keyword for the declared type."
        },
        "caption": {
          "type": "string",
          "description": "Optional one-line caption rendered under the diagram."
        }
      }
    }
  }
}