JSON reports: ascribe agents

The JSON Schemas of what ascribe agents index, sync, and prompt write with --format json.

Part of the JSON report contract, whose rules every document here follows.

ascribe agents index

schemas/agents-index.schema.json:

{
  "$defs": {
    "IndexPage": {
      "description": "A page copied into the folder an index points into.",
      "properties": {
        "path": {
          "description": "Its Markdown version's path in the folder.",
          "type": "string"
        },
        "source": {
          "description": "The page, as a path from the content root.",
          "type": "string"
        }
      },
      "required": [
        "source",
        "path"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe agents index --format json` answers.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "build": {
      "description": "The build.",
      "type": "string"
    },
    "bytes": {
      "description": "How many bytes it holds.",
      "minimum": 0,
      "type": "integer"
    },
    "changed": {
      "description": "Whether that file changed: with `--dry-run`, whether it would.",
      "type": "boolean"
    },
    "file": {
      "description": "The file the index was written into, between its markers, from the\nfolder the command ran in; `null` when it was printed.",
      "type": [
        "string",
        "null"
      ]
    },
    "folder": {
      "description": "The folder the pages were copied into, from the folder the command\nran in; `null` without `--pages`.",
      "type": [
        "string",
        "null"
      ]
    },
    "left_out": {
      "description": "The offered pages the index leaves out to stay under `limit`, as paths\nfrom the content root.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "limit": {
      "description": "The most bytes the index holds.",
      "minimum": 0,
      "type": "integer"
    },
    "listed": {
      "description": "The pages the index lists, as paths from the content root, in its\norder.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "offered": {
      "description": "How many pages the build offers: those it publishes, apart from the\n`unlisted`.",
      "minimum": 0,
      "type": "integer"
    },
    "pages": {
      "description": "The pages copied into the folder: every offered page, with\n`--pages`.",
      "items": {
        "$ref": "#/$defs/IndexPage"
      },
      "type": "array"
    },
    "schema_version": {
      "description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
      "minimum": 0,
      "type": "integer"
    },
    "text": {
      "description": "The index's Markdown.",
      "type": "string"
    },
    "without_description": {
      "description": "The pages the index lists without their description, to stay under\n`limit`, as paths from the content root.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "written": {
      "description": "Whether the file and the pages were written: false when the index\nwas printed, or with `--dry-run`.",
      "type": "boolean"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "build",
    "limit",
    "bytes",
    "offered",
    "listed",
    "left_out",
    "without_description",
    "file",
    "changed",
    "written",
    "folder",
    "pages",
    "text"
  ],
  "title": "AgentsIndexReport",
  "type": "object"
}

ascribe agents sync

schemas/agents-sync.schema.json:

{
  "$defs": {
    "Agent": {
      "description": "An agent that reads a file `sync` writes, as `sync` names it.",
      "oneOf": [
        {
          "const": "claude_code",
          "description": "Claude Code.",
          "type": "string"
        },
        {
          "const": "codex",
          "description": "Codex.",
          "type": "string"
        },
        {
          "const": "copilot",
          "description": "GitHub Copilot, in an editor or on GitHub.",
          "type": "string"
        },
        {
          "const": "copilot_cloud",
          "description": "Copilot's cloud agent only.",
          "type": "string"
        },
        {
          "const": "cursor",
          "description": "Cursor.",
          "type": "string"
        },
        {
          "const": "gemini_cli",
          "description": "Gemini CLI.",
          "type": "string"
        }
      ]
    },
    "SyncFile": {
      "description": "A file in `ascribe agents sync --format json`.",
      "properties": {
        "changed": {
          "description": "Whether it changed: with `check`, whether it's out of date.",
          "type": "boolean"
        },
        "path": {
          "description": "Its path, from the current directory, `/`-separated.",
          "type": "string"
        },
        "read_by": {
          "description": "The agents that read it.",
          "items": {
            "$ref": "#/$defs/Agent"
          },
          "type": "array"
        }
      },
      "required": [
        "path",
        "changed",
        "read_by"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe agents sync --format json` writes: each file it writes,\nand what it has to say.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "check": {
      "description": "Whether it ran with `--check`, which writes nothing.",
      "type": "boolean"
    },
    "files": {
      "description": "Each file, in the order it was first planned.",
      "items": {
        "$ref": "#/$defs/SyncFile"
      },
      "type": "array"
    },
    "mcp_settings": {
      "description": "With `--cloud` and no `--agent`, the MCP server's JSON to paste into\nthe repository's settings for Copilot's cloud agent; else `null`."
    },
    "notes": {
      "description": "The notes for the person running it, which it also writes to\nstandard error.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "schema_version": {
      "description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
      "minimum": 0,
      "type": "integer"
    },
    "unread": {
      "description": "What an agent doesn't read of what's written, and the target that\nadds it, a sentence each.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "written": {
      "description": "Whether it wrote the files: false with `--check` or `--dry-run`.",
      "type": "boolean"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "check",
    "written",
    "files",
    "notes",
    "unread",
    "mcp_settings"
  ],
  "title": "AgentsSyncReport",
  "type": "object"
}

ascribe agents prompt

schemas/agents-prompt.schema.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe agents prompt <NAME> --format json` writes: the prompt.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "name": {
      "description": "The prompt's name.",
      "type": "string"
    },
    "schema_version": {
      "description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
      "minimum": 0,
      "type": "integer"
    },
    "text": {
      "description": "The prompt, as `--format text` prints it.",
      "type": "string"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "name",
    "text"
  ],
  "title": "AgentsPromptReport",
  "type": "object"
}

With --list:

schemas/agents-prompt-list.schema.json:

{
  "$defs": {
    "PromptArgument": {
      "description": "An argument of a prompt.",
      "properties": {
        "description": {
          "description": "What it is.",
          "type": "string"
        },
        "name": {
          "description": "Its name, the `key` of `--arg key=value`.",
          "type": "string"
        },
        "required": {
          "description": "Whether the prompt needs it.",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "description",
        "required"
      ],
      "type": "object"
    },
    "PromptListed": {
      "description": "A prompt in `ascribe agents prompt --list --format json`.",
      "properties": {
        "arguments": {
          "description": "Its arguments, which `--arg key=value` gives.",
          "items": {
            "$ref": "#/$defs/PromptArgument"
          },
          "type": "array"
        },
        "description": {
          "description": "What it asks an agent to do.",
          "type": "string"
        },
        "name": {
          "description": "Its name, which `ascribe agents prompt` takes.",
          "type": "string"
        },
        "title": {
          "description": "A short name for people.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "title",
        "description",
        "arguments"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe agents prompt --list --format json` writes: every prompt,\nwith its arguments.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "prompts": {
      "description": "The prompts, in order.",
      "items": {
        "$ref": "#/$defs/PromptListed"
      },
      "type": "array"
    },
    "schema_version": {
      "description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "prompts"
  ],
  "title": "AgentsPromptListReport",
  "type": "object"
}