workflows.json reference

The .cate/workflows.json file is the single source of truth for a Cate-managed repository. Created during setup, it defines everything Cate needs to manage your project: issue tracker connection, status definitions, autonomy settings, work queue priorities, and command definitions.

Field names use camelCase (protobuf JSON serialization format).

Top-level structure

{
  "version": "2",
  "project": { ... },
  "tracker": { ... },
  "git": { ... },
  "autonomy": { ... },
  "statuses": [ ... ],
  "queue": { ... },
  "commands": { ... }
}

project

Basic project metadata.

Field	Type	Description
name	string	Repository or project name
description	string	Brief project description, used by agents for context

tracker

Connection details for the issue tracker and project board. The shape differs by provider.

GitHub tracker

"tracker": {
  "provider": "github",
  "owner": {
    "name": "acme-corp",
    "type": "OWNER_TYPE_ORGANIZATION"
  },
  "repo": "my-project",
  "projectName": "My Project Board",
  "projectNumber": 3,
  "statusFieldId": "PVTSSF_lADOBQ...",
  "statusOptions": {
    "ready":          { "optionId": "47fc9ee4" },
    "in_progress":    { "optionId": "98236657" },
    "in_review":      { "optionId": "da82de31" },
    "human_review":   { "optionId": "12a5b6c7" },
    "done":           { "optionId": "b6b4a997" }
  }
}

Field	Type	Description
provider	string	Must be "github"
owner.name	string	GitHub username or organization name
owner.type	string	"OWNER_TYPE_USER" or "OWNER_TYPE_ORGANIZATION"
repo	string	Repository name
projectName	string	Display name of the GitHub Projects board
projectNumber	number	GitHub Projects board number (visible in the board URL)
statusFieldId	string	GitHub Projects Status field ID from the GraphQL API
statusOptions	object	Map of status keys to their GitHub option IDs

The statusFieldId and all optionId values come from the GitHub GraphQL API during setup. Do not invent placeholder values — all IDs must be real.

Jira tracker

"tracker": {
  "provider": "jira",
  "projectName": "My Project",
  "statusOptions": {
    "ready":          { "optionId": "10004" },
    "in_progress":    { "optionId": "10005" },
    "in_review":      { "optionId": "10006" },
    "human_review":   { "optionId": "10007" },
    "done":           { "optionId": "10008" }
  },
  "jira": {
    "site": "mycompany.atlassian.net",
    "cloudId": "dc9ebf1b-bdaf-49c9-93c9-e625b5381f4d",
    "projectKey": "PROJ",
    "boardId": 2,
    "blockingLinkType": "Blocks"
  }
}

Field	Type	Description
provider	string	Must be "jira"
projectName	string	Jira project display name
statusOptions	object	Map of status keys to Jira status IDs (as optionId)
jira.site	string	Jira site URL, e.g. mycompany.atlassian.net
jira.cloudId	string	Jira cloud instance ID
jira.projectKey	string	Jira project key, e.g. PROJ
jira.boardId	number	Jira board ID
jira.blockingLinkType	string	Issue link type for blocker relationships. Default: "Blocks". Omit unless your Jira instance uses a different name.

git

Git conventions for the project.

Field	Type	Default	Description
defaultBranch	string	"main"	Default branch name
branchPattern	string	"task/ISSUE-{number}-{description}"	Branch naming pattern. Use {number} and {description} as placeholders.
commitFormat	string	"conventional"	Commit message format. "conventional" uses feat(scope): description. Use "{number} {description}" for a simpler format.

autonomy

Default autonomy level applied to all issues.

Field	Type	Default	Description
default	string	"full"	Either "full" or "supervised". See Autonomy levels.

statuses

Array of status definitions. Each entry maps to a column on your project board.

Field	Type	Description
id	string	Internal key in snake_case. Used in queue entries and status transitions.
name	string	Display name. Must match the column name on your project board exactly.
color	string	Hex color for dashboard display.

"statuses": [
  { "id": "ready",          "name": "To Do",          "color": "#3b82f6" },
  { "id": "in_progress",    "name": "In Progress",    "color": "#f59e0b" },
  { "id": "in_review",      "name": "AI Review",      "color": "#8b5cf6" },
  { "id": "human_review",   "name": "Human Review",   "color": "#ec4899" },
  { "id": "done",           "name": "Done",            "color": "#22c55e" }
]

queue

Defines which board statuses each agent role pulls work from, in priority order.

worker — code agents

Entries are processed in order. Each entry has a status (referencing a status id).

"worker": {
  "entries": [
    { "status": "ready" }
  ]
}

Agents skip issues with open blockers automatically.

reviewer — code reviewers

Reviewers only pick up issues that have an open PR.

"reviewer": {
  "entries": [
    { "status": "in_review" }
  ]
}

human-review — your attention queue

Issues that surface in the dashboard’s human review queue.

"human-review": {
  "entries": [
    { "status": "human_review" }
  ]
}

This queue is optional. If omitted, Cate doesn’t surface human review items in the dashboard, but agents continue to work normally.

in_progress — visibility queue

Tracks which issues are actively being worked on.

"in_progress": {
  "entries": [
    { "status": "in_progress" }
  ]
}

commands

Defines available commands, their parameters, tab lifecycle, and status transitions.

Field	Type	Description
name	string	Display name in the dashboard menu
description	string	Brief description shown in the menu
prompt	string	Path to the prompt file, relative to .cate/
tab	object	Tab lifecycle
parameters	object	Named input parameters
transitions	array	Valid status transitions this command can make

Tab lifecycle

Persistent commands (work, review) have pre-allocated tabs. The app dispatches issues to idle persistent tabs automatically.

"tab": { "persistent": { "minAllocation": 3 } }

minAllocation controls how many tabs are created when the repo opens.

Ephemeral commands (plan, collaborate, setup, human review, etc.) spin up on demand and terminate when the session ends.

"tab": { "ephemeral": {} }