# 4.1 Minion System

# Minion System

Minions are **one-shot autonomous agents** (inspired by Stripe's internal system). Each minion:

1. Gets a single task
2. Runs in an isolated git worktree
3. Has full tool access (read/write files, run commands)
4. Follows a blueprint (YAML chain of steps)
5. Produces verifiable output
6. Exits

## How to Use

```bash
# Run a minion for a specific task
node minion.js run "Fix login validation bug" --project ~/ALAI/products/Drop

# Run a minion tied to an MC task
node minion.js run "Add rate limiting" --project ~/ALAI/products/Drop --mc-task 1234

# Queue for batch processing
node minion.js enqueue "Refactor auth module" --project ~/ALAI/products/Drop
```

## Minion Execution Flow

```
Task + Project
     │
     ▼
1. Create isolated git worktree (branch: minion/<id>)
2. Load context (project README, relevant files, HiveMind knowledge)
3. Select blueprint based on task type
4. Execute blueprint steps:
   │
   ├── Step 1: Analyze (understand the codebase)
   ├── Step 2: Plan (create execution plan)
   ├── Step 3: Build (implement changes)
   ├── Step 4: Test (run tests, verify)
   └── Step 5: Report (write GOTCHA summary)
   │
5. Quality gate — verify output, run tests
6. Return result (success/failure + artifacts)
```

## Blueprint Types

| Blueprint | Purpose |
|-----------|---------|
| `minion-one-shot.yaml` | General purpose — analyze, plan, build, test |
| `minion-bugfix.yaml` | Bug fixing — reproduce, diagnose, fix, verify |
| `minion-refactor.yaml` | Refactoring — understand, plan, refactor, test |
| `minion-security-fix.yaml` | Security fixes — audit, fix, verify |
| `minion-docs.yaml` | Documentation — read code, generate docs |
| `codecraft-nextjs-app.yaml` | Full Next.js app scaffold (CodeCraft) |
| `codecraft-api-backend.yaml` | API backend scaffold (CodeCraft) |
| `securion-security-review.yaml` | Security audit chain (Securion) |

## Git Worktree Isolation

Each minion runs in its own git branch/worktree:
- **Branch:** `minion/<short-id>`
- **Path:** `~/system/.claude/worktrees/minion-<id>`
- Changes don't affect main branch until merged
- Multiple minions can work in parallel on different branches