Claude Epic Workflow

GitHub Epic workflow system for Claude Code — automated issue orchestration with sub-agent support.

Stop manually tracking issue dependencies and switching branches. Define an epic, and let coordinated agents analyze, implement, test, and PR each issue in parallel — with automatic dependency ordering, self-healing quality checks, and full resumability.

Quick Start

Install via npm

npx claude-epic-workflow init

Or install globally:

npm install -g claude-epic-workflow
claude-epic init

Install from source

git clone <repo-url>
cd claude-epic-workflow
./install.sh

What It Does

Claude Epic Workflow turns your GitHub epics into fully automated development pipelines. Given an epic issue with child issues, the system analyzes dependencies, computes execution waves, creates isolated git worktrees per issue, and invokes Claude Code to implement, test, and submit pull requests — all without human intervention.

The workflow is driven by 19 Claude Code slash commands that cover every stage of the development lifecycle: from planning new epics (/epic) and implementing individual issues (/issue-auto) to reviewing PRs (/review-pr), enforcing code conventions (/gate-check), and publishing release notes (/release-note). Commands integrate with GitHub's issue tracker for real-time progress visibility.

For large epics, /epic-orchestrate spawns parallel sub-agents using Claude Code's Task tool. A dependency graph is computed using Kahn's topological sort, issues are grouped into execution waves, and up to 5 worker agents run concurrently per wave — each in its own isolated worktree. State is checkpointed to GitHub comments so orchestration survives interruptions and can be resumed across sessions.

Available Commands (19)

Issue Management

| Command | Description | |---------|-------------| | /issue <number> | Fetch GitHub issue context and post a "Work Started" comment | | /issue-auto <number> | Full automation: analyze, implement, quality-check, commit, and open PR | | /issue-quick <number> | Quick path: implement, commit, push, and close issue on current branch | | /issue-update <number> | Post a typed progress update to a GitHub issue (progress/blocker/question) | | /issue-complete | Verify changes, post completion summary, generate commit and PR description | | /review-pr <branch> | Fetch PR comments, classify actionable feedback, apply fixes, and re-push |

Epic Management

| Command | Description | |---------|-------------| | /epic <title> | Plan and create a new feature epic with structured child issues | | /epic-status <number> | Check epic progress; team-aware when orchestration is active | | /epic-analyze <number> | Deep per-issue analysis via parallel agents: file impact, conflicts, complexity | | /epic-orchestrate <number> | Full orchestration: dependency waves + parallel sub-agents per wave | | /epic-validate <number> | Validate epic/issue structure and auto-fix missing labels, task lists, parent refs |

Team and Sprint

| Command | Description | |---------|-------------| | /sprint-team | Run a predefined sprint with an explicit dependency graph using agent teams |

Code Quality

| Command | Description | |---------|-------------| | /gate-check | Pre-PR convention enforcement: security, user ID patterns, DB migrations, TypeScript | | /self-review | AI-driven code review of your own diff across 8 quality categories | | /verify | Run lint, typecheck, and security checks; auto-fix where possible |

Documentation

| Command | Description | |---------|-------------| | /update-readmes [scope] | Recursively create or update README files using parallel Sonnet agents | | /release-note <source> | Generate user-friendly release notes from commits, issues, epics, or date ranges | | /release-note-remove <version> | Remove a release note and its associated notifications |

Configuration

The installer creates .epic-workflow.json in your project root:

{
  "worktreeBase": "../worktrees",
  "branchPrefix": "feature/issue-",
  "labels": {
    "inProgress": "in-progress",
    "blocked": "blocked",
    "blockedUpstream": "blocked-upstream",
    "needsReview": "needs-review"
  },
  "validation": {
    "typecheck": "npm run typecheck",
    "test": "npm run test:quiet"
  }
}

Auto-detects Node.js, Rust, Go, and Python projects and sets sensible validation commands for each.

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | worktreeBase | Directory for worktrees (relative to repo root) | ../worktrees | | branchPrefix | Prefix for feature branches | feature/issue- | | labels.inProgress | Label for work in progress | in-progress | | labels.blocked | Label for blocked issues | blocked | | labels.blockedUpstream | Label for upstream blockers | blocked-upstream | | labels.needsReview | Label for PR review | needs-review | | validation.typecheck | Command for type checking | npx tsc --noEmit | | validation.test | Command for running tests | npm run test:quiet |

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | EPIC_MAIN_BRANCH | Main branch name for PR base and syncing | main | | EPIC_BRANCH_PREFIX | Prefix for per-epic integration branches | epic | | EPIC_STREAM_OUTPUT | Show streaming progress during runs (default: true) | true or false | | EPIC_SLACK_WEBHOOK_URL | Slack incoming webhook URL for notifications | https://hooks.slack.com/services/... | | EPIC_NOTIFICATION_CHANNEL | Override Slack channel (optional) | #epic-alerts |

Prerequisites

• Claude Code CLI installed and authenticated
• GitHub CLI (gh) authenticated with your GitHub account
• jq for JSON processing
• Git repository with a GitHub remote

# macOS
brew install gh jq

# Ubuntu/Debian
sudo apt-get install gh jq

# Authenticate GitHub CLI
gh auth login

How It Works

The core flow moves from epic planning through parallel implementation to a single integration PR:

1. Epic creation — /epic explores the codebase with parallel agents, designs a structured implementation plan, and creates an epic issue plus numbered child issues on GitHub with dependency annotations.

2. Dependency analysis — /epic-orchestrate (or the shell script's analyze subcommand) performs two-tier dependency discovery: fast text pattern extraction (depends on #X, blocked by #X) followed by parallel Explore agents that detect file-level conflicts between issues.

3. Wave computation — Kahn's topological sort groups issues into parallel execution waves. Issues with no blocking dependencies form Wave 1; each subsequent wave unlocks when its predecessors are merged.

4. Isolated worktrees — Each issue gets its own git worktree under ../worktrees/issue-42, branched from the epic integration branch (epic-<number>). This lets multiple agents work in parallel without interfering with each other.

5. Parallel sub-agents — /epic-orchestrate spawns up to 5 worker agents concurrently per wave using Claude Code's Task tool. Each worker runs /issue-auto inside its worktree: analyze → implement → typecheck/lint/test → gate-check → self-review → PR.

6. Wave merging — After each wave completes, issue PRs are merged into the epic integration branch. The next wave branches from the freshly-integrated base, so each wave builds on the previous wave's changes.

7. Resumability — Orchestration state is checkpointed to GitHub comments after each wave. If the session is interrupted, /epic-orchestrate detects the prior state and resumes from the last completed wave.

8. Epic PR — When all waves complete, a final integration PR is opened from epic-<number> into main. Full validation (typecheck, tests, build) runs on the integrated branch before the PR is created.

Error Handling and Self-Healing

/issue-auto includes a multi-phase self-healing loop. When quality checks (lint, typecheck, tests) fail, the agent automatically:

1. Analyzes the error output to identify root causes
2. Applies targeted fixes (not blind retries)
3. Re-runs the failing checks
4. Repeats up to 3 cycles before escalating

After implementation passes, a secondary review phase runs /gate-check and /self-review. If either finds critical issues, the agent fixes them and re-validates. This means most issues complete without human intervention, even when the first implementation attempt has problems.

See docs/AUTO_HEALING.md for the full algorithm.

Shell Script

scripts/epic-workflow.sh provides the CLI interface for running epics and managing worktrees:

# Preview what would happen (no side effects)
./scripts/epic-workflow.sh --dry-run run-epic 100 --auto

# Full automation — implement all issues end-to-end
./scripts/epic-workflow.sh run-epic 100 --auto

# Fast path — all issues on one branch, single PR
./scripts/epic-workflow.sh run-epic 100 --fast-auto

# Work on a single issue
./scripts/epic-workflow.sh start 42
cd ../worktrees/issue-42
claude

# Inside the Claude session:
/issue 42           # Fetch context, post "Work Started"
/issue-update 42    # Post a progress update
/issue-complete     # Verify, commit, create PR

# Other management commands
./scripts/epic-workflow.sh list 100          # List issues in epic #100
./scripts/epic-workflow.sh status           # Show active worktrees
./scripts/epic-workflow.sh cleanup 42       # Remove worktree for issue #42
./scripts/epic-workflow.sh cleanup-all      # Remove all worktrees

Auto mode vs Fast-auto mode:

| Aspect | --auto | --fast-auto | |--------|----------|---------------| | Isolation | Separate worktree per issue | Single shared branch | | PRs created | One per issue | One for the entire epic | | Quality checks | Per issue with self-healing | Once at the end | | Speed | Slower, more thorough | Faster | | Best for | Complex features, critical code | Small tasks, rapid prototyping |

Sub-Agent Architecture

/epic-analyze and /epic-orchestrate use Claude Code's Task tool to spawn parallel sub-agents:

• Research agents — analyze issue dependencies, identify affected files, and detect conflicts between issues in the same wave
• Worker agents — implement issues in isolated git worktrees, running the full /issue-auto pipeline (implement → quality checks → gate-check → self-review → PR)
• Explore agents — used during dependency discovery to perform deep file-level analysis beyond what text pattern matching can detect

The orchestrator coordinates all agents, merges completed waves, and posts progress updates to GitHub after each wave.

Epic Structure Requirements

For the epic runner to discover sub-issues, the epic issue body should reference them using task list syntax:

## Tasks

- [ ] #100 Database schema changes
- [ ] #101 API endpoints (depends on #100)
- [ ] #102 Frontend components (depends on #101)
- [ ] #103 Write integration tests (depends on #101)

Dependency Specification

Dependencies can also be declared in individual issue bodies:

## Description

Implement the user profile page.

**Depends on #100** (API endpoints must be ready)
**Blocked by #101** (database migrations)

Supported patterns: depends on #X, blocked by #X, after #X, requires #X

Customization

Gate Check Rules

gate-check.md enforces project conventions via pattern matching on the diff. The default ruleset covers 5 categories:

| Category | Rules | Severity | |----------|-------|----------| | Security | Secret exposure via public env vars, direct external API calls from client | CRITICAL/HIGH | | User IDs | Auth provider IDs used in business logic instead of internal IDs | CRITICAL/HIGH | | Database | Non-idempotent migrations, NOT NULL columns without defaults, dropped columns | CRITICAL/HIGH | | TypeScript | any type usage, unsafe error handling patterns | HIGH/MEDIUM | | Data | Mock data in production paths, leftover console.log statements | HIGH/MEDIUM |

Edit gate-check.md to add rules specific to your stack (authentication patterns, ORM conventions, API model ID formats, etc.).

Sprint Definitions

Edit sprint-team.md to define named sprints with explicit issue lists and dependency graphs. Useful for recurring release patterns where the same set of issue types is created each cycle.

README Generation Scope

/update-readmes defaults to scanning all source directories. Pass a scope argument to limit the scan:

/update-readmes client     # client/ only
/update-readmes server     # server/ only
/update-readmes all        # all directories (default)

Progress Tracking

GitHub Updates (Auto Mode)

In --auto mode, progress is posted directly to the epic issue on GitHub:

• "Run Started" comment when the epic run begins, showing total issues and mode
• Progress update after each issue completes, with a visual progress bar and issue status table
• Completion summary when all issues are processed, with timing and PR links

Local Progress File

The epic runner writes .epic-progress-<epic-number>.json locally to support resuming runs:

{
  "epic": 100,
  "started": "2025-03-01T10:00:00Z",
  "mode": "auto",
  "issues": {
    "101": { "status": "completed", "pr_url": "...", "duration_minutes": 15 },
    "102": { "status": "in_progress", "started": "..." }
  },
  "parallelBatches": [[101, 103], [102]],
  "stats": { "completed": 3, "failed": 0, "retries": 1 }
}

Notifications

The workflow sends notifications when human attention is needed (PR merge timeout, unresolvable review comments, blocked issues):

# Set up Slack notifications
export EPIC_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"
export EPIC_NOTIFICATION_CHANNEL="#releases"

Desktop notifications are also sent automatically on macOS (osascript) and Linux (notify-send). A notification log is written to .epic-notifications.log.

CLI Reference

claude-epic init          Install to current project
claude-epic update        Update templates to latest version
claude-epic remove        Uninstall from project
claude-epic doctor        Check installation health

Uninstall

./scripts/epic-workflow.sh cleanup-all
claude-epic remove

Or manually remove the installed files:

rm -f scripts/epic-workflow.sh
rm -f .claude/commands/{epic,epic-status,epic-analyze,epic-orchestrate}.md
rm -f .claude/commands/{issue,issue-auto,issue-quick,issue-update,issue-complete}.md
rm -f .claude/commands/{review-pr,verify,self-review,gate-check,sprint-team}.md
rm -f .claude/commands/{update-readmes,release-note,release-note-remove}.md
rm -f .epic-workflow.json .epic-progress-*.json .epic-notifications.log

License

MIT