docs: add canonical AGENTS.md for the GitHub-as-code repo

[devantler]

🤖 Generated by the Daily AI Assistant

Fixes #55.

Problem

devantler-tech/.github — the org's GitHub-as-code source of truth (deploy/, Crossplane +
provider-upjet-github, published as a cosign-signed OCI artifact and reconciled by the platform
github-config tenant) — had no AGENTS.md, so the daily engineer (and Copilot code review,
Cursor, Codex, …) operate it with no canonical instructions and no ## Maintenance card. Every other
actively-developed portfolio repo carries one.

What this does

Adds a canonical AGENTS.md (96 lines) that:

• Defers to the root contract. Points at the monorepo's root AGENTS.md for the shared
  engineering contract; documents only what's repo-specific.
• Captures the golden rules that have been hard-won maintainer feedback and were previously
  unwritten here: manage GitHub declaratively, never imperatively (the tenant reverts gh api/UI
  drift; applying an existing label is triage, editing a label definition is config); ownership →
  the maintainers team, not individuals; Observe-first adoption (external-name + management
  policy excluding Delete); and that IssueLabels is authoritative (enumerate a repo's live
  labels before applying, or it deletes undeclared ones).
• Maps the deploy/ layout (repositories/, teams/, labels/, provider-config,
  external-secret, kustomization).
• Adds the ## Maintenance card: the exact validate command (kubectl kustomize deploy/, which is
  what ci.yaml runs and the sole CI - Required Checks gate), the roadmap home (epic Roadmap: declarative GitHub-org-as-code — extend coverage & sustain the source of truth #56), and a
  repo-specific watch-list (drift/coverage, the cd.yaml publish path, agent-file freshness).

Scope decisions (worth a reviewer's eye)

#55 listed three gaps; this PR addresses them as follows:

1. AGENTS.md — added (the core of this PR). ✅
2. .github/copilot-instructions.md — intentionally not added. Per the root contract, we have
   retired the separate Copilot-review instruction file org-wide — Copilot code review reads AGENTS.md
   directly (since 2026-06-18), so a parallel file is redundant. The issue's premise here is now stale.
3. CONTRIBUTING.md deploy/ guidance — intentionally not added to .github/CONTRIBUTING.md.
   That file is the org-wide default community-health file rendered for every repo in the org, so
   deploy/-specific guidance does not belong there. The Crossplane authoring workflow now lives in
   AGENTS.md (the repo's canonical file) alongside the existing architecture notes in
   deploy/README.md. ✅ (intent covered, correct home)

Validation

• kubectl kustomize deploy/ builds clean (the CI - Required Checks gate; unchanged by this docs-only diff).
• All relative links in AGENTS.md resolve to existing paths.

Docs-only; no behaviour change. Opened as a draft for promotion.