Custom Commands

Cate ships with stock commands — plan, triage, collaborate, review, work. Custom commands let you add your own: license audits, dependency updates, release note generation, migration scripts, compliance checks — anything you want an agent to repeat reliably. Custom commands appear in the Custom menu alongside the built-in workflows.

What you’ll need

• A repository with Cate set up (quickstart)
• An idea for what you want to automate

Start the workflow builder

Open the Custom Workflow command from the dashboard. A new tab opens with the workflow builder agent.

Describe what you want

The agent asks: “What do you want this workflow to automate? Describe what triggers it, what it does, and what it produces.”

It follows up with focused questions:

• What kind of work is this? Analysis, code generation, migration, compliance, documentation, something else?
• Does it need the issue tracker? Creating issues, reading them, posting comments, changing statuses?
• Does it produce files? If the workflow creates or modifies repository files — updating a THIRD-PARTY-LICENSES file, generating release notes, modifying configuration — it gets a full git lifecycle: branch, commit, push, PR. The agent handles this automatically.
• Interactive or autonomous? Does it need a conversation with you at runtime, or should it run end-to-end on its own?
• Existing tools? Are there scripts, utilities, or patterns in the codebase it should use?

Codebase exploration

The agent silently explores your codebase for relevant patterns, configuration files, and dependencies. It checks .cate/research/ for prior knowledge and looks at .cate/guardrails/ for quality patterns when relevant. This context informs the prompt it authors.

Name and categorize

The agent presents its understanding and proposes:

• Name — a kebab-case identifier (for example, license-audit) that becomes the prompt filename
• Category — groups related workflows in the Custom menu. Examples: Compliance, Maintenance, Release, Documentation, Quality.
• Description — a one-line summary that appears in the menu alongside the workflow name

Prompt authoring

The agent drafts the workflow prompt — a structured markdown file with phased instructions that tell the executing agent what to do. The draft includes status reporting and phases tailored to your workflow’s purpose.

For workflows that modify files, the prompt includes a complete git lifecycle: create a branch, commit changes, push, and open a PR — following the same conventions as Cate’s built-in work command.

The agent presents the draft for your review and iterates until you’re satisfied.

Files created

The agent writes two files to your repository:

Prompt file — .cate/commands/custom/<workflow-name>.md — the workflow instructions. Version-controlled in your repo, so the whole team gets the workflow.

Registration — .cate/custom-workflows.json updated with the workflow’s name, description, category, and prompt path. This is what makes the workflow appear in the Custom menu.

The agent commits both files and offers to push and open a PR. The new workflow appears in the Custom menu the next time you restart Cate or re-open the repository.

Stock vs. custom commands

Cate maintains a clear separation:

• .cate/commands/ contains stock command files synced from the Cate app on every repo open. Do not edit these directly — your changes will be overwritten.
• .cate/commands/custom/ contains your team’s commands. These are committed to your repo and never touched by Cate’s sync.

When a command runs, Cate checks custom/ first and falls back to the stock version. To override a built-in command (like work or review), copy the stock file to custom/ and edit it there.