The part I spent the most time on wasn't the fan-out loop itself — that's a straightforward per-binding install with failure isolation, so one bad binding doesn't take the rest of the fleet down. It was site.lock.yaml. A site's pack source points at a git ref like main, and main moves. Once a site fans out to a dozen workspaces, "what commit is actually running" stops being a question you can answer by eyeballing a YAML file — you need a pin, and you need the install path to refuse to guess.

So aoh install --site won't run without a lock that agrees with site.yaml. It resolves every pack through the lock's resolvedCommit, never by re-resolving the ref itself. aoh lock only writes entries that don't exist yet; aoh lock --update is the only thing that moves a pin forward, and it demands --yes if the source changed, not just the commit. I proved this end to end with a real git fixture: lock a pack, push a new commit upstream, re-install without updating — the old commit is still what lands. Only after aoh lock --update does the new one show up, and a commit that deletes a file actually removes it from every workspace, not just adds the new ones.

That last part — convergence, not just fan-out — is what makes this feel like inventory rather than a batch script. Ansible's inventory never made you think about drift because the module system handled convergence per-host. AOH's install path now does the same per-workspace, and the lock is what makes "per-workspace" mean something across an entire fleet instead of one binding at a time.

I didn't want the docs to be a bolt-on written in a single pass at the end. AOH's whole pitch is that good agentic work follows a loop — brainstorm the shape, write the plan down, execute in reviewable slices, check the result against reality — so I built the docs site the same way I build a pack.

It started as a brainstorm, not a docs outline: what does someone actually need in the first sixty seconds, what's a concept versus a tutorial versus a reference page, which claims in the existing markdown are real versus roadmap. That turned into a written plan — sections, deck filenames, which pages get interactive components, a hard build gate (onBrokenLinks: 'throw', zero tolerance) — before any content got written.

Then it went to subagent-driven execution: one task per slice (scaffold, concepts, decks, getting-started, tutorials, reference, this landing-and-blog task), each one reviewed on its own before the next started. A concept page couldn't claim a feature that wasn't in the code — the drift model, the eval runner, non-Hermes adapters are all marked "planned" rather than described as if they were shipped. And the whole thing closes with a full-branch review before it's called done, the same review discipline that gates a pack going into collections/core/.

It's a small thing, maybe, but it's the same conviction the harness itself is built on: process worth having for code is process worth having for the words describing that code, too.

If you want to see where it landed, the repo's right there — github.com/agenticdevops/aoh. Try it: clone it, run uv run aoh validate against one of the example packs, and see if the docs actually got you there without detours.

Shipping the Claude Code and Codex adapters this week meant answering a question I'd put off: does either runtime have a config surface that can say "no" to kubectl delete before the request leaves the agent? Codex, no — execpolicy rules match a literal command prefix, and three trivial forms slip past it: put --context first, use an absolute binary path, or wrap the call in sh -c. All three return no decision at all, silently.

Claude Code surprised me. .claude/settings.json supports permissions.deny at the subcommand level — name kubectl delete, kubectl apply, helm upgrade specifically, and Claude Code refuses the tool call outright. Most people evaluating it for ops work don't know this exists; I didn't, until I went looking while building this adapter. The AOH-generated workspace now sets it for every mutation verb in the shared kubectl/helm list.

A literal deny list has the same blind spot Codex's rules do, so I paired it with a PreToolUse hook — kubectl-guard.sh — that actually parses the command instead of pattern-matching it: strips sudo/env wrappers, unwraps sh -c, strips absolute paths, tokenizes past flags for the real verb. Fail-closed everywhere: bad JSON, missing jq, any shell metacharacter, all block. It catches all three forms that beat Codex's rules. It also has a sharp edge I didn't expect until testing it: it blocks every compound Bash command, kubectl or not, because it can't safely tokenize syntax it doesn't parse. kubectl get pods | grep Pending gets blocked right alongside kubectl delete pod x. Documented, not silently patched around.

Here's the honest part. Neither the deny list nor the hook is a boundary — they're guardrails, best-effort, scoped to commands routed through Claude Code's own Bash tool, blind to anything outside that session. The actual boundary is what it was in the Hermes tutorial: a scoped ServiceAccount whose RBAC the API server checks on every request, regardless of what Claude Code's config catches. If the hook has a bug, that's a worse experience, not a security failure — the cluster still says no.

Try it: the new Claude Code tutorial walks through generating the workspace, reading the deny list and hook yourself, and watching both walls hold — one best-effort, one absolute.

I wanted to answer one question honestly: if I tell an AOH pack its agent is kubectl-readonly, is that a comment or is it true? "Instructed not to delete things" and "physically incapable of deleting things" are very different claims, and I only wanted to ship the second one.

The answer ended up living outside the agent entirely. install-hermes-agent --binding now generates a provision.sh that a human runs once, by hand — AOH never touches the cluster itself, it only writes files. That script creates a dedicated ServiceAccount, a ClusterRole scoped to get/list/watch, binds them together, and writes a scoped kubeconfig. The agent launches with that kubeconfig, not yours.

Then I proved it without the agent anywhere in the loop. Same kubeconfig, two commands, on a real kind cluster:

kubectl --kubeconfig "$KC" get pods -A                                        # works
kubectl --kubeconfig "$KC" delete pod coredns-668d6bf9bc-kw88m -n kube-system  # Forbidden

The API server itself rejected the delete — Error from server (Forbidden): ... cannot delete resource "pods". Nothing about how the request was made changed between the two calls; only the RBAC attached to the identity that sent it. That's the guardrail I wanted: it lives in the target platform, not in a prompt telling the agent to behave.

While that provision-script generator was under final review, a real bug surfaced: binding values (context names, namespaces) were being interpolated straight into bash without validation — a textbook shell-injection opening if a binding file ever came from somewhere less trusted than my own repo. The fix was a strict allowlist regex on every value before it touches the generated script, with a PackError if anything outside [A-Za-z0-9._-] shows up. Caught before it shipped, but a good reminder that "generates a shell script" is a security-sensitive code path, review or no review.

Full walkthrough, copy-pasteable commands, and the honesty note about what "read-only" doesn't cover: the kubeops-readonly tutorial. If you've got a kind cluster lying around, try it — watch the API server say no.

AOH's spec started with a Workflow kind: a YAML file that named a sequence of skills a role should run in order. It felt obvious at the time — Ansible has playbooks, so AOH should have something that chains steps. I wrote it, wired the validator to it, had the Hermes adapter emit commands for it.

Then I actually looked at what was in one. A workflow file was a name, a list of skill references, and maybe a note on ordering. Every field in it either duplicated something already declared on the role, or restated the skill's own name back at me. It carried zero logic of its own — it was a reference bundle wearing a kind's clothing.

Around the same time I was reading through how Superpowers structures its own skills, and the pattern clicked: a multi-step process isn't a different kind of thing from a skill — it's a skill whose body happens to orchestrate other skills by name. platform-sre-triage doesn't need a Workflow wrapper; it needs a SKILL.md that says "run X, then branch on the result, then run Y." That's still a skill. The runtime doesn't care that it's "a workflow" — it just executes what the SKILL.md tells it to.

So Workflow came out. The multi-skill workflows in the example packs became process skills — same content, one fewer kind to validate, reference, and keep in sync with the role. While I was in there breaking things, I also renamed agents/ to roles/ (role is the real-world word; "agent" was doing double duty with the runtime concept) and picked ops: as the canonical command prefix Hermes emits, instead of aoh:.

Fewer kinds, same expressiveness, less to keep consistent. If you want the current shape of the spec — what's mandatory, what's opt-in, and where process skills fit — the pack spec reference has the whole thing. Try it: run aoh validate against a skills-only pack and watch how little ceremony it actually takes to get to a valid one.