{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/command-parameters.schema.json",
  "title": "Command catalog",
  "description": "What `commands.mjs --json` prints: every /multi-agent:<id> command with the parameters, surface and confirmation it declares in its SKILL.md frontmatter, defaults filled in. A client renders a button or a form from this without hard-coding a command. The frontmatter is the source; `_command-contract.mjs` holds it to `argument-hint`. Every field is `x-sensitivity: none`: nothing here is specific to a machine or a person.",
  "type": "object",
  "additionalProperties": false,
  "required": ["contractVersion", "commands"],
  "properties": {
    "contractVersion": {
      "type": "string",
      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
      "x-sensitivity": "none",
      "description": "Major 1. A minor bump adds fields; a consumer ignores keys it does not know."
    },
    "commands": {
      "type": "array",
      "x-sensitivity": "none",
      "items": { "$ref": "#/$defs/command" }
    }
  },
  "$defs": {
    "command": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "argumentHint", "parameters", "gui", "destructive", "confirm"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]*$",
          "x-sensitivity": "none",
          "description": "The command directory name; invoked as /multi-agent:<id>."
        },
        "argumentHint": {
          "type": "string",
          "x-sensitivity": "none",
          "description": "The human hint, verbatim. Empty when the command declares none."
        },
        "parameters": {
          "type": "array",
          "x-sensitivity": "none",
          "items": { "$ref": "#/$defs/parameter" }
        },
        "gui": {
          "enum": ["button", "form", "hidden"],
          "x-sensitivity": "none",
          "description": "button: runs with no input. form: collect parameters first. hidden: not offered as an action (maintainer tooling, help text). Independent of disable-model-invocation, which only stops the model invoking the command itself."
        },
        "destructive": {
          "type": "boolean",
          "x-sensitivity": "none",
          "description": "Removes something that is not trivially recreated: a worktree, a branch, logs, an install, user instruction lines."
        },
        "confirm": {
          "enum": ["required", "none"],
          "x-sensitivity": "none",
          "description": "required: a client asks before launching. Always required when destructive. The command keeps its own in-session confirmation either way."
        }
      }
    },
    "parameter": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "kind"],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^(--)?[a-z0-9][a-z0-9-]*$",
          "x-sensitivity": "none",
          "description": "`--name` for a flag, typed as written. Otherwise a positional, in order; a positional of kind flag is a literal keyword typed as its name."
        },
        "kind": {
          "enum": ["run-id", "branch", "pull-request", "issue-key", "path", "text", "enum", "flag"],
          "x-sensitivity": "none",
          "description": "run-id: #N or a task id. pull-request: a PR number or URL. issue-key: a Jira key or a GitHub issue reference. flag: present or absent, no value."
        },
        "required": {
          "type": "boolean",
          "default": false,
          "x-sensitivity": "none",
          "description": "Omitted in frontmatter means false; the catalog always carries it."
        },
        "repeat": {
          "type": "boolean",
          "default": false,
          "x-sensitivity": "none",
          "description": "More than one value: space-separated for a positional, comma-separated for a flag."
        },
        "enum": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string" },
          "x-sensitivity": "none",
          "description": "The allowed values. Present exactly when kind is enum."
        }
      }
    }
  }
}