autopilot

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# BMAD Autopilot

[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](VERSION)

**Autonomous Development Orchestrator for Claude Code**

BMAD Autopilot is a state-machine-driven bash orchestrator that automates the entire development cycle from epic selection to PR merge. It works with Claude Code CLI and GitHub Copilot to provide a fully autonomous development experience.

## Features

- 🤖 **Fully Autonomous** - No human intervention required after starting
- 🔄 **State Machine** - Resumable workflow that survives interruptions
- 📋 **Multi-Epic Support** - Process all epics or filter by pattern
- 🔍 **GitHub Copilot Integration** - Waits for reviews, fixes issues, replies to comments
- ✅ **CI Integration** - Waits for checks, fixes failures automatically
- 📝 **Detailed Logging** - Full audit trail in `.autopilot/autopilot.log`
- 🔀 **Parallel Mode** - Work on next epic while waiting for PR review (experimental)
- 🔒 **Secure Config** - Safe config parsing with whitelisted keys only

## Prerequisites

Required tools:
- `claude` - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
- `gh` - [GitHub CLI](https://cli.github.com/)
- `jq` - JSON processor
- `rg` - [ripgrep](https://github.com/BurntSushi/ripgrep)
- `git` - Git version control

## Installation

### Quick Install

```bash
# Clone the repository
git clone https://github.com/hanibalsk/autopilot.git
cd autopilot

# Run the install script
./install.sh
```

### Manual Install

1. Copy the main script to your project:

```bash
mkdir -p /your/project/.autopilot
cp scripts/bmad-autopilot.sh /your/project/.autopilot/
chmod +x /your/project/.autopilot/bmad-autopilot.sh
```

2. (Optional) Install Claude Code commands:

```bash
# Local installation (recommended)
mkdir -p /your/project/.claude/commands
cp commands/*.md /your/project/.claude/commands/

# Or global installation
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/
```

## Usage

### Basic Usage

```bash
# From your project root:
cd /path/to/your/project

# Process ALL epics from _bmad-output/epics.md
./.autopilot/bmad-autopilot.sh

# Process specific epics only
./.autopilot/bmad-autopilot.sh "7A 8A 10B"

# Process epic with suffix
./.autopilot/bmad-autopilot.sh "10A-SSO"

# Use regex patterns
./.autopilot/bmad-autopilot.sh "10A.*"      # matches 10A, 10A-SSO, etc.
./.autopilot/bmad-autopilot.sh "7.* 10.*"   # multiple patterns
```

### Resume After Interruption

```bash
# Resume from where it left off
./.autopilot/bmad-autopilot.sh --continue

# Resume with specific pattern
./.autopilot/bmad-autopilot.sh "7A" --continue
```

### Using Claude Code Commands

If you installed the Claude Code commands:

```
/autopilot           # process all epics
/autopilot 7A 8A     # specific epics
```

## Workflow State Machine

```
┌─────────────────────────────────────────────────────────────────┐
│  CHECK_PENDING_PR -> FIND_EPIC -> CREATE_BRANCH ->              │
│  DEVELOP_STORIES -> CODE_REVIEW -> CREATE_PR ->                 │
│  WAIT_COPILOT -> (add to pending) -> FIND_EPIC (next epic)     │
│       │                                                         │
│       ▼                                                         │
│  FIX_ISSUES ◄─── (if unresolved threads exist)                 │
│       │                                                         │
│       └──────► WAIT_COPILOT (re-review after fixes)            │
│                                                                 │
│  Background: pending PRs auto-merged when approved              │
└─────────────────────────────────────────────────────────────────┘
```

### Phase Descriptions

| Phase | Description |
|-------|-------------|
| `CHECK_PENDING_PR` | Look for unfinished PRs from previous runs |
| `FIND_EPIC` | Find next epic from `_bmad-output/epics*.md` |
| `CREATE_BRANCH` | Create `feature/epic-{ID}` branch |
| `DEVELOP_STORIES` | Run BMAD dev-story workflow via Claude (interactive) |
| `CODE_REVIEW` | Run BMAD code-review workflow, fix issues (interactive) |
| `CREATE_PR` | Create PR, add to pending list, continue to next epic |
| `WAIT_COPILOT` | Check Copilot review - if no issues, continue to next epic |
| `FIX_ISSUES` | Fix issues, post reply, resolve threads, loop back |
| `MERGE_PR` | Squash merge, delete branch, mark complete |
| `DONE` | All epics processed! |
| `BLOCKED` | Manual intervention needed |

### Auto-Approve Workflow

The `auto-approve.yml` GitHub workflow handles PR approval automatically:

**Approval conditions (ALL must be met):**
1. At least 10 minutes since last push
2. Copilot review exists
3. All review threads resolved
4. All CI checks passed

**Features:**
- Dismisses stale approvals if unresolved threads exist
- Autopilot continues to next epic immediately after PR creation
- Pending PRs are monitored and auto-merged when approved

### FIX_ISSUES Phase

When Copilot has review comments:
1. Fetches unresolved thread content (file, line, comment) via GraphQL
2. Claude fixes the issues
3. Posts reply to PR acknowledging feedback
4. Resolves all threads via GraphQL mutation
5. Pushes fixes → Copilot re-reviews → auto-approve triggers

## Configuration

### Configuration File

Copy `config.example` to `.autopilot/config` and customize:

```bash
cp .autopilot/config.example .autopilot/config
```

Settings can be configured via (in order of priority):
1. Command line flags (`--debug`)
2. Environment variables (`AUTOPILOT_DEBUG=1`)
3. Config file (`.autopilot/config`)

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AUTOPILOT_DEBUG` | `0` | Enable debug logging to `.autopilot/tmp/debug.log` |
| `MAX_TURNS` | `80` | Max Claude turns per phase |
| `CHECK_INTERVAL` | `30` | Seconds between CI/Copilot checks |
| `MAX_CHECK_WAIT` | `60` | Max iterations waiting for CI checks |
| `MAX_COPILOT_WAIT` | `60` | Max iterations waiting for Copilot review |
| `AUTOPILOT_RUN_MOBILE_NATIVE` | `0` | Set to `1` to run Gradle builds |
| `AUTOPILOT_BASE_BRANCH` | auto | Override base branch (auto-detects main/master) |

### Execution Mode

| Variable | Default | Description |
|----------|---------|-------------|
| `PARALLEL_MODE` | `0` | `0` = sequential, `1+` = use git worktrees |
| `PARALLEL_CHECK_INTERVAL` | `60` | Seconds between pending PR checks |
| `MAX_PENDING_PRS` | `2` | Max concurrent PRs in pending list |

**All modes auto-continue:** After creating a PR, the autopilot immediately continues to the next epic. PR reviews run in background and are auto-merged when approved.

- `PARALLEL_MODE=0`: One branch at a time on main worktree (simple)
- `PARALLEL_MODE=1+`: Uses git worktrees for parallel branch management (useful when fixing multiple PRs)

### Epic Source Files

The autopilot reads epics from `_bmad-output/` directory:

- `epics.md`
- `@epics.md`
- `epics-002.md`, `epics-*.md`, etc.

Epic IDs are extracted from lines like:
```markdown
#### Epic 7A: User Authentication
#### Epic 10A-SSO: Cross-Platform SSO
```

## Project Structure

```
.autopilot/
├── bmad-autopilot.sh    # Main orchestrator script
├── state.json           # Current state (auto-managed)
├── autopilot.log        # Full execution log
└── tmp/                 # Temporary files
    ├── copilot.txt
    ├── copilot_latest.json
    └── claude-output.txt
```

## Customization

### Local Checks

The `autopilot_checks()` function in the script auto-detects your project type:

- **Rust** (`backend/Cargo.toml`): `cargo fmt`, `cargo clippy`, `cargo test`
- **TypeScript/pnpm** (`frontend/package.json`): `pnpm run check`, `pnpm run test`
- **Gradle** (`mobile-native/gradlew`): Optional, set `AUTOPILOT_RUN_MOBILE_NATIVE=1`

Modify this function to add your own checks.

### BMAD Workflows

The script calls these BMAD workflows:
- `/bmad:bmm:workflows:dev-story` - Story development
- `/bmad:bmm:workflows:code-review` - Code review

Ensure these are available in your `.claude/commands/bmad/` or `.cursor/rules/bmad/`.

## Troubleshooting

### View Logs

```bash
tail -f .autopilot/autopilot.log
```

### Check State

```bash
cat .autopilot/state.json | jq
```

### Reset State

```bash
rm .autopilot/state.json
```

### Debug Mode

```bash
# Via command line flag
./.autopilot/bmad-autopilot.sh --debug

# Via environment variable
AUTOPILOT_DEBUG=1 ./.autopilot/bmad-autopilot.sh

# View debug log
tail -f .autopilot/tmp/debug.log
```

Debug mode logs detailed information about Copilot detection, state transitions, and API calls.

## License

MIT License - see [LICENSE](https://github.com/hanibalsk/autopilot/tree/HEAD/LICENSE)

## Contributing

Contributions welcome! Please read the contributing guidelines first.

## Credits

Built for use with [BMAD Method](https://github.com/bmad-method) and Claude Code.

BMAD Autopilot

Autonomous Development Orchestrator for Claude Code

BMAD Autopilot is a state-machine-driven bash orchestrator that automates the entire development cycle from epic selection to PR merge. It works with Claude Code CLI and GitHub Copilot to provide a fully autonomous development experience.

Features

🤖 Fully Autonomous - No human intervention required after starting
🔄 State Machine - Resumable workflow that survives interruptions
📋 Multi-Epic Support - Process all epics or filter by pattern
🔍 GitHub Copilot Integration - Waits for reviews, fixes issues, replies to comments
✅ CI Integration - Waits for checks, fixes failures automatically
📝 Detailed Logging - Full audit trail in .autopilot/autopilot.log
🔀 Parallel Mode - Work on next epic while waiting for PR review (experimental)
🔒 Secure Config - Safe config parsing with whitelisted keys only

Prerequisites

Required tools:

claude - Claude Code CLI
gh - GitHub CLI
jq - JSON processor
rg - ripgrep
git - Git version control

Installation

Quick Install

# Clone the repository
git clone https://github.com/hanibalsk/autopilot.git
cd autopilot

# Run the install script
./install.sh

Manual Install

Copy the main script to your project:

mkdir -p /your/project/.autopilot
cp scripts/bmad-autopilot.sh /your/project/.autopilot/
chmod +x /your/project/.autopilot/bmad-autopilot.sh

(Optional) Install Claude Code commands:

# Local installation (recommended)
mkdir -p /your/project/.claude/commands
cp commands/*.md /your/project/.claude/commands/

# Or global installation
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

Usage

Basic Usage

# From your project root:
cd /path/to/your/project

# Process ALL epics from _bmad-output/epics.md
./.autopilot/bmad-autopilot.sh

# Process specific epics only
./.autopilot/bmad-autopilot.sh "7A 8A 10B"

# Process epic with suffix
./.autopilot/bmad-autopilot.sh "10A-SSO"

# Use regex patterns
./.autopilot/bmad-autopilot.sh "10A.*"      # matches 10A, 10A-SSO, etc.
./.autopilot/bmad-autopilot.sh "7.* 10.*"   # multiple patterns

Resume After Interruption

# Resume from where it left off
./.autopilot/bmad-autopilot.sh --continue

# Resume with specific pattern
./.autopilot/bmad-autopilot.sh "7A" --continue

Using Claude Code Commands

If you installed the Claude Code commands:

/autopilot           # process all epics
/autopilot 7A 8A     # specific epics

Workflow State Machine

┌─────────────────────────────────────────────────────────────────┐
│  CHECK_PENDING_PR -> FIND_EPIC -> CREATE_BRANCH ->              │
│  DEVELOP_STORIES -> CODE_REVIEW -> CREATE_PR ->                 │
│  WAIT_COPILOT -> (add to pending) -> FIND_EPIC (next epic)     │
│       │                                                         │
│       ▼                                                         │
│  FIX_ISSUES ◄─── (if unresolved threads exist)                 │
│       │                                                         │
│       └──────► WAIT_COPILOT (re-review after fixes)            │
│                                                                 │
│  Background: pending PRs auto-merged when approved              │
└─────────────────────────────────────────────────────────────────┘

Phase Descriptions

Phase	Description
`CHECK_PENDING_PR`	Look for unfinished PRs from previous runs
`FIND_EPIC`	Find next epic from `_bmad-output/epics*.md`
`CREATE_BRANCH`	Create `feature/epic-{ID}` branch
`DEVELOP_STORIES`	Run BMAD dev-story workflow via Claude (interactive)
`CODE_REVIEW`	Run BMAD code-review workflow, fix issues (interactive)
`CREATE_PR`	Create PR, add to pending list, continue to next epic
`WAIT_COPILOT`	Check Copilot review - if no issues, continue to next epic
`FIX_ISSUES`	Fix issues, post reply, resolve threads, loop back
`MERGE_PR`	Squash merge, delete branch, mark complete
`DONE`	All epics processed!
`BLOCKED`	Manual intervention needed

Auto-Approve Workflow

The auto-approve.yml GitHub workflow handles PR approval automatically:

Approval conditions (ALL must be met):

At least 10 minutes since last push
Copilot review exists
All review threads resolved
All CI checks passed

Features:

Dismisses stale approvals if unresolved threads exist
Autopilot continues to next epic immediately after PR creation
Pending PRs are monitored and auto-merged when approved

FIX_ISSUES Phase

When Copilot has review comments:

Fetches unresolved thread content (file, line, comment) via GraphQL
Claude fixes the issues
Posts reply to PR acknowledging feedback
Resolves all threads via GraphQL mutation
Pushes fixes → Copilot re-reviews → auto-approve triggers

Configuration

Configuration File

Copy config.example to .autopilot/config and customize:

cp .autopilot/config.example .autopilot/config

Settings can be configured via (in order of priority):

Command line flags (--debug)
Environment variables (AUTOPILOT_DEBUG=1)
Config file (.autopilot/config)

Environment Variables

Variable	Default	Description
`AUTOPILOT_DEBUG`	`0`	Enable debug logging to `.autopilot/tmp/debug.log`
`MAX_TURNS`	`80`	Max Claude turns per phase
`CHECK_INTERVAL`	`30`	Seconds between CI/Copilot checks
`MAX_CHECK_WAIT`	`60`	Max iterations waiting for CI checks
`MAX_COPILOT_WAIT`	`60`	Max iterations waiting for Copilot review
`AUTOPILOT_RUN_MOBILE_NATIVE`	`0`	Set to `1` to run Gradle builds
`AUTOPILOT_BASE_BRANCH`	auto	Override base branch (auto-detects main/master)

Execution Mode

Variable	Default	Description
`PARALLEL_MODE`	`0`	`0` = sequential, `1+` = use git worktrees
`PARALLEL_CHECK_INTERVAL`	`60`	Seconds between pending PR checks
`MAX_PENDING_PRS`	`2`	Max concurrent PRs in pending list

All modes auto-continue: After creating a PR, the autopilot immediately continues to the next epic. PR reviews run in background and are auto-merged when approved.

PARALLEL_MODE=0: One branch at a time on main worktree (simple)
PARALLEL_MODE=1+: Uses git worktrees for parallel branch management (useful when fixing multiple PRs)

Epic Source Files

The autopilot reads epics from _bmad-output/ directory:

epics.md
@epics.md
epics-002.md, epics-*.md, etc.

Epic IDs are extracted from lines like:

#### Epic 7A: User Authentication
#### Epic 10A-SSO: Cross-Platform SSO

Project Structure

.autopilot/
├── bmad-autopilot.sh    # Main orchestrator script
├── state.json           # Current state (auto-managed)
├── autopilot.log        # Full execution log
└── tmp/                 # Temporary files
    ├── copilot.txt
    ├── copilot_latest.json
    └── claude-output.txt

Customization

Local Checks

The autopilot_checks() function in the script auto-detects your project type:

Rust (backend/Cargo.toml): cargo fmt, cargo clippy, cargo test
TypeScript/pnpm (frontend/package.json): pnpm run check, pnpm run test
Gradle (mobile-native/gradlew): Optional, set AUTOPILOT_RUN_MOBILE_NATIVE=1

Modify this function to add your own checks.

BMAD Workflows

The script calls these BMAD workflows:

/bmad:bmm:workflows:dev-story - Story development
/bmad:bmm:workflows:code-review - Code review

Ensure these are available in your .claude/commands/bmad/ or .cursor/rules/bmad/.

Troubleshooting

View Logs

tail -f .autopilot/autopilot.log

Check State

cat .autopilot/state.json | jq

Reset State

rm .autopilot/state.json

Debug Mode

# Via command line flag
./.autopilot/bmad-autopilot.sh --debug

# Via environment variable
AUTOPILOT_DEBUG=1 ./.autopilot/bmad-autopilot.sh

# View debug log
tail -f .autopilot/tmp/debug.log

Debug mode logs detailed information about Copilot detection, state transitions, and API calls.

License

MIT License - see LICENSE

Contributing

Contributions welcome! Please read the contributing guidelines first.

Credits

Built for use with BMAD Method and Claude Code.