claude-code-kit 0.20.0__tar.gz → 0.21.0__tar.gz

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "claude-kit",
       "source": "./",
       "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker): install CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json, then run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.",
-      "version": "0.20.0",
+      "version": "0.21.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker). `claude-kit init` asks ordered questions and installs CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates with working memory and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to claude-kit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [semantic versioning](https://semver.org/).
 
+## [0.21.0] — 2026-06-22
+
+**Add two stack-collection skills — `cron-and-scheduled-jobs` (scheduled/recurring jobs across Kubernetes
+CronJobs and Temporal Schedules) and `kubectl-operations` (the full kubectl command surface for operating
+those workloads) — now 45 skills.**
+
+### Added
+
+- **`cron-and-scheduled-jobs`** — a stack-derived skill documenting how scheduled/recurring jobs are
+  configured in system config and invoked, across the two mechanisms this stack uses:
+  - **Kubernetes CronJob route** — the schedule is declared in Helm `values.yaml` under a `Crons.<job>`
+    block (`Schedule`, `Envs: {MODE: cron, CRON_JOB: <name>}`, `ConcurrencyPolicy: Forbid`, `Suspend`,
+    `TtlSecondsAfterFinished`); the chart renders one `batch/v1` CronJob per entry (`restartPolicy:
+    Never`, history limits 3/1). The shared image boots one-shot in `MODE=cron` and dispatches a single
+    named job from a Python cron registry (simple `name→callable` or rich `name→{task, description,
+    schedule}`), instrumented via `record_cron_job_executed`. Documents the chart's missing
+    `timeZone`/`startingDeadlineSeconds` and how to compensate.
+  - **Temporal Schedule route** — `cron_expressions` vs `ScheduleIntervalSpec` (interval+offset to dodge
+    the UTC-cron timezone foot-gun), `ScheduleOverlapPolicy.SKIP` + `pause_on_failure`, and the one-shot
+    k8s `Job` (not a CronJob) that registers the schedule. Cross-links `temporal-config-driven` (which
+    owns workflow/activity/worker mechanics and the create-or-update registration loop) rather than
+    duplicating it.
+  - Plus a decision matrix for choosing k8s CronJob vs Temporal Schedule, and the cross-cutting concerns
+    (concurrency, timezone, history, missed runs, suspend vs pause, observability, idempotency).
+  - Fully genericized; **not** wired into the catalog/scaffold (`claude-kit init` output is unchanged).
+
+- **`kubectl-operations`** — a stack-derived, operations-first skill for running `kubectl` against this
+  stack's workloads:
+  - **Full command surface**, grouped by task — `get`/`describe`/`explain`/`api-resources`;
+    `apply`/`create`/`edit`/`patch`/`set`/`replace`; `logs`/`exec`/`port-forward`/`cp`/`debug`/
+    `attach`/`proxy`; `rollout`/`scale`/`autoscale`; `events`/`top`; `label`/`annotate`; `config`
+    (contexts & namespaces); `auth can-i`; `wait`/`diff`/`kustomize`; node `cordon`/`drain`/`taint`.
+    (`kubectl delete` is intentionally omitted — see the guardrail below — in favour of reversible
+    alternatives: `scale --replicas=0`, `rollout undo`, or removing the object from the Git/Helm source.)
+  - **Output formatting & selectors** — `-o wide/yaml/json/name/jsonpath/custom-columns/go-template`,
+    `--sort-by`, label (`-l`) and field selectors, `--watch`, with copy-ready JSONPath recipes.
+  - **Context/namespace/RBAC safety** (the #1 footgun) and **day-2 debugging playbooks** —
+    CrashLoopBackOff, ImagePullBackOff, Pending/unschedulable, OOMKilled, a cron that didn't fire, a
+    Service with no endpoints.
+  - Cross-links `cron-and-scheduled-jobs`, `kubernetes-workload-hardening`,
+    `containerization-and-deployment`, `temporal-config-driven`, and `observability-and-logging`. Fully
+    genericized; **not** wired into the catalog/scaffold. The collection index is updated (45 skills).
+
+- **Plugin guardrail `guard-kubectl-delete`** — a `PreToolUse(Bash)` hook that blocks `kubectl delete`
+  from the agent's Bash tool (exit 2), joining the `rm -rf` / `push main` / `guard-destructive-git` /
+  `guard-secrets` destructive-command family. It matches the `delete` **subcommand** as a whole word —
+  sparing the safe look-alikes `config delete-context`, `drain --delete-emptydir-data`,
+  `wait --for=delete`, and the read-only `auth can-i delete …` — and splits compound commands on
+  `;`/`|`/`&` so a chained `… | xargs kubectl delete` can't slip past. It refuses with the reversible
+  alternatives (`scale --replicas=0`, `rollout undo`, GitOps reconcile) and degrades to a no-op without
+  `jq`. Wired into the **plugin** (`hooks/hooks.json`) only; intentionally **not** added to the pip-CLI
+  scaffold registry, so `claude-kit init` output is unchanged.
+
 ## [0.20.0] — 2026-06-20
 
 **Expand the stack-specific skill collection: 21 new skills + 7 fold-in enhancements + a security pass,

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.20.0
+Version: 0.21.0
 Summary: Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.
 Project-URL: Homepage, https://github.com/ajyadav013/claude-kit
 Project-URL: Repository, https://github.com/ajyadav013/claude-kit

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/docs/stack-skills/README.md

@@ -1,6 +1,6 @@
 # Production Engineering Skills Collection
 
-These forty-three Claude Code skills encode production-proven engineering conventions derived from real-world Python/FastAPI, Node/Express, and React services. Each skill was extracted from analyzing patterns across multiple production backend and frontend services, capturing canonical patterns for FastAPI microservices, async Python, Kafka/Temporal integration, multi-tenancy, database access, layered configuration, Redis caching, GCS file handling, LLM integration (Vertex AI / Langfuse), Node/Express services, React frontends (state, data-fetching, forms, design systems, testing), observability (including Grafana dashboards & unified alerting), authentication, containerization (with granular Dockerfile/compose deep-dives), testing, data pipelines, security scanning (OWASP ZAP VAPT/DAST and autonomous AI pentesting), security architecture (edge-to-service signed-identity trust boundary, Kubernetes workload hardening), and modernization strategies. Use them to align new projects with established patterns, audit existing services, or onboard engineers to modern Python, Node, and React development practices.
+These forty-five Claude Code skills encode production-proven engineering conventions derived from real-world Python/FastAPI, Node/Express, and React services. Each skill was extracted from analyzing patterns across multiple production backend and frontend services, capturing canonical patterns for FastAPI microservices, async Python, Kafka/Temporal integration, multi-tenancy, database access, layered configuration, Redis caching, GCS file handling, LLM integration (Vertex AI / Langfuse), Node/Express services, React frontends (state, data-fetching, forms, design systems, testing), observability (including Grafana dashboards & unified alerting), authentication, containerization (with granular Dockerfile/compose deep-dives), testing, data pipelines, security scanning (OWASP ZAP VAPT/DAST and autonomous AI pentesting), security architecture (edge-to-service signed-identity trust boundary, Kubernetes workload hardening), scheduled & recurring jobs (Kubernetes CronJob + Temporal Schedule), kubectl day-2 operations, and modernization strategies. Use them to align new projects with established patterns, audit existing services, or onboard engineers to modern Python, Node, and React development practices.
 
 > **Where these live in this repo:** the skill folders are under [`skills/`](../../skills/) (auto-discovered by the claude-kit plugin). The links below point there.
 
@@ -51,6 +51,8 @@ These forty-three Claude Code skills encode production-proven engineering conven
 | **shannon-ai-pentest** | Drive Shannon (by Keygraph) — an autonomous **white-box** AI pentest that reads an app's source, plans attacks, runs **real proof-of-concept exploits** against the live app, and reports only proven findings. Documents the external **AGPL-3.0** `npx @keygraph/shannon` CLI (setup/start/status/logs/stop/workspaces + flags), AI-provider & model-tier config (Anthropic/Bedrock/Vertex/proxy), the YAML engagement config (auth + login-flows + TOTP, scope avoid/focus rules, report filters), output layout, and safety. Not bundled — installed separately (complements `zap-vapt-scanning`) | [SKILL.md](../../skills/shannon-ai-pentest/SKILL.md) |
 | **edge-to-service-trust-boundary** | The cryptographic trust contract between an API gateway/edge and the services behind it — edge **HMAC-signs** forwarded identity/tenant headers (signature + timestamp), downstream services **verify with constant-time compare and fail closed**, reject replayed/skewed requests, **detect conflicts** across resolution sources, and still enforce their own authz. Anti-patterns: `verify_signature=False`-then-trust, naked-header trust, fail-open. Complements `auth-and-rbac` + `multi-tenancy-patterns` | [SKILL.md](../../skills/edge-to-service-trust-boundary/SKILL.md) |
 | **kubernetes-workload-hardening** | Runtime/manifest-layer Kubernetes hardening — pod/container `securityContext` (runAsNonRoot, drop-ALL caps, `readOnlyRootFilesystem`, seccomp `RuntimeDefault`), **default-deny NetworkPolicy** + explicit allows, **digest-pinned** images, resource requests/limits, **restricted PodSecurity** admission, least-privilege ServiceAccount/RBAC, and secrets via `secretRef`. The runtime layer atop the `dockerfile-*`/`docker-shared` image-build skills | [SKILL.md](../../skills/kubernetes-workload-hardening/SKILL.md) |
+| **cron-and-scheduled-jobs** | Scheduled/recurring jobs two ways — **Kubernetes CronJob** declared in Helm values (`Crons` block) firing a one-shot `MODE=cron` pod that dispatches a named job from a Python registry, and **Temporal Schedules** (cron vs interval specs, `ScheduleOverlapPolicy.SKIP`, pause-on-failure, idempotent create-or-update registration run as a one-shot k8s `Job`) — how each is configured + invoked, concurrency/timezone/history, and choosing between them | [SKILL.md](../../skills/cron-and-scheduled-jobs/SKILL.md) |
+| **kubectl-operations** | Operating Kubernetes workloads with `kubectl` — the full command surface (get/describe/explain, apply/create/edit/patch/delete, logs/exec/port-forward/cp/debug, rollout/scale/autoscale, config contexts/namespaces, auth can-i, jobs/cronjobs, node cordon/drain) + output formatting (`-o jsonpath/custom-columns/go-template`), label/field selectors, dry-run+diff, and day-2 debugging playbooks (CrashLoopBackOff, ImagePullBackOff, Pending, OOMKilled, cron didn't fire, Service has no endpoints). Context/namespace safety first | [SKILL.md](../../skills/kubectl-operations/SKILL.md) |
 
 > **Existing skills extended (this release):** `fastapi-service-patterns` (API versioning + conditional routes), `python-dao-and-database` (MongoDB advanced — aggregation/bulk-upsert/indexes), `temporal-config-driven` (schedule registration), `graphql-patterns` (advanced Apollo Client setup), `containerization-and-deployment` (Makefile dev workflow + Kerberos kinit bootstrap), and `testing-conventions` (GitHub Actions test orchestration) each gained a new section + reference file. A follow-on **security pass** further extended `observability-and-logging` (PII/secret redaction processor + `references/pii-redaction.md`), `testing-conventions` (security-regression tests — negative authz, cross-tenant/RLS, IDOR, lockout, signed-header trust — + `references/security-regression-tests.md`), `graphql-patterns` (a CSRF-token clarification on the Apollo preflight note), and the **core** `security-and-hardening` skill (a CSRF synchronizer-token pattern + an outbound-TLS-verification ban).
 
@@ -101,11 +103,13 @@ These forty-three Claude Code skills encode production-proven engineering conven
    - "run Shannon / autonomous or white-box AI pentest / exploit-test an app from its source / set up @keygraph/shannon / proof-by-exploitation report" → **shannon-ai-pentest**
    - "sign forwarded identity headers / verify a gateway HMAC signature / trust x-user-data behind a gateway / fail closed on forwarded identity / prevent header spoofing or direct-to-service bypass" → **edge-to-service-trust-boundary**
    - "harden a Kubernetes Deployment / add securityContext / write a NetworkPolicy / enforce PodSecurity restricted / pin an image digest / least-privilege ServiceAccount + RBAC" → **kubernetes-workload-hardening**
+   - "add a cron job / scheduled job / recurring job / declare a CronJob in Helm values / wire a MODE=cron entrypoint / register a Temporal schedule / choose k8s CronJob vs Temporal schedule" → **cron-and-scheduled-jobs**
+   - "run kubectl / inspect a Deployment or pod / tail logs / exec into a container / port-forward / roll out or roll back / kubectl -o jsonpath / debug CrashLoopBackOff or ImagePullBackOff / switch kube context or namespace / auth can-i" → **kubectl-operations**
 
 4. **References:** Each skill includes a `references/` subdirectory with detailed evidence files showing the exact file paths, snippets, and patterns from source repositories.
 
 ## Scope and Limitations
 
 - **Source:** These skills are derived from real-world production Python/FastAPI and React services as of June 2026. They reflect real-world conventions, including some anti-patterns that are documented for awareness.
-- **Stack coverage:** Python FastAPI + SQLAlchemy (1.4 and 2.0) + Kafka + Temporal + Redis (caching); layered configuration (configargparse + YAML + Pydantic); GCS file ops + Excel/CSV reporting; LLM integration (Claude on Vertex AI via AnthropicVertex + Langfuse tracing); Node/Express + Objection/Knex + Joi; React + Vite + TypeScript (Zustand, TanStack Query, react-hook-form + Zod, Radix + Tailwind, Vitest + RTL + MSW); limited MongoDB (sync pymongo + aggregation/bulk/index patterns); BigQuery/GCS data pipelines; Strawberry GraphQL (backend) + Apollo Client (frontend); Docker + docker-compose + k8s; Cloud Run + GitHub Actions CI/CD; pytest + pytest-asyncio + Playwright; OpenTelemetry + Sentry + Prometheus + NewRelic; Grafana dashboards + unified alerting (Prometheus/Tempo/Pyroscope/managed-cloud datasources); argon2 + JWT + pyotp; Alembic migrations; multi-provider email/SMS notifications; OWASP ZAP VAPT/DAST scanning with automated PDF reporting; Shannon autonomous white-box AI pentesting (an external AGPL-3.0 CLI — documented, not bundled); edge-to-service HMAC-signed forwarded-identity trust boundary; Kubernetes runtime/manifest hardening (securityContext, NetworkPolicy, PodSecurity, RBAC, digest-pinned images).
+- **Stack coverage:** Python FastAPI + SQLAlchemy (1.4 and 2.0) + Kafka + Temporal + Redis (caching); layered configuration (configargparse + YAML + Pydantic); GCS file ops + Excel/CSV reporting; LLM integration (Claude on Vertex AI via AnthropicVertex + Langfuse tracing); Node/Express + Objection/Knex + Joi; React + Vite + TypeScript (Zustand, TanStack Query, react-hook-form + Zod, Radix + Tailwind, Vitest + RTL + MSW); limited MongoDB (sync pymongo + aggregation/bulk/index patterns); BigQuery/GCS data pipelines; Strawberry GraphQL (backend) + Apollo Client (frontend); Docker + docker-compose + k8s; Cloud Run + GitHub Actions CI/CD; pytest + pytest-asyncio + Playwright; OpenTelemetry + Sentry + Prometheus + NewRelic; Grafana dashboards + unified alerting (Prometheus/Tempo/Pyroscope/managed-cloud datasources); argon2 + JWT + pyotp; Alembic migrations; multi-provider email/SMS notifications; OWASP ZAP VAPT/DAST scanning with automated PDF reporting; Shannon autonomous white-box AI pentesting (an external AGPL-3.0 CLI — documented, not bundled); edge-to-service HMAC-signed forwarded-identity trust boundary; Kubernetes runtime/manifest hardening (securityContext, NetworkPolicy, PodSecurity, RBAC, digest-pinned images); scheduled/recurring jobs (Kubernetes CronJob declared in Helm values + Temporal Schedules); kubectl day-2 operations (full command surface, output formatting/JSONPath, contexts/RBAC, debugging playbooks).
 - **What's NOT covered:** SQLModel, Tortoise ORM, beanie/motor (async MongoDB), Django, Flask, and non-Express Node frameworks (NestJS, Fastify). These were absent (or single-repo only) in the analyzed codebases and were deliberately not created.

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/hooks/hooks.json

@@ -18,7 +18,8 @@
           { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'rm[[:space:]]+-[^[:space:]]*r[^[:space:]]*f'; then echo 'BLOCKED: rm -rf is disabled by claude-kit. Move to trash or delete specific paths explicitly.' >&2; exit 2; fi" },
           { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'git[[:space:]]+push.*[[:space:]:](main|master)([[:space:]]|$)'; then echo 'BLOCKED: refusing to push to main/master — use a feature branch and a PR.' >&2; exit 2; fi" },
           { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-destructive-git.sh\"" },
-          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-secrets.sh\"" }
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-secrets.sh\"" },
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-kubectl-delete.sh\"" }
         ]
       },
       {

claude_code_kit-0.21.0/hooks/scripts/guard-kubectl-delete.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash): BLOCK `kubectl delete` — destructive deletes must not run from an agent session.
+#
+# Why a guard (block, exit 2) and not a warn: a delete is irreversible and trivially misfires against
+# the wrong namespace or cluster. A PreToolUse advisory would be theatre — the resource would already
+# be gone. So this refuses and points at the reversible alternatives (scale to 0, rollout undo, or
+# removing the object from the Git/Helm source and letting the pipeline reconcile). It joins the
+# guard-rm-rf / guard-push-main / guard-destructive-git destructive-command family.
+#
+# Scope is deliberately the `delete` SUBCOMMAND only, matched as a whole word, so it spares the safe
+# look-alikes that merely contain the string "delete":
+#   - `kubectl config delete-context|delete-cluster|delete-user` (local kubeconfig edits, hyphenated)
+#   - `kubectl drain ... --delete-emptydir-data`                 (a drain flag, hyphenated)
+#   - `kubectl wait --for=delete ...`                            (a wait condition, after '=')
+#   - `kubectl auth can-i delete <res>`                          (a READ-ONLY RBAC query)
+# Compound commands are split on ; | & first, so a chained delete (e.g. `get -o name | xargs kubectl
+# delete`) is caught per-segment. Threat model: this prevents accidental agent deletes, not a determined
+# operator who deliberately crafts a bypass string (they own the machine and can disable the hook).
+#
+# Degrades to a no-op (fail-open) without jq — consistent with the other script-backed guards.
+command -v jq >/dev/null 2>&1 || exit 0
+CMD="$(jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+[ -z "$CMD" ] && exit 0
+
+# Split on shell separators → one segment per line; drop read-only `auth can-i` queries; keep only
+# kubectl segments; then look for a bare `delete` verb (not delete-context, --delete-*, or --for=delete).
+if printf '%s' "$CMD" | tr ';|&' '\n\n\n' \
+  | grep -vE 'auth[[:space:]]+can-i' \
+  | grep -E '(^|[[:space:]])kubectl(\.exe)?[[:space:]]' \
+  | grep -qE '(^|[[:space:]])delete([[:space:]]|$)'; then
+  echo "BLOCKED: 'kubectl delete' is disabled by claude-kit — destructive deletes must not run from an agent session." >&2
+  echo "  Use a reversible alternative: 'kubectl scale --replicas=0' to stop a workload, 'kubectl rollout undo' to roll back," >&2
+  echo "  or remove the resource from the Git/Helm source and let the pipeline reconcile." >&2
+  echo "  Read-only checks still work ('kubectl auth can-i delete <res>', 'kubectl get/describe'). (guard-kubectl-delete.sh)" >&2
+  exit 2
+fi
+exit 0

{claude_code_kit-0.20.0 → claude_code_kit-0.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.20.0"
+version = "0.21.0"
 description = "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop."
 readme = "README.md"
 requires-python = ">=3.9"

claude_code_kit-0.21.0/skills/cron-and-scheduled-jobs/README.md

@@ -0,0 +1,45 @@
+# Cron & Scheduled Jobs
+
+A stack-derived skill for **scheduled / recurring jobs** as this stack actually runs them — across the
+two mechanisms it uses and where each one keeps the schedule.
+
+The same business need ("run this every night") is implemented two opposite ways here, and the
+confusing part is *where the schedule lives*:
+
+- **Kubernetes CronJob** — the schedule is **Helm config** (`Crons.<name>.Schedule`); the cluster fires
+  a one-shot pod that runs the shared image in `MODE=cron` and dispatches a single named job from a
+  Python registry, then exits. There is no in-app scheduler.
+- **Temporal Schedule** — the schedule is a **server-owned object** registered by a one-shot deploy step;
+  Temporal fires a workflow, with overlap policy, pause-on-failure, catch-up, and manual triggers.
+
+## What this skill covers
+
+- **k8s CronJob route**: the Helm `Crons` values block → the rendered `CronJob` and its defaults
+  (`concurrencyPolicy: Forbid`, history limits, `restartPolicy: Never`, `ttlSecondsAfterFinished`); the
+  `MODE=cron` + `CRON_JOB` entrypoint dispatch; the one-shot runner; simple vs rich cron registries;
+  the execution metric and retry; and the chart's missing `timeZone`/`startingDeadlineSeconds`.
+- **Temporal Schedule route**: `cron_expressions` vs `ScheduleIntervalSpec` (and why intervals dodge the
+  UTC-cron foot-gun); `ScheduleOverlapPolicy.SKIP` + `pause_on_failure`; idempotent create-or-update
+  registration; the one-shot k8s `Job` that registers a schedule; manual trigger and lifecycle helpers.
+- **Choosing between them** and the cross-cutting operational concerns (concurrency, timezone, history,
+  missed runs, suspend vs pause, observability).
+
+## Relationship to other skills
+
+- `temporal-config-driven` — the **workflow/activity/worker** mechanics (retries, idempotency, worker
+  bootstrap) and the deeper schedule-registration reference. This skill owns the **scheduling /
+  recurrence dimension** and the **CronJob-vs-Temporal decision**, and cross-links rather than repeats.
+- `containerization-and-deployment` — the multi-`MODE` entrypoint and Helm packaging that the CronJob
+  route builds on.
+- `kubernetes-workload-hardening` — securityContext / NetworkPolicy / resources for the CronJob pod.
+- `observability-and-logging` — the `record_cron_job_executed` metric and alerting on missing runs.
+
+## How to use
+
+Read `SKILL.md` for the conventions, the two-mechanism decision table, and both copy-ready skeletons.
+See `references/` for the field-by-field Helm/CronJob detail, the Temporal schedule patterns, and the
+operational decision matrix.
+
+> Stack-derived: encodes a real Python/FastAPI + Kubernetes + Temporal deployment topology. **Not**
+> wired into `claude-kit init`; install it deliberately. All names (service, registry, namespace, job
+> names, hosts) are generic placeholders — no internal services, hosts, project IDs, or cluster names.

claude_code_kit-0.21.0/skills/cron-and-scheduled-jobs/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: cron-and-scheduled-jobs
+description: Scheduled / recurring jobs across the two mechanisms this stack uses — Kubernetes CronJobs (the schedule is declared in Helm values under a Crons block, and the app is invoked one-shot via MODE=cron + CRON_JOB into a Python cron registry) and Temporal Schedules (recurrence owned by the Temporal server via cron_expressions or interval specs, with overlap policy, pause-on-failure, and idempotent create-or-update registration run as a one-shot k8s Job). Covers how each is configured, how the schedule maps to the code that runs, concurrency/timezone/history, observability, and choosing between them. Use when adding a periodic or scheduled job, wiring a MODE=cron entrypoint and cron registry, declaring a CronJob in Helm values, registering or updating a Temporal schedule, or deciding between a Kubernetes CronJob and a Temporal Schedule.
+---
+
+# Cron & Scheduled Jobs
+
+Two mechanisms run recurring work in this stack, and they put the *schedule* in two very different
+places. Knowing which one you're in tells you where the schedule lives and what owns the recurrence:
+
+1. **Kubernetes CronJob** — the cluster's `CronJob` controller is the scheduler. It fires a fresh pod
+   on the schedule; the pod runs the **same service image** booted in a one-shot `MODE=cron` that
+   executes a single named job from a Python registry and exits. The schedule lives in **Helm values**,
+   never in the app.
+2. **Temporal Schedule** — the **Temporal server** is the durable scheduler. A `Schedule` object fires
+   a workflow on a cron expression or interval; a missed window, catch-up, pause, and backfill are all
+   first-class. The schedule lives in **a registration step** (run once / idempotently on deploy).
+
+> Companion skills: `temporal-config-driven` (workflow/activity/worker mechanics, retries, idempotency,
+> and the deeper schedule-registration reference — this skill cross-links it rather than repeating it),
+> `containerization-and-deployment` (the `MODE`-dispatch entrypoint and Helm packaging),
+> `kubernetes-workload-hardening` (securityContext/NetworkPolicy for the CronJob pod), and
+> `observability-and-logging` (the cron execution metric).
+
+## When to use
+
+- Adding a **periodic / scheduled job** to a service and deciding where the schedule belongs
+- Wiring a **`MODE=cron` entrypoint** and registering a job in the **Python cron registry**
+- Declaring a **CronJob in Helm values** (`Crons` block) and understanding the rendered manifest
+- **Registering or updating a Temporal Schedule** (cron vs interval, overlap, pause-on-failure)
+- Deploying schedule registration as a **one-shot k8s `Job`**
+- Choosing between a **Kubernetes CronJob** and a **Temporal Schedule**
+- Debugging "the job didn't run", overlapping runs, timezone drift, or piled-up executions
+
+## Two mechanisms at a glance
+
+| | **Kubernetes CronJob + `MODE=cron`** | **Temporal Schedule** |
+|---|---|---|
+| Scheduler | k8s `CronJob` controller | Temporal server |
+| Where the schedule lives | Helm `values.yaml` → `Crons.<name>.Schedule` | a registration step (`create_schedule`) |
+| What runs | one-shot pod: `MODE=cron CRON_JOB=<name>` → registry handler → exit | a Temporal workflow |
+| Recurrence units | 5-field cron only | cron **or** interval (`every=` + `offset=`) |
+| Overlap control | `concurrencyPolicy: Forbid` (coarse) | `ScheduleOverlapPolicy.SKIP/BUFFER_ONE/...` (rich) |
+| Missed-run visibility | none (the pod just didn't run) | first-class (server tracks it) |
+| Pause / backfill / manual fire | suspend the CronJob (no backfill) | `pause`/`unpause`/`backfill`/`trigger` |
+| Retry across fires | none (pod exits; next fire is fresh) | per-fire `pause_on_failure` + workflow RetryPolicy |
+| Best for | simple, self-contained periodic app tasks | durable/long jobs needing overlap, catch-up, visibility |
+
+## Core conventions
+
+### Kubernetes CronJob + `MODE=cron`
+
+**The schedule is config, not code.** You declare a cron under the service's `Crons` block in Helm
+values; the chart renders one `kind: CronJob` per entry. The job's *only* app-side coupling is two env
+vars — `MODE=cron` and `CRON_JOB=<name>` — that tell the shared image which single job to run.
+
+```yaml
+# Helm values — Projects.<service>.Crons.<job-name>
+Crons:
+  nightly-report:
+    Schedule: "0 2 * * *"            # 5-field cron (the authoritative schedule)
+    Envs:
+      MODE: cron                     # boot the image in one-shot cron mode
+      CRON_JOB: nightly-report       # which registry entry to run
+    ConcurrencyPolicy: Forbid        # default; don't start a fire if the last is still running
+    Suspend: false                   # set true to pause without deleting
+    TtlSecondsAfterFinished: 300     # GC the finished Job pod
+    # Parallelism, Resources, NodeSelector, Tolerations also supported
+```
+
+The rendered CronJob carries sensible defaults from the chart: `concurrencyPolicy: Forbid`,
+`failedJobsHistoryLimit: 3`, `successfulJobsHistoryLimit: 1`, `restartPolicy: Never`,
+`ttlSecondsAfterFinished: 300`. **The chart has no `timeZone` and no `startingDeadlineSeconds`** — so
+the schedule evaluates in the cluster's timezone (usually UTC) and a controller that's down past a fire
+window silently skips it. Plan around both (see `references/choosing-and-operations.md`).
+
+**The app side is a one-shot dispatcher, not a daemon.** A multi-mode `entrypoint.py` reads `MODE`; the
+`cron` branch runs a single job from a registry and the process exits. There is no in-process scheduler
+or loop — k8s owns the cadence.
+
+```python
+# entrypoint.py — the cron branch of the MODE dispatch
+if MODE == "cron":                    # (server / consumer / worker / temporal_worker handled above)
+    from crons.run import main as cron_main
+    asyncio.run(cron_main())          # runs ONE job named by CRON_JOB, then exits
+
+# crons/run.py — look up CRON_JOB, run it once, record the outcome
+async def main():
+    name = loaded_config.CRON_JOB
+    entry = CRON_TASKS.get(name)
+    if not entry:
+        raise ValueError(f"No cron job found for name: {name}")
+    start = asyncio.get_event_loop().time()
+    try:
+        result = await entry["task"]()                       # one-shot
+        record_cron_job_executed(name, "success", asyncio.get_event_loop().time() - start)
+        return result
+    except Exception:
+        record_cron_job_executed(name, "error", asyncio.get_event_loop().time() - start)
+        raise
+```
+
+**The registry maps a name to a handler.** Two shapes are common — a plain `name → async callable`, or a
+richer `name → {task, description, schedule}`. In the rich shape the `schedule` field is
+**documentation only**; the authoritative schedule is the Helm `Crons` entry. Keep them in sync by
+convention (the registry comment should point at the Helm values).
+
+```python
+# crons/registry.py — rich shape (schedule is a doc hint, NOT the real schedule)
+CRON_TASKS = {
+    "nightly-report": {
+        "task": generate_nightly_report,
+        "description": "Aggregate yesterday's events into the report table",
+        "schedule": "0 2 * * *",        # for reference; defined for real in Helm values
+    },
+}
+# simple shape: CRON_TASKS = {"nightly-report": generate_nightly_report}
+```
+
+Conventions that matter for CronJobs:
+- **Idempotency is the job's responsibility.** `concurrencyPolicy: Forbid` prevents *overlap*, not
+  *re-runs* — a retried/late fire may reprocess the same window. Make the handler safe to run twice
+  (upsert, watermark/cursor, or a dedupe key).
+- **Exit non-zero on failure.** `restartPolicy: Never` + a raised exception marks the Job failed and
+  surfaces in `failedJobsHistoryLimit`. Don't swallow the exception.
+- **Handle SIGTERM** for a graceful stop on pod eviction/rollout.
+- **Emit the execution metric** (`record_cron_job_executed(name, status, duration)`) so cron health is
+  observable — see `observability-and-logging`.
+
+### Temporal Schedule
+
+When the work is already a Temporal workflow, or needs durability / overlap control / catch-up /
+visibility, let the Temporal **server** own the recurrence with a `Schedule`. The workflow/activity
+mechanics live in `temporal-config-driven`; this skill covers the **scheduling dimension**.
+
+**Prefer an interval spec over a cron expression for daily-ish cadences.** Temporal evaluates
+`cron_expressions` in **UTC** by default (the chart/clients here don't set `time_zone`), so
+`["0 9 * * *"]` fires at 09:00 *UTC*, not local. An interval with an offset is timezone-explicit and
+avoids the foot-gun:
+
+```python
+from datetime import timedelta
+from temporalio.client import (
+    Schedule, ScheduleActionStartWorkflow, ScheduleIntervalSpec,
+    ScheduleOverlapPolicy, SchedulePolicy, ScheduleSpec,
+)
+
+# Two fires/day, offset so they land at ~09:00 / 21:00 local (UTC+5:30 here):
+spec = ScheduleSpec(
+    intervals=[ScheduleIntervalSpec(every=timedelta(hours=12), offset=timedelta(hours=3, minutes=30))]
+)
+# (cron form, if you must: ScheduleSpec(cron_expressions=["0 2 * * *"]) — remember it's UTC)
+```
+
+**Register idempotently, and run it as a one-shot Job.** Build the schedule from the `spec` above plus
+an `action` and `policy`, then register it safely:
+
+```python
+schedule = Schedule(
+    action=ScheduleActionStartWorkflow(ReportWorkflow.run, {"mode": "daily"},
+                                       id="nightly-report-run", task_queue="report-queue"),
+    spec=spec,
+    policy=SchedulePolicy(overlap=ScheduleOverlapPolicy.SKIP, pause_on_failure=True),
+)
+# create-or-update: try client.create_schedule(...) / except "already exists" -> handle.update(...)
+```
+
+**Registration is a deploy step, not worker startup** — a separate one-shot k8s `kind: Job` (not a
+CronJob) runs `python -m <pkg>.schedules ensure` after the worker Deployment is up, writing the schedule
+into Temporal, which then fires it. The full create-or-update loop, the CLI, and the lifecycle helpers
+(`pause`/`unpause`/`delete`/`update`) are owned by the **`temporal-config-driven`** skill; the Job
+manifest, the interval/overlap details, and the manual-trigger snippet are in
+`references/temporal-schedules.md`.
+
+### Choosing between them
+
+- **Kubernetes CronJob** when the task is a simple, self-contained periodic job, runs to completion in
+  one shot, and `Forbid` overlap is enough. Lowest moving parts; the schedule is plain Helm config.
+- **Temporal Schedule** when the job is long or durable, needs **overlap policy** finer than Forbid,
+  **catch-up / backfill**, **per-fire pause-on-failure**, **missed-run visibility**, or is already a
+  Temporal workflow. The server gives you scheduling observability a CronJob can't.
+
+Don't run both for the same job (double fires). See `references/choosing-and-operations.md` for the
+full decision matrix and the timezone/overlap/history details.
+
+## Skeleton / example
+
+A "nightly report" job, shown both ways. **Pick one** — they're alternatives, not layers.
+
+```text
+Kubernetes CronJob route                      Temporal Schedule route
+────────────────────────                      ───────────────────────
+Helm values: Crons.nightly-report             schedules.py: ensure() create-or-update
+  Schedule "0 2 * * *"                           ScheduleSpec(intervals=[every=24h, offset=...])
+  Envs MODE=cron CRON_JOB=nightly-report         overlap=SKIP, pause_on_failure=True
+        │ k8s CronJob controller fires a pod   deploy: one-shot Job runs `... schedules ensure`
+        ▼                                              │ Temporal server fires the workflow
+entrypoint MODE=cron → crons/run.main()                ▼
+  CRON_TASKS["nightly-report"]["task"]()        ReportWorkflow.run  (worker consumes it)
+  record_cron_job_executed(...) → exit
+```
+
+See `references/kubernetes-cronjob.md` and `references/temporal-schedules.md` for the complete,
+copy-ready versions of each.
+
+## Anti-patterns to avoid
+
+- **Putting the real schedule in app config.** For the k8s route the registry's `schedule` field is a
+  doc hint only — the cluster reads the Helm `Crons.Schedule`. Editing the Python value changes nothing.
+- **Assuming local time.** Both k8s CronJob (no `timeZone` in this chart) and Temporal `cron_expressions`
+  evaluate in **UTC** here. Use interval+offset (Temporal) or compute the UTC cron, and write the
+  intended local time in a comment.
+- **Relying on `concurrencyPolicy` for correctness.** `Forbid` stops overlap, not duplicate processing.
+  Non-idempotent handlers corrupt data on a late/retried fire.
+- **Swallowing the exception** so the pod exits 0 — the failure never shows in
+  `failedJobsHistoryLimit` and the job looks healthy while doing nothing.
+- **Registering a Temporal schedule at worker startup**, or with a bare `create_schedule` that crashes
+  the second deploy on "already exists." Use a one-shot Job + create-or-update.
+- **Confusing a registration `Job` with a `CronJob`.** The schedule-registration manifest is a `Job`
+  (runs once); the recurrence is owned by Temporal, not by re-running the Job.
+- **Running the same job as both a k8s CronJob and a Temporal schedule** — it fires twice.
+- **No execution metric / no alert** — a cron that silently stops is invisible until something
+  downstream is missing. Emit `record_cron_job_executed` and alert on missing successes.
+- **Unbounded history / no TTL** — leftover Job pods pile up; keep `ttlSecondsAfterFinished` and the
+  history limits.
+
+## References
+
+- [kubernetes-cronjob.md](./references/kubernetes-cronjob.md) — The Helm `Crons` values schema, the
+  rendered CronJob and its defaults, the `MODE=cron` entrypoint + one-shot runner, registry shapes,
+  instrumentation/retry, and the `timeZone`/`startingDeadlineSeconds` gaps.
+- [temporal-schedules.md](./references/temporal-schedules.md) — Cron vs interval specs, overlap and
+  pause-on-failure policy, idempotent create-or-update registration, the one-shot registration Job,
+  manual trigger, and lifecycle helpers (cross-links `temporal-config-driven`).
+- [choosing-and-operations.md](./references/choosing-and-operations.md) — Decision matrix and the
+  cross-cutting operational concerns: concurrency, timezone, history limits, missed runs/catch-up,
+  suspend vs pause, and observability.
+- [repo-evidence.md](./references/repo-evidence.md) — Representative patterns described generically.

claude_code_kit-0.21.0/skills/cron-and-scheduled-jobs/references/choosing-and-operations.md

@@ -0,0 +1,86 @@
+# Choosing a mechanism + operational concerns (reference)
+
+## Decision matrix
+
+Start from the job's needs, not the tooling. Walk these in order — the first "yes" usually decides it.
+
+| Question | If yes → |
+|---|---|
+| Is the work already a Temporal workflow? | **Temporal Schedule** (don't fork it into a CronJob) |
+| Must a *missed* fire be visible / caught up later? | **Temporal Schedule** (server tracks missed windows; the CronJob chart has no `startingDeadlineSeconds`) |
+| Do you need overlap handling finer than "skip if running"? | **Temporal Schedule** (`BUFFER_ONE`, `CANCEL_OTHER`, …) |
+| Should a failing run pause the schedule (not fire-and-fail forever)? | **Temporal Schedule** (`pause_on_failure`) |
+| Do you need backfill / replay of past windows? | **Temporal Schedule** |
+| Is the run long-lived and must survive worker/pod restarts mid-run? | **Temporal Schedule** (durable workflow) |
+| Is it a short, self-contained task where "skip if still running" is enough? | **Kubernetes CronJob** |
+| Do you want the fewest moving parts and the schedule as plain Helm config? | **Kubernetes CronJob** |
+
+Rules of thumb:
+- **Default to the k8s CronJob** for simple periodic app tasks — it's the least machinery and the
+  schedule is one line of Helm config.
+- **Reach for Temporal** the moment you need scheduling *observability or control* the CronJob can't
+  give you (missed-run tracking, overlap policy, pause-on-failure, backfill, durability).
+- **Never run both** for the same logical job — it fires twice. Pick one home for the schedule.
+
+## Concurrency / overlap
+
+- **k8s CronJob:** `concurrencyPolicy` is coarse — `Forbid` (default here; skip if the last is still
+  running), `Allow`, or `Replace`. It prevents overlapping *pods*; it does **not** make a handler
+  exactly-once. A late or manually re-triggered fire can still reprocess a window — the handler must be
+  idempotent.
+- **Temporal:** `ScheduleOverlapPolicy` is rich — `SKIP` (convention here), `BUFFER_ONE`, `BUFFER_ALL`,
+  `CANCEL_OTHER`, `TERMINATE_OTHER`, `ALLOW_ALL`. Choose based on whether a long run should skip,
+  queue, or pre-empt the next.
+
+## Timezone
+
+Both routes default to **UTC** here, and getting this wrong is the most common "it ran at the wrong
+time" bug:
+- **k8s CronJob:** the chart sets no `timeZone`, so `Schedule` evaluates in the cluster zone (UTC).
+  Compute the UTC time for your intended local hour, and comment the local intent
+  (`# 07:30 UTC = 13:00 IST`).
+- **Temporal:** `cron_expressions` evaluate in UTC unless `time_zone` is set (it isn't here). Prefer a
+  `ScheduleIntervalSpec(every=..., offset=...)` — the offset places the fire at the local wall-clock
+  time explicitly and dodges DST/zone ambiguity for fixed-interval cadences.
+
+## Missed runs / catch-up
+
+- **k8s CronJob:** no `startingDeadlineSeconds` in this chart → if the controller is down across a fire
+  window, that fire is **silently skipped**, no catch-up. For jobs where a missed run matters, either
+  move to Temporal or add an external "did it run in the last N hours?" alert keyed on the execution
+  metric.
+- **Temporal:** the server records missed windows; overlap/backfill policies decide whether to catch up.
+
+## History / cleanup
+
+- **k8s CronJob:** the chart fixes `failedJobsHistoryLimit: 3` and `successfulJobsHistoryLimit: 1`, and
+  `ttlSecondsAfterFinished` (default 300) GCs finished Job pods. Keep these bounded so pods don't pile
+  up; bump the failed-history limit temporarily when debugging a flaky job.
+- **Temporal:** runs are workflow executions, retained per the namespace's retention policy and visible
+  in the Temporal UI.
+
+## Suspend vs pause
+
+- **k8s CronJob:** `Suspend: true` in Helm values (renders `suspend: true`) stops new fires without
+  deleting the CronJob. In-flight jobs continue. `Ignore: true` removes the CronJob from the render
+  entirely.
+- **Temporal:** `pause()/unpause()` on the schedule handle (also auto-paused by `pause_on_failure`).
+  Paused schedules keep their definition and history; unpausing resumes future fires.
+
+## Observability
+
+- Emit `record_cron_job_executed(name, "success"|"error", duration_seconds)` from the cron runner so
+  every fire is a data point (see `observability-and-logging`). Build the alert on **absence of
+  success** (a cron that silently stops is invisible otherwise), not just on errors.
+- For Temporal, the server UI shows recent/next fires, paused state, and per-run history — but still
+  alert on "no successful run in the expected window" so a paused-on-failure schedule is noticed.
+- Log with the job name and a run/correlation id so a single fire is greppable end to end.
+
+## Idempotency (both routes)
+
+Neither route guarantees exactly-once delivery of *effects*. Design every scheduled handler to be safe
+to run twice:
+- upsert instead of insert; carry a watermark/cursor; or derive a deterministic dedupe/run key from the
+  window (e.g. the date) so re-processing the same window is a no-op.
+- For Temporal, a deterministic workflow id per window makes a duplicate fire a no-op (the server
+  rejects a duplicate running id); see `temporal-config-driven` for `activity_id`-based idempotency.