From f349428d0e4c6fb9410de04b6be7e104a792f01a Mon Sep 17 00:00:00 2001 From: jklein Date: Fri, 21 Aug 2026 18:36:31 +0200 Subject: [PATCH] Keep workflow docs in CLAUDE.md and general repo info in README current - CLAUDE.md: document plan-on-issue step, doc-currency rules, k3d verification convention - README: document validate-charts PR pipeline, branch-filtered publish trigger, strict lint, local k3d runtime verification --- CLAUDE.md | 17 ++++++++++++----- README.md | 7 +++++-- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a984a2d..67c30f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,16 +7,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co The main Claude session acts as the **task manager** and does not implement issues itself: 1. **Plan first, get approval**: The manager presents a plan for the issue and waits for the user's explicit approval. No implementation before approval. -2. **Delegate implementation**: After approval, the manager launches a dedicated **development agent**. The agent implements the issue completely on its own branch and opens a PR. -3. **PR comment handling by the agent**: After opening the PR, the development agent watches it for review comments. New comments are addressed automatically (code changes, reply on the thread), and addressed threads are marked as **resolved**. -4. **Agent lifetime**: The development agent terminates itself once its PR has been merged (or closed). -5. Only after the PR has been **merged by the user** may work on the next issue begin. The user merges; never merge yourself. -6. **After the merge, verify the linked issue was closed** (auto-close via "Fixes #n"); close it manually if not. +2. **Document the final plan on the issue**: Once approved, the plan is posted as a comment on the GitHub issue before implementation starts (skip if the issue body already contains the full plan; later decisions go there as comments too). +3. **Delegate implementation**: After approval, the manager launches a dedicated **development agent**. The agent implements the issue completely on its own branch and opens a PR. +4. **PR comment handling by the agent**: After opening the PR, the development agent watches it for review comments. New comments are addressed automatically (code changes, reply on the thread), and addressed threads are marked as **resolved**. +5. **Agent lifetime**: The development agent terminates itself once its PR has been merged (or closed). +6. Only after the PR has been **merged by the user** may work on the next issue begin. The user merges; never merge yourself. +7. **After the merge, verify the linked issue was closed** (auto-close via "Fixes #n"); close it manually if not. Additional rules for all commits, PRs, issues, and comments: - Do **not** add a `Co-Authored-By` trailer and do **not** append "Generated with Claude Code" footers. +## Keep the docs current + +- Changes to this issue workflow always go into this CLAUDE.md file. +- General repository information (charts, CI pipelines, conventions, tooling) always lives in README.md. Any PR that changes repo-wide behavior must update README.md in the same PR. +- Runtime verification of chart changes is done in a local, throwaway k3d cluster (k3d is installed on the maintainer's machine): stub CRD for `OnePasswordItem`, dummy secrets, throwaway infrastructure (postgres/redis) where needed. + ## What this repo is A collection of self-made Helm charts, one directory per chart, published to a private OCI registry via GitHub Actions. There is no build system or test suite — validation is done with Helm itself: diff --git a/README.md b/README.md index f22c352..7cac6b5 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,10 @@ Collection of some self-made helm-charts. Each top-level directory is a standalo ## CI/CD (GitHub Actions) -- `publish-.yml` — one thin workflow per chart; triggers on any push touching `/**` (or manually) and calls the reusable workflow below. **A push to a chart directory on `main` publishes that chart**, so the chart version must be bumped in the same change. +- `publish-.yml` — one thin workflow per chart; triggers on pushes to `main` touching `/**` (or manually) and calls the reusable workflow below. **A push to a chart directory on `main` publishes that chart**, so the chart version must be bumped in the same change. - `publish-helm-chart.yml` — reusable workflow: `helm package`, then `helm push` to the private JK-Registry. Registry credentials come from 1Password Connect (`OP_CONNECT_TOKEN` secret, items under `op://GitHub-Actions/`). - `change-app-version.yml` — manually dispatched app-version bump; the chart must be listed in its `chart-name` choice list. +- `validate-charts.yml` — PR pipeline: detects which charts a PR touches and, for exactly those, runs `helm lint --strict`, `helm package`, and a chart-version bump check (`template-chart` is exempt from the version check). PRs without chart changes skip the build matrix. ## Creating a new chart @@ -46,12 +47,14 @@ Collection of some self-made helm-charts. Each top-level directory is a standalo Validate locally with: ```bash -helm lint +helm lint --strict helm template --set ingress.domain=example.com --set ingress.clusterIssuer=letsencrypt ``` (required values vary per chart) +For runtime verification (do the workloads actually start, do probes/security settings hold?), use a throwaway local [k3d](https://k3d.io) cluster: `k3d cluster create `, apply a stub CRD for `OnePasswordItem` plus dummy secrets (and throwaway postgres/redis pods where the app needs them), `helm install` the chart, watch pod readiness/events, then `k3d cluster delete `. + ## Chart conventions - Resources are named `{{ .Release.Name }}-{{ .Chart.Name }}-`; template files are named `..yaml` (StatefulSets use `.sfs.yaml`).