AGENTS.md - Agent Coding Guidelines

Follow the AGENTS.md format. Keep this file short (~50-80 lines); load detailed context from .agents/ only when task triggers match.

Overview

GitOps-based Kubernetes cluster on Talos Linux with FluxCD reconciliation. Make changes through this repo; avoid direct cluster edits.

Structure: kubernetes/ (manifests, HelmReleases), talos/ (machine configs), docs/ (runbooks), .agents/ (on-demand context). Tool versions: .mise.toml.

Commands (run these first)

• Task runner: mise exec -- task reconcile, mise exec -- task talos:generate-config, mise exec -- task talos:apply-node IP=..., mise exec -- task talos:upgrade-node IP=...
• Validate before commit: mise exec -- kubeconform -strict kubernetes/, mise exec -- shellcheck scripts/*.sh
• Tooling: run flux, helm, kubectl, kustomize, sops, age, talhelper, talosctl, yq, jq, kubeconform, shellcheck via mise exec -- <cmd>.

Tool use and context

• Prefer tools over memory: when a tool can provide current data, use it first. Hedge only on tool errors, ambiguity, or empty results.
• ToolHive workflow is mandatory when available: if both find_tool and call_tool exist, always use this sequence:
  1. Run find_tool with a relevant query.
  2. Identify the correct tool name and required parameters from the result.
  3. Run call_tool with those parameters.
  4. Interpret the result and respond naturally; never return raw JSON/tool output.
• Load context on demand: read only .agents/ files whose trigger keywords match the task; do not preload all files.

.agents/ (load on demand)

• learned-preferences.md: use for revert/undo, resource usage, MCP vs shell, find_tool/call_tool, and confidence guidance.
• learned-workspace.md: use for HTTPRoute, ToolHive, MCPServer, Flux, Talos, Reloader, in-cluster URLs, Rook, RBAC, and zap context.
• common-operations.md: use for app add/upgrade, SOPS/secrets, debugging/logs, and backup/restore/volsync procedures.

learned-preferences.md and learned-workspace.md are authoritative and updated by continual learning.

ToolHive operator/CRD upgrades: follow .agents/skills/toolhive-upgrades/SKILL.md (OpenSkills registry: toolhive-upgrades). That workflow requires a code-reviewer subagent pass before declaring the upgrade complete.

Learned User Preferences

• Prefer fixing root causes (disk headroom, capacity, correct config) over silencing alerts or only lowering warning thresholds.

Code style

• URLs: use ${SECRET_DOMAIN}; never hardcode domains.
• YAML: 2-space indent, LF endings. Use anchors (&, *) only within one --- document (Kustomize does not resolve across documents).
• For *-opt MCPServer objects, keep them in the same file as the primary and fully duplicate spec (no cross-document <<:/*spec_anchor).
• Secrets: SOPS only; never commit plaintext secrets or age.key.
• Kubernetes naming: lowercase-dashes; place resources in kubernetes/apps/<app>/<type>/ with ks.yaml.
• Shell scripts: set -euo pipefail and pass shellcheck.

Safety and permissions (three-tier)

• Always: Read files, list dirs, validation (kubeconform, shellcheck), flux-local test/diff, format/lint.
• Ask first: Git push (always ask before any push), push to main, force push, applying to live cluster (task reconcile, flux reconcile, talos apply), decrypting/editing SOPS secrets, deleting resources.
• Never: Commit secrets or age.key (no exceptions).

When stuck

Ask a clarifying question, propose a short plan, or open a draft PR with notes. Avoid large speculative changes without confirmation.

PR / commit checklist

• Title: Conventional Commits (for example feat(scope): description).
• Run validation commands above and keep diffs small and focused.