diff --git a/.gitignore b/.gitignore index c0ed8c8..045affe 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ Thumbs.db # Review gate state (transient) .review-state/ .worker-state/ +releases/ diff --git a/docs/releasing-worker.md b/docs/releasing-worker.md new file mode 100644 index 0000000..0829676 --- /dev/null +++ b/docs/releasing-worker.md @@ -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 +``` diff --git a/pkgs/worker/default.nix b/pkgs/worker/default.nix new file mode 100644 index 0000000..e045d06 --- /dev/null +++ b/pkgs/worker/default.nix @@ -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 ) +# 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 ]; + }; +}) diff --git a/skills.nix b/skills.nix index 8213f5e..ccaf230 100644 --- a/skills.nix +++ b/skills.nix @@ -3,10 +3,12 @@ bd-issue-tracking = "BD issue tracking skill"; code-review = "Multi-lens code review with issue filing"; doc-review = "AI-assisted documentation review"; + hq = "Multi-agent orchestration with worker CLI"; niri-window-capture = "Invisibly capture window screenshots"; ops-review = "Multi-lens ops/infrastructure review"; orch = "Orchestration and consensus skill"; playwright-visit = "Browser automation and content extraction"; + review-gate = "Quality gate for agent work"; screenshot-latest = "Find latest screenshots"; spec-review = "Technical specification review"; tufte-press = "Generate study card JSON"; diff --git a/skills/hq/README.md b/skills/hq/README.md new file mode 100644 index 0000000..8b4b288 --- /dev/null +++ b/skills/hq/README.md @@ -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 diff --git a/skills/hq/SKILL.md b/skills/hq/SKILL.md index c1d37af..d49b938 100644 --- a/skills/hq/SKILL.md +++ b/skills/hq/SKILL.md @@ -426,10 +426,33 @@ 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 +### 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