What the agent does
The agent clones the repository into its own cloud sandbox and reads the chart before it touches the README. In a chart like charts/podinfo in stefanprodan/podinfo, Chart.yaml is apiVersion: v1, version: 6.17.0, appVersion: 6.17.0, with home, sources, one maintainer and kubeVersion: ">=1.23.0-0". values.yaml has about forty top-level keys: replicaCount, logLevel, host, backend, backends, image (repository ghcr.io/stefanprodan/podinfo, tag, pullPolicy, pullSecrets), ui, faults, service (ports 9797, 9898, 9999, nodePort 31198, trafficDistribution), h2c, config, extraArgs, extraEnvs, tls, certificate, hpa, cache, redis, serviceAccount, securityContext, ingress, httpRoute, grpcRoute, serviceMonitor, resources, nodeSelector, tolerations, affinity, podAnnotations, podDisruptionBudget and probes. Three keys (ingress, httpRoute, grpcRoute) already carry a # -- ... comment in the exact form helm-docs reads; the other 34 comment lines are plain # notes.
The chart's README.md has three sections: ## Installing the Chart (the OCI install from ghcr.io/stefanprodan/charts/podinfo, the Cosign verification command and the GitHub Pages repository), ## Uninstalling the Chart, and ## Configuration, a hand-maintained table of 84 parameter rows with defaults and descriptions. There is no README.md.gotmpl. .github/workflows/test.yml runs make test, helm lint ./charts/podinfo/, helm template piped into flux-schema validate, the Kustomize and Timoni checks, and ends with a step that fails when git diff --stat is not empty, printing run make test and commit changes. That last step is the hook the agent uses.
The agent installs the helm-docs release binary and starts with the values file: for each of the 84 table rows it adds a # -- <description> comment above the matching key, keeping the table's wording, and converts the plain # notes that describe a key into the same form. It lists the rows whose key no longer exists in values.yaml and the keys that have no row, so nothing is silently dropped or invented, and leaves descriptions empty where the table had none. Then it writes charts/podinfo/README.md.gotmpl: the Installing and Uninstalling sections copied verbatim, followed by {{ template "chart.valuesSection" . }}, with chart.header and chart.description from Chart.yaml at the top. helm-docs --chart-search-root charts regenerates README.md, and the agent diffs it against the old one row by row.
For the check, it adds a helm-docs target to the Makefile and a step in test.yml, after helm lint, that runs the same command; because the existing final step already fails on a dirty tree, a pull request that changes values.yaml without regenerating the README fails with the README diff in the log and the message the maintainers already know. The agent changes no template and no value, and runs helm lint and helm template once more to show the chart renders as before.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add helm-docs to this repository's Helm chart. Read Chart.yaml, values.yaml, the existing README and the CI workflow first. Move every description from the README's hand-written parameters table into a `# --` comment above the matching key in values.yaml, keeping the wording; list any table row whose key no longer exists and any key with no row. Write a README.md.gotmpl that keeps the existing install and uninstall sections verbatim and renders the values table from the comments, regenerate the README, and diff it against the old one. Add a Makefile target and a CI step that regenerate the README so the workflow's existing dirty-tree check fails when the docs are stale. Change no template and no default value. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that adds charts/podinfo/README.md.gotmpl, changes charts/podinfo/values.yaml (comments only, no value moved), charts/podinfo/README.md (now generated), Makefile and .github/workflows/test.yml. The description has the row-by-row diff of the old and new tables, the list of stale rows and undocumented keys, and the helm lint and helm template output from the sandbox showing the rendered manifests are unchanged.
The run's record keeps every command with its output, including the helm-docs version installed, the regeneration and the two Helm runs, so a reviewer can confirm the README was generated and not edited, and that the defaults column matches values.yaml exactly.
Before merging, a reviewer reads the stale-rows list and deletes or restores each, writes descriptions for the undocumented keys the agent left blank, and decides whether the release workflow that publishes the chart should also run helm-docs so a published chart never ships a README behind its values.
Run it on every chart values change
The setup is one POST /o/{org}/sessions with this body and the repository in resources, started from a terminal; the run continues in its sandbox after you close the window, and a follow-up (POST /o/{org}/sessions/{id}/messages) can change the template layout without starting over. After the merge, the CI step does the ongoing work: every pull request that touches values.yaml has to regenerate the README or it fails.
For a repository with many charts, an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize can run a shorter prompt that regenerates the README for the charts the pull request touched and pushes the result to its branch, with the event added after the prompt so the agent knows which pull request it is.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A chart README goes stale one value at a time, and moving to a generator by hand means copying dozens of descriptions into comments without losing or changing any. The agent does that copy mechanically, reports every mismatch between the table and the values file instead of guessing, and keeps the prose sections exactly as written.
The sandbox has Helm and the helm-docs binary the agent installs, so the regeneration, helm lint and helm template run for real and the output stays in the run's record. Several charts in a repository, or several repositories, can be done at once in separate sandboxes, each with its own pull request.
Frequently asked questions
Will it change my chart's values or templates?
No. Only comments are added to values.yaml, and the agent runs helm template before and after to show the rendered manifests are identical. Templates, Chart.yaml and the hooks are untouched.
What happens to the parts of my README that are not the table?
They move into README.md.gotmpl verbatim, so the install commands, the signature verification and the uninstall section render exactly as they did. Only the parameters table is generated from now on.
What if the table and values.yaml disagree?
The agent lists each row whose key is gone and each key without a row in the pull request and leaves the description blank rather than inventing one. You decide which rows to drop and what the undocumented keys mean.
How does CI catch a stale README?
The workflow regenerates the README with helm-docs and then runs its existing check that the working tree is clean. A pull request that changed values.yaml without regenerating fails with the README diff in the log. There is no separate tool to learn.
More Helm jobs
More jobs like this: Hand off a long task
- Add a Horizontal Pod Autoscaler to Kustomize Deployments (Kustomize)
- Add HTTP Timeouts to a Go CLI (Go CLI)
- Add i18n to a Blazor Web App (Blazor)