docs: add worklog for HQ deployment and Codex skills integration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 06:56:49 -08:00 · 2026-01-13 06:56:49 -08:00 · 3cc7540c46
parent 06f5fafd1a
commit 3cc7540c46
1 changed files with 210 additions and 0 deletions
--- a/docs/worklogs/2026-01-13-hq-deployment-codex-skills-integration.md
+++ b/docs/worklogs/2026-01-13-hq-deployment-codex-skills-integration.md
@ -0,0 +1,210 @@
+---
+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)