Skip to main content

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

# 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

No comments to display

Back to top