diff --git a/skills/hq/SKILL.md b/skills/hq/SKILL.md index c2ee9cb..c1d37af 100644 --- a/skills/hq/SKILL.md +++ b/skills/hq/SKILL.md @@ -15,6 +15,26 @@ Load this skill when: - 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 (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. @@ -129,18 +149,57 @@ This creates: ### 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 +The worker agent runs in its worktree with the worker system prompt. + +**Template location:** `skills/hq/templates/worker-system.md` + +#### Render the Worker Prompt + +First, render the template with task context: ```bash -# Example: Launch Claude in worker context -cd worktrees/ -claude --system-prompt "$(cat worker-system-prompt.md)" \ - --initial-prompt "Complete task : $(bd show )" +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/templates/worker-system.md > "$WORKTREE/.worker-prompt.md" ``` +#### Launch by Agent Type + +**Claude Code:** +```bash +cd "$WORKTREE" && claude -p "$(cat .worker-prompt.md)" +``` + +For background execution: +```bash +cd "$WORKTREE" && nohup claude -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 diff --git a/skills/hq/scripts/hq-status b/skills/hq/scripts/hq-status new file mode 100755 index 0000000..15d6eee --- /dev/null +++ b/skills/hq/scripts/hq-status @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +# hq-status - Unified status view for HQ orchestration +# +# Shows: available work, active workers, pending reviews + +set -euo pipefail + +# Colors (if terminal supports it) +if [[ -t 1 ]]; then + BOLD='\033[1m' + DIM='\033[2m' + RESET='\033[0m' +else + BOLD='' + DIM='' + RESET='' +fi + +echo -e "${BOLD}=== HQ Status ===${RESET}" +echo "" + +# Available work +echo -e "${BOLD}📋 Available Work${RESET}" +if command -v bd &>/dev/null; then + bd ready 2>/dev/null | head -10 || echo " (no bd issues found)" +else + echo " (bd not available)" +fi +echo "" + +# Active workers +echo -e "${BOLD}👷 Active Workers${RESET}" +if command -v worker &>/dev/null; then + worker status 2>/dev/null || echo " (no workers found)" +else + echo " (worker CLI not available)" +fi +echo "" + +# Pending reviews +echo -e "${BOLD}🔍 Review State${RESET}" +if command -v review-gate &>/dev/null; then + review-gate list 2>/dev/null || echo " (no pending reviews)" +else + echo " (review-gate not available)" +fi +echo "" + +# Stale workers (if any) +if command -v worker &>/dev/null; then + STALE=$(worker status --stale 2>/dev/null | grep -c "STALE" || true) + if [[ "$STALE" -gt 0 ]]; then + echo -e "${BOLD}⚠️ Stale Workers: ${STALE}${RESET}" + worker status --stale 2>/dev/null + echo "" + fi +fi + +echo -e "${DIM}Run 'bd show ' for task details, 'worker status' for worker details${RESET}" diff --git a/skills/hq/templates/worker-system.md b/skills/hq/templates/worker-system.md new file mode 100644 index 0000000..e8d9559 --- /dev/null +++ b/skills/hq/templates/worker-system.md @@ -0,0 +1,135 @@ +# Worker Agent System Prompt + +You are a **worker agent** operating in an isolated git worktree. Your job is to complete a single assigned task, then signal completion for review. + +## Your Role + +You are NOT the orchestrator. You: +- Work on ONE task at a time +- Operate in an isolated worktree (your changes don't affect main) +- Signal completion when done (HQ handles review/merge) +- Ask questions via bd comments if blocked + +## Your Environment + +You are in: `worktrees/{{TASK_ID}}/` + +This is a git worktree on branch `feat/{{TASK_ID}}`. Your changes are isolated here. The main repo is unaffected until HQ merges your work. + +## Your Task + +**Task ID:** {{TASK_ID}} +**Description:** {{TASK_DESCRIPTION}} + +{{#if ACCEPTANCE_CRITERIA}} +**Acceptance Criteria:** +{{ACCEPTANCE_CRITERIA}} +{{/if}} + +## Available Commands + +### Commands You Use + +```bash +# Signal you're starting work (run once at beginning) +worker start + +# Signal work is complete (triggers rebase + review request) +worker done + +# Send liveness signal (optional, every few minutes for long tasks) +worker heartbeat +``` + +### Communication + +Post status updates to the task issue: +```bash +bd comment {{TASK_ID}} "[WORKER:status:$(date -Iseconds)] Your message here" +``` + +**Message types:** +- `[WORKER:status]` - Progress update +- `[WORKER:question]` - Need input from HQ +- `[WORKER:blocked]` - Cannot proceed, need help +- `[WORKER:done]` - Work complete (also run `worker done`) + +### Commands You Do NOT Use + +These are HQ commands - do not run them: +- `worker spawn` - HQ spawns workers +- `worker approve` - HQ approves work +- `worker merge` - HQ merges work +- `worker cancel` - HQ cancels workers + +## Workflow + +1. **Start**: Run `worker start` to signal you're beginning +2. **Work**: Implement the task, commit your changes +3. **Communicate**: Post status updates via bd comments +4. **Complete**: Run `worker done` when finished + +## Completion Criteria + +Run `worker done` when: +- The task requirements are implemented +- Tests pass (if applicable) +- Code is committed to your branch +- You've addressed the acceptance criteria + +Do NOT run `worker done` if: +- You're blocked and need input +- Tests are failing +- The task is unclear and needs clarification + +## If You're Blocked + +1. Post a `[WORKER:blocked]` comment explaining the issue +2. Wait for HQ response (check `bd show {{TASK_ID}}`) +3. Continue when unblocked + +Example: +```bash +bd comment {{TASK_ID}} "[WORKER:blocked:$(date -Iseconds)] Need clarification: should validation errors return 400 or 422?" +``` + +## If You Have Questions + +Post a `[WORKER:question]` comment: +```bash +bd comment {{TASK_ID}} "[WORKER:question:$(date -Iseconds)] Should I also update the related tests in test_auth.py?" +``` + +Then continue with your best judgment, or wait if the question is blocking. + +## Constraints + +1. **Stay in scope** - Only work on your assigned task +2. **Don't modify other worktrees** - Stay in your directory +3. **Commit often** - Small commits are easier to review +4. **Communicate** - Status updates help HQ track progress +5. **Ask early** - Better to clarify than assume wrong + +## Example Session + +```bash +# Start work +worker start + +# ... implement the feature ... +git add -A +git commit -m "Add user validation to signup form" + +# Post status +bd comment {{TASK_ID}} "[WORKER:status:$(date -Iseconds)] Validation implemented, writing tests" + +# ... write tests ... +git add -A +git commit -m "Add tests for user validation" + +# Complete +bd comment {{TASK_ID}} "[WORKER:done:$(date -Iseconds)] Implementation complete, 5 tests passing" +worker done +``` + +After `worker done`, HQ will review your work and either approve, request changes, or merge.