Pi Agent — Helios + Minion Multi-Agent System

A complete multi-agent coding system built on Pi. Includes Helios (orchestrator) and Minion (workers) with 19 extensions, 7 skills, and 9 specialized agent roles.

Quick Start

# 1. Install Pi CLI
npm install -g @cgh567/cli

# 2. Clone this repo
git clone https://github.com/helios-agi/helios-agent.git ~/.pi/agent

# 3. Run setup (installs all extensions)
cd ~/.pi/agent && bash setup.sh

# 4. Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# 5. Start Pi (you are Helios)
pi

What You Get

Helios (Orchestrator)

Helios splits complex tasks across parallel subagents. It never writes code directly — it delegates to specialized agents.

Minion (Workers)

Minion agents implement tasks using TDD with 11 pre-completion gates. Each worker receives a single task and grinds until it's done.

9 Agent Roles

Agent	Role	Model
scout	Fast codebase recon	claude-haiku-4-5
planner	Task graph creation	claude-sonnet-4-6
worker	TDD implementation	claude-sonnet-4-6
reviewer	Adversarial code review	claude-opus-4-6
judge	Cycle evaluation	claude-opus-4-6
sub-planner	Recursive subsystem planning	claude-sonnet-4-6
debug-worker	Runtime bug diagnosis	claude-sonnet-4-6
researcher	Web research	claude-sonnet-4-6
context-builder	Requirements analysis	claude-sonnet-4-6

3 Dispatch Engines

1. subagent() — Single tasks, parallel batches, chain pipelines
2. coordinate() — Structured TASK-XX specs with parallel workers + review
3. orchestrate.sh — Shell-based planner→worker→judge cycle loop

7 Skills

• engineering — TDD workflow, pre-completion gates, design heuristics
• helios-orchestrator — Multi-cycle planner→worker→judge orchestration
• helios-prime — Delegation enforcement protocol
• helios-health — System health diagnostics
• focus — Development context awareness
• agent-pr-guardrails — Prevent agents from merging PRs
• skill-graph — Memgraph knowledge graph integration

19 Extensions

All from nicobailon's Pi extensions: pi-subagents, pi-coordination, pi-messenger, pi-web-access, pi-interactive-shell, pi-design-deck, pi-interview-tool, pi-review-loop, pi-model-switch, pi-foreground-chains, pi-annotate, pi-boomerang, pi-powerline-footer, pi-prompt-template-model, pi-rewind-hook, pi-skill-palette, skills-hook, surf-cli, visual-explainer

Usage

# Helios orchestrates (delegates to workers)
pi "Build a REST API with JWT auth"

# Direct agent dispatch
subagent({ agent: "worker", task: "Add rate limiting to /api/login" })

# Parallel workers
subagent({ tasks: [
  { agent: "worker", task: "Task 1: Add bcrypt" },
  { agent: "worker", task: "Task 2: Create login endpoint" }
]})

# Structured plan execution
plan({ input: "Build user auth" })    # Creates TASK-XX spec
coordinate({ plan: "specs/auth.md" }) # Executes with parallel workers

# Shell automation
~/.pi/agent/skills/helios-orchestrator/scripts/orchestrate.sh "Build user auth"

Structure

~/.pi/agent/
├── agents/                  # 9 Feynman agent definitions
│   ├── worker.md            # Minion worker (TDD + 11 gates)
│   ├── planner.md           # Helios planner (hypothesis-driven)
│   ├── judge.md             # Cycle evaluator (semi-formal verification)
│   ├── coordination/        # Variants for coordinate() engine
│   └── crew/                # Variants for pi-messenger Crew
├── docs/                    # Documentation index and references
│   ├── README.md            # Docs index
│   └── guide/               # Agent-readable installation and setup guides
│       └── installation.md  # Step-by-step installation guide
├── prompts/                 # Templates (post-mortem, adversarial-review)
├── skills/                  # 7 skills (loaded on demand)
├── extensions/              # Local extension hooks
├── scripts/                 # Utility scripts
├── .planning/               # GSD lifecycle artifacts (gitignored transient data)
│   ├── PLAN.md              # Goal-backward plan (discuss → plan)
│   ├── CONTEXT.md           # Discuss-phase findings
│   ├── VERIFICATION.md      # Verifier output
│   └── debug/               # Transient debug sessions (active/ is gitignored)
├── APPEND_SYSTEM.md         # Helios system prompt (injected into Pi)
├── AGENTS.md                # Agent-readable project context (per-directory)
├── settings.json            # Pi config + extension manifest
├── setup.sh                 # One-command setup
└── git/                     # Extension clones (created by setup.sh)

GSD Lifecycle

Every non-trivial task follows the GSD (Get Shit Done) execution standard:

discuss → plan → execute → verify

1. Discuss — Helios identifies gray areas, asks clarifying questions, and produces CONTEXT.md
2. Plan — Planner (Wheeler) creates a goal-backward PLAN.md with wave-based task decomposition
3. Execute — Workers (Dyson) implement using TDD: RED → GREEN → refactor, with pipe verification
4. Verify — Verifier (Hans) checks invariants, data flows, and acceptance criteria, producing VERIFICATION.md

Artifacts live in .planning/ at the repo root. Transient debug sessions (.planning/debug/active/) are gitignored.

Agent-Readable Installation Guide

The file docs/guide/installation.md is a structured, machine-readable guide written for AI agents (Helios, workers) to consume during setup tasks. It covers:

• Prerequisites and environment setup
• Dependency installation order
• Extension registration
• Health checks and smoke tests

Human users can read it too — it mirrors setup.sh but with rationale and troubleshooting context.

For Familiar Users

This repo is the Pi-only component. If you're using the Familiar desktop app, the app's setup script handles this automatically. The Familiar app adds:

• Electron frontend (emdash)
• WebSocket Helios integration
• Desktop observation pipeline
• Minion task management UI

This repo gives you the full agent experience without the desktop app.

Paper References

Agent improvements based on "Agentic Code Reasoning" (Anthropic 2026):

• Vacuous Test Guard (cpp_3)
• Name Resolution Audit (django-13670)
• Indirection Check (Mockito_8)
• Confident Wrong Answer warning (py_5)
• Gates 11-12 in pre-completion checklist