> Per AI Blitz Plan §global. Layer: 1. Repo: devops-infra-helm-charts.

# 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:

1. **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.
2. **Read [AGENT_BOUNDARIES.md](./AGENT_BOUNDARIES.md)** to confirm which Layer the operation lives in.
3. **Read [SANCTITY_RULES.md](./SANCTITY_RULES.md)** to confirm the operation is not on the don't-touch list.
4. **Read [`wiki/entities/DevOps Infra Helm Charts.md`](../../wiki/entities/DevOps%20Infra%20Helm%20Charts.md)** for the conceptual model (this repo as values store; sister repo as routing layer).
5. **Skim [`docs/architecture.md`](../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](./coding-guidelines/helm-values.md) — values-file conventions
- [coding-guidelines/argocd.md](./coding-guidelines/argocd.md) — Argo CD interaction model
- [coding-guidelines/observability.md](./coding-guidelines/observability.md) — VM / Mimir / Loki / Tempo / Grafana

## Authoring loop

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

1. **Branch off `main`.** Never push to `main`. The branch name should describe the cluster × app being touched.
2. **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.
3. **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
   ```
4. **Commit.** The pre-commit hooks run automatically:
   - **TruffleHog** — secret scan, blocking. NEVER bypass. See [claude/08-pre-commit-and-hooks.md](../../claude/08-pre-commit-and-hooks.md).
   - CAC and Yaak hooks are gated/no-op on this repo.
5. **Open a PR.** Pair with a sister-repo PR if a new Argo Application is being introduced.
6. **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](../platform/procedures/onboard-app-to-cluster.md) and [platform/procedures/update-chart-version.md](../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](./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](./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/`](../../wiki/analyses/) where helpful.

## See also

- [AGENT_BOUNDARIES.md](./AGENT_BOUNDARIES.md)
- [SANCTITY_RULES.md](./SANCTITY_RULES.md)
- [escalation-matrix.md](./escalation-matrix.md)
- [coding-guidelines/helm-values.md](./coding-guidelines/helm-values.md)
- [../architecture.md](../architecture.md)