Agent Operations Guide

A meta-guide for any AI agent (or human contributor wearing the agent hat) doing work in this repo. Read this first; it tells you which other docs to load and in what order.

Pre-flight (always, every task)

Before reading any task-specific file:

Read the repo-root CLAUDE.md. It is the authoritative source for the NEVER-DO list, cluster naming, versioned siblings, multi-Contour pattern, and the Layer constraint summary. Everything else in docs/ derives from it.
Read AGENT_BOUNDARIES.md to confirm which Layer the operation lives in.
Read SANCTITY_RULES.md to confirm the operation is not on the don't-touch list.
Read wiki/entities/DevOps Infra Helm Charts.md for the conceptual model (this repo as values store; sister repo as routing layer).
Skim docs/architecture.md if the task touches more than one chart or cluster.

If the task targets a specific chart family (Contour, Vault, Argo CD, observability stack), also load the relevant coding guideline before editing:

coding-guidelines/helm-values.md — values-file conventions
coding-guidelines/argocd.md — Argo CD interaction model
coding-guidelines/observability.md — VM / Mimir / Loki / Tempo / Grafana

Authoring loop

The supported edit path for almost every task in this repo:

Branch off main. Never push to main. The branch name should describe the cluster × app being touched.
Edit the single targeted file under helm-overrides/<cluster>/<app>/custom-values.yaml (or sibling <extra>.yaml). No drive-by edits to other apps in the same directory. No cross-cluster "normalization" in the same PR.
Dry-run with helm template to confirm the values render. Use the command from the root CLAUDE.md Quick reference table:
```
helm template <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml
```
Commit. The pre-commit hooks run automatically:
- TruffleHog — secret scan, blocking. NEVER bypass. See claude/08-pre-commit-and-hooks.md.
- CAC and Yaak hooks are gated/no-op on this repo.
Open a PR. Pair with a sister-repo PR if a new Argo Application is being introduced.
Reviewer + Argo CD UI Sync are the safety gates. Once the PR is merged to main, Argo CD on the target cluster reconciles. Per-cluster syncPolicy (auto vs manual) is set in the sister repo Meesho/devops-infra-argo-config, not here.

See platform/procedures/onboard-app-to-cluster.md and platform/procedures/update-chart-version.md for two of the most common authoring loops.

When to refuse

Refuse the operation outright if it falls into one of these categories. Cite SANCTITY_RULES.md in the refusal:

Direct push to main, or any --force push.
Bypassing the pre-commit hook (--no-verify, git commit -n).
Curl / probe / query against any production endpoint (*.meesho.int, *.mrouter.int, *.meeshogcp.in).
Edit to repository.yaml (owned by registry-bootstrap).
Edit to an Argo Application / ApplicationSet manifest (lives in sister repo).
Cross-cluster copy-paste of nodeSelector / tolerations / computeClass without rewrite.
Deletion of a versioned-sibling chart without confirming zero sister-repo references.

When to escalate

If the operation is potentially valid but exceeds Layer-1 authority — chart fork, dep bump with breaking changes, StorageClass/PriorityClass edit, Vault HA work — stop and escalate per escalation-matrix.md. The escalation matrix maps each situation to an owner and a channel.

Tooling commands (cheat sheet)

The repo-root CLAUDE.md Quick reference table is the source of truth. Reproduced here for convenience:

Task	Command
Install pre-commit hooks	`pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type post-commit`
Re-run pre-commit on staged changes	`pre-commit run`
Render a chart locally	`helm template <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml`
Refresh subchart deps	`helm dependency update helm-templates/<chart>`
Diff against live release	`helm diff upgrade <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml`
Lint a chart	`helm lint helm-templates/<chart>`
Find which clusters override an app	`find helm-overrides -maxdepth 2 -type d -name '<app>'`

Output discipline

Generate diffs and PRs; do not apply directly to clusters. In-cluster mutation is incident response, not authoring.
Surgical edits only. Touch the cluster × application asked for; leave the rest.
Cross-link reasoning to ADRs in wiki/analyses/ where helpful.

5.4 KiB Raw Blame History Unescape Escape