docs: add HQ deployment and worker release documentation
- Add docs/releasing-worker.md with build and release process - Add pkgs/worker/default.nix template for nix packaging - Add skills/hq/README.md with installation and deployment guide - Update skills/hq/SKILL.md with detailed requirements table - Add hq and review-gate to skills.nix - Add releases/ to .gitignore Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dan
parent
560e92e678
commit
dcb29c12cd
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -30,3 +30,4 @@ Thumbs.db
|
||||||
# Review gate state (transient)
|
# Review gate state (transient)
|
||||||
.review-state/
|
.review-state/
|
||||||
.worker-state/
|
.worker-state/
|
||||||
|
releases/
|
||||||
|
|
|
||||||
113
docs/releasing-worker.md
Normal file
113
docs/releasing-worker.md
Normal file
|
|
@ -0,0 +1,113 @@
|
||||||
|
# Releasing Worker CLI
|
||||||
|
|
||||||
|
How to build and release the worker CLI binary.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Nim 2.2+ (via `nix-shell -p nim`)
|
||||||
|
- Git with push access to this repo
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Enter nix shell with nim
|
||||||
|
nix-shell -p nim
|
||||||
|
|
||||||
|
# Build release binary
|
||||||
|
cd src
|
||||||
|
nim c -d:release --mm:orc worker.nim
|
||||||
|
|
||||||
|
# Output: src/worker.out (~1MB)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Create Release Tarball
|
||||||
|
|
||||||
|
```bash
|
||||||
|
VERSION="0.1.0" # Update version
|
||||||
|
mkdir -p releases
|
||||||
|
tar -czvf "releases/worker_${VERSION}_linux_amd64.tar.gz" \
|
||||||
|
-C src worker.out \
|
||||||
|
--transform "s/worker.out/worker/"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Release to GitHub
|
||||||
|
|
||||||
|
1. Tag the release:
|
||||||
|
```bash
|
||||||
|
git tag -a "worker-v${VERSION}" -m "Worker CLI v${VERSION}"
|
||||||
|
git push origin "worker-v${VERSION}"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Create GitHub release:
|
||||||
|
```bash
|
||||||
|
gh release create "worker-v${VERSION}" \
|
||||||
|
--title "Worker CLI v${VERSION}" \
|
||||||
|
--notes "Multi-agent worker coordination CLI" \
|
||||||
|
"releases/worker_${VERSION}_linux_amd64.tar.gz"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Get the SHA256 for nix packaging:
|
||||||
|
```bash
|
||||||
|
nix-prefetch-url --unpack \
|
||||||
|
"https://github.com/USERNAME/skills/releases/download/worker-v${VERSION}/worker_${VERSION}_linux_amd64.tar.gz"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Nix Package
|
||||||
|
|
||||||
|
After releasing, update the nix package in `dotfiles/pkgs/worker/default.nix`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ lib, stdenvNoCC, fetchzip, autoPatchelfHook, stdenv }:
|
||||||
|
|
||||||
|
stdenvNoCC.mkDerivation (finalAttrs: {
|
||||||
|
pname = "worker";
|
||||||
|
version = "0.1.0"; # Update version
|
||||||
|
|
||||||
|
src = fetchzip {
|
||||||
|
url = "https://github.com/USERNAME/skills/releases/download/worker-v${finalAttrs.version}/worker_${finalAttrs.version}_linux_amd64.tar.gz";
|
||||||
|
sha256 = "sha256-XXXX"; # Update hash from nix-prefetch-url
|
||||||
|
stripRoot = false;
|
||||||
|
};
|
||||||
|
|
||||||
|
nativeBuildInputs = [ autoPatchelfHook ];
|
||||||
|
buildInputs = [ stdenv.cc.cc.lib ];
|
||||||
|
|
||||||
|
dontConfigure = true;
|
||||||
|
dontBuild = true;
|
||||||
|
dontStrip = true;
|
||||||
|
|
||||||
|
installPhase = ''
|
||||||
|
runHook preInstall
|
||||||
|
install -Dm755 worker $out/bin/worker
|
||||||
|
runHook postInstall
|
||||||
|
'';
|
||||||
|
|
||||||
|
meta = with lib; {
|
||||||
|
description = "Multi-agent worker coordination CLI";
|
||||||
|
homepage = "https://github.com/USERNAME/skills";
|
||||||
|
license = licenses.mit;
|
||||||
|
platforms = [ "x86_64-linux" ];
|
||||||
|
mainProgram = "worker";
|
||||||
|
};
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## Version Bumping
|
||||||
|
|
||||||
|
1. Update `src/worker.nimble`:
|
||||||
|
```nim
|
||||||
|
version = "X.Y.Z"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Update `docs/releasing-worker.md` examples
|
||||||
|
|
||||||
|
3. Rebuild and release
|
||||||
|
|
||||||
|
## Testing the Release
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Extract and test
|
||||||
|
tar -xzf releases/worker_${VERSION}_linux_amd64.tar.gz
|
||||||
|
./worker --help
|
||||||
|
./worker status
|
||||||
|
```
|
||||||
73
pkgs/worker/default.nix
Normal file
73
pkgs/worker/default.nix
Normal file
|
|
@ -0,0 +1,73 @@
|
||||||
|
# Worker CLI Nix Package
|
||||||
|
#
|
||||||
|
# This package installs the worker CLI binary from a release tarball.
|
||||||
|
# See docs/releasing-worker.md for how to create releases.
|
||||||
|
#
|
||||||
|
# To use:
|
||||||
|
# 1. Copy this to dotfiles/pkgs/worker/default.nix
|
||||||
|
# 2. Update the URL to point to your release location
|
||||||
|
# 3. Update the sha256 hash (use nix-prefetch-url --unpack <url>)
|
||||||
|
# 4. Add to your system/home configuration
|
||||||
|
|
||||||
|
{ lib
|
||||||
|
, stdenvNoCC
|
||||||
|
, fetchzip
|
||||||
|
, fetchurl
|
||||||
|
, autoPatchelfHook
|
||||||
|
, stdenv
|
||||||
|
}:
|
||||||
|
|
||||||
|
stdenvNoCC.mkDerivation (finalAttrs: {
|
||||||
|
pname = "worker";
|
||||||
|
version = "0.1.0";
|
||||||
|
|
||||||
|
# Option 1: Fetch from GitHub releases (when available)
|
||||||
|
# src = fetchzip {
|
||||||
|
# url = "https://github.com/OWNER/skills/releases/download/worker-v${finalAttrs.version}/worker_${finalAttrs.version}_linux_amd64.tar.gz";
|
||||||
|
# sha256 = lib.fakeHash; # Replace after first build attempt
|
||||||
|
# stripRoot = false;
|
||||||
|
# };
|
||||||
|
|
||||||
|
# Option 2: Fetch from local/private git forge
|
||||||
|
# src = fetchzip {
|
||||||
|
# url = "https://git.example.com/releases/worker_${finalAttrs.version}_linux_amd64.tar.gz";
|
||||||
|
# sha256 = lib.fakeHash;
|
||||||
|
# stripRoot = false;
|
||||||
|
# };
|
||||||
|
|
||||||
|
# Option 3: Local file (for testing)
|
||||||
|
src = fetchurl {
|
||||||
|
url = "file:///home/dan/proj/skills/releases/worker_${finalAttrs.version}_linux_amd64.tar.gz";
|
||||||
|
sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Will fail, get real hash from error
|
||||||
|
};
|
||||||
|
|
||||||
|
sourceRoot = ".";
|
||||||
|
|
||||||
|
nativeBuildInputs = [
|
||||||
|
autoPatchelfHook
|
||||||
|
];
|
||||||
|
|
||||||
|
buildInputs = [
|
||||||
|
stdenv.cc.cc.lib # libstdc++
|
||||||
|
];
|
||||||
|
|
||||||
|
dontConfigure = true;
|
||||||
|
dontBuild = true;
|
||||||
|
dontStrip = true;
|
||||||
|
|
||||||
|
installPhase = ''
|
||||||
|
runHook preInstall
|
||||||
|
install -Dm755 worker $out/bin/worker
|
||||||
|
runHook postInstall
|
||||||
|
'';
|
||||||
|
|
||||||
|
meta = with lib; {
|
||||||
|
description = "Multi-agent worker coordination CLI for HQ orchestration";
|
||||||
|
homepage = "https://github.com/OWNER/skills";
|
||||||
|
license = licenses.mit;
|
||||||
|
maintainers = [ ];
|
||||||
|
platforms = [ "x86_64-linux" ];
|
||||||
|
mainProgram = "worker";
|
||||||
|
sourceProvenance = with sourceTypes; [ binaryNativeCode ];
|
||||||
|
};
|
||||||
|
})
|
||||||
|
|
@ -3,10 +3,12 @@
|
||||||
bd-issue-tracking = "BD issue tracking skill";
|
bd-issue-tracking = "BD issue tracking skill";
|
||||||
code-review = "Multi-lens code review with issue filing";
|
code-review = "Multi-lens code review with issue filing";
|
||||||
doc-review = "AI-assisted documentation review";
|
doc-review = "AI-assisted documentation review";
|
||||||
|
hq = "Multi-agent orchestration with worker CLI";
|
||||||
niri-window-capture = "Invisibly capture window screenshots";
|
niri-window-capture = "Invisibly capture window screenshots";
|
||||||
ops-review = "Multi-lens ops/infrastructure review";
|
ops-review = "Multi-lens ops/infrastructure review";
|
||||||
orch = "Orchestration and consensus skill";
|
orch = "Orchestration and consensus skill";
|
||||||
playwright-visit = "Browser automation and content extraction";
|
playwright-visit = "Browser automation and content extraction";
|
||||||
|
review-gate = "Quality gate for agent work";
|
||||||
screenshot-latest = "Find latest screenshots";
|
screenshot-latest = "Find latest screenshots";
|
||||||
spec-review = "Technical specification review";
|
spec-review = "Technical specification review";
|
||||||
tufte-press = "Generate study card JSON";
|
tufte-press = "Generate study card JSON";
|
||||||
|
|
|
||||||
184
skills/hq/README.md
Normal file
184
skills/hq/README.md
Normal file
|
|
@ -0,0 +1,184 @@
|
||||||
|
# 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 -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
|
||||||
|
└── templates/
|
||||||
|
└── 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
|
||||||
|
|
@ -426,10 +426,33 @@ bd close skills-abc
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- `bd` CLI (beads issue tracking)
|
### Required
|
||||||
- `worker` CLI (from this repo)
|
|
||||||
- `orch` CLI (optional, for second opinions)
|
| CLI | Purpose | Installation |
|
||||||
- Git with worktree support
|
|-----|---------|--------------|
|
||||||
|
| `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
|
## Open Questions
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue