Issue tracker setup

During setup, Cate configures the connection to your issue tracker and project board. This page covers what gets configured and how to adjust it if you need to make changes manually.

Required status columns

Cate expects five status columns on your project board:

Column	Purpose
To Do	Available work, ordered by priority (top of the list = highest priority)
In Progress	Being actively worked on by an agent
AI Review	PR created, awaiting agent code review
Human Review	Agent reviewed — ready for you to merge
Done	Merged and closed

The setup agent creates these columns automatically for new boards. For existing boards, it checks for any missing columns and offers to add them.

GitHub Projects setup

Cate uses GitHub Issues for work items and GitHub Projects for board management.

Connecting an existing board

If you have an existing GitHub Projects board, provide its project number during setup. The agent queries the board, verifies the required status columns exist, and maps their GitHub option IDs into workflows.json. If any columns are missing, it offers to add them.

The project number appears in the board URL: github.com/orgs/your-org/projects/3 -> project number is 3.

Creating a new board

If you don’t have a board, the setup agent creates one:

1. Creates a GitHub Projects board linked to your repository
2. Replaces the default columns (Todo, In Progress, Done) with the five required statuses
3. Links the repository to the project

The board is created under your GitHub username or organization, depending on the repository ownership.

Jira setup

Cate connects to your Jira project using your site URL, project key, and board ID.

What the agent configures

During setup, the agent:

1. Connects to your Jira instance using your credentials
2. Lists available projects and boards for you to select
3. Maps your Jira board’s existing statuses to the five required statuses
4. Records the Jira cloud ID, board ID, and status IDs in workflows.json

Status mapping

Cate maps its five required statuses to your Jira workflow statuses. If your Jira project already has matching statuses, the agent maps them directly. If any are missing, it tells you to configure them in Jira’s workflow settings first — board columns are read-only via API.

Blocker link type

Cate uses issue links to track blockers. By default it uses "Blocks" as the link type. If your Jira instance uses a different name for blocking relationships, update jira.blockingLinkType in workflows.json.

Manual adjustments

To update the tracker configuration without re-running full setup, edit .cate/workflows.json directly. See the workflows.json reference for the complete field schema.

The most common manual adjustments:

• Changing the project board — update tracker.projectNumber (GitHub) or tracker.jira.boardId (Jira)
• Fixing status option IDs — update the statusOptions map if you renamed or recreated board columns