211 lines
8.2 KiB
Markdown
211 lines
8.2 KiB
Markdown
---
|
|
title: "HQ Deployment Documentation and Codex Skills Integration"
|
|
date: 2026-01-13
|
|
keywords: [hq, worker-cli, codex, skills-deployment, cross-agent, nix-module, orch-consensus]
|
|
commits: 3
|
|
compression_status: uncompressed
|
|
---
|
|
|
|
# Session Summary
|
|
|
|
**Date:** 2026-01-13 (Continuation of HQ multi-agent architecture work)
|
|
**Focus Area:** Making HQ deployable, adding Codex support to skills infrastructure
|
|
|
|
# Accomplishments
|
|
|
|
- [x] Ran orch consensus on HQ architecture - received comprehensive feedback from GPT-5.2
|
|
- [x] Filed orch bug report (orch-d08) for Gemini/OpenRouter model failures
|
|
- [x] Created worker release documentation (`docs/releasing-worker.md`)
|
|
- [x] Created nix package template (`pkgs/worker/default.nix`)
|
|
- [x] Built and released worker v0.1.0 tarball (327KB)
|
|
- [x] Added `hq` and `review-gate` to `skills.nix`
|
|
- [x] Created comprehensive `skills/hq/README.md` deployment guide
|
|
- [x] Updated `skills/hq/SKILL.md` with requirements table and model config
|
|
- [x] Filed dotfiles-u96: Add worker CLI package
|
|
- [x] Filed dotfiles-ha0: Add Codex skills deployment
|
|
- [x] Added `codexSkills` option to ai-skills nix module
|
|
- [x] Added Codex per-repo support to `use-skills.sh`
|
|
- [x] Closed skills-legi: Codex per-repo skills support
|
|
|
|
# Key Decisions
|
|
|
|
## Decision 1: Binary release distribution (like beads)
|
|
|
|
- **Context:** worker CLI is a Nim binary needing distribution for HQ to work
|
|
- **Options considered:**
|
|
1. Build from source in nix flake (requires Nim, lockfile complexity)
|
|
2. Binary releases via git forge (simple, like beads pattern)
|
|
3. Separate worker flake (overkill)
|
|
- **Rationale:** Option 2 matches existing beads pattern, simple to implement
|
|
- **Impact:** Tarball committed to repo, fetchable via git forge raw URL
|
|
|
|
## Decision 2: Extend ai-skills module for Codex
|
|
|
|
- **Context:** Codex loads skills from `~/.codex/skills/`, not covered by existing module
|
|
- **Options considered:**
|
|
1. Extend ai-skills module with `codexSkills` option
|
|
2. Symlink approach in home-manager
|
|
3. Use Codex's skill-installer
|
|
- **Rationale:** Option 1 keeps consistent pattern with Claude/OpenCode
|
|
- **Impact:** Single config manages all three agent skill deployments
|
|
|
|
## Decision 3: Per-repo Codex skills via CODEX_HOME
|
|
|
|
- **Context:** `use-skills.sh` deploys to `.claude/skills/` and `.opencode/skills/`
|
|
- **Rationale:** Check for `CODEX_HOME` env var, deploy to `$CODEX_HOME/skills/` if set
|
|
- **Impact:** Users set `export CODEX_HOME="$PWD/.codex"` in .envrc for per-repo Codex skills
|
|
|
|
# Problems & Solutions
|
|
|
|
| Problem | Solution | Learning |
|
|
|---------|----------|----------|
|
|
| Orch consensus failed for Gemini/OpenRouter models | Filed bug orch-d08; models work via `llm` directly but fail through orch | Issue in async model loading, not API keys |
|
|
| Can't merge integration→master (worktree conflict) | Left on integration branch, documented for later | Beads worktree setup blocks ff-merge |
|
|
| releases/ was gitignored | Un-ignored and committed tarball directly | 327KB small enough for git |
|
|
| No URL for worker binary | Committed to repo, accessible via git forge raw URL | `https://git.clarun.xyz/.../releases/worker_0.1.0_linux_amd64.tar.gz` |
|
|
|
|
# Technical Details
|
|
|
|
## Code Changes
|
|
|
|
- Total files modified: 16
|
|
- Key files changed:
|
|
- `modules/ai-skills.nix` - Added `codexSkills` option and deployment
|
|
- `bin/use-skills.sh` - Added `$CODEX_HOME/skills/` symlink support
|
|
- `skills/hq/SKILL.md` - Model config section, explicit `--model sonnet-4.5`
|
|
- `skills/hq/README.md` - Comprehensive deployment guide
|
|
- `pkgs/worker/default.nix` - Nix package template for worker CLI
|
|
- New files created:
|
|
- `docs/releasing-worker.md` - Build and release process
|
|
- `releases/worker_0.1.0_linux_amd64.tar.gz` - Binary release
|
|
- `skills/hq/README.md` - Deployment documentation
|
|
|
|
## Commands Used
|
|
|
|
```bash
|
|
# Create release tarball
|
|
tar -czvf "releases/worker_${VERSION}_linux_amd64.tar.gz" \
|
|
-C src worker.out --transform "s/worker.out/worker/"
|
|
|
|
# Get SHA256 for nix
|
|
nix hash to-sri sha256:$(sha256sum releases/worker_0.1.0_linux_amd64.tar.gz | cut -d' ' -f1)
|
|
# Result: sha256-Lz+gnjeedjwVV31rcijjQpMguMrBfvSfOUcOyLaFiI8=
|
|
|
|
# Clean up stale workers
|
|
worker cancel --taskId=skills-xyz --cleanup --reason="Stale from testing"
|
|
|
|
# Orch consensus (GPT worked, Gemini/OpenRouter failed)
|
|
orch consensus "architecture review..." flash gemini gpt --temperature 1.0
|
|
```
|
|
|
|
## Architecture Notes
|
|
|
|
### HQ Deployment Model
|
|
```
|
|
skills repo provides:
|
|
├── skills/hq/ # Skill files (SKILL.md, templates, scripts)
|
|
├── pkgs/worker/ # Nix package template
|
|
├── releases/ # Binary tarballs
|
|
└── modules/ai-skills.nix # Home-manager module
|
|
|
|
dotfiles configures:
|
|
├── pkgs/worker/ # Copy of nix package
|
|
├── home.packages # Install worker globally
|
|
└── services.ai-skills # Deploy skills to ~/.codex/skills/
|
|
```
|
|
|
|
### Cross-Agent Skills Flow
|
|
```
|
|
Global skills: nix flake → home-manager → ~/.claude/skills/
|
|
→ ~/.config/opencode/skills/
|
|
→ ~/.codex/skills/ (NEW)
|
|
|
|
Per-repo: .skills manifest → direnv → .claude/skills/
|
|
→ .opencode/skills/
|
|
→ $CODEX_HOME/skills/ (NEW)
|
|
```
|
|
|
|
# Process and Workflow
|
|
|
|
## What Worked Well
|
|
|
|
- Orch consensus provided valuable architecture feedback (even with only GPT)
|
|
- Following beads pattern for binary distribution kept things simple
|
|
- Filing issues for dotfiles keeps concerns separated
|
|
- Existing ai-skills module made Codex addition trivial
|
|
|
|
## What Was Challenging
|
|
|
|
- Orch model failures (Gemini, OpenRouter) - works directly via llm but not through orch
|
|
- Worktree blocking master branch merge
|
|
- Multiple layers of deployment (skills repo → dotfiles → user repos)
|
|
|
|
# Learning and Insights
|
|
|
|
## Technical Insights
|
|
|
|
- `llm` library plugins load correctly but orch's async model loading has issues
|
|
- Codex uses `~/.codex/skills/` (different from Claude/OpenCode patterns)
|
|
- Worker CLI is actually already installed globally via nix profile
|
|
- Tarball in git is fine for small binaries (~300KB)
|
|
|
|
## Process Insights
|
|
|
|
- Filing issues in downstream repos (dotfiles, orch) keeps separation clean
|
|
- Each repo handles its own concerns - skills provides, dotfiles integrates
|
|
|
|
## Architectural Insights
|
|
|
|
- Three-tier skill deployment: system (Codex built-in), global (home-manager), per-repo (direnv)
|
|
- Skills are portable across Claude/OpenCode/Codex - same SKILL.md format
|
|
- HQ depends on worker CLI which needs separate installation path
|
|
|
|
# Context for Future Work
|
|
|
|
## Open Questions
|
|
|
|
- How to merge integration→master with worktree conflict?
|
|
- Should orch handle model failures more gracefully?
|
|
- Best practice for worker version updates?
|
|
|
|
## Next Steps
|
|
|
|
- Dotfiles: Implement dotfiles-u96 (worker CLI package)
|
|
- Dotfiles: Implement dotfiles-ha0 (Codex skills deployment)
|
|
- Merge integration→master once worktree resolved
|
|
- Test full HQ workflow with Codex as orchestrator
|
|
|
|
## Related Work
|
|
|
|
- Previous: [[file:2026-01-11-hq-architecture-orch-consensus-beads-cleanup.org][HQ Architecture and Orch Consensus]]
|
|
- Previous: [[file:2026-01-11-worker-cli-cleanup-refactors.org][Worker CLI Cleanup]]
|
|
- Issues: dotfiles-u96 (worker package), dotfiles-ha0 (Codex skills), orch-d08 (model failures)
|
|
|
|
# Raw Notes
|
|
|
|
## Orch Consensus Summary (GPT-5.2)
|
|
|
|
Key feedback on HQ architecture:
|
|
- **Support** overall - "Git worktrees + explicit state machine + text-based skills makes the system portable"
|
|
- **Risk:** Split-brain state between SQLite, git, and bd comments
|
|
- **Gap:** Idempotency/crash recovery under-specified
|
|
- **Gap:** Implicit dependencies (same files) not detected
|
|
- **Suggestion:** WIP limit of 3-7 workers, measure review queue time
|
|
- **Suggestion:** Human checkpoints for security/auth, large refactors, >2 request-changes cycles
|
|
|
|
## Files Pushed to Git Forge
|
|
|
|
Worker binary accessible at:
|
|
```
|
|
https://git.clarun.xyz/dan/skills/raw/branch/master/releases/worker_0.1.0_linux_amd64.tar.gz
|
|
SHA256: sha256-Lz+gnjeedjwVV31rcijjQpMguMrBfvSfOUcOyLaFiI8=
|
|
```
|
|
|
|
# Session Metrics
|
|
|
|
- Commits made: 3 (on integration branch)
|
|
- Files touched: 16
|
|
- Lines added/removed: +1106/-10
|
|
- Issues filed: 3 (dotfiles-u96, dotfiles-ha0, orch-d08)
|
|
- Issues closed: 1 (skills-legi)
|