@hermes-hq/hodios-schema 0.1.0

package/schemas/entry.schema.json

@@ -0,0 +1,694 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hermes-ide.com/prompts/schema/v1/entry.schema.json",
+  "title": "Hodios entry",
+  "description": "Frontmatter of a Hodios library entry (prompt, persona, workflow, rule or style). A superset of Agent Skills SKILL.md frontmatter.",
+  "type": "object",
+  "required": [
+    "schema",
+    "id",
+    "kind",
+    "title",
+    "description",
+    "category",
+    "version",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": 1,
+      "description": "Entry format version. Always 1."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Globally unique, immutable id. Equals the entry folder name."
+    },
+    "kind": {
+      "enum": [
+        "prompt",
+        "persona",
+        "workflow",
+        "rule",
+        "style"
+      ],
+      "description": "Entry kind. Equals the entry file name."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 80
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Third person; says what it does and when to use it (lint PS023: 40-200 chars)."
+    },
+    "category": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Primary category from vocab/category.yml. Path: library/<domain>/<category>/<id>/; the domain comes from the vocab."
+    },
+    "subcategory": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Optional value from vocab/subcategory.yml whose parent is the category (TAXONOMY.md §2.4)."
+    },
+    "proposed_category": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Only for category \"unsorted\": the category this entry should graduate into (TAXONOMY.md §2.5)."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$",
+      "description": "Entry semver."
+    },
+    "status": {
+      "enum": [
+        "incubating",
+        "experimental",
+        "stable",
+        "deprecated"
+      ]
+    },
+    "aliases": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true,
+      "description": "Old ids that resolve to this entry. Never the entry’s own id."
+    },
+    "replaced_by": {
+      "type": "string",
+      "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Successor id when status is deprecated."
+    },
+    "sunset": {
+      "type": "string",
+      "pattern": "^20\\d{2}\\.([1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\.(0|[1-9]\\d*)$",
+      "description": "Catalog version after which a deprecated entry may be removed."
+    },
+    "stage": {
+      "type": "array",
+      "description": "Lifecycle stages from vocab/stage.yml.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "stack": {
+      "type": "array",
+      "description": "Technologies from vocab/stack.yml. Empty means stack-agnostic.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "requires": {
+      "type": "array",
+      "description": "Capabilities from vocab/requires.yml, or mcp:<server>.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9][a-z0-9._-]*)?$"
+      },
+      "uniqueItems": true
+    },
+    "role": {
+      "type": "array",
+      "description": "Audience roles from vocab/role.yml. Empty means anyone.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true,
+      "maxItems": 4
+    },
+    "subject": {
+      "type": "array",
+      "description": "Subjects, fields or human languages from vocab/subject.yml. Empty means any.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true,
+      "maxItems": 4
+    },
+    "advice_risk": {
+      "type": "array",
+      "description": "Professional-advice areas from vocab/advice-risk.yml (TAXONOMY.md §3.9).",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true,
+      "maxItems": 4
+    },
+    "lang": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
+      "description": "BCP 47 language of the entry text. Defaults to en."
+    },
+    "inputs": {
+      "type": "array",
+      "description": "Input types from vocab/inputs.yml.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "output": {
+      "type": "array",
+      "description": "Output types from vocab/output.yml.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "tags": {
+      "type": "array",
+      "description": "Free tags, normalized by vocab/tags.yml (lint PS007: at most 8).",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "risk": {
+      "enum": [
+        "read-only",
+        "edits-files",
+        "runs-commands",
+        "network",
+        "external"
+      ]
+    },
+    "invocation": {
+      "enum": [
+        "user",
+        "model",
+        "both"
+      ]
+    },
+    "effort": {
+      "enum": [
+        "quick",
+        "standard",
+        "deep"
+      ]
+    },
+    "interaction": {
+      "enum": [
+        "one-shot",
+        "interactive",
+        "autonomous"
+      ]
+    },
+    "model_tier": {
+      "enum": [
+        "small",
+        "mid",
+        "frontier"
+      ]
+    },
+    "reasoning": {
+      "enum": [
+        "off",
+        "optional",
+        "recommended"
+      ]
+    },
+    "level": {
+      "enum": [
+        "beginner",
+        "intermediate",
+        "expert"
+      ]
+    },
+    "pairs_with": {
+      "type": "object",
+      "description": "UI hint only; never a runtime dependency.",
+      "additionalProperties": false,
+      "properties": {
+        "prompts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "uniqueItems": true
+        },
+        "personas": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "uniqueItems": true
+        },
+        "workflows": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "uniqueItems": true
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "uniqueItems": true
+        },
+        "styles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^(@[a-z0-9](-?[a-z0-9]){0,38}/)?(?=[a-z0-9-]{1,64}$)[a-z0-9]+(-[a-z0-9]+)*$"
+              },
+              "level": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 5
+              }
+            }
+          }
+        }
+      }
+    },
+    "args": {
+      "type": "array",
+      "description": "Typed arguments, referenced in the body as {{name}}.",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "description",
+          "type"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "type": {
+            "enum": [
+              "string",
+              "text",
+              "enum",
+              "number",
+              "boolean"
+            ]
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "default": {
+            "type": [
+              "string",
+              "number",
+              "boolean"
+            ]
+          },
+          "enum": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 2,
+            "uniqueItems": true
+          }
+        },
+        "if": {
+          "properties": {
+            "type": {
+              "const": "enum"
+            }
+          }
+        },
+        "then": {
+          "required": [
+            "enum"
+          ]
+        },
+        "else": {
+          "not": {
+            "required": [
+              "enum"
+            ]
+          }
+        }
+      }
+    },
+    "output_contract": {
+      "type": "object",
+      "required": [
+        "format"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "format": {
+          "enum": [
+            "markdown",
+            "json",
+            "yaml",
+            "text",
+            "diff"
+          ]
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "strict": {
+          "type": "boolean"
+        }
+      }
+    },
+    "authorship": {
+      "enum": [
+        "human",
+        "ai-assisted",
+        "ai-generated"
+      ]
+    },
+    "authors": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9](-?[A-Za-z0-9]){0,38}$"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "GitHub logins of the accountable humans."
+    },
+    "last_reviewed": {
+      "type": "string",
+      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
+    },
+    "changelog": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "version",
+          "note"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "version": {
+            "type": "string",
+            "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
+          },
+          "note": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          }
+        }
+      }
+    },
+    "targets": {
+      "type": "object",
+      "description": "Per-target escape hatch. Every use prints a compiler warning.",
+      "propertyNames": {
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "additionalProperties": {
+        "type": "object"
+      }
+    },
+    "voice": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Persona only."
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "read",
+          "search",
+          "edit",
+          "write",
+          "shell",
+          "web",
+          "git"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "Persona only. Abstract tools, mapped per target."
+    },
+    "color": {
+      "enum": [
+        "red",
+        "orange",
+        "yellow",
+        "green",
+        "cyan",
+        "blue",
+        "purple",
+        "pink"
+      ],
+      "description": "Persona only."
+    },
+    "keep_coding_instructions": {
+      "type": "boolean",
+      "description": "Persona only."
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Workflow only. Ordered, gated steps; each file lives in steps/.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "file",
+          "stage",
+          "gate"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "file": {
+            "type": "string",
+            "pattern": "^steps/\\d{2}-[a-z0-9]+(-[a-z0-9]+)*\\.md$"
+          },
+          "stage": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "gate": {
+            "enum": [
+              "approve",
+              "none"
+            ]
+          },
+          "artifact": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "applies_to": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true,
+      "description": "Rule only. Glob patterns; omit for an always-on rule."
+    },
+    "levels": {
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "description": "Style only. Exactly 5 levels, from lightest (1) to strongest (5).",
+      "items": {
+        "type": "object",
+        "required": [
+          "label",
+          "instruction"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "instruction": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 600
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "workflow"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "steps"
+        ]
+      },
+      "else": {
+        "not": {
+          "required": [
+            "steps"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "style"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "levels"
+        ]
+      },
+      "else": {
+        "not": {
+          "required": [
+            "levels"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "rule"
+          }
+        }
+      },
+      "else": {
+        "not": {
+          "required": [
+            "applies_to"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "persona"
+          }
+        }
+      },
+      "else": {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "voice"
+              ]
+            },
+            {
+              "required": [
+                "tools"
+              ]
+            },
+            {
+              "required": [
+                "color"
+              ]
+            },
+            {
+              "required": [
+                "keep_coding_instructions"
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "deprecated"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "replaced_by"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "authorship": {
+            "enum": [
+              "ai-assisted",
+              "ai-generated"
+            ]
+          }
+        },
+        "required": [
+          "authorship"
+        ]
+      },
+      "then": {
+        "required": [
+          "authors"
+        ]
+      }
+    }
+  ]
+}