plan.schema.json

{
  "$id": "https://github.com/codeabovelab/codeboost/schema/versions/1/plan.schema.json",
  "title": "codeboost plan",
  "description": "A plan for one GitHub issue, written by Claude, Codex, or a person. Version 1. Strict-mode compatible: every object lists all its properties as required and allows no others; optional values are nullable. See docs/plan-format.md. There is no $schema line on purpose: Claude Code's --json-schema rejects the draft 2020-12 URL. Validate with a draft 2020-12 validator.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "issue",
    "revision",
    "summary",
    "items",
    "questions"
  ],
  "properties": {
    "schema_version": {
      "description": "Plan format version. Always 1 for this schema.",
      "type": "integer",
      "enum": [
        1
      ]
    },
    "issue": {
      "description": "The GitHub issue number this plan fixes. Import must reject a mismatch with the selected task issue in the selected repository; JSON Schema alone cannot enforce this context-dependent check.",
      "type": "integer",
      "minimum": 1
    },
    "revision": {
      "description": "Plan revision: 1 for the first plan, then +1 for each new revision. codeboost sets the final number on import.",
      "type": "integer",
      "minimum": 1
    },
    "summary": {
      "description": "What the plan does, in one or two plain sentences.",
      "type": "string",
      "minLength": 1,
      "maxLength": 600
    },
    "items": {
      "description": "The plan items, in the order they should run.",
      "type": "array",
      "minItems": 1,
      "maxItems": 30,
      "items": {
        "$ref": "#/$defs/item"
      }
    },
    "questions": {
      "description": "Questions for the person reviewing the plan, when the issue leaves something undecided. Empty when there are none. Ask instead of guessing.",
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 400
      }
    }
  },
  "$defs": {
    "item": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "title",
        "intent",
        "files",
        "acceptance",
        "depends_on"
      ],
      "properties": {
        "id": {
          "description": "P followed by a number: P1, P2, and so on. Unique in the plan.",
          "type": "string",
          "pattern": "^P[1-9][0-9]{0,2}$"
        },
        "title": {
          "description": "A short title, like a good commit subject.",
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "intent": {
          "description": "Why this item exists, in one or two sentences. The review agent checks the code against it.",
          "type": "string",
          "minLength": 1,
          "maxLength": 600
        },
        "files": {
          "description": "The declared files: every file this item will add, change, rename, or delete, with what changes in each. The agent may edit only these.",
          "type": "array",
          "minItems": 1,
          "maxItems": 40,
          "items": {
            "$ref": "#/$defs/file"
          }
        },
        "acceptance": {
          "description": "How to check the item. At least one entry. Prefer a cmd that codeboost can run.",
          "type": "array",
          "minItems": 1,
          "maxItems": 10,
          "items": {
            "$ref": "#/$defs/check"
          }
        },
        "depends_on": {
          "description": "IDs of items that must be done first. Only earlier items. Empty when none.",
          "type": "array",
          "maxItems": 29,
          "items": {
            "type": "string",
            "pattern": "^P[1-9][0-9]{0,2}$"
          }
        }
      }
    },
    "file": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path",
        "kind",
        "renamed_from",
        "change"
      ],
      "properties": {
        "path": {
          "description": "Path from the repo root, with forward slashes. For a rename, the new path.",
          "type": "string",
          "minLength": 1,
          "maxLength": 300,
          "pattern": "^[^/\\\\][^\\\\]*$"
        },
        "kind": {
          "description": "edit: change an existing file. add: create a new file. delete: remove a file. rename: move a file, optionally changing it.",
          "type": "string",
          "enum": [
            "edit",
            "add",
            "delete",
            "rename"
          ]
        },
        "renamed_from": {
          "description": "The old path when kind is rename; otherwise null.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 300
        },
        "change": {
          "description": "What changes in this file, in plain words. Name functions and behavior, not line numbers.",
          "type": "string",
          "minLength": 1,
          "maxLength": 1200
        }
      }
    },
    "check": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "text"
      ],
      "properties": {
        "type": {
          "description": "cmd: one program and its literal arguments, for example go test ./... -run TestRetry. codeboost splits it into arguments and runs it in the container without a shell, using the strict quoting/tokenization grammar in docs/plan-format.md; shell syntax outside quoted literal arguments and all expansions are forbidden; the complete parsed argv must exactly match an entry on the repo's approved command list, including every flag and argument. Prefix matching and appended arguments are not allowed. An unlisted argv cannot execute until the person explicitly approves that exact allowlist entry. It passes when it exits 0. check: a statement the review agent judges against the code.",
          "type": "string",
          "enum": [
            "cmd",
            "check"
          ]
        },
        "text": {
          "description": "The command, or the statement to check.",
          "type": "string",
          "minLength": 1,
          "maxLength": 400
        }
      }
    }
  }
}