Imported from olga-mir/playground (AGENTS.md). Install upstream with npx skills add olga-mir/playground. Copyright stays with the author.

Project purpose

A learning and exploration platform for experienced Kubernetes and Platform Engineers. Aims for prod-like solutions while remaining fully disposable — provisioned at the start of a session, torn down at the end. All operations must be captured in manifests, scripts, or Taskfiles. Runs in a personal GCP account: be cost- and security-aware.

Critical rules

• Never proactively create .md or README files — only when explicitly asked
• Never commit project IDs or other semi-sensitive values
• Use git mv (not mv) for versioned files
• Always place a newline at the end of files
• Validate Taskfile changes with yq before saving
• Pass --context inline on every kubectl command — never as a separate step; combine related operations into one command to minimise approval prompts
• Use Taskfile tasks for common operations like triggering workflows (task debug:trigger-flux-bootstrap-workflow) or resuming the orchestrator (task agentic:resume PHASE=...) to ensure consistent behavior and use established "recipes".

Architecture overview

Three-cluster hub-and-spoke fleet, provisioned in order:

kind (local bootstrap)
  └─ provisions → GKE control-plane   (Crossplane + Flux + platform services)
                    └─ provisions → GKE apps-dev   (tenant workloads)

• Crossplane v2 handles GKE cluster provisioning (no claims — direct namespace-scoped XRs)
• Flux GitOps manages everything on each cluster once bootstrapped
• GitHub Actions bootstraps Flux on new GKE clusters, triggered by Flux notifications

Cluster contexts

Key entry points

Domain docs

Deep-dive context for specific areas — read the relevant doc when working in that domain:

• Infrastructure & Cluster Provisioning — Crossplane, GKE, kind setup, provisioning flow
• Flux & GitOps — Kustomize structure, known Flux quirks, debugging, image automation
• GitHub Integration — GitHub App auth, Actions workflows, notifications
• Tenants — Tenant onboarding, multi-repo GitOps, image promotion
• Version Upgrades — Weekly automated upgrades: how the scan works, adding new components, known quirks
• Agentic Loop — Automated provisioning pipeline: DSPy modules, phases, fast-paths, escalation logic, snapshot artifacts
• Operations — Fleet health check, key task commands, load testing and performance experiments

Variables

Env vars in .setup-env are sourced in the working terminal but are not accessible to agents. Required vars are documented in each domain doc.

Secrets and Keys

Critical distinction for AI agents:

• ANTHROPIC_API_KEY: Used by GitHub Actions and local claude CLI for repo-level automations.
• KAGENT_ANTHROPIC_API_KEY: A separate, specific key used by kagent workloads running inside the Kubernetes cluster. NEVER conflate these or swap their names in manifests or workflows.