Skip to main content
Overcut gives you two ways to create and edit workflows:
  1. Workflow Builder: a visual, drag-and-drop editor inside Overcut where you build workflows step by step
  2. Playbook Repo + AI Agent: clone the open-source Overcut Playbooks repo, open it in your preferred AI coding tool (Claude Code, Cursor, Codex, Gemini), and let the agent create or modify workflows for you
Both approaches produce the same result: a workflow.json that you can import and run in Overcut.

Workflow Builder

Build workflows visually: drag actions onto a canvas, configure triggers, assign agents, and publish directly from the UI.

Playbook Repo + AI Agent

Clone the playbook repo, open it in your AI coding tool, and ask the agent to create or modify workflows with full context about Overcut’s capabilities.

​
Using the Workflow Builder

The Workflow Builder is a visual editor inside Overcut where you can:
  • Drag and drop actions (agent.run, agent.session, git.clone, etc.) onto a canvas
  • Configure triggers (PR opened, issue labeled, mention, slash command, scheduled)
  • Assign agents to each step and set timeouts
  • Edit step prompts inline
  • Publish, version, and manage workflows
This is the best option when you want to build a workflow interactively, or make quick edits to an existing one.

​
Using the Playbook Repo with AI

For more complex workflows, or when you want to create and iterate faster, the Overcut Playbooks repository provides an AI-powered workspace. The repo ships with built-in skills and rules for popular AI coding tools, so your agent understands Overcut’s workflow format, triggers, actions, template variables, and agent tools out of the box.

​
Why use the playbook repo?

Ready-to-Use Workflows

Import any of the 15+ pre-built playbooks directly into Overcut. No need to build from scratch.

AI-Assisted Authoring

Built-in skills teach your AI coding agent everything about Overcut workflows, so it can create or modify playbooks for you.

Works with Any Agent

Skills are shared across Claude Code, Cursor, Codex, Gemini, and more. Use whichever tool you prefer.

Learn by Example

Study real, production-tested workflows to understand patterns and build your own.

​
Getting Started

1

Clone the repository

2

Open in your preferred AI coding tool

Open the cloned repo in Claude Code, Cursor, Codex, Gemini, or any AI-enabled editor. The repo automatically loads the right skills and rules for each tool.
3

Start asking

Ask your AI agent to explore existing playbooks, modify them, or create entirely new workflows. For example:
  • “Create a new playbook that runs security checks when a PR is opened”
  • “Modify the code-review playbook to add a linting step”
  • “Add a step to the create-pr-from-design playbook that notifies Slack when done”
The AI agent automatically picks up the repo’s conventions: workflow.json format, step ID naming rules, prompt file structure, and all available trigger types, actions, and template variables.

​
Built-in AI Skills

The repo includes 6 deep-reference skills that give your AI coding agent comprehensive knowledge about Overcut’s workflow system. These are stored in .agents/skills/ and automatically symlinked to each tool’s config directory (.claude/skills/, .cursor/skills/, .codex/skills/, .gemini/skills/). Each skill includes a main reference (SKILL.md) and detailed lookup tables in a references/ folder, giving the agent everything it needs to produce valid, well-structured playbooks.
The skills activate automatically based on context. When you ask the agent to create a trigger, it loads the workflow-triggers skill. When you ask about coordinating multiple agents, it loads the agent-session-design skill.

​
Understanding Playbook Structure

Every playbook follows a consistent structure that both humans and AI agents can work with:

​
The Filename Convention

The most important rule: prompt filenames must exactly match the step IDs in workflow.json. For example, if a step has "id": "prep-context", the corresponding prompt file must be named prep-context.md. This convention enables a powerful workflow:
  1. Edit the markdown prompt file in your editor
  2. The change is immediately readable by your AI agent
  3. Ask the agent to update workflow.json to match, or use the included sync-prompts.py script

​
Import a Playbook into Overcut

1

Download the workflow file

Navigate to the playbook folder in the repository and download the workflow.json file.
2

Open the Workflow Builder

In Overcut, go to the Workflow Builder and click Import Workflow.
3

Upload the JSON file

Select the downloaded workflow.json file to import the complete workflow structure.
4

Map your agents

Every step that uses agent.run or agent.session references an agent ID. During import, you’ll map each reference to one of your own configured agents. Choose the agent whose role and tools best match the step’s purpose.
For example, a step labeled “Backend Developer” should map to an agent with code editing tools, while a “Code Reviewer” step should map to an agent with pull request review tools.
5

Customize and publish

Review the imported workflow, adjust prompts or timeouts as needed, and publish it.
For full details on the import/export process, see Import & Export Workflows.

​
Choosing the Right Agent for Each Step

When mapping agents during import (or when building a new playbook), consider what each step needs:
The model used for each step follows a cascade: agent-specific setting → workflow default → workspace default → system default. You can override the model at any level to balance cost and capability.

​
Edit Existing Playbooks with AI

The fastest way to customize a playbook is to ask your AI agent directly.

​
Modify prompts

Open the repo in your preferred tool and ask:
The agent will edit planning.md and update the corresponding instruction in workflow.json, maintaining the filename-to-step-ID convention.

​
Add or remove steps

The agent will create a new prompt file, update workflow.json with the step definition and flow connections, and ensure the step ID matches the filename.

​
Change triggers or conditions

The agent knows all 22 trigger event types and their condition operators, so it can reconfigure the trigger correctly.

​
Create a New Workflow from Scratch

You don’t have to start from an existing playbook. Ask your AI agent to build one from your requirements:
The agent will:
  • Create the playbook folder with the correct naming convention
  • Write workflow.json with all steps, flow connections, and trigger configuration
  • Create individual prompt .md files for each agent step
  • Write a README.md with usage instructions
Point the agent to similar existing playbooks as reference. For example: “Use the create-pr-from-design playbook as a pattern: it has a similar multi-step structure with progress tracking.”

​
Example: The Create PR from Design Playbook

To see these concepts in action, look at the create-pr-from-design playbook, the most detailed workflow in the repo. It automatically creates implementation pull requests from approved design documents, triggered by the /pr slash command on an issue.

​
The 8-step pipeline

​
How steps connect

Each step’s output flows to the next via template variables:

​
Agent assignment

This playbook uses two agent personas, Backend Developer and Frontend Developer, assigned to different steps based on the task:
  • Single-focus steps (prep context, setup PR, finalize) use agent.run with one agent
  • Complex steps (planning, implementation, validation) use agent.session with both agents coordinated by an automatic coordinator
When you import this playbook, you’ll map these to your own agents with the appropriate roles and tools.

​
Sync Prompts Utility

The repo includes a sync-prompts.py script that reads all .md prompt files in a playbook directory and updates the corresponding instruction fields in workflow.json:
This is useful when you’ve edited prompt files manually (without AI) and want to sync the changes into the workflow definition. The script matches filenames to step IDs, handles JSON escaping, and reports any mismatches.

​
Next Steps