dabruhce-multi-agent-orchestration

# Colony Orchestration Skill

Multi-agent task delegation and process orchestration with audit logging and agent learning capabilities.

## Quick Start

```bash
# Single task - auto-routed
node scripts/colony.mjs dispatch "find top 5 time-series databases"

# Multi-stage process
node scripts/colony.mjs process validate-idea --context "AI meal planning for parents"
node scripts/colony.mjs process-status  # check progress
node scripts/colony.mjs approve abc123  # continue past checkpoint

# Check audit stats
node scripts/colony.mjs audit

# View agent memory
node scripts/colony.mjs memory scout
```

## Agents

| Agent | Role | Specialization |
|-------|------|----------------|
| **scuttle** | researcher | Quick searches, lookups, fact-finding |
| **scout** | researcher | Deep market/competitor research, intelligence |
| **forecast** | analyst | Data analysis, trends, projections |
| **pincer** | coder | Writing, debugging, refactoring code |
| **shell** | ops | Git, deployments, system tasks |
| **forge** | product | PRDs, specs, roadmaps |
| **ledger** | finance | Pricing, costs, business cases |
| **muse** | creative | Brainstorming, naming, ideas |
| **scribe** | writer | Blog posts, docs, long-form content |
| **quill** | copywriter | Landing pages, sales copy, ads |
| **echo** | social | Tweets, social posts, promotion |
| **sentry** | qa | Testing, bug verification |

## Task Commands

### Dispatch (Auto-Route)
```bash
node scripts/colony.mjs dispatch "research best practices for API rate limiting"
```
Automatically detects the best agent based on task keywords.

### Assign to Specific Agent
```bash
node scripts/colony.mjs assign scout "find top 5 time-series databases"
node scripts/colony.mjs assign pincer "refactor the auth module to use JWT"
node scripts/colony.mjs assign shell "deploy the staging branch"
```

### Check Status
```bash
node scripts/colony.mjs status
```
Shows all agents and their current tasks.

### Get Results
```bash
node scripts/colony.mjs results              # Latest completed task
node scripts/colony.mjs results abc123       # Specific task by ID
```

### View History
```bash
node scripts/colony.mjs history              # Last 10 completed/failed
node scripts/colony.mjs history --limit 20   # Custom limit
```

## Process Commands

Processes are multi-stage workflows that chain agents together.

### List Available Processes
```bash
node scripts/colony.mjs processes
```

### Start a Process
```bash
node scripts/colony.mjs process <process-name> --context "description"
```

Examples:
```bash
node scripts/colony.mjs process validate-idea --context "AI-powered meal planning for busy parents"
node scripts/colony.mjs process content-pipeline --context "How to use vector databases for RAG"
node scripts/colony.mjs process product-launch --context "Life Lunch ritual kit for parents"
node scripts/colony.mjs process bug-triage --context "Login fails with OAuth on mobile"
```

### Check Process Status
```bash
node scripts/colony.mjs process-status           # Show latest run
node scripts/colony.mjs process-status abc123    # Specific run
```

Shows: current stage, completed stages, checkpoints, output files.

### View Process Runs
```bash
node scripts/colony.mjs runs                 # All runs (active, paused, completed)
node scripts/colony.mjs runs --limit 5       # Last 5
```

### Approve Checkpoint
When a process hits a checkpoint, it pauses for human approval:
```bash
node scripts/colony.mjs approve abc123
```

Also used to retry a failed stage.

### Cancel a Process
```bash
node scripts/colony.mjs cancel abc123
```

## Audit Commands

Track agent performance, task statistics, and system health.

### Dashboard
```bash
node scripts/colony.mjs audit
```
Shows global stats, per-agent summary, and recent events.

### Agent Details
```bash
node scripts/colony.mjs audit agent scout
node scripts/colony.mjs audit agent pincer
```
Shows detailed stats for a specific agent including:
- Total tasks, success rate
- Average duration
- Token usage
- Recent failures

### Event Log
```bash
node scripts/colony.mjs audit log              # Last 20 events
node scripts/colony.mjs audit log --limit 50   # More events
```

### Slowest Tasks
```bash
node scripts/colony.mjs audit slow             # Top 10 slowest
node scripts/colony.mjs audit slow --limit 20
```

### Recent Failures
```bash
node scripts/colony.mjs audit failures         # Last 10 failures
node scripts/colony.mjs audit failures --limit 20
```

## Learning Commands

Agents learn from experience and share knowledge.

### Feedback
Record feedback for completed tasks:
```bash
node scripts/colony.mjs feedback abc123 "Great research, but needed more pricing data"
```

### Agent Memory
Each agent has a persistent memory file with lessons learned:

```bash
# View an agent's memory
node scripts/colony.mjs memory scout

# Add a lesson
node scripts/colony.mjs memory scout add "Always check publication dates on research sources"

# Add to specific sections
node scripts/colony.mjs memory scout add "Use bullet points for clarity" --pattern
node scripts/colony.mjs memory scout add "Missed competitor X in analysis" --mistake
node scripts/colony.mjs memory scout add "Prefers markdown tables over lists" --pref
```

### Shared Learnings
Cross-agent insights and lessons:

```bash
# View all shared learnings
node scripts/colony.mjs learn

# Add a learning
node scripts/colony.mjs learn add "validate-idea works better with 3 competitors max" --category process
node scripts/colony.mjs learn add "Always verify API rate limits early" --category technical --source run-abc123
```

### Global Context
Shared context all agents can access:

```bash
# View global context
node scripts/colony.mjs context

# Set preferences
node scripts/colony.mjs context set preferences.codeStyle "TypeScript, functional"
node scripts/colony.mjs context set preferences.timezone "America/Chicago"

# Add active facts (temporary context)
node scripts/colony.mjs context add-fact "We're targeting enterprise customers"
node scripts/colony.mjs context add-fact "Launch deadline is Q2 2024"

# Add decisions
node scripts/colony.mjs context add-decision "Use Postgres over MySQL" --project "life-lunch"

# Add projects
node scripts/colony.mjs context add-project "life-lunch"
```

### Retrospective
Review recent activity and generate insights:

```bash
node scripts/colony.mjs retro              # Last 7 days
node scripts/colony.mjs retro --days 14    # Last 14 days
```

Shows:
- Task completion summary
- Per-agent stats
- Failure patterns
- Suggested learnings

## Available Processes

### validate-idea
**Validate a business idea end-to-end**
- Stages: brainstorm → research → analyze → spec → estimate
- Checkpoints: after analyze
- Output: business-case.md

### product-launch
**End-to-end product launch**
- Stages: research → spec → build → copy
- Checkpoints: after spec, after copy
- Output: market-brief.md, prd.md, code/, landing-copy.md

### content-pipeline
**Research, write, publish, promote content**
- Stages: research → draft → review → publish → promote
- Checkpoints: review (human reviews draft)
- Output: research.md, draft.md, social-posts.md

### bug-triage
**Reproduce, fix, deploy bug fixes**
- Stages: reproduce → fix → test → deploy
- Checkpoints: none (fast path)
- Output: bug-report.md, fix-summary.md

### customer-research
**Deep dive on a customer segment**
- Stages: identify → pain-points → validate → synthesize
- Checkpoints: none
- Output: customer-profile.md, insights.md

### landing-page
**Create a full landing page**
- Stages: strategy → copy → review → build
- Checkpoints: after copy review
- Output: strategy.md, copy.md, landing.html, landing.css

## How Processes Work

1. **Start** - Process creates a run entry and spawns first stage agent
2. **Execute** - Each stage runs with inputs from previous stages
3. **Checkpoint** - If stage is a checkpoint, process pauses for approval
4. **Continue** - After approval, next stage runs