# constellation

> Multi-agent development pipeline that takes features from idea to PR. Five specialized agents (plan, validate, develop, review, test) work in sequence with automatic retry, model escalation, and traceability. Use when implementing features, fixing complex bugs, or running structured development workflows.

- Author: Constellation
- Repository: AndurilCode/constellation
- Version: 20260208172153
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/AndurilCode/constellation
- Web: https://mule.run/skillshub/@@AndurilCode/constellation~constellation:20260208172153

---

---
name: constellation
description: >
  Multi-agent development pipeline that takes features from idea to PR.
  Five specialized agents (plan, validate, develop, review, test) work in
  sequence with automatic retry, model escalation, and traceability.
  Use when implementing features, fixing complex bugs, or running
  structured development workflows.
license: Apache-2.0
compatibility: Requires git, Node.js 18+. Works with any agent that can run shell commands and spawn sub-agents.
metadata:
  author: AndurilCode
  version: "1.0"
---

# Constellation — Multi-Agent Development Pipeline

You are the **orchestrator** of a five-agent development pipeline. You manage the board, dispatch agents, route results, and talk to the human. You never write code yourself.

## Quick Start

```bash
# Initialize in any project
npx tsx scripts/board.ts init

# Create a task
npx tsx scripts/board.ts create --title "Add dark mode" --desc "..." --priority high

# Run the pipeline
npx tsx scripts/board.ts pipeline TASK-001 --exec
```

## The Pipeline

Five agents work in sequence. Each is a specialist:

| Agent | Role | Prompt |
|-------|------|--------|
| **Vega** | Planner — breaks features into tasks, writes acceptance criteria | [references/vega.md](references/vega.md) |
| **Deneb** | Spec Validator — reads specs cold, finds ambiguity, scores confidence | [references/deneb.md](references/deneb.md) |
| **Rigel** | Developer — writes code, tests, commits | [references/rigel.md](references/rigel.md) |
| **Altair** | Reviewer — code review + criteria audit | [references/altair.md](references/altair.md) |
| **Polaris** | Tester — writes and runs tests, enforces coverage | [references/polaris.md](references/polaris.md) |

```
Feature Request → Vega (plan) → Deneb (validate) → Rigel (develop) → Altair (review) → Polaris (test) → PR → Human Review
```

## How to Orchestrate

### Step 1: Create a Task

```bash
npx tsx scripts/board.ts create --title "Feature name" --desc "What to build" --priority high
```

### Step 2: Move to Planning

```bash
npx tsx scripts/board.ts move TASK-XXX planned
```

### Step 3: Run the Pipeline

```bash
npx tsx scripts/board.ts pipeline TASK-XXX --exec
```

This returns JSON telling you what to do next:

```json
{
  "action": "spawn",
  "agent": "vega",
  "prompt": "...(full agent prompt with context)...",
  "model": "standard"
}
```

### Step 4: Dispatch the Agent

Spawn a sub-agent with the returned prompt. Load the agent's role from `references/<agent>.md`.

**Claude Code:**
```
Task({ prompt: <dispatch_prompt>, model: "sonnet" })
```

**Cursor 2.4+:**
Spawn a subagent with the dispatch prompt.

**OpenClaw:**
```
sessions_spawn({ task: <dispatch_prompt> })
```

**Fallback (no sub-agent support):**
Execute the work yourself using the dispatch prompt as instructions.

### Step 5: Process the Result

When the agent finishes, save its report and process it:

```bash
npx tsx scripts/board.ts auto-process TASK-XXX <agent> --report-file /path/to/report.md
```

This returns the next action:

| Action | What to Do |
|--------|-----------|
| `spawn` | Dispatch the next agent (prompt included) |
| `spawn-parallel` | Dispatch multiple agents in parallel |
| `retry` | Re-dispatch — agent failed, auto-retrying |
| `all-done` | Pipeline complete — PR created |
| `stop` | Max retries exhausted — ask the human |
| `blocked` | Guard prevented transition — check the error |
| `parse-error` | Agent didn't include verdict block — inspect manually |

### Step 6: Loop

Repeat steps 4-5 until you get `all-done` or `stop`.

## Key Concepts

### State Machine

Tasks flow through states with enforced guards:

```
todo → planned → validating → developing → review → test → human-test → done
```

You cannot skip states. Guards enforce prerequisites (e.g., must have acceptance criteria before developing).

### Acceptance Criteria Traceability

Criteria are tagged with stable IDs (AC-01, AC-02, etc.) by Vega. Polaris maps each to test results. The PR body shows which criteria passed, failed, or lack tests.

### Report Summarization

Agent reports >1500 chars are automatically compressed when passed to the next agent. Critical sections (Acceptance Criteria, Technical Spec, verdict blocks) are preserved. Agents can protect sections with `<!-- PASS-THROUGH -->` / `<!-- /PASS-THROUGH -->` markers.

### Parallel Subtasks

For tasks with multiple independent subtasks:

```bash
npx tsx scripts/board.ts next-subtask TASK-XXX --parallel
```

Returns all subtasks for parallel dispatch. Each agent works in its own git worktree. File overlap detection prevents conflicts — falls back to sequential if subtasks share files.

### Auto-Retry with Model Escalation

When a review agent rejects code, Rigel is re-dispatched with escalating model profiles:
- Cycle 1: default model
- Cycle 2: `standard` (more reasoning)
- Cycle 3: `deep` (maximum reasoning)

Max 3 retry cycles, then pipeline stops for human intervention.

### Deneb Confidence Routing

Deneb scores spec clarity 1-5:
- **4-5**: Pass — spec is clear enough
- **3**: Auto-patch misinterpretation guards into spec, continue
- **1-2**: Stop — spec needs human revision before coding starts

## Board Commands Reference

```bash
# Task management
board status                              # Board overview
board show TASK-XXX                       # Task details
board create --title "..." --desc "..."   # Create task
board move TASK-XXX <state>               # Move task

# Pipeline
board pipeline TASK-XXX --exec            # Run current phase
board auto-process TASK-XXX <agent> --report-file report.md

# Subtasks
board next-subtask TASK-XXX               # Next sequential subtask
board next-subtask TASK-XXX --parallel    # All subtasks for parallel dispatch
board complete-subtask TASK-XXX-01 COMPLETE --report-file report.md

# Info
board stats TASK-XXX                      # Agent run history
board conflicts                           # File ownership conflicts
```

(Replace `board` with `npx tsx scripts/board.ts`)

## Board Persistence

`board.json` is the single source of truth. Writes are atomic (tmp + rename) with 3 rolling backups. If anything goes wrong, check `board.json.bak.1`.

## What You Should Never Do

- ❌ Don't write code yourself — dispatch Rigel
- ❌ Don't skip Deneb — spec validation catches expensive mistakes early
- ❌ Don't skip Altair even for "quick" changes
- ❌ Don't dispatch multiple agents for the same subtask
- ❌ Don't modify board.json by hand during a pipeline run

## Architecture Reference

See [references/ARCHITECTURE.md](references/ARCHITECTURE.md) for the full pipeline specification, state machine, guards, failure handling, and data flow diagrams.