Imported from the-robot-lives/cluster-tools (AGENTS.md). Install upstream with npx skills add the-robot-lives/cluster-tools. Copyright stays with the author.

AGENTS.md — cluster-utils

Guidance for Codex, Grok, Cursor, and other AGENTS.md / AGENT.md tools.

Claude Code loads CLAUDE.md. Same policy; this file is the harness-shaped sibling (numbered MUST first, markdown headings). If both this file and a parent AGENTS.md load, this file wins on conflict.

MUST (every turn)

1. Trinity Protocol (REQUIRED): substantive responses run Orientation → Friction → Response (assumptions surfaced; WEDGE/SHADOW/CRITIC; meta-review). Full text: trl-infra protocols/the-trinity-protocol.md (+ .summary.md).
2. No shell in the main thread — delegate lookups/builds/test runs to tasker subagents; they report answers, not raw output.
3. Worktrees (REQUIRED): canonical placement .claude/worktrees/<name>/, created from this repo's own .git off develop; .claude/worktrees/ is gitignored — see Worktrees — Canonical Convention below.
4. PRs target develop. Never merge or push main (CI/CD-only release path).

Identity

Kubernetes cluster ops helper; see bin/ and README.md. Coupled to trl-infra .infra-config.yaml + terraform/; shares k8-lib.

Part of the Noizu utilities fleet (trl-infra monorepo, Portfolio/Utilities/source/*). Installed to ~/.local/bin via monorepo root make install-utilities; some packages are also dual-path registered at repo-root utilities/<group>/ (same remote/SHA).

Commands

make test      # test target (see Makefile; some are no-op placeholders)
make install   # install binaries/completions to ~/.local/bin

Branch & PR Policy

• Submodules sit on develop — keep your checkout on develop.
• All PRs target develop (feature/bug/task branches fork from develop).
• main is CI/CD-only: CI/CD automation performs all merges into main (release path). Never merge to or push main by hand.

Worktrees — Canonical Convention (REQUIRED)

All work happens on git worktrees, created from this repo's own .git — never work directly on a shared checkout of develop/main.

• Placement (fixed): every worktree lives inside this repo's checkout at .claude/worktrees/<name>/ — never siblings (<repo>.worktrees/), never ad-hoc paths. Matches Claude Code's native worktree tooling, so harness-created and manual worktrees coexist.

• Naming: <name> = branch name with / → - (branch feature/vfs-wave1 → .claude/worktrees/feature-vfs-wave1).

• Creation — from this repo's own .git, based on develop (never main):

  git -C <this-repo> worktree add .claude/worktrees/<name> -b <branch> develop

• Hygiene: .claude/worktrees/ is gitignored in this repo; never commit its contents. One worktree per task; remove it when the work lands (git worktree remove .claude/worktrees/<name> — keep the branch).

• Addressing: git -C <this-repo>/.claude/worktrees/<name> …; verify branch + clean index before any git write; no git stash.

• Elixir projects: the MAIN checkout owns deps/ + _build/; each worktree symlinks deps (and _build where needed) to the canonical checkout by absolute path — no per-worktree re-fetch/recompile.

• Legacy placements (.worktrees/, .wt/, <repo>.worktrees/ siblings, staging/) are grandfathered — do not create new ones; migrate opportunistically. staging/ remains local-only experiments (never pushed/submoduled).

Pointers

• Claude Code baseline: CLAUDE.md