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

git clone https://github.com/overcut-ai/overcut-playbooks.git
cd overcut-playbooks
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/).
SkillWhat It Teaches the Agent
Workflow TriggersAll 22 event types (issue, PR, mention, scheduled, manual), condition operators, slash command setup, and cron scheduling
Step ActionsThe 5 action types (agent.run, agent.session, git.clone, repo.identify, ci.executeWorkflow) with full parameter schemas
Agent Session DesignWhen to use agent.session vs agent.run, coordinator patterns, delegation templates, exit criteria, and interactive sessions
Agent Tools ReferenceAll 35+ user-configurable tools across 8 categories, plus the 5 built-in agent types and their tool presets
Template VariablesHandlebars {{}} syntax for referencing trigger context, step outputs, and using helpers like comparison and iteration
Prompt EngineeringStructured output patterns, tool constraint tables, progress tracking, idempotency markers, and cross-workflow triggering
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: 
playbook-name/
├── workflow.json          # The importable workflow definition
├── README.md              # Documentation and usage guide
├── step-id-name.md        # Prompt for a step (filename = step ID)
├── another-step-id.md     # Each step gets its own prompt file
└── special-agents/        # (Optional) Custom agent instructions
    └── agent-name.md

​
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
python3 scripts/sync-prompts.py create-pr-from-design

​
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 Use Cases.

​
Choosing the Right Agent for Each Step

When mapping agents during import (or when building a new playbook), consider what each step needs:
Step PurposeRecommended Agent TypeKey Tools Needed
Code analysis / implementationSenior DeveloperFile system, code utilities, git operations
Code reviewCode ReviewerPull request review, inline comments
DocumentationTech WriterFile system, ticket/issue tools
Planning / requirementsProduct ManagerTicket tools, exploration
Repository explorationExplore AgentSearch, file reading
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: 
Update the planning step in create-pr-from-design to also
consider performance implications for each phase.
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

Add a new step after "validate-implementation" that runs
a security scan before finalizing the PR.
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

Change this playbook's trigger from a slash command to
automatically run when an issue is labeled "implement".
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: 
Create a new playbook called "auto-test-generation" that:
1. Triggers when a PR is opened
2. Clones the repo and checks out the PR branch
3. Analyzes which files changed
4. Generates unit tests for the changed code
5. Commits the tests and pushes to the PR branch
6. Posts a comment on the PR summarizing what was tested
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

StepActionWhat It Does
Identify Reposrepo.identifyDetermines which repository the issue relates to
Clone Repogit.cloneShallow-clones the identified repository
Prepare Contextagent.runReads the issue, resolves dependencies, determines the base branch
Planningagent.sessionCreates a phased implementation plan from the design document
Setup PRagent.runCreates a branch and opens a draft pull request
Implement Changesagent.sessionImplements each phase with individual commits and progress tracking
Validateagent.sessionWrites tests, runs validation, fixes lint issues
Finalize PRagent.runUpdates PR description, removes draft status, posts completion summary

​
How steps connect

Each step’s output flows to the next via template variables: 
{{outputs.identify-repos}}     → Clone step knows which repo
{{outputs.prep-context}}       → Planning step knows the scope and base branch
{{outputs.planning.message}}   → Implementation step knows the phased plan
{{outputs.setup-pr.message}}   → Implementation step knows the branch and PR URL

​
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: 
python3 scripts/sync-prompts.py <playbook-directory>
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