Agent Protocol

How agents work in this lab — the rules that keep two bots and one human from tripping over each other.

One thread per issue

Every work item is exactly one GitHub issue. Discussion, plan, review, authorization, execution evidence, and follow-ups all live on that thread. Do not split a work item across issues, chat threads, or side channels — the issue is the record.

Review ≠ authorization

• The agent drafts the plan and writes it up in the handoff format: Context / What I did / What I need from you / Acceptance criteria.
• The peer agent reviews the plan and states agreement or requested changes.
• Execution starts only when the human authorizes it (“approve and build” or equivalent). A peer’s approval alone is never authorization. An explicit human choice beats agent consensus every time.

Human-only secrets steps

Agents never handle raw secret values. The following are always human steps:

• Placing tokens/credentials into GitHub Actions secrets (e.g. DOCS_DEPLOY_PAT, read-only inventory service-account tokens).
• Creating or rotating credentials at the issuer (Harbor robot accounts, cloud PATs, registry credentials).
• Supplying kubeconfigs or any cluster access material — agents receive them via the secure channel and never write them into the repo, docs, or logs.

If a step needs a secret you do not have, stop at that step, name exactly what is needed and where the human must place it, and continue with the parts that do not need it.

Secrets hygiene

• No IPs, hostnames, tailnet names, SSH paths, tokens, kubeconfigs, keys, emails, personal names, or home paths in this repo — ever. The CI pipeline enforces this with gitleaks on source, gitleaks on the Astro dist/ bundle (showcase + this book, one build), and inventory/audit-bundle.py on the same bundle.
• The generator script (inventory/generate-inventory.py) reads only names and app versions of images — never env vars, never secrets.
• Report a suspected leak the moment you see it; do not try to clean it quietly. Rotating the exposed credential is the human’s call.

Working with your peer

• Review like you will operate it: check the plan against the IAC repos and these docs, not just against its own description.
• When you disagree, say what would change your mind — concrete, on the issue.
• When plans change mid-execution, update the issue before continuing; the issue thread is the shared state.
• Keep handoffs terse. The human reads on a phone and listens more than reads: lead with the one decision or action needed.