# HQ - Multi-Agent Orchestration Skill

HQ (Headquarters) enables any AI agent to orchestrate multi-agent coding workflows. It coordinates work across isolated worker agents, ensures quality through review cycles, and maintains progress toward goals.

## Features

- **Cross-agent compatible** - Works with Claude Code, Gemini, OpenCode, Codex
- **Isolated workers** - Each worker operates in its own git worktree
- **State tracking** - SQLite-backed worker state machine
- **Review gates** - Quality enforcement before merge
- **Message passing** - Inter-agent communication via BD comments

## Requirements

### Required CLIs

| CLI | Purpose | Installation |
|-----|---------|--------------|
| `worker` | Worker lifecycle management | See [Installing Worker](#installing-worker) |
| `bd` | Issue tracking, inter-agent messaging | `cargo install beads` or nix package |
| `git` | Version control, worktrees | System package |

### Optional CLIs

| CLI | Purpose | Installation |
|-----|---------|--------------|
| `review-gate` | Quality gate enforcement | Skills repo: `skills/review-gate/` |
| `orch` | Multi-model consensus | Skills repo: `skills/orch/` |

## Installing Worker

### Option 1: From Release (Recommended)

```bash
# Download latest release
curl -LO https://github.com/OWNER/skills/releases/download/worker-v0.1.0/worker_0.1.0_linux_amd64.tar.gz
tar -xzf worker_0.1.0_linux_amd64.tar.gz
sudo mv worker /usr/local/bin/

# Or with nix (if package is set up)
nix profile install .#worker
```

### Option 2: Build from Source

```bash
# Requires Nim 2.2+
nix-shell -p nim
cd src
nim c -d:release --mm:orc worker.nim
cp worker.out ~/.local/bin/worker
```

### Option 3: Nix Package

Copy `pkgs/worker/default.nix` to your dotfiles and add to your configuration.

## Installing BD (Beads)

```bash
# From cargo
cargo install beads

# Or from nix (if package exists)
nix profile install nixpkgs#beads
```

Initialize beads in your repo:
```bash
bd init
```

## Deploying the HQ Skill

### Via Nix Home Manager

1. Add `hq` to your `claudeCodeSkills` list in home-manager config
2. Run `home-manager switch`

### Manual Deployment

```bash
# Copy skill to Claude Code skills directory
mkdir -p ~/.claude/skills/hq
cp -r skills/hq/* ~/.claude/skills/hq/

# Or symlink
ln -s /path/to/skills/hq ~/.claude/skills/hq
```

### Per-Project Deployment

Add to `.skills` manifest:
```
hq
```

Then in `.envrc`:
```bash
source ~/proj/skills/bin/use-skills.sh
load_skills_from_manifest
```

## Quick Start

1. **Initialize tracking** (if not already done):
   ```bash
   bd init
   ```

2. **Find work**:
   ```bash
   bd ready
   ```

3. **Spawn a worker**:
   ```bash
   worker spawn skills-abc --description "Implement feature X"
   ```

4. **Launch worker agent** (see SKILL.md for agent-specific commands):
   ```bash
   cd worktrees/skills-abc
   claude --model sonnet-4.5 -p "$(cat .worker-prompt.md)"
   ```

5. **Monitor and review**:
   ```bash
   worker status
   worker approve skills-abc
   worker merge skills-abc
   ```

## File Structure

```
skills/hq/
├── SKILL.md              # Agent instructions (load this)
├── README.md             # This file
├── scripts/
│   └── hq-status         # Unified status dashboard
└── assets/
    └── worker-system.md  # Worker agent prompt template
```

## Documentation

- [SKILL.md](./SKILL.md) - Full orchestration instructions for agents
- [Worker CLI Guide](../../docs/worker-cli-dev-guide.md) - Worker CLI development
- [Releasing Worker](../../docs/releasing-worker.md) - How to release worker binaries

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         HQ (Skill)                          │
│  Orchestration decisions: what to work on, when to spawn,   │
│  approve/reject, WIP limits                                 │
└─────────────────────────────────────────────────────────────┘
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │ worker CLI  │    │ review-gate │    │     bd      │
    │             │    │             │    │             │
    │ - spawn     │    │ - CI gates  │    │ - issues    │
    │ - status    │    │ - evidence  │    │ - comments  │
    │ - approve   │    │ - verify    │    │ - deps      │
    │ - merge     │    │             │    │             │
    └─────────────┘    └─────────────┘    └─────────────┘
           │
           ▼
    ┌─────────────┐
    │    git      │
    │             │
    │ - worktrees │
    │ - branches  │
    │ - commits   │
    └─────────────┘
```

## License

MIT
