> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create & Edit Workflows

> Build workflows visually in the Workflow Builder or use the open-source playbook repo with your preferred AI coding agent to create and customize workflows.

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](https://github.com/overcut-ai/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.

<CardGroup cols={2}>
  <Card title="Workflow Builder" icon="palette" href="/docs/how-to/workflow-builder">
    Build workflows visually: drag actions onto a canvas, configure triggers, assign agents, and publish directly from the UI.
  </Card>

  <Card title="Playbook Repo + AI Agent" icon="brain-circuit">
    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.
  </Card>
</CardGroup>

***

## Using the Workflow Builder

The [Workflow Builder](/docs/how-to/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](https://github.com/overcut-ai/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?

<CardGroup cols={2}>
  <Card title="Ready-to-Use Workflows" icon="bolt">
    Import any of the 15+ pre-built playbooks directly into Overcut. No need to build from scratch.
  </Card>

  <Card title="AI-Assisted Authoring" icon="brain-circuit">
    Built-in skills teach your AI coding agent everything about Overcut workflows, so it can create or modify playbooks for you.
  </Card>

  <Card title="Works with Any Agent" icon="plug">
    Skills are shared across Claude Code, Cursor, Codex, Gemini, and more. Use whichever tool you prefer.
  </Card>

  <Card title="Learn by Example" icon="graduation-cap">
    Study real, production-tested workflows to understand patterns and build your own.
  </Card>
</CardGroup>

***

## Getting Started

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/overcut-ai/overcut-playbooks.git
    cd overcut-playbooks
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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"*
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## 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/`).

| Skill                     | What It Teaches the Agent                                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Workflow Triggers**     | All 22 event types (issue, PR, mention, scheduled, manual), condition operators, slash command setup, and cron scheduling         |
| **Step Actions**          | The 5 action types (`agent.run`, `agent.session`, `git.clone`, `repo.identify`, `ci.executeWorkflow`) with full parameter schemas |
| **Agent Session Design**  | When to use `agent.session` vs `agent.run`, coordinator patterns, delegation templates, exit criteria, and interactive sessions   |
| **Agent Tools Reference** | All 35+ user-configurable tools across 8 categories, plus the 5 built-in agent types and their tool presets                       |
| **Template Variables**    | Handlebars `{{}}` syntax for referencing trigger context, step outputs, and using helpers like comparison and iteration           |
| **Prompt Engineering**    | Structured 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.

<Note>
  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.
</Note>

***

## 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

```bash theme={null}
python3 scripts/sync-prompts.py create-pr-from-design
```

***

## Import a Playbook into Overcut

<Steps>
  <Step title="Download the workflow file">
    Navigate to the playbook folder in the repository and download the `workflow.json` file.
  </Step>

  <Step title="Open the Workflow Builder">
    In Overcut, go to the Workflow Builder and click **Import Workflow**.
  </Step>

  <Step title="Upload the JSON file">
    Select the downloaded `workflow.json` file to import the complete workflow structure.
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Customize and publish">
    Review the imported workflow, adjust prompts or timeouts as needed, and publish it.
  </Step>
</Steps>

For full details on the import/export process, see [Import & Export Workflows](/docs/workflows/workflow-import-export).

***

## Choosing the Right Agent for Each Step

When mapping agents during import (or when building a new playbook), consider what each step needs:

| Step Purpose                   | Recommended Agent Type | Key Tools Needed                            |
| ------------------------------ | ---------------------- | ------------------------------------------- |
| Code analysis / implementation | Senior Developer       | File system, code utilities, git operations |
| Code review                    | Code Reviewer          | Pull request review, inline comments        |
| Documentation                  | Tech Writer            | File system, ticket/issue tools             |
| Planning / requirements        | Product Manager        | Ticket tools, exploration                   |
| Repository exploration         | Explore Agent          | Search, file reading                        |

<Note>
  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.
</Note>

***

## 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

<Tip>
  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."*
</Tip>

***

## 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

| Step                  | Action          | What It Does                                                           |
| --------------------- | --------------- | ---------------------------------------------------------------------- |
| **Identify Repos**    | `repo.identify` | Determines which repository the issue relates to                       |
| **Clone Repo**        | `git.clone`     | Shallow-clones the identified repository                               |
| **Prepare Context**   | `agent.run`     | Reads the issue, resolves dependencies, determines the base branch     |
| **Planning**          | `agent.session` | Creates a phased implementation plan from the design document          |
| **Setup PR**          | `agent.run`     | Creates a branch and opens a draft pull request                        |
| **Implement Changes** | `agent.session` | Implements each phase with individual commits and progress tracking    |
| **Validate**          | `agent.session` | Writes tests, runs validation, fixes lint issues                       |
| **Finalize PR**       | `agent.run`     | Updates 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`:

```bash theme={null}
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

* **[Browse the Playbooks Repository](https://github.com/overcut-ai/overcut-playbooks)**: Explore all available workflows and their READMEs
* **[Import & Export Workflows](/docs/workflows/workflow-import-export)**: Detailed guide for importing workflows into Overcut
* **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use `agent.run` vs `agent.session`
* **[Workflow Builder](/docs/how-to/workflow-builder)**: Learn the visual editor for fine-tuning imported workflows
* **[Contributing Guide](https://github.com/overcut-ai/overcut-playbooks/blob/main/CONTRIBUTING.md)**: Share your playbooks with the community