---
name: hq
description: Orchestrate multi-agent workflows using worker CLI and bd issue tracking
---

# HQ - Multi-Agent Orchestration Skill

You are operating as HQ (Headquarters) - the orchestrator for multi-agent coding workflows. Your job is to coordinate work across isolated worker agents, ensure quality through review cycles, and maintain progress toward goals.

## When to Use This Skill

Load this skill when:
- Managing multiple parallel coding tasks
- Delegating work to worker agents
- Running unattended/autonomous coding sessions
- Coordinating complex features across multiple workers

## Cross-Agent Compatibility

**HQ can be any agent** that can execute bash commands. The skill works with:
- Claude Code
- Gemini (with shell access)
- OpenCode
- Codex (OpenAI)

**Workers can be different agents than HQ.** Common pattern:
- HQ: Gemini or Codex (orchestration)
- Workers: Claude Code Sonnet 4.5 (implementation)

All coordination happens through:
- Filesystem (worktrees, context files)
- Git (branches, commits)
- SQLite (worker state via `worker` CLI)
- BD comments (inter-agent messaging)

No agent-specific APIs required.

## Architectural Boundaries

HQ is a **thin orchestration layer**. It makes decisions but delegates execution to specialized components.

**HQ owns (orchestration decisions):**
- What work to pick next
- When to spawn workers
- Approve/reject/escalate decisions
- WIP limits and capacity
- Definition of Done conventions

**HQ delegates to worker CLI:**
- Worker lifecycle (spawn, start, done, merge)
- State machine and retry counting
- Rebase handling and conflict resolution
- Background process management
- Stale worker detection and recovery

**HQ delegates to review-gate:**
- CI/test verification before approve
- Quality enforcement and evidence collection
- Post-merge verification

**HQ delegates to bd:**
- Issue state persistence
- Message format and context pruning
- Comment history management

**HQ delegates to infrastructure:**
- Sandboxing and security boundaries
- Disk space and dependency caching
- Container isolation (if used)

**Principle:** If something can be handled by a lower layer, delegate it. HQ should not implement retry logic, rebase commands, or test runners - it just invokes tools that do.

## Subscription & Model Configuration

The preferred configuration for worker agents is:
- **Default Model:** `sonnet-4.5`
- **Subscription:** Claude Max (ensure `claude setup-token` is configured if using service tokens)

When launching workers, always explicitly specify the model to ensure consistency across environments.

## Core Loop

```
1. ASSESS: Check current state (bd ready, worker status)
2. PLAN: Decide what to work on next
3. DELEGATE: Spawn workers for tasks
4. MONITOR: Watch progress, handle reviews
5. ITERATE: Approve/reject, escalate if stuck
6. COMPLETE: Merge approved work, close issues
```

## Available Tools

### Issue Tracking (bd)

```bash
# Find available work
bd ready                          # Issues with no blockers
bd list --status=open             # All open issues
bd show <id>                      # Full issue details

# Track work
bd update <id> --status=in_progress  # Claim work
bd comment <id> "status update"      # Add progress note
bd close <id>                        # Mark complete
```

### Worker Management (worker)

```bash
# Orchestrator commands (you run these)
worker spawn <task-id>            # Create isolated worktree
worker status                     # Dashboard of all workers
worker status --stale             # Show workers needing attention
worker approve <task-id>          # Approve completed work
worker request-changes <task-id>  # Send back for revision
worker merge <task-id>            # Merge approved work
worker cancel <task-id>           # Abort and cleanup

# Worker state flow:
# ASSIGNED → WORKING → IN_REVIEW → APPROVED → COMPLETED
```

### Second Opinions (orch)

```bash
# When uncertain about a decision
orch consensus "Should we refactor X or just fix Y?" flash gemini gpt

# When reviewing worker output
orch consensus "Is this implementation correct?" flash gemini --file path/to/code
```

## Workflow: Delegating to Workers

### 1. Find Work

```bash
bd ready
```

Pick a task that:
- Has clear requirements (check `bd show <id>`)
- Is appropriately scoped (single feature/fix)
- Has no unresolved dependencies

### 2. Spawn Worker

```bash
worker spawn <task-id> --description "Brief task description"
```

This creates:
- Branch: `feat/<task-id>`
- Worktree: `worktrees/<task-id>/`
- State: ASSIGNED

### 3. Launch Worker Agent

The worker agent runs in its worktree with the worker system prompt.

**Template location:** `skills/hq/assets/worker-system.md`

#### Render the Worker Prompt

First, render the template with task context:

```bash
TASK_ID="skills-abc"
TASK_DESC=$(bd show $TASK_ID --format=oneline 2>/dev/null)
WORKTREE="worktrees/$TASK_ID"

# Render template (simple sed substitution)
sed -e "s/{{TASK_ID}}/$TASK_ID/g" \
    -e "s/{{TASK_DESCRIPTION}}/$TASK_DESC/g" \
    skills/hq/assets/worker-system.md > "$WORKTREE/.worker-prompt.md"
```

#### Launch by Agent Type

**Claude Code:**
```bash
# Using Sonnet 4.5 with Max subscription
cd "$WORKTREE" && claude --model sonnet-4.5 -p "$(cat .worker-prompt.md)"
```

For background execution:
```bash
cd "$WORKTREE" && nohup claude --model sonnet-4.5 -p "$(cat .worker-prompt.md)" > worker.log 2>&1 &
disown
```

**OpenCode:**
```bash
cd "$WORKTREE" && opencode -p "$(cat .worker-prompt.md)"
```

**Codex (OpenAI):**
```bash
cd "$WORKTREE" && codex "$(cat .worker-prompt.md)"
```

#### What the Worker Template Does

The rendered prompt ensures the agent:
- Knows it's a worker (not HQ)
- Has access to `worker start`, `worker done`, `worker heartbeat`
- Cannot access HQ commands (spawn, approve, merge)
- Uses the tagged message format for communication
- Operates only in its worktree

### 4. Monitor Progress

```bash
# Check all workers
worker status

# Check specific task
worker status | grep <task-id>

# Read worker's communication
bd show <task-id>  # Comments from worker appear here
```

### 5. Handle Review

When worker reaches IN_REVIEW:

```bash
# Review the changes
cd worktrees/<task-id>
git log --oneline -10
git diff origin/master...HEAD

# Or use review skill
/code-review worktrees/<task-id>

# Decision
worker approve <task-id>          # If good
worker request-changes <task-id>  # If needs work
```

### 6. Merge and Close

```bash
worker merge <task-id>
bd close <task-id>
```

## Handling Problems

### Stale Worker (no heartbeat)

```bash
worker status --stale

# If worker is stuck, options:
# 1. Check if process is alive
# 2. Send message via bd comment
# 3. Cancel and retry
worker cancel <task-id> --reason "Stale - no progress"
worker spawn <task-id>
```

### Review Cycle Stuck

If a worker fails review multiple times:

1. Check the pattern - is the task unclear?
2. Use orch for second opinion on approach
3. After 3 failures, escalate to human

```bash
# Add comment for human attention
bd comment <task-id> "ESCALATE: Worker failed review 3x. Need human guidance."
bd update <task-id> --priority=1
```

### Merge Conflicts

If `worker merge` fails:

```bash
# Worker needs to rebase
worker request-changes <task-id> --comment "Rebase required - conflicts with recent changes"
```

## Communication Protocol

> **Note:** Using bd comments for inter-agent messaging is a pragmatic starting point.
> This may evolve into a dedicated message layer if we hit scaling or structure limits.

### Message Format

Use tagged single-line format for all bd comments:

```
[ROLE:type:timestamp] Message content
```

**Roles:**
- `HQ` - Orchestrator messages
- `WORKER` - Worker agent messages
- `HUMAN` - Human operator messages

**Types:**
- `cmd` - Command/instruction
- `status` - Progress update
- `question` - Asking for input
- `done` - Work complete signal
- `blocked` - Cannot proceed
- `escalate` - Needs human attention

**Examples:**
```
[HQ:cmd:2026-01-11T15:00] Focus on error handling before adding features
[WORKER:status:2026-01-11T15:05] Found 3 test failures, investigating auth.py
[WORKER:question:2026-01-11T15:10] Should I also fix the related TODO on line 42?
[WORKER:done:2026-01-11T15:30] Implementation complete, 12 tests passing
[HQ:cmd:2026-01-11T15:35] Approved. Proceed with merge.
[WORKER:blocked:2026-01-11T16:00] Rebase conflict in config.py, need guidance
[HQ:escalate:2026-01-11T16:05] Human input needed - ambiguous requirements
```

### Reading Messages

```bash
# All comments on a task
bd show <task-id>

# Filter recent (if supported)
bd show <task-id> --comments --last 5
```

### Sending Messages

```bash
# HQ sending command
bd comment <task-id> "[HQ:cmd:$(date -Iseconds)] Focus on error handling first"

# Or simpler (timestamp optional for humans)
bd comment <task-id> "[HQ:cmd] Approved, ready for merge"
```

### Message Channels

Workers communicate via:
1. **BD comments** - Primary channel (tagged format above)
2. **Worker state** - Visible in `worker status`
3. **Commit messages** - Visible in worktree git log

## Decision Guidelines

### When to Approve

- Tests pass (if applicable)
- Code addresses the task requirements
- No obvious regressions
- Style matches codebase

### When to Request Changes

- Missing error handling
- Tests failing
- Requirements not fully met
- Code quality issues

### When to Escalate to Human

- Task requirements are ambiguous
- Worker failed 3+ review cycles
- Architectural decision needed
- Security-sensitive changes

### When to Use orch

- Uncertain about approval decision
- Multiple valid approaches exist
- Need to validate worker's reasoning
- Complex tradeoffs

## Constraints

1. **One worker per task** - Don't spawn duplicate workers
2. **Sequential merges** - Merge one at a time to avoid conflicts
3. **Review everything** - Never auto-approve without review
4. **Escalate early** - 3 failures = human needed
5. **Document decisions** - Use bd comments for audit trail

## Example Session

```bash
# Start of session
bd ready
# Shows: skills-abc "Add user validation", skills-xyz "Fix timeout bug"

# Spawn workers for both
worker spawn skills-abc --description "Add user validation"
worker spawn skills-xyz --description "Fix timeout bug"

# Launch worker agents (in separate terminals/processes)
# ... workers do their work ...

# Monitor
worker status
# TASK         STATE       LAST HEARTBEAT
# skills-abc   WORKING     2m ago
# skills-xyz   IN_REVIEW   --

# Review skills-xyz
cd worktrees/skills-xyz
git diff origin/master...HEAD
# Looks good
worker approve skills-xyz
worker merge skills-xyz
bd close skills-xyz

# Check on skills-abc
worker status
# skills-abc   IN_REVIEW   --

# Review
cd worktrees/skills-abc
# ... review code ...
# Needs work
worker request-changes skills-abc --comment "Missing input sanitization"

# ... worker makes changes, resubmits ...

# Re-review, approve, merge
worker approve skills-abc
worker merge skills-abc
bd close skills-abc
```

## Requirements

### Required

| CLI | Purpose | Installation |
|-----|---------|--------------|
| `worker` | Worker lifecycle | See README.md for install options |
| `bd` | Issue tracking | `cargo install beads` or nix |
| `git` | Worktrees, branches | System package |

### Optional

| CLI | Purpose | Installation |
|-----|---------|--------------|
| `review-gate` | Quality gates | `skills/review-gate/` |
| `orch` | Multi-model consensus | `skills/orch/` |

### Verify Installation

```bash
# Check all required tools
command -v worker && worker --help | head -1
command -v bd && bd --version
command -v git && git --version

# Optional
command -v review-gate && echo "review-gate available"
command -v orch && echo "orch available"
```

## Open Questions

HQ-specific questions (other concerns delegated to appropriate layers):

1. **WIP limits** - How many concurrent workers before HQ becomes bottleneck? Likely budget/cost constraint.

2. **Human checkpoints** - When does HQ pause for human vs continue? Currently via stop hooks and review-gate.

3. **Definition of Done** - Per-issue-type checklists? How prescriptive should HQ be?

4. **Dependency scoping** - How to detect cross-cutting work that shouldn't parallelize?

**Delegated to other layers (see respective issues):**
- Worker launch mechanism → worker CLI (skills-q8i0)
- Context pruning → bd (skills-8hyz)
- Garbage collection → worker CLI (skills-w9a4)
- Retry counting → worker CLI (skills-vdup)
- CI/test gates → review-gate (skills-lr29)
- Security/sandboxing → infrastructure (skills-365b)
