dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

hq: add cross-agent instructions and worker templates

Browse source 
- Add Cross-Agent Compatibility section to SKILL.md
- Document concrete launch commands per agent type (Claude, OpenCode, Codex)
- Add worker-system.md template for worker agent prompts
- Add hq-status script for unified status view
- Simplify by documenting patterns rather than building --agent flag

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dan 2026-01-12 13:53:05 -08:00
parent 949250bbe9
commit 560e92e678
3 changed files with 261 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
skills/hq/SKILL.md
View file

@ -15,6 +15,26 @@ Load this skill when:
- Running unattended/autonomous coding sessions - Running unattended/autonomous coding sessions
- Coordinating complex features across multiple workers - 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 ## Architectural Boundaries
HQ is a **thin orchestration layer**. It makes decisions but delegates execution to specialized components. 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 ### 3. Launch Worker Agent
The worker agent runs in its worktree with a system prompt that: The worker agent runs in its worktree with the worker system prompt.
- Focuses on the specific task
- Has access to `worker start`, `worker done`, `worker heartbeat` **Template location:** `skills/hq/templates/worker-system.md`
- Cannot access HQ commands
#### Render the Worker Prompt
First, render the template with task context:
```bash ```bash
# Example: Launch Claude in worker context TASK_ID="skills-abc"
cd worktrees/<task-id> TASK_DESC=$(bd show $TASK_ID --format=oneline 2>/dev/null)
claude --system-prompt "$(cat worker-system-prompt.md)" \ WORKTREE="worktrees/$TASK_ID"
--initial-prompt "Complete task <task-id>: $(bd show <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 ### 4. Monitor Progress
```bash ```bash

59
skills/hq/scripts/hq-status Executable file
View file

@ -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 <id>' for task details, 'worker status' for worker details${RESET}"

135
skills/hq/templates/worker-system.md Normal file
View file

@ -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.