> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Colony — Multi-Agent Missions

> Give Fliiq a mission and five specialized agents collaborate to deliver results

Colony is Fliiq's multi-agent system. Five specialized agents — Intelligence, Research, Scout, QA, and Governance — coordinate autonomously to tackle objectives that benefit from breadth of exploration, competing perspectives, and self-critique.

## Quick Start

```bash theme={null}
fliiq colony start --mission "build the 50 most useful skills for freelancers"

# Dry run — 15-minute test to preview how agents approach the mission
fliiq colony start --mission "..." --dry-run

# Check progress
fliiq colony status

# View results
fliiq colony report
fliiq colony report --html
```

## The Five Agents

| Agent            | Role             | What It Does                                                                                                                                                        |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Intelligence** | Research Analyst | Scans the landscape for relevant prior art, tools, and developments. Produces structured Intelligence briefs that other agents consume.                             |
| **Scout**        | Product Manager  | Identifies opportunities and breaks the mission into concrete deliverables. Runs demand-sensing (community signals) and demand-generation (persona-based ideation). |
| **Research**     | CTO              | Evaluates technical feasibility and drafts detailed proposals. Reads Intelligence briefs and Scout's proposals to ground ideas in reality.                          |
| **QA**           | QA Lead          | Tests changes, monitors metrics, catches regressions. Establishes baselines before changes ship and validates after.                                                |
| **Governance**   | Staff Engineer   | Final decision-maker. Reviews proposals, approves or rejects, manages the codebase. The only agent with git write access.                                           |

<Warning>
  This is not a democracy. Governance has final authority. QA opposition is a strong negative signal. Intelligence produces knowledge but doesn't vote. Research and Scout propose and advocate.
</Warning>

## How Missions Work

Give Colony a mission and all five agents focus on that objective:

```bash theme={null}
fliiq colony start --mission "research every AI agent framework and map the competitive landscape"
```

* **Duration:** Up to 1 hour (hard cap)
* **Cooldowns:** 5–10 minutes between agent cycles for fast iteration
* **Output:** A `mission-deliverable.md` with approved proposals, rejected proposals with reasoning, key findings, and completion stats
* **Completion:** Three layers — duration ceiling, stall detection (3 empty cycles → auto-shutdown), and Governance declaration when the objective is met

Missions are designed for iteration — run a mission, review the deliverable, refine the objective, run again.

## How It Works

Agents coordinate through shared state on the filesystem — no databases, no message queues:

```
.colony/
├── state/
│   ├── proposals/        # One YAML file per proposal
│   ├── intelligence/     # Research briefs
│   ├── votes/            # Agent vote records
│   ├── reflections/      # Per-agent learning logs
│   ├── metrics/          # QA baselines and results
│   └── governance_decisions.jsonl
└── reports/
    └── mission-deliverable-001.md  # Your mission results
```

Every change flows through a **proposal lifecycle**: an agent drafts a proposal → other agents evaluate and vote → Governance approves or rejects → approved proposals get implemented → QA validates the result. High-risk changes get escalated to you for human review.

The Orchestrator manages the event-driven loop: when Intelligence writes a new brief, Research and Scout are triggered. When a proposal is approved and implemented, QA runs validation. When QA detects a regression, Research investigates. The system is self-sustaining once bootstrapped.

## When to Use Colony vs Regular Fliiq

**Colony is for WHAT and WHY. Regular Fliiq is for HOW.**

| Question                     | Use    |
| ---------------------------- | ------ |
| "What should we build?"      | Colony |
| "Build this thing"           | Fliiq  |
| "Which approach is best?"    | Colony |
| "Implement this approach"    | Fliiq  |
| "What are we missing?"       | Colony |
| "Fix what's broken"          | Fliiq  |
| "Explore this problem space" | Colony |

Colony earns its overhead when you need:

1. **Breadth of exploration** — many options to consider before committing
2. **Competing perspectives** — genuine tension between approaches
3. **Curation at scale** — filtering a large space to the best subset
4. **Self-critique** — output benefits from adversarial review before delivery

## Mission Categories

Colony handles a range of mission types:

* **Curation & prioritization** — "Map every API that would be useful as a Fliiq skill, categorized by domain"
* **Strategy & decision-making** — "Should the business model be subscription, usage-based, or freemium? Argue both sides."
* **Creative divergence → convergence** — "Propose 5 different onboarding flows and pick the most compelling"
* **Research & synthesis** — "Research how 10 different AI products handle memory and personalization"
* **System design** — "Design the architecture for a skill marketplace with tradeoffs"
* **Adversarial review** — "Review our current security model and identify every attack vector"

## CLI Reference

| Command                                        | Description                 |
| ---------------------------------------------- | --------------------------- |
| `fliiq colony start --mission "..."`           | Start a colony mission      |
| `fliiq colony start --mission "..." --dry-run` | 15-minute test run          |
| `fliiq colony status`                          | Check current colony status |
| `fliiq colony report`                          | Generate text report        |
| `fliiq colony report --html`                   | Generate HTML report        |
| `fliiq colony stop`                            | Stop the colony early       |

Colony requires a local `.fliiq/` directory. Run `fliiq init --project` first if you haven't already.