Turn a CLI coding agent into a coordinated platform engineering teammate.
A portable, runtime-neutral behavioral specification and coordination protocol for AI agents doing Kubernetes, Helm, ArgoCD, CI, and observability work. Works with Aider, Claude Code, Codex CLI, Factory Droid, Goose, OpenCode, or any CLI agent that can read instructions and run shell commands.
Most agent setups stop at "give it a system prompt." That falls apart on real infra work — multi-step rollouts, second opinions on risky PRs, memory that survives context resets, safe Kubernetes defaults, and parallel investigation across clusters. This harness adds the behavioral specification and coordination protocol around the prompt.
| Why it pays off |
|---|
| ~70x fewer tokens for architecture questions via Graphify graph queries vs. linear file reads. |
60–90% token compression on verbose CLI output via rtk with zero workflow change. |
Cross-session memory via bd — task state, comments, and durable learnings survive every compaction. |
Hand-curated knowledge base (agent-knowledge/references/) — markdown-only index.md, log.md, and numbered learnings-*.md agents read before they grep the repo. Adapted from Karpathy's LLM Wiki. |
3x+ wall-clock speedup on N-cluster validation via parallel sub-agent dispatch (core/protocols/parallel-dispatch.md). |
Second-agent PR review with structured bot-reply protocol (core/protocols/pr-review-loop.md). |
18 observability skills install via gcx skills install --all — no vendoring. |
┌─────────────────────────────────────────────────┐
│ AGENTS.md │
│ routing rules · safety defaults · memory keys │
└────────────────────┬────────────────────────────┘
│
┌─────────────────────────────┼─────────────────────────────┐
│ │ │
┌────────▼────────┐ ┌──────────▼────────┐ ┌──────────▼─────────┐
│ Specialist │ │ Durable state │ │ Local knowledge │
│ sub-agents │ │ (bd / Beads) │ │ base + Graphify │
│ │ │ │ │ │
│ task-planner │ │ tasks, comments, │ │ agent-knowledge/ │
│ tool-researcher │ │ memories, ready │ │ references/ │
│ helm-engineer │ │ queues survive │ │ index · log · │
│ argocd-engineer │◄────────┤ compaction │────────►│ learnings-*.md │
│ platform-engr │ │ │ │ (Karpathy Wiki) │
│ pr-reviewer │ └─────────┬─────────┘ │ scripts/ · metrics│
│ general-engineer│ │ │ + graph queries │
└────────┬────────┘ │ └────────────────────┘
│ ▼
│ ┌──────────────────────────────────┐
└───────────►│ Skills (executable playbooks) │
│ │
│ shiny-engineer · create-pr · │
│ helm-upgrade · k8s-debug · │
│ graphify · contract-validation │
│ │
│ + 18 observability skills │
│ via `gcx skills install` │
└────────────────┬─────────────────┘
│
┌───────────▼────────────┐
│ Token economics │
│ │
│ rtk command policy │
│ (native / rtk-safe / │
│ raw-required) │
└────────────────────────┘
The compaction-and-recovery loop is documented end-to-end in LIFECYCLE.md.
# 1. Install the three required tools
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash # bd
pipx install graphify # graph
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | bash # rtk
# Optional: Grafana stack? Install gcx + the 18-skill bundle.
brew install grafana/grafana/gcx
gcx skills install --all # → ~/.agents/skills/
# 2. Clone the harness somewhere you can reference it
git clone https://github.com/<owner>/platform-agent-harness ~/platform-agent-harness
export HARNESS=~/platform-agent-harness
# 3. Drop the instruction contract into your infra repo
cp "$HARNESS/templates/AGENTS.template.md" ./AGENTS.md
# 4. Initialize task state and build a repo graph
bd init && bd prime
graphify . --no-viz
# 5. Wire your runtime — pick one from adapters/
cat "$HARNESS/adapters/<your-runtime>/README.md"Customize the placeholders in AGENTS.md (cluster naming, repo conventions, contact names) and you are running. Every adapter README has a concrete file-mapping table, copy commands, and verification steps.
For a public companion repo using this exact operating model, see Thakurvaibhav/k8s — a GitOps-driven "Platform in a Box" with Argo CD App-of-Apps, Envoy Gateway, Prometheus/Thanos, Kyverno, and Sealed Secrets.
| Layer | Path | What it provides |
|---|---|---|
| Agent prompts | core/agents/ |
7 specialist sub-agents (planner, researcher, helm, argocd, platform/observability, PR reviewer, general-engineer) with explicit "when to invoke / when NOT to invoke" boundaries |
| Protocols | core/protocols/ |
8 canonical rules: harness-pillars, delegation, bd-and-memory, rtk-command-policy, graphify-first, pr-review-loop, parallel-dispatch, safety-and-handoff |
| Skills | skills/ |
12 portable executable playbooks (shiny-engineer, create-pr, helm-upgrade, k8s-debug, graphify, contract-validation, adopt-eval, upstream-triage, stakeholder-comms, stop-slop-code, systematic-debugging, ingest-reading); observability skills live in gcx skills install |
| Domain packs | domain-packs/ |
Kubernetes safety, Helm essentials, observability-via-gcx — focused, not exhaustive |
| Hooks | core/hooks/ |
Transcript-parsing pre-compact memory snapshot, rtk autoprefix, context-threshold warning, learning-capture gate |
| Tools | tools/ |
One-pagers for bd, Graphify, rtk, gcx with upstream install links |
| Adapters | adapters/ |
Concrete wiring for 6 CLI agent runtimes |
| Agent knowledge | agent-knowledge/ |
Shared, runtime-neutral knowledge home (see agent-knowledge/README.md): references/ (hand-curated index.md, log.md, numbered learnings-*.md — Karpathy LLM Wiki pattern), scripts/ (knowledge-search, drift-check, learn, codex-dispatch, codex-session-prime, auto-consolidate), metrics/ (read-frequency + citation telemetry), reading/ (external-source distilled notes, separate trust tier) |
| Templates | templates/ |
AGENTS.template.md to drop into your repo + dispatch / handoff / validation contracts |
| Examples | examples/ |
2 end-to-end worked stories: Helm chart upgrade and alert investigation |
| Sanitization | sanitization/ |
Pre-publish gate using trufflehog + gitleaks + local denylist |
Every sub-agent ends a non-trivial task with a four-step Task Completion Checklist (canonical: core/protocols/bd-and-memory.md):
bd remember— persist any non-obvious finding as a self-contained memory.- Append one line to
agent-knowledge/references/log.md. - If a finding refines or contradicts an existing item, update or
CONFLICT:-flag the rightagent-knowledge/references/learnings-*.mdentry. - Update
agent-knowledge/references/index.mdonly when a doc was added or removed.
The handoff report has a mandatory ## Knowledge updates section (templates/handoff-report.template.md) — agents must list what they changed, or write None. next to each row. This is the explicit gate that keeps the local knowledge base alive across sessions.
- Not a documentation library. Every file pulls weight in a real agent session.
- Not org-specific. Real cluster names, ticket prefixes, and internal URLs have been redacted. The patterns are portable.
- Not a fork of any agent runtime. The same instruction contract loads under all six runtimes via the adapters.
- No mutating Kubernetes commands (
apply|create|delete|patch|replace|edit|scale|rollout|...). - No
helm install|upgrade|uninstall|rollback. - No pushes to
main/master; no force-push to protected branches. - Read-only by default; runtime denylists pin the rest.
- All examples and templates use synthetic placeholders (
<cluster>,<service>,<TICKET-KEY>).
The patterns here come from production platform-engineering work. The harness vendors and sanitizes that work into a portable kit. The agent runtimes and tools it composes are all upstream open-source projects — see installation/prerequisites.md.