Files
cozystack/AGENTS.md
T
Aleksei Sviridkin 1e7ba63c57 docs(agents): define testing and authoring conventions
Require tests for behavior changes without inventing failures for prose
or unchanged upstream updates. Keep new image build filenames explicit
and preserve the existing lookup policy.

Correct the assertion guidance: Bats can fail on a final negation,
while cozytest appends a successful return. Separate numeric validation
from text coercion and account for null parent maps in Helm values.

Validation: markdownlint (MD013 excluded) and git diff --check pass.

Fixes: 5137d98e71 ("test(bats): refuse a negated assertion across every suite")
Assisted-by: LLM
Signed-off-by: Aleksei Sviridkin <f@lex.la>
2026-11-12 16:52:11 +03:00

14 KiB

AI Agents Overview

This file provides structured guidance for AI coding assistants and agents working with the Cozystack project.

Activation

CRITICAL: When the user asks you to do something that matches the scope of a documented process, you MUST read the corresponding documentation file and follow the instructions exactly as written.

  • Commits, PRs, git operations (e.g., "create a commit", "make a PR", "fix review comments", "rebase", "cherry-pick")

    • Read: contributing.md
    • Action: Read the entire file and follow ALL instructions step-by-step
  • Changelog generation (e.g., "generate changelog", "create changelog", "prepare changelog for version X")

    • Read: changelog.md
    • Action: Read the entire file and follow ALL steps in the checklist. Do NOT skip any mandatory steps
  • Release creation (e.g., "create release", "prepare release", "tag release", "make a release")

    • Read: releasing.md
    • Action: Read the file and follow the referenced release process: docs/release.md indexes one page per topic under docs/release/
  • Backports, patch content (e.g., "backport this fix", "will this reach 1.6", "what goes into the next patch", "open a PR against release-X.Y")

    • Read: backports.md
    • Action: Read the entire file. Backports are automatic: a fix merged to main with a fix title, or a security one for a fix that comes through a security advisory, reaches the release lines the batch runs for, the newest released lines and any line in its rc window, so never open a backport PR by hand. A pull request against release-* from outside the team is closed automatically when it is opened; a maintainer keeps a fix with no counterpart on main by reopening it
  • Image references, tags and digests (e.g., "why is this image tagged rc", "add an image to a package", "change how an image is stamped", "promotion/nightly missed an image", "where do image refs live")

    • Read: image-refs.md
    • Action: Read the entire file. Image refs live in three storage shapes and carry three classes of tag; a tool that knows only one shape skips images silently rather than failing. hack/lib/image-refs.sh is the enumeration shared by the promote, retag, mirror, candidate-verify, multi-arch stitch and verify, and retention tooling — extend it there rather than teaching an individual script a new path. The one exception is hack/overlay-main-images.sh, which reads refs but walks the tree itself, so a newly declared file does not reach it; hack/promote-packages-artifact.sh sources nothing because it publishes the whole tree and consumes no refs at all — the doc carries both cases
  • Retiring an application (e.g., "remove the X app", "deprecate X", "drop X from the catalog", "what happens to instances people already created")

    • Read: deprecating-applications.md
    • Action: Read the entire file before touching the tree. Deleting a chart is not a deletion: pruning its PackageSource garbage-collects the ArtifactGenerator and both ExternalArtifacts, which are the chartRef targets of the rd release and of every tenant release, so surviving instances sit Ready=False for good and HelmReleaseNotReady fires on every cluster carrying the bundle. An application with a successor migrates onto it; one without is frozen, per cluster, on the artifact that cluster already renders from, with the digest read off the live OCIRepository at hook time rather than written into the migration. The tenant RBAC grant comes out of the chart and is re-applied by the migration on the clusters that froze
  • Go code, Helm charts, build and test commands, project structure (e.g., "add a field to this CRD", "fix this controller", "add a value to the postgres chart", "regenerate the values schema", "how do I build/test this", "where should I put X", "what's the convention for Y", "how is the project organized")

    • Read: overview.md
    • Action: Read the section that matches — Go Code (controller-runtime patterns, kubebuilder markers), Helm Charts (umbrella pattern, vendored upstream charts, which lookup is allowed), Values schema generation, Build and Development Commands, Testing, Package Structure
  • E2E tests and E2E CI (e.g., "write/fix an e2e test", "stabilize a flaky test", "add a bats test", "change the e2e workflow", "why did e2e fail")

    • Read: e2e-testing.md
    • Action: Read the entire file and follow the conventions exactly — no new retries on deterministic steps, event-driven backstops before every kubectl wait, no test-level EXIT/RETURN traps (a self-contained one inside a Chainsaw script step or an explicit subshell is fine — see the doc), no assertion beginning with ! (errexit exempts an inverted status, so it can be silently ignored — write if cmd; then echo "FAIL: …"; false; fi), fail-fast on HelmRelease readiness
  • General questions about contributing

    • Read: contributing.md
    • Action: Read the file to understand git workflow, commit format, PR process
  • Issue and PR labeling, triage (e.g., "label this issue", "what label should I use", "triage this", "categorize")

    • Read: .github/labels.yml
    • Action: Use labels defined there. Conventions follow the Kubernetes scheme — kind/* (type), area/* (subsystem), priority/* (urgency), triage/* (review state), lifecycle/* (auto-close), do-not-merge/* (PR blockers), security/* (severity)
    • For triage/*: .github/workflows/issue-triage.yaml labels an issue on arrival and sweeps daily for any open issue carrying none, so change a triage decision by replacing the label rather than removing it — remove the only triage/* label an issue has and the next sweep puts one back
    • A feature request that needs design first gets triage/needs-proposal, is re-filed in cozystack/community as an issue or a design-proposal PR, and is closed here with a link to it (re-file rather than transfer, so the label stays on the closed issue as the record); work in this repository starts only once that proposal is accepted, from a new issue that references it
    • For area/*: accuracy outweighs reuse. If no existing area/* truly fits the change, propose a new one via PR (extend .github/labels.yml and the scope mapping in .github/workflows/pr-labeler.yaml) — do not shoehorn the change into a wrong area. area/uncategorized is the auto-labeler fallback; treat it as a signal to pick a fit, create a new area, or correct the PR title
    • PR titles: a Conventional Commits header (type(scope): description, types from contributing.md) auto-applies kind/* and area/* via .github/workflows/pr-labeler.yaml. Append ! (or add a BREAKING CHANGE: footer) to apply kind/breaking-change

Important rules:

  • Match scope, then read first. Load a process file only when the task genuinely falls in its scope, and load it before starting work — not midway through. Tasks outside a file's scope should not pull it into context.
  • Follow it exactly. Do not assume you already know the process, and do not skip steps (changelog.md especially). Where the documentation and your instinct disagree, the documentation wins.
  • overview.md is the standing reference for structure and conventions, useful even when no route above points at it.

Working Principles

These hold for every task, whichever document the routes above point at.

  • A causal claim needs a mechanism. A failure that appeared after a commit, a bump or a rerun was not thereby caused by it, and matching symptoms prove nothing either: unrelated faults often look identical from outside. Back a root cause with a log line, a reproducer, a bisect, or a ruled-out alternative; without one, name at least two hypotheses and what would tell them apart. Before tying a problem to a change, check whether it predates the change (an older run, a condition's lastTransitionTime, git blame). Close a hypothesis when evidence rules it out. Missing evidence means inconclusive, not coincidence: record that limit, stop treating the hypothesis as a cause, and revisit it only with new evidence or a concrete discriminating check.
  • Verify, do not recall. Versions, CLI flags, API fields and defaults drift faster than a model's training data. Check the upstream source, the documentation at the pinned version, or --help before writing code or advice that depends on them. When a problem is not solved after two attempts, stop and research it instead of trying a third variation.
  • Long flag names. New and changed commands in docs, scripts, CI and PR text spell options out (--namespace, --output, --filename, --message), so that a reader does not need to know what -f means to this particular tool. An option with no long form is the only exception.
  • Name the cluster. Management and tenant clusters are different targets. Every kubectl call, including reads, carries --context; cluster-facing Helm commands carry --kube-context. Use the human-approved target and the task's kubeconfig where one was supplied, not the ambient current context. Before running wrappers or cluster-facing tests, verify that they propagate the chosen target. Tests that need no cluster must not inherit live cluster credentials.
  • Respect the reader's time. Lead with the answer or decision; prefer direct wording over formalities, filler and repeated conclusions. Put necessary detail after a short summary or in a linked document.
  • Public text. Everything that reaches GitHub (commits, PR and issue bodies, review comments, code comments) is in English. It names no private infrastructure (cluster, customer or internal namespace names) and none of an agent's private tooling (custom skills, slash commands). Nothing is published on someone's behalf without their approval, unless they have delegated it.

Project Overview

Cozystack is a Kubernetes-based platform for building cloud infrastructure with managed services (databases, VMs, K8s clusters), multi-tenancy, and GitOps delivery.

Quick Reference

Code Structure

  • packages/core/ - Core platform charts (installer, platform)
  • packages/system/ - System components (CSI, CNI, operators)
  • packages/apps/ - User-facing applications in catalog
  • packages/extra/ - Tenant-specific modules
  • cmd/, internal/, pkg/ - Go code
  • api/ - Kubernetes CRDs

Conventions

  • Helm Charts: Umbrella pattern, vendored upstream charts in charts/
  • Go Code: Controller-runtime patterns, kubebuilder style
  • Git Commits: Conventional Commits (type(scope): description) with --signoff; an agent-assisted commit adds one Assisted-by: LLM trailer
  • Comments and commit bodies: WHY, not a narration of WHAT; see Review Blockers in contributing.md
  • Prose: One continuous line per paragraph — see Prose Formatting

What NOT to Do

  • ❌ Edit /vendor/, zz_generated.*.go, upstream charts directly
  • ❌ Modify go.mod/go.sum manually (use go get)
  • ❌ Force push to main/master
  • ❌ Commit built artifacts from _out
  • ❌ Credit an AI model or its vendor by name in a commit trailer or in an authorship line in a PR description or comment, or put a Claude-Session: trailer or a session URL into any of them
  • ❌ Hardwrap a prose paragraph in markdown, a PR body, or an issue comment

Prose Formatting

Markdown files and everything an agent publishes to GitHub — PR bodies, issue bodies, review comments, release notes — use one continuous line per paragraph. Renderers collapse a soft line break into a space, so a paragraph hardwrapped at ~80 columns renders exactly like the same paragraph on one line, while breaking narrow viewports, mangling nested list and table rendering, and turning a one-word edit into a diff that reflows the entire block. The renderer decides where the line ends; the author does not.

Line breaks stay wherever they carry meaning: code fences, one item per list line, tables, headings, blockquotes, front matter, and README badge stacks. The rule governs prose paragraphs and nothing else. Commit messages are the deliberate exception — git log and the tooling around it still expect a body wrapped at ~72 columns.

This is the rule LLM agents break most often, because an ~80-column wrap is correct in the places they spend most of their time (Go comments, commit bodies) and the reflex leaks from there into documentation and GitHub. Treat it as a mechanical check at the moment of writing, not as a style preference to weigh: before saving a markdown file or passing --body to gh, look at each paragraph and confirm it is a single line.

The rule applies to prose this repository owns, and to new or changed paragraphs. Much of the existing tree predates it and is wrapped throughout; that is not a defect to go and fix. Vendored upstream chart docs (packages/*/*/charts/**) must stay verbatim — make update regenerates them — and published changelogs are historical records. Neither is in scope.

.claude/hooks/md-no-hardwrap.py enforces the rule for agents that support PreToolUse hooks (registered for Claude Code in .claude/settings.json). It refuses a Write/Edit/MultiEdit that would add a hardwrapped paragraph, list item or blockquote to a markdown file, and a gh command that would publish one to GitHub. A break counts as added only when the edit wrote both lines it joins, so fixing a typo inside a paragraph that was already wrapped goes through, while rewriting the same file as fresh hardwrapped prose does not. Anything it cannot read with certainty it allows — a guard that blocks legitimate work gets switched off, and then it guards nothing — which includes a body the shell assembles at runtime, and a --body-file written by the very command being checked, since the file does not exist yet when the hook runs. hack/md-no-hardwrap.bats covers it under make unit-tests and requires python3. Agents on other harnesses are held to the same rule without the hook.

.claude/settings.json is tracked, so keep personal Claude Code overrides in .claude/settings.local.json, which is not. A personal .claude/settings.json predating this will be overwritten on pull without warning, because git had been ignoring it.