From 7a73ed9b1c4c6f2a3f3e2e8def07be02d737073a Mon Sep 17 00:00:00 2001 From: dan Date: Mon, 12 Jan 2026 10:20:14 -0800 Subject: [PATCH] feat: add HQ orchestration skill with architectural boundaries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Initial SKILL.md defining thin orchestration layer - Core loop: Assess → Plan → Delegate → Monitor → Iterate → Complete - Explicit delegation to worker CLI, review-gate, bd, infrastructure - Communication protocol using tagged single-line format - Open questions scoped to HQ-specific concerns Co-Authored-By: Claude Opus 4.5 --- skills/hq/SKILL.md | 393 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 skills/hq/SKILL.md diff --git a/skills/hq/SKILL.md b/skills/hq/SKILL.md new file mode 100644 index 0000000..c2ee9cb --- /dev/null +++ b/skills/hq/SKILL.md @@ -0,0 +1,393 @@ +--- +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 + +## 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. + +## 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 # Full issue details + +# Track work +bd update --status=in_progress # Claim work +bd comment "status update" # Add progress note +bd close # Mark complete +``` + +### Worker Management (worker) + +```bash +# Orchestrator commands (you run these) +worker spawn # Create isolated worktree +worker status # Dashboard of all workers +worker status --stale # Show workers needing attention +worker approve # Approve completed work +worker request-changes # Send back for revision +worker merge # Merge approved work +worker cancel # 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 `) +- Is appropriately scoped (single feature/fix) +- Has no unresolved dependencies + +### 2. Spawn Worker + +```bash +worker spawn --description "Brief task description" +``` + +This creates: +- Branch: `feat/` +- Worktree: `worktrees//` +- State: ASSIGNED + +### 3. Launch Worker Agent + +The worker agent runs in its worktree with a system prompt that: +- Focuses on the specific task +- Has access to `worker start`, `worker done`, `worker heartbeat` +- Cannot access HQ commands + +```bash +# Example: Launch Claude in worker context +cd worktrees/ +claude --system-prompt "$(cat worker-system-prompt.md)" \ + --initial-prompt "Complete task : $(bd show )" +``` + +### 4. Monitor Progress + +```bash +# Check all workers +worker status + +# Check specific task +worker status | grep + +# Read worker's communication +bd show # Comments from worker appear here +``` + +### 5. Handle Review + +When worker reaches IN_REVIEW: + +```bash +# Review the changes +cd worktrees/ +git log --oneline -10 +git diff origin/master...HEAD + +# Or use review skill +/code-review worktrees/ + +# Decision +worker approve # If good +worker request-changes # If needs work +``` + +### 6. Merge and Close + +```bash +worker merge +bd close +``` + +## 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 --reason "Stale - no progress" +worker spawn +``` + +### 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 "ESCALATE: Worker failed review 3x. Need human guidance." +bd update --priority=1 +``` + +### Merge Conflicts + +If `worker merge` fails: + +```bash +# Worker needs to rebase +worker request-changes --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 + +# Filter recent (if supported) +bd show --comments --last 5 +``` + +### Sending Messages + +```bash +# HQ sending command +bd comment "[HQ:cmd:$(date -Iseconds)] Focus on error handling first" + +# Or simpler (timestamp optional for humans) +bd comment "[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 + +- `bd` CLI (beads issue tracking) +- `worker` CLI (from this repo) +- `orch` CLI (optional, for second opinions) +- Git with worktree support + +## 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)