Add Kustomize overlay guardrails skill and prompt

promptbook/prompts.json

@@ -779,6 +779,26 @@
       ],
       "formatNotes": "All three. Point the tool at the model client or gateway code, the retry and fallback config, the application config with model aliases, the auth or caller-identity code, and the metrics setup. Copilot: llm-cost path instructions plus those files in agent mode (or save it as `.github/prompts/add-llm-token-budgets-and-cost-tracking.prompt.md`). Claude Code: the llm-cost-latency-budget-guardrails skill plus the files. Codex: AGENTS.md LLM cost and latency section, then the diff.",
       "body": "Task: Add token budgets, cost tracking, and latency measurement to the LLM calls in the service I specify. Inventory every model call, meter usage from provider responses, price it from a versioned table, cap each request, add caller and global budgets, fix retry accounting, and finish with a minimal diff, tests, and a cost report.\n\nContext placeholders (fill from the repo or ask only if missing):\n- Service or module root: {{APP_PATH}}\n- Stack: {{STACK}}  (Spring Boot + Spring AI | LangChain4j | plain HTTP client | Python SDK | gateway)\n- Providers and models: {{PROVIDERS}}  (e.g. Azure OpenAI deployments, OpenAI-compatible endpoints, OpenRouter, Anthropic)\n- Callers to attribute: {{CALLERS}}  (service, tenant, user, or feature; and where the identity comes from)\n- Price source: {{PRICES}}  (list prices with date, or negotiated rates; currency)\n- Budgets: {{BUDGETS}}  (e.g. 200k tokens per caller per day, $50 global per day, max 8 agent steps)\n- Latency SLO: {{SLO}}  (e.g. p95 time to first token ≤ 1.5 s, p95 total ≤ 8 s)\n- Usage store and metrics: {{STORE}}  (database table, append-only log, Micrometer/OpenTelemetry metrics backend)\n- Mode: {{MODE}}  (report-only | enforce)\n\nRequirements:\n\n1. Inventory\n   - Table of every model call in {{APP_PATH}}: file and method, route or feature, caller, model alias, max output tokens (or \"not set\"), streaming, tools or agent loop, retry and fallback policy\n   - Flag calls with no max output tokens, streams that never read usage, agent loops with no step cap, and retries of non-retryable errors\n\n2. Metering\n   - One usage hook (client interceptor, gateway filter, or callback), not per-call code\n   - Read provider usage: input, output, and, where reported, cached-input and reasoning tokens; for OpenAI-compatible streams request the final usage chunk and count streams that end without it\n   - Record: request ID, trace ID, route, caller ID (stable ID, never an email), requested alias, resolved provider and model version, attempt number, outcome, token counts, timings, cost, price table version\n   - Never store prompts or completions in the usage store; redact them in logs\n\n3. Pricing\n   - Versioned price table from {{PRICES}} keyed by provider, model, and token type, with effective date and currency\n   - Cost computed at write time; unit tests for every token type and for a model missing from the table (record it, flag it, don't price it as zero)\n\n4. Request caps\n   - Explicit max output tokens per route, input and retrieved-context caps, tool-result size cap, agent step and total-token cap per run\n   - A clear error or trim policy when a cap is hit; a CI or unit check that fails when a route has no max output tokens\n\n5. Budgets\n   - Per-caller per-window and global daily budgets from {{BUDGETS}}\n   - Reserve an estimate before the call, reconcile with actual usage after it, release on failure; safe under concurrency\n   - Blocked response: documented status (e.g. 429 with reason and Retry-After) and a metric; in report-only {{MODE}}, log and count would-be blocks without rejecting\n   - Alert at a threshold below the global ceiling and on sudden jumps in tokens per request\n\n6. Retries and fallbacks\n   - Retry only timeouts, 429, and 5xx, with capped exponential backoff and jitter, honouring Retry-After, with a total attempt and time limit\n   - Every attempt's tokens count against the caller's budget; record which provider and model each attempt used\n   - Cancel the upstream call when the client disconnects\n\n7. Latency\n   - Histograms for total duration, time to first token, output tokens per second, gateway overhead, and retry wait, tagged by route, provider, model, and outcome\n   - Labels stay low-cardinality: no user IDs, request IDs, or prompt text; if using OpenTelemetry GenAI conventions, pin the version\n   - Report against {{SLO}}\n\n8. Report and tests\n   - A query or endpoint that reports cost, tokens, p95 latency, and error rate per day, route, caller, and model from {{STORE}}\n   - Tests: pricing, reserve-and-reconcile under concurrency, streaming with and without final usage, retry accounting, blocked response, missing-price handling\n\nConstraints:\n- Minimal diff. Don't change prompts, models, or routing unless a finding requires it; report findings instead.\n- Don't invent prices, token counts, or traffic numbers. Use placeholders and state assumptions.\n- Don't put prompts, completions, secrets, or personal data in the usage store, metrics, or test fixtures.\n- Put price table changes in their own commit with an effective date.\n- Optimize for GitHub Copilot, Claude Code, and Codex: give concrete diffs and a checklist.\n- Leave dashboard building and provider migrations as follow-up notes.\n\nOutput format:\n1. Inventory table with flagged calls\n2. Usage record schema and where it is written\n3. Caps and budgets table: route or caller | limit | window | current behaviour | new behaviour\n4. Retry and fallback policy before and after\n5. Patch (usage hook, price table, caps, budgets, retry changes, metrics, report query, tests)\n6. Sample report output with placeholder numbers clearly marked, plus follow-ups\n\nStart from {{APP_PATH}}. Meter before you limit: get honest usage numbers first, then add caps and budgets.\n"
+    },
+    {
+      "id": "scaffold-kustomize-aks-overlays",
+      "title": "Scaffold or Clean Up Kustomize Overlays for AKS",
+      "whenToUse": "Set up new Kustomize manifests or clean up existing ones for a service on AKS: map overlays, replace deprecated fields with proof the rendered output is unchanged, split into base, components, and overlays, fix labels, images, generators, and secrets, and add a CI gate that builds, validates, policy-checks, and diffs every overlay.",
+      "tools": [
+        "copilot",
+        "claude-code",
+        "codex"
+      ],
+      "tags": [
+        "kubernetes",
+        "kustomize",
+        "aks",
+        "gitops",
+        "ci",
+        "devsecops"
+      ],
+      "formatNotes": "All three. Point the tool at the manifests folder, the CI workflow that deploys it, and any per-environment values files. Copilot: kustomize path instructions plus those files in agent mode (or save it as `.github/prompts/scaffold-kustomize-aks-overlays.prompt.md`). Claude Code: the kustomize-aks-overlay-guardrails skill plus the files. Codex: AGENTS.md Kubernetes manifests section, then the diff.",
+      "body": "Task: Set up or clean up Kustomize manifests for the service I specify so each environment is a small overlay on one base, every overlay renders and validates in CI, and reviewers see the rendered diff. Finish with a minimal diff, the CI job, and a rendered-output comparison.\n\nContext placeholders (fill from the repo or ask only if missing):\n- Manifests root: {{K8S_PATH}}  (e.g. deploy/k8s)\n- Environments and clusters: {{ENVS}}  (e.g. dev, stage, prod on AKS; namespace per env)\n- Kubernetes versions: {{K8S_VERSIONS}}  (per cluster)\n- Image registry and tagging: {{IMAGES}}  (e.g. ACR, digest pinned by CI)\n- Config and secrets: {{CONFIG}}  (which values differ per env; where secrets live, e.g. Azure Key Vault)\n- Identity: {{IDENTITY}}  (e.g. AKS workload identity client ID per env)\n- Optional pieces: {{COMPONENTS}}  (e.g. monitoring annotations, PodDisruptionBudget, topology spread for prod)\n- CI system: {{CI}}  (GitHub Actions | Azure Pipelines | Jenkins)\n- Tool versions: {{TOOLS}}  (kustomize, kubeconform, kube-linter or policy tool)\n\nRequirements:\n\n1. Map the current state\n   - Table: overlay | what it changes from base | cluster and namespace | deprecated fields | copied base resources | secrets in Git\n   - Render every overlay as it is today with the pinned kustomize version and save the output for comparison\n\n2. Modernize\n   - Replace `bases`, `commonLabels`, `patchesStrategicMerge`, `patchesJson6902`, and `vars` with `resources`, `labels`, `patches`, and `replacements` (`kustomize edit fix` first, then hand-check)\n   - Rendered output must match the saved output, or list and justify every difference\n\n3. Structure\n   - `base/` environment-neutral; `components/` for {{COMPONENTS}}; `overlays/<env>/` with only real differences\n   - Strategic merge patches for values; JSON 6902 patches with explicit targets for list edits (`args`, `command`, env lists without a merge key) and removals\n   - Small, named patch files; no overlay copies a full base resource\n\n4. Labels and selectors\n   - Stable identity labels in base selectors; extra labels via `labels:` with `includeSelectors: false`\n   - Flag any change that would alter an existing Deployment or StatefulSet selector and stop for confirmation instead of applying it\n\n5. Images and config\n   - Images set with the `images:` field in each overlay; prod pinned to a digest or immutable tag; no `latest` in any rendered output\n   - ConfigMaps from `configMapGenerator` with hash suffixes on; document any `disableNameSuffixHash`\n\n6. Secrets and identity\n   - No secret values or committed secret files; use a SecretProviderClass for Azure Key Vault through the Secrets Store CSI driver with workload identity from {{IDENTITY}}\n   - List any secret that was committed in history so it can be rotated\n\n7. CI gate in {{CI}}\n   - For each overlay: build with pinned kustomize, fail on warnings; kubeconform strict against {{K8S_VERSIONS}} with CRD schemas; policy check with the pinned tool\n   - On pull requests, render each overlay on the base and head branches and publish the diff as a comment or artifact\n   - Pin every tool version and action\n\nConstraints:\n- Minimal diff. Don't change resource requests, replicas, probes, or app config values unless a finding requires it; report findings instead.\n- Don't apply anything to a cluster. `kubectl diff -k` against non-production is the most you suggest running.\n- Don't invent cluster names, versions, IDs, or digests; use placeholders and state assumptions.\n- Don't add Helm, and don't enable Helm inflation inside Kustomize.\n- Optimize for GitHub Copilot, Claude Code, and Codex: give concrete diffs and a checklist.\n\nOutput format:\n1. Current-state table with flagged issues\n2. New directory tree\n3. Patch (kustomization files, patches, components, generators, SecretProviderClass, CI job)\n4. Rendered-output comparison per overlay: identical, or each difference with its reason\n5. Risk list (selector changes, secrets to rotate, version gaps) and follow-ups\n\nStart from {{K8S_PATH}}. Render before you refactor, and prove the rendered output is unchanged unless you meant to change it.\n"
     }
   ]
 }