agentleFS
bjw-s-labsbjw-s-labs/home-ops/AGENTS.md

home-ops

AGENTS.md869 starsChanged 33 days agoApache-2.0View on GitHub

This file is the canonical, agent-independent source of repository policy. Essential rules live here directly; do not rely on agent-specific import syntax to load them.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

10 rules. About 2 are common, 1 is distinctive, and 7 are very specific to this project.

  • ≈2

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Prefer immutable @sha256: digests for container images.

    line 21
  2. Very specific:

    When editing YAML, read .agents/instructions/sorting.instructions.md and preserve its Kubernetes and app-template ordering conventions.

    line 23
  3. Very specific:

    Keep component-specific documentation alongside its configuration.

    line 25
  4. Common:

    Never commit plaintext credentials, resolved secrets, kubeconfigs, or Talos client configuration.

    line 29
  5. Very specific:

    Treat persistent-volume changes, CloudNativePG bootstrap/recovery and object-store settings, backup policies, resource renames, and Flux …

    line 32
  6. Very specific:

    Use the repository's mise-managed tools and inspect just --list for available recipes.

    line 38
  7. Distinctive:

    Read the matching skill before performing these tasks:

    line 53
  8. Very specific:

    Add a Kubernetes application: .agents/skills/add-app/SKILL.md.

    line 55
  9. Very specific:

    Keep shared policy in this file, task workflows in .agents/skills/, and detailed conditional guidance in .agents/instructions/.

    line 64
  10. Common:

    Keep personal model preferences, credentials, permissions, and MCP configuration in user-level configuration, synchronized through dotfiles …

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Repository instructions

This file is the canonical, agent-independent source of repository policy. Essential rules live here directly; do not rely on agent-specific import syntax to load them.

Repository map

  • kubernetes/apps/<namespace>/<app>/: application Flux Kustomizations, HelmReleases, chart sources, and configuration.
  • kubernetes/flux/cluster/: Flux entry point and cluster-wide application patches.
  • kubernetes/components/: reusable Kustomize components, including namespaces, CloudNativePG, and backups.
  • kubernetes/talos/: Talos templates, node overrides, version declarations, and operational recipes.
  • kubernetes/bootstrap/: cluster bootstrap configuration and recipes.
  • docker/ and ansible/: Docker-host applications and host provisioning.
  • .forgejo/workflows/: CI and AI PR review; .renovate/: dependency-update presets.
  • .mise.toml: tool versions and environment; .justfile and mod.just files: operational commands.

Project conventions

  • This repository manages live infrastructure through GitOps. Flux can reconcile changes under kubernetes/ soon after merge. Consider rendered resources and deployment impact, not only the source diff.
  • Kubernetes applications live under kubernetes/apps/<namespace>/<app>/. Follow existing neighboring applications rather than assuming a shared-base or multi-cluster overlay layout.
  • metadata.namespace is intentionally omitted on application HelmReleases and Flux Kustomizations. Namespace kustomizations at kubernetes/apps/<namespace>/kustomization.yaml set the namespace of the Flux Kustomizations; each application's Flux Kustomization sets spec.targetNamespace for its deployed resources. Do not add redundant namespaces or flag their absence without checking that chain.
  • Prefer immutable @sha256: digests for container images. OCI Helm chart sources use OCIRepository.spec.ref.tag or a version selector; do not apply the container-image digest convention to chart references.
  • For dependency reviews, verify upstream changes using available read-only release notes, changelogs, source comparisons, or image metadata. Helm chart and container-image reviews require upstream evidence, not only Renovate's description. Report unavailable evidence as unverified; never invent tool results or compatibility claims.
  • When editing YAML, read .agents/instructions/sorting.instructions.md and preserve its Kubernetes and app-template ordering conventions. Avoid unrelated sorting churn, and do not reorder configuration embedded in string fields.
  • Application workloads normally use Flux HelmReleases with spec.chartRef pointing to a per-app OCIRepository in ocirepository.yaml. Follow the add-app skill for scaffolding; existing raw manifests and operator-managed resources are not automatically violations.
  • Keep component-specific documentation alongside its configuration. Do not copy another home-ops repository's paths, architecture, or operational commands without checking this tree.

Secrets and operational safety

  • Never commit plaintext credentials, resolved secrets, kubeconfigs, or Talos client configuration. Kubernetes application secrets normally come from External Secrets backed by 1Password; keep secret values out of inline Helm values.
  • Talos templates intentionally contain op:// references resolved at runtime through op inject. Docker-host and Ansible workflows also use 1Password; follow their existing mechanisms rather than requiring Kubernetes External Secrets outside Kubernetes.
  • Local template rendering can resolve real credentials. Do not include resolved output in logs, responses, or committed files.
  • Treat persistent-volume changes, CloudNativePG bootstrap/recovery and object-store settings, backup policies, resource renames, and Flux prune/suspend changes as potential data-loss or availability risks. Inspect affected consumers and rendered changes before recommending them.
  • CloudNativePG components live under kubernetes/components/cnpg/. Read the existing cluster configuration and just k8s seed-cnpg recipe before changing bootstrap behavior; do not replace recovery with initdb as a generic fix.
  • Repository edits do not authorize live infrastructure changes. Do not apply, reconcile, upgrade, delete, reset, or seed infrastructure unless the user explicitly requests that operation.

Validation

Use the repository's mise-managed tools and inspect just --list for available recipes. Note that mise install has an Ansible Galaxy post-install hook; it is not a read-only validation command.

For Kubernetes manifest changes, inspect the rendered impact when tools and network access permit:

flate test all --path ./kubernetes/flux/cluster
flate diff all --path ./kubernetes/flux/cluster --base origin/main

These commands may fetch upstream sources. They do not replace checking CRDs, secrets, or runtime behavior omitted from rendered output. For documentation-only changes, targeted reference and whitespace checks are sufficient. Report which checks ran and any validation gaps; do not claim an unavailable render or test passed.

For Talos/Kubernetes upgrades, read kubernetes/talos/version.yaml and the relevant templates/recipes. Verify the target Kubernetes version against the specific Talos release's published support matrix and cite it in reviews; an unchecked pairing is unverified, not implicitly compatible.

Task guidance

Read the matching skill before performing these tasks:

  • Add a Kubernetes application: .agents/skills/add-app/SKILL.md.
  • Deploy or change an application on a Docker host: .agents/skills/add-docker-app/SKILL.md.
  • Review a Renovate update: .agents/skills/renovate-review/SKILL.md.
  • Review a pull request: also read .agents/instructions/pr-review.instructions.md. Renovate guidance supplements, rather than replaces, the general review procedure.

Detailed task guidance does not grant tool permissions or override repository policy. CI consumers must explicitly load the applicable guidance; Markdown references are not automatic includes.

Instruction ownership

  • Keep shared policy in this file, task workflows in .agents/skills/, and detailed conditional guidance in .agents/instructions/. Do not duplicate policy in task files.
  • CLAUDE.md and .claude/skills are compatibility symlinks to the canonical instructions and skills. Keep agent-specific directories limited to adapters and configuration, not alternative copies of shared guidance.
  • Keep personal model preferences, credentials, permissions, and MCP configuration in user-level configuration, synchronized through dotfiles or another user-configuration mechanism when needed across machines. The existing .codex/config.toml is a legacy exception pending migration to that mechanism.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.