npm package: @baseappnet/github-flow
Description: CLI tool for managing GitHub Issues and Pull Requests with an AI agent review pipeline
Author: BaseApp
Latest version: 1.0.3

# GitHub Flow Manager

A CLI tool and library for managing GitHub Issues and Pull Requests with an AI agent review pipeline. This tool orchestrates multi-agent code reviews using GitHub Copilot, automatically transitioning tasks through a configurable review pipeline.

## Overview

When a task is created, GitHub Copilot picks it up and creates a Pull Request. The workflow manager then cycles the PR through multiple AI "reviewer" personas (each with different expertise), and finally assigns it to a human for final approval.

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Frontend       │ ──► │  Security       │ ──► │  Testing        │ ──► │  Human          │
│  Architect      │     │  Engineer       │     │  Architect      │     │  Manager        │
│  (Copilot)      │     │  (Copilot)      │     │  (Copilot)      │     │  (You)          │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
```

## Installation

### As a Global CLI Tool

```bash
npm install -g @baseappnet/github-flow
```

### As a Project Dependency

```bash
npm install @baseappnet/github-flow
```

### From Source

```bash
git clone https://github.com/baseapp-net/github-flow.git
cd github-flow
npm install
npm run build
npm link  # Makes 'github-flow' available globally
```

## Quick Start

### 1. Initialize Configuration

```bash
cd your-project
github-flow init
```

This creates:
- `github-flow.config.js` - Agent and pipeline configuration
- `.env` - Environment variables (GITHUB_TOKEN, etc.)

### 2. Configure Your Agents

Edit `github-flow.config.js` to define your review agents:

```javascript
module.exports = {
  agents: {
    'frontend-architect': {
      name: 'Frontend Architect',
      githubUsername: 'your-username',
      description: 'Frontend code quality specialist',
    },
    'security-engineer': {
      name: 'Security Engineer',
      githubUsername: 'your-username',
      description: 'Security and vulnerability assessment',
    },
    'engineering-manager': {
      name: 'Engineering Manager',
      githubUsername: 'your-username',
      description: 'Final human review',
      isHuman: true,  // Marks the final human reviewer
    },
  },

  reviewPipeline: [
    'frontend-architect',
    'security-engineer',
    'engineering-manager',
  ],
};
```

### 3. Set Up Environment

Edit `.env`:

```env
GITHUB_TOKEN=ghp_your_token_here
GITHUB_OWNER=your-org
GITHUB_REPO=your-repo
```

### 4. Create a Task

```bash
github-flow create --title "Add user authentication" --roles frontend-architect
```

## CLI Commands

### Create a Task

```bash
# Assign to single role
github-flow create --title "Feature Name" --description "Description" --roles frontend-architect

# Assign to multiple roles
github-flow create --title "Bug Fix" --roles frontend-architect,security-engineer
```

### Run the Review Pipeline

```bash
github-flow run-pipeline --issue 42
```

This automatically:
1. Waits for Copilot to create a PR
2. Transitions through each reviewer in the pipeline
3. Waits for each Copilot session to complete
4. Assigns to the human manager at the end

Options:
- `--poll <seconds>` - Poll interval (default: 15)
- `--max-attempts <number>` - Max poll attempts (default: 200)

### Manual Transition

```bash
github-flow transition --issue 42 --stage "Review: Security" --reviewer security-engineer
```

### Check & Advance All Tasks

```bash
github-flow check-advance
```

Scans all open tasks and advances any that are ready. Designed for cron jobs.

### Show Pipeline

```bash
github-flow show-pipeline
```

### List Agents

```bash
github-flow list-agents
```

### Interactive Mode

```bash
github-flow
```

Launches an interactive menu for all operations.

## Using as a Library

```typescript
import { WorkflowManager, GitHubFlowConfig } from '@baseappnet/github-flow';

const config: GitHubFlowConfig = {
  owner: 'my-org',
  repo: 'my-repo',
  token: process.env.GITHUB_TOKEN!,
  agents: {
    'frontend': {
      role: 'frontend',
      name: 'Frontend Architect',
      githubUsername: 'user1',
      description: 'Frontend specialist',
    },
    'manager': {
      role: 'manager',
      name: 'Engineering Manager',
      githubUsername: 'user2',
      description: 'Final reviewer',
      isHuman: true,
    },
  },
  reviewPipeline: ['frontend', 'manager'],
  workflowStages: ['Backlog', 'In Progress', 'Review', 'Done'],
};

const manager = new WorkflowManager(config);

// Create a task
await manager.createTask('My Feature', 'Description here', ['frontend']);

// Run the full pipeline
await manager.runReviewPipeline({ issueNumber: 42 });

// Or transition manually
await manager.transitionTask({
  issueNumber: 42,
  stage: 'Review: Frontend',
  reviewerRole: 'frontend',
});
```

## Configuration Reference

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | Yes | GitHub personal access token |
| `GITHUB_OWNER` | Yes* | Repository owner (org or user) |
| `GITHUB_REPO` | Yes* | Repository name |
| `GITHUB_API_URL` | No | GitHub Enterprise API URL |

*Can also be set in config file

### Config File Options

```javascript
module.exports = {
  // Optional if set in .env
  owner: 'your-org',
  repo: 'your-repo',

  // Required: Define your agents
  agents: {
    'role-id': {
      name: 'Display Name',
      githubUsername: 'github-username',
      description: 'What this agent does',
      isHuman: false,  // Set true for human reviewers
    },
  },

  // Required: Order of reviewers
  reviewPipeline: ['role1', 'role2', 'human-role'],

  // Optional: Custom workflow stages
  workflowStages: ['Backlog', 'In Progress', 'Review', 'Done'],
};
```

## How It Works

1. **Task Creation**: Creates a GitHub Issue with appropriate labels and assignees
2. **PR Detection**: Monitors for Copilot to create a linked Pull Request
3. **Session Monitoring**: Watches the Copilot check run status
4. **Transition**: When a session completes, transitions to the next reviewer
5. **Comments**: Adds comments instructing Copilot to adopt the new persona
6. **Human Handoff**: Final reviewer (marked `isHuman: true`) receives the PR for manual review

## Examples

See the `examples/` directory for project-specific configurations:
- `online-forms.config.js` - Angular + AWS Serverless project
- `bankapis.config.js` - CDK-focused project

## License

MIT