minion-engine 0.4.0

# Minion Engine

**Automate code review, bug fixing, and PR creation with AI — defined in YAML, executed in Docker.**

Minion Engine is a CLI tool that runs multi-step AI workflows. You define what you want in a YAML file, and it orchestrates everything: shell commands, Claude AI calls, conditional logic, and parallel execution — all inside an isolated Docker sandbox.

```
You write YAML → Minion runs AI workflows → Results appear as PR comments, fixes, reports
```

## Why?

**Without Minion Engine**, reviewing a PR means:
- Open the PR, read each file manually
- Switch context between Python, TypeScript, Rust conventions
- Remember to check for security issues, type safety, error handling
- Write your findings as a comment

**With Minion Engine**, one command does it all:
```bash
minion execute code-review.yaml -- 42
```
In ~40 seconds, every changed file is reviewed with **language-specific criteria** (Python gets Python rules, TypeScript gets TypeScript rules), the project architecture is considered, and a structured report is posted as a PR comment.

## Quick Start

```bash
# 1. Install (Rust toolchain required)
cargo install minion-engine

# 2. Set your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Authenticate with GitHub (GH_TOKEN is auto-detected)
gh auth login

# 4. Go to your project and run a workflow
cd /path/to/your-project
minion execute code-review.yaml -- 42   # Review PR #42
```

That's it. Docker image is **built automatically** on first run. No manual setup needed.

## What Can It Do?

| Workflow | What it does |
|----------|-------------|
| **code-review** | Review a PR — detects language per file, loads language-specific prompts, posts findings as PR comment |
| **fix-issue** | Fetch a GitHub issue → plan → implement → lint → test → create PR |
| **fix-test** | Detect failing tests → analyze → fix → verify — repeat until green |
| **security-audit** | Scan codebase for OWASP vulnerabilities with AI analysis |
| **generate-docs** | Generate documentation from source code |

All workflows are YAML files you can customize or create from scratch.

## Prerequisites

| Requirement | How to get it | Notes |
|-------------|---------------|-------|
| **Rust toolchain** | [rustup.rs](https://rustup.rs) | For `cargo install` |
| **ANTHROPIC_API_KEY** | [console.anthropic.com](https://console.anthropic.com) | `export ANTHROPIC_API_KEY="sk-ant-..."` |
| **Docker Desktop** | [docker.com](https://www.docker.com/products/docker-desktop/) | Sandbox runs workflows in isolation |
| **gh CLI** | [cli.github.com](https://cli.github.com) | `gh auth login` — GH_TOKEN is **auto-detected** |

> **Docker image auto-build:** The first time you run a workflow, Minion automatically builds the sandbox image (`minion-sandbox:latest`). This takes ~2 minutes once and never needs to be repeated.

## Features

### 🐳 Docker Sandbox (default)

Every workflow runs inside an isolated Docker container. Your project is copied in, the AI works in isolation, and only the results come back. If anything goes wrong, the container is destroyed — zero impact on your project.

```bash
minion execute code-review.yaml -- 42        # Sandbox ON (default)
minion execute code-review.yaml --no-sandbox -- 42  # Run locally instead
```

### 🔍 Language-Aware Code Review

The code review workflow detects the language of each changed file and applies **language-specific review criteria**:

- **Python** → checks for bare `except:`, missing type annotations, mutable default arguments
- **TypeScript** → checks for `any` types, missing `await`, unhandled promise rejections
- **Rust** → checks for `unwrap()` in production, unnecessary clones, unsafe blocks
- **Java** → checks for resource leaks, null safety, checked exceptions
- Falls back to generic review for other languages

### 📐 Architecture Context

If your project has a `CLAUDE.md`, `ARCHITECTURE.md`, or `README.md`, the code review workflow reads it automatically and uses it to evaluate whether changes align with your project's design.

### 🎯 Stack Detection & Prompt Registry

Minion detects your project's tech stack (Rust, Python, TypeScript, React, Java, etc.) from file markers (`Cargo.toml`, `package.json`, `requirements.txt`) and uses it to select the right prompts and tools.

## CLI Reference

### `minion execute`

```bash
minion execute <workflow.yaml> [flags] -- [target]
```

| Flag | Description |
|------|-------------|
| `--no-sandbox` | Disable Docker sandbox (sandbox is ON by default) |
| `--verbose` | Show all step outputs |
| `--quiet` | Only show errors |
| `--json` | Output result as JSON |
| `--dry-run` | Show what steps would run without executing |
| `--var KEY=VALUE` | Set a workflow variable (repeatable) |
| `--timeout SECONDS` | Override global timeout |
| `--resume STEP` | Resume from a specific step |

```bash
# Examples
minion execute code-review.yaml -- 42              # Review PR #42
minion execute fix-issue.yaml --verbose -- 247     # Fix issue with verbose output
minion execute fix-test.yaml -- 7                  # Fix failing tests for PR #7
minion execute security-audit.yaml                 # Security audit (no target needed)
minion execute workflow.yaml --var mode=strict -- 5 # Pass variables
```

### `minion init`

```bash
minion init <name> [--template <template>]
```

Creates a new workflow from a built-in template.

Templates: `blank`, `fix-issue`, `code-review`, `security-audit`

### `minion validate`

```bash
minion validate <workflow.yaml>
```

Parses and validates a workflow without executing it.

### `minion list`

```bash
minion list
```

Lists workflows found in the current directory, `./workflows/`, and `~/.minion/workflows/`.

### `minion inspect`

```bash
minion inspect <workflow.yaml>
```

Shows config layers, scopes, step dependency graph, and dry-run summary.

## Workflow YAML Format

```yaml
name: my-workflow
version: 1
description: "What this workflow does"

config:
  global:
    timeout: 300s
  chat:
    provider: anthropic
    model: claude-sonnet-4-20250514
    api_key_env: ANTHROPIC_API_KEY
  cmd:
    fail_on_error: true

steps:
  - name: get_info
    type: cmd
    run: "gh issue view {{ target }} --json title,body"

  - name: analyze
    type: chat
    prompt: |
      Analyze this issue and suggest a fix:
      {{ steps.get_info.stdout }}

  - name: report
    type: cmd
    run: "echo 'Analysis complete'"
```

## Step Types

| Type | Description |
|------|-------------|
| `cmd` | Execute a shell command |
| `agent` | Invoke Claude Code CLI |
| `chat` | Direct Anthropic API call |
| `gate` | Evaluate a condition, control flow |
| `repeat` | Run a scope repeatedly (retry loop) |
| `map` | Run a scope once per item in a list |
| `parallel` | Run nested steps concurrently |
| `call` | Invoke a scope once |

## Template Variables

| Variable | Description |
|----------|-------------|
| `{{ target }}` | Target argument passed after `--` |
| `{{ steps.<name>.stdout }}` | stdout of a cmd step |
| `{{ steps.<name>.stderr }}` | stderr of a cmd step |
| `{{ steps.<name>.exit_code }}` | Exit code of a cmd step |
| `{{ steps.<name>.response }}` | Response from a chat/agent step |
| `{{ scope.value }}` | Current item in a map/repeat scope |
| `{{ scope.index }}` | Current iteration index (0-based) |
| `{{ args.<key> }}` | Variable set via `--var KEY=VALUE` |
| `{{ prompts.<name> }}` | Load a prompt from the prompt registry |

## Example Output

```
▶ code-review
  🔒 Sandbox mode: FullWorkflow
  🐳 Creating Docker sandbox container…
  🔒 Sandbox ready — container 0.7s, copy 7.7s, git 0.3s (total 8.7s)
  ✓ get_diff (1.2s)
  ✓ changed_files (1.2s)
  ✓ check_files (0.0s)
  ✓ file_reviews (12.9s)
  ✓ summary (24.5s)
  ✓ post_comment (1.3s)
  ✓ report (0.2s)
  📦 Copying results from sandbox…
  🗑️  Sandbox destroyed

✓ Done — 7 steps in 41.9s
```

## Project Structure

```
src/
  cli/          # CLI commands (execute, validate, list, init, inspect)
  engine/       # Core engine — step execution, context, templates
  workflow/     # YAML parsing, validation
  steps/        # Step executors (cmd, agent, chat, gate, repeat, map, parallel)
  sandbox/      # Docker sandbox management
  prompts/      # Stack detection and prompt registry
  config/       # 4-layer config resolution
  plugins/      # Dynamic plugin system
workflows/      # Example workflow YAML files
prompts/        # Language-specific prompt templates
```

## License

MIT