AGENTS.md

This file provides instructions for AI agents working with the Overcut Playbooks repository. It contains essential information for creating, updating, and maintaining playbooks (workflow templates).

📋 Project Overview

This repository contains Overcut Playbooks - pre-built, customizable AI agent workflows for software development automation. Each playbook is a complete workflow that can be imported into Overcut and customized for specific needs.

Key Technologies:

Overcut Workflow JSON format (version 1.0.0)
Markdown for prompts and documentation
Git for version control

Detailed Reference Skills: The .agents/skills/ directory contains deep-dive reference skills for triggers, step actions, agent sessions, template variables, prompt engineering, and agent tools. These are symlinked into each agent's config folder (.claude/, .cursor/, .codex/, .gemini/, .agent/) and activate automatically when relevant.

🏗️ Repository Structure

Each playbook must follow this structure:

playbook-name/
├── workflow.json          # Complete workflow definition (REQUIRED)
├── README.md              # Documentation following standard template (REQUIRED)
├── step-id-name.md        # Prompt file for each step (REQUIRED - one per step)
├── another-step-id.md     # Additional step prompts as needed
├── special-agents/        # (OPTIONAL) Specialized agent instructions
│   └── agent-name.md      # Instructions for configuring custom agents
└── ...                    # More steps as needed

🎯 Creating New Playbooks

Follow this design-first approach to ensure the workflow is well-planned before implementation:

Step 1: Create Playbook Folder

Naming: Use lowercase-with-hyphens (e.g., auto-code-review, migration-assistant)
Location: Root of repository
Command: mkdir playbook-name && cd playbook-name

Step 2: Create README.md with High-Level Flow

Start with the design and documentation first. This helps clarify the workflow structure before implementation.

Use this template structure:

# [Workflow Name]

## 📋 Overview

[2-3 sentences about what it does and outputs]

## ⚡ Triggers

[Automatic and manual triggers]

## 🎯 Use Cases

[When to use this workflow]

## 🔧 Prerequisites

[Required setup, agents needed]

## 🏗️ Workflow Steps

[Step-by-step breakdown with agent assignments and durations]

- List each step with its purpose, agent type, and estimated duration
- Describe the flow between steps
- Identify what data passes between steps

## 🎨 Customization

[How to adapt the workflow, which prompts to edit]

## 🔗 Related Workflows

[Links to related playbooks]

README Requirements:

Complete all sections, especially the "Workflow Steps" section
Define the high-level flow and step sequence
Document what each step does and which agents are needed
Include customization guide
Document prerequisites clearly
Add related workflow links
Grammar and spelling checked

Purpose: The README serves as the design document. It should clearly describe:

What the workflow does
How it flows from step to step
What each step accomplishes
What data/context flows between steps

Step 3: Create Step Prompt Files

After the README is approved, create the prompt files. This ensures the prompts align with the design and makes sense before creating the JSON structure.

CRITICAL NAMING RULE: Prompt filenames MUST match the step IDs you'll use in workflow.json (use kebab-case).

Process:

Identify steps from README: Based on the "Workflow Steps" section, list all steps
Name each step: Use descriptive kebab-case names (e.g., prepare-review-plan, code-review, submit-review)
Create prompt files: For each step, create {step-id}.md with detailed instructions

Example:

Planned step: "Prepare Review Plan"
Step ID: prepare-review-plan
Prompt filename: prepare-review-plan.md ✅
NOT: step-1-prepare-review-plan.md ❌
NOT: prepareReviewPlan.md ❌

For each step:

Create a .md file with the step ID as the filename
Write clear, detailed instructions for that step
Include:
- What the step should accomplish
- What inputs it receives (from previous steps or triggers)
- What outputs it should produce
- How to handle errors
- Format requirements for outputs

Prompt File Guidelines:

Use clear, specific instructions
Include examples when helpful
Handle error cases explicitly
Specify output format requirements
Pass complete context between steps using {{outputs.step-id.message}} for agent steps or {{outputs.step-id}} for infrastructure steps
Reference the step's role in the overall workflow
Ensure prompts align with the README design

Purpose: Creating prompts first helps validate:

The workflow design makes sense
Steps have clear responsibilities
Data flow between steps is well-defined
The prompts are complete and actionable

Step 4: Create workflow.json

Finally, create the workflow.json based on the approved README design and prompt files. The JSON structure should implement exactly what was designed.

The workflow.json file must follow this structure:

{
  "_formatVersion": "1.0.0",
  "workflow": {
    "name": "Workflow Display Name",
    "description": "Brief description of what the workflow does",
    "instructions": [...],
    "definition": {
      "flow": [...],
      "name": "Workflow Name",
      "steps": [...],
      "triggers": [...],
      "version": "1.0.0",
      "priority": 3,
      "timeoutMs": 3600000
    }
  },
  "refs": {
    "agents": [...]
  }
}

Key Requirements:

Step IDs must match prompt filenames exactly (e.g., if you have prepare-review-plan.md, the step ID must be "prepare-review-plan")
Valid JSON syntax (validate before committing)
Each step must have a unique id field
Step IDs must be kebab-case (e.g., prepare-review-plan, code-review)
Include appropriate stepMaxDurationMinutes for each step
Define triggers (automatic events or manual slash commands)
Include agent references in refs.agents array
Flow connections must match the sequence described in README
Set instruction to null for infrastructure steps (git.clone, repo.identify) — prompt content will be synced separately

Implementation Process:

Create steps array: For each prompt file, create a step object with:
- id: Must match the prompt filename (without .md)
- name: Human-readable step name
- action: agent.run, agent.session, git.clone, etc.
- params: Step-specific parameters
- instruction: Set to null initially (will be synced from .md files)
- stepMaxDurationMinutes: Based on README estimates
Create flow array: Define connections between steps based on README workflow sequence
Create triggers: Based on README trigger section
Add agent references: List all agents used in refs.agents
Sync prompt content into workflow.json using the sync script:

python3 scripts/sync-prompts.py <playbook-directory>

This automatically copies content from each {step-id}.md file into the matching step's instruction field in workflow.json, handling JSON escaping correctly.

Validation:

Run python3 scripts/sync-prompts.py <playbook-directory> — it reports any mismatches
Verify flow matches README sequence
Verify triggers match README description

Step 5: Special Agents (If Needed)

When to use special-agents/ folder:

✅ Specialized roles requiring domain-specific knowledge (e.g., Security Engineer, Database Architect)
✅ Agents needing detailed behavioral guidelines or decision frameworks
✅ Custom agent personas unique to this workflow

When NOT to use:

❌ Generic roles (Backend Developer, Frontend Developer, Code Reviewer)
❌ Agents that work with default Overcut configurations
❌ Simple delegation without specialized expertise

Special Agent File Structure:

# [Agent Name] Agent Instructions

## Role Identity

[Who the agent is and their expertise]

## Core Responsibilities

[What the agent does]

## Expertise

[Technical knowledge areas]

## Key Principles

[Behavioral guidelines]

## Analysis Framework

[Decision-making process]

🔄 Updating Existing Playbooks

Updating Prompts

Edit the prompt file (e.g., code-review.md)
Run the sync script to update workflow.json automatically:

python3 scripts/sync-prompts.py <playbook-directory>

Example:

# Edit the prompt file
vim code-review/code-review.md

# Sync all prompts into workflow.json
python3 scripts/sync-prompts.py code-review

The script reads all *.md files in the playbook directory (excluding README.md), matches each to a step in workflow.json by filename == step ID, and updates the instruction field with the file content. It handles JSON escaping automatically and reports any mismatches between .md files and steps.

Important: Always use this script instead of manually copying prompt content into workflow.json. Manual copying is error-prone due to JSON string escaping (newlines, quotes, etc.).

Adding New Steps

Add step to workflow.json with unique id
Create corresponding {step-id}.md file
Add flow connection in workflow.definition.flow
Update README.md workflow steps section

Modifying Workflow Structure

Update workflow.definition.flow for step connections
Maintain valid JSON structure
Update README.md to reflect changes
Test workflow import in Overcut

✅ Quality Standards

Workflow Files (workflow.json)

✅ Valid JSON syntax (no trailing commas, proper escaping)
✅ Complete step definitions (id, name, action, params, instruction)
✅ Clear step names and descriptions
✅ Appropriate timeout values (stepMaxDurationMinutes)
✅ Proper flow connections (all steps reachable)
✅ Valid trigger configurations
✅ Tested and working in Overcut

Prompt Files (*.md)

✅ Filename matches step ID exactly (case-sensitive)
✅ Clear, specific instructions
✅ Include examples when helpful
✅ Handle error cases explicitly
✅ Specify output format requirements
✅ Pass complete context between steps using {{outputs.step-id.message}} (agent steps) or {{outputs.step-id}} (infrastructure steps)
✅ No sensitive data or credentials

Documentation (README.md)

✅ Grammar and spelling checked
✅ All template sections completed
✅ Code examples are accurate
✅ Customization guide included
✅ Prerequisites clearly stated
✅ Related workflows linked

Special Agents (special-agents/*.md)

✅ Only for specialized domain expertise
✅ Clear role identity and expertise areas
✅ Key principles and decision frameworks included
✅ Examples provided where helpful

🔧 Common Workflow Patterns

Step Actions Quick Reference

Action	Purpose	Has Instruction?	Key Params
`agent.run`	Single agent executes a prompt	Yes	`agentId`, `agentEngine`
`agent.session`	Coordinator orchestrates agents	Yes	`agentIds`, `goal`, `exitCriteria`
`git.clone`	Clone repositories	No	`repoFullName`, `branch`, `cloneOptions`
`repo.identify`	Identify relevant repos for a ticket	No	`maxResults`, `minConfidence`
`ci.executeWorkflow`	Trigger external CI pipeline	No	`repoFullName`, `workflowId`, `ref`, `inputs`

For complete parameter schemas, see the step-actions skill.

Git Operations

{
  "id": "git-clone",
  "name": "Clone Repo",
  "action": "git.clone",
  "params": {
    "branch": "{{trigger.pullRequest.headBranch}}",
    "repoFullName": "{{trigger.repository.fullName}}"
  }
}

Agent Run (Single Agent)

Use agent.run for straightforward, single-pass tasks where one agent can complete the work without coordination or iteration.

{
  "id": "step-id",
  "name": "Step Name",
  "action": "agent.run",
  "params": {
    "agentId": "agent-id-here"
  },
  "instruction": "[Content from step-id.md]"
}

Agent Session (Coordinated Execution)

Use agent.session when a step needs a coordinator to oversee execution. This applies not only to multi-agent coordination, but also to:

Multi-step processes that require sequencing, verification between steps, or iterative refinement
Error recovery where a coordinator can detect failures, retry, or adjust course
Iterative loops (e.g., draft → review → revise → approve cycles) that need supervision to track progress and enforce limits
Verification-heavy tasks where each sub-task's output must be confirmed before proceeding to the next

The coordinator pattern ensures reliability by giving an orchestrating agent oversight of the process, rather than relying on a single agent to self-manage complex sequences.

{
  "id": "step-id",
  "name": "Step Name",
  "action": "agent.session",
  "params": {
    "goal": "Goal description",
    "agentIds": ["agent-id-1", "agent-id-2"],
    "agentEngine": "overcut",
    "exitCriteria": {
      "timeLimit": {
        "maxDurationMinutes": 30
      }
    }
  },
  "instruction": "[Content from step-id.md]"
}

For coordinator tools, delegation templates, and interactive session patterns, see the agent-session-design skill.

Repository Identification (Issue-Triggered Workflows)

Use repo.identify → git.clone when a workflow starts from an issue/ticket and needs to determine which repos to work with:

{
  "id": "identify-repos",
  "name": "Identify Repositories",
  "action": "repo.identify",
  "params": {
    "maxResults": 3,
    "minConfidence": 0.2
  },
  "instruction": null
}

Chain it with git.clone using template syntax:

{
  "id": "clone-repo",
  "action": "git.clone",
  "params": {
    "repoFullName": "{{outputs.identify-repos}}",
    "cloneOptions": { "depth": 1 }
  }
}

Flow Connections

{
  "flow": [
    {
      "to": "step-2",
      "from": "step-1",
      "condition": null
    }
  ]
}

Triggers

Automatic (Event-based):

{
  "event": "pull_request_opened",
  "conditions": {
    "combinator": "and",
    "rules": [
      { "field": "context.pullRequest.draft", "operator": "equals", "value": "false" }
    ]
  }
}

Manual (Slash Command):

{
  "event": "manual",
  "slashCommand": {
    "command": "review",
    "requireMention": false
  }
}

CI Workflow (Event-based):

{
  "event": "ci_workflow_failed",
  "conditions": {
    "combinator": "and",
    "rules": [
      { "field": "context.ciWorkflow.branch", "operator": "equals", "value": "main" }
    ]
  }
}

For all 28 event types, condition operators, schedule triggers, and real-world examples, see the workflow-triggers skill.

Workflow Configuration

Field	Default	Description
`priority`	5	Execution priority (1-100, lower = higher priority)
`timeoutMs`	—	Abort workflow after this time (min: 30000ms)
`statusUpdateMethod`	`"comment"`	`"comment"`, `"reuse_comment"`, or `"static_comment"`

🚨 Critical Rules

Filename-ID Matching: Prompt filenames MUST match step IDs exactly (case-sensitive, kebab-case)
No Sensitive Data: Never include API keys, tokens, credentials, or organization-specific agent IDs
Valid JSON: Always validate JSON syntax before committing
Complete Documentation: Every playbook must have a complete README.md
Tested Workflows: Only submit workflows that have been tested in Overcut

📝 Output Reference Syntax

When passing data between steps, use this syntax:

{{outputs.step-id}} - Reference full output from infrastructure steps (git.clone, repo.identify)
{{outputs.step-id.message}} - Reference text output from agent steps (agent.run, agent.session)
{{trigger.pullRequest.headBranch}} - Reference PR branch
{{trigger.repository.fullName}} - Reference repository name
{{trigger.issue.title}} - Reference issue title
{{trigger.trigger.label}} - Reference trigger-specific data (e.g., label that was added)

For the complete list of trigger context fields and Handlebars helpers, see the template-variables skill.

🔍 Validation Checklist

Before submitting a playbook, verify:

All prompt filenames match step IDs exactly
workflow.json has valid JSON syntax
All steps have corresponding .md files
README.md follows template and is complete
No sensitive data included
Flow connections are valid (all steps reachable)
Triggers are properly configured
Special agents (if any) are documented appropriately
Workflow has been tested in Overcut

📚 Reference Examples

Study these playbooks for patterns, ordered by complexity:

Simple (good starting point):

Auto PR Description (auto-pr-description/) — 3 steps, agent.run only, conditional skip pattern, idempotency markers

Medium (introduces coordination):

Remediate CVEs (remediate-cves/) — 4 steps, repo.identify → git.clone chain, agent.session, label-based triggers, specialized agents
Code Review (code-review/) — 5 steps, scratchpad tools + JSONL pattern, chunk processing, multi-agent delegation with tool constraints

Complex (full patterns):

Create PR from Design (create-pr-from-design/) — 8 steps, blocking/gating, dependency resolution, phased implementation, progress tracking

🎯 Common Tasks

Task: Create New Playbook

Follow the design-first approach:

Create folder with kebab-case name
Create README.md with high-level flow design (triggers, steps, data flow)
Create {step-id}.md prompt files for each planned step (validate design makes sense)
Generate workflow.json based on approved README design and prompt files
Add special-agents/ if needed
Validate JSON syntax and step ID ↔ filename matching
Test workflow in Overcut

Task: Update Existing Prompt

Edit the {step-id}.md file
Update workflow.json: find step with matching id, update instruction field
Verify filename still matches step ID
Update README.md if step behavior changed significantly

Task: Add Step to Existing Workflow

Follow the design-first approach:

Update README.md workflow steps section (document the new step's purpose and position in flow)
Create {step-id}.md prompt file (ensure it makes sense in the workflow context)
Add step to workflow.json with unique id matching the prompt filename
Add flow connection in workflow.definition.flow
Copy prompt content to step's instruction field in workflow.json

Task: Fix Workflow Issues

Validate JSON syntax
Check all step IDs are unique
Verify all prompt files exist and match step IDs
Check flow connections (no orphaned steps)
Verify trigger configuration

🔗 Additional Resources

Overcut Documentation
CONTRIBUTING.md - Detailed contribution guidelines
README.md - Repository overview and playbook catalog

Remember: The goal is to create reusable, well-documented workflows that help developers automate common software development tasks. Quality and clarity are more important than speed.

Navigation Menu

Uh oh!

AGENTS.md

📋 Project Overview

🏗️ Repository Structure

🎯 Creating New Playbooks

Step 1: Create Playbook Folder

Step 2: Create README.md with High-Level Flow

Step 3: Create Step Prompt Files

Step 4: Create workflow.json

Step 5: Special Agents (If Needed)

🔄 Updating Existing Playbooks

Updating Prompts

Adding New Steps

Modifying Workflow Structure

✅ Quality Standards

Workflow Files (workflow.json)

Prompt Files (*.md)

Documentation (README.md)

Special Agents (special-agents/*.md)

🔧 Common Workflow Patterns

Step Actions Quick Reference

Git Operations

Agent Run (Single Agent)

Agent Session (Coordinated Execution)

Repository Identification (Issue-Triggered Workflows)

Flow Connections

Triggers

Workflow Configuration

🚨 Critical Rules

📝 Output Reference Syntax

🔍 Validation Checklist

📚 Reference Examples

🎯 Common Tasks

Task: Create New Playbook

Task: Update Existing Prompt

Task: Add Step to Existing Workflow

Task: Fix Workflow Issues

🔗 Additional Resources

Uh oh!

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md

📋 Project Overview

🏗️ Repository Structure

🎯 Creating New Playbooks

Step 1: Create Playbook Folder

Step 2: Create README.md with High-Level Flow

Step 3: Create Step Prompt Files

Step 4: Create workflow.json

Step 5: Special Agents (If Needed)

🔄 Updating Existing Playbooks

Updating Prompts

Adding New Steps

Modifying Workflow Structure

✅ Quality Standards

Workflow Files (workflow.json)

Prompt Files (*.md)

Documentation (README.md)

Special Agents (special-agents/*.md)

🔧 Common Workflow Patterns

Step Actions Quick Reference

Git Operations

Agent Run (Single Agent)

Agent Session (Coordinated Execution)

Repository Identification (Issue-Triggered Workflows)

Flow Connections

Triggers

Workflow Configuration

🚨 Critical Rules

📝 Output Reference Syntax

🔍 Validation Checklist

📚 Reference Examples

🎯 Common Tasks

Task: Create New Playbook

Task: Update Existing Prompt

Task: Add Step to Existing Workflow

Task: Fix Workflow Issues

🔗 Additional Resources