skills/docs/worklogs/2026-01-13-hq-deployment-codex-skills-integration.md

title	date	keywords	commits	compression_status
HQ Deployment Documentation and Codex Skills Integration	2026-01-13	hq worker-cli codex skills-deployment cross-agent nix-module orch-consensus	3	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

• Ran orch consensus on HQ architecture - received comprehensive feedback from GPT-5.2
• Filed orch bug report (orch-d08) for Gemini/OpenRouter model failures
• Created worker release documentation (docs/releasing-worker.md)
• Created nix package template (pkgs/worker/default.nix)
• Built and released worker v0.1.0 tarball (327KB)
• Added hq and review-gate to skills.nix
• Created comprehensive skills/hq/README.md deployment guide
• Updated skills/hq/SKILL.md with requirements table and model config
• Filed dotfiles-u96: Add worker CLI package
• Filed dotfiles-ha0: Add Codex skills deployment
• Added codexSkills option to ai-skills nix module
• Added Codex per-repo support to use-skills.sh
• 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

# 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)