---
name: 'improve-claude-md'
description: 'Audit and improve the CLAUDE.md files listed in the run worklist: apply only high/medium priority fixes, create the ones that are missing, and delete instructions already fully covered by a repository skill. Driven non-interactively by a GitHub workflow (.github/workflows/weekly-claude-md-improver.yml owns the schedule and resolves the worklist, which differs per repository); not intended for interactive use.'
model: opus
allowed-tools: Read Edit Write Glob Grep Skill
disable-model-invocation: true
---

# CLAUDE.md Improver

Audit and improve the `CLAUDE.md` files this run owns, create the ones that are missing, then report
what changed.

You are running **NON-INTERACTIVELY in CI**: no human is available to confirm anything. Never ask a
question — either apply a change that is clearly correct, or skip it and say so in the final summary.
Apply fixes directly to the files as you go.

These are standing instructions for the whole run, not a one-time checklist.

## Step 1 — Build the skill inventory

Before touching any `CLAUDE.md`, list every skill available in this repository.

Use `Glob` with the pattern `**/.claude/skills/**/SKILL.md`. Match at any depth: a `.claude/skills`
directory can itself live in a sub-directory, and skills may be nested. Ignore any hit under
`node_modules`. Ignore **this** skill (`improve-claude-md`) — it is CI tooling, not a
developer convention, so it never justifies deleting anything.

For each remaining `SKILL.md`, collect **only** the YAML frontmatter `name` and `description`. Do not
read skill bodies at this stage — inlining them wastes the context you need for the audit itself.

Then state the count out loud, for example `Loaded frontmatter for 10 skill(s)`, and list the paths.
This line matters: a regression that silently empties the inventory (a gitignored `.claude/skills`, a
narrowed checkout, a changed glob) must be visible in the run log instead of quietly degrading into
"skip deduplication".

If the inventory is empty, say so explicitly and **skip Step 5 (deduplication) entirely** for the
whole run.

## Step 2 — Read the worklist

`Read` `tmp/claude-md-worklist.txt`. It holds one repository-relative `CLAUDE.md` path per line, and
it is **authoritative**: the workflow resolved it for this repository, and the scope differs between
repositories on purpose. In the open-source repository it is every `CLAUDE.md` in the tree; in the
proprietary fork it is only the packages that do not exist upstream, because every shared file is
owned by the other repository's run of this same workflow. Editing a file outside the worklist
diverges it between the two repositories and conflicts on the next sync.

So: **do not glob for `CLAUDE.md` files, and never add a path of your own.** If the worklist is
missing or empty, stop immediately — do not fall back to a glob — and end the run with a single line
starting `INCOMPLETE RUN:` that says the worklist could not be read. A silent full-tree fallback is
exactly the failure this file exists to prevent.

Print the paths, numbered, followed by the count — for example `Worklist: 8 file(s)`. This printed
list is the only record of what the run was supposed to cover, so print it in full before editing
anything.

Some paths may not exist yet. That is intentional: a listed path with no file behind it is a package
whose `CLAUDE.md` has to be **created** (Step 3).

Process the files **one at a time**, in worklist order. Announce each path as `[n/total] <path>`
before you start on it, so the CI log shows progress and a run that stops early is visible at a glance.

Never narrow the worklist on your own: no sampling, no "the rest look fine", no stopping once the
edits feel sufficient. Every file in the list gets its own pass through Steps 3-5.

## Step 3 — Create a missing CLAUDE.md

When a worklist path does not exist, author it. Its directory is a package root — call it
`packages/<pkg>/`.

**First, check the package is worth documenting.** `Glob` `packages/<pkg>/src/**/*`. If it holds two
files or fewer, the package is a stub barrel with nothing to say: **skip it**, create nothing, and
record it in the Step 6 report as deliberately skipped with its file count. A `CLAUDE.md` that only
restates the package name is worse than no file at all.

Otherwise read enough of the package to describe it honestly — never guess:

- `project.json` (the Nx project name, and the `env:*` tag) and `package.json`
- `README.md`, if there is one
- `src/index.ts` (the public barrel) and `src/<Name>Hexa.ts` (the entry point)
- the shape of `src/application/`, `src/domain/`, `src/infra/`, `src/nest-api/`, `test/` — whichever
  are present

Then `Write` the file, matching the house style of the packages that already have one.
`packages/git/CLAUDE.md` and `packages/llm/CLAUDE.md` are the two best models — read one before you
start writing:

- `# <Name> Package` heading, then one or two sentences on what the package owns.
- Only sections that earn their place: what is non-obvious, what surprises a newcomer, what to reuse
  instead of rewriting, how to add a new case to an existing switch or factory. Concrete file paths
  and type names, not adjectives.
- **Do not restate the shared conventions.** The generic package layout, the `env:*` tags and import
  boundaries, the `/test` subpath rule and branded IDs are all in `packages/CLAUDE.md` — a package
  file that repeats them is duplicate content, which Step 5 would delete anyway.
- Aim for 30-70 lines, in line with the existing package docs.
- Close with the pointer line every sibling uses, verbatim:

  `Shared package conventions (env tags, layout, /test subpath, branded IDs): [../CLAUDE.md](../CLAUDE.md)`

- Respect the repository's own standards. In the proprietary fork,
  `.claude/rules/packmind/standard-packmind-proprietary.md` forbids importing from
  `@packmind/editions` — never write an example that does.

Then put the new file through Steps 4 and 5 like any other, so bootstrapped and pre-existing files
meet the same bar.

## Step 4 — Audit each file

For each `CLAUDE.md`, use the `claude-md-improver` skill (from the `claude-md-management` plugin,
installed by the workflow) to audit and improve that file.

Apply only **HIGH** and **MEDIUM** priority fixes that have a clear, unambiguous positive impact —
for example:

- outdated or incorrect commands
- broken links or wrong file paths
- stale structure or architecture references

Do **not** make low-priority, subjective, or stylistic changes, and skip anything ambiguous. When in
doubt, leave the text alone and note it in the summary.

## Step 5 — Deduplicate against skills

`CLAUDE.md` must not restate what a skill already carries. Any instruction, procedure, convention, or
example in the file that is already covered by one of the skills from Step 1 is duplicate content:
delete it outright, leaving **no** pointer or cross-reference in its place.

Rules:

- Delete only when the skill **clearly and fully** owns that topic. If a skill covers the topic only
  partially, or you are in any doubt, leave the `CLAUDE.md` text untouched.
- You may read a `SKILL.md` body when its frontmatter description alone cannot settle whether
  coverage is full. Read it only for that decision.
- Never delete content that no skill covers.
- If the Step 1 inventory was empty, skip this step entirely.

## Guardrails

**Packmind standards regions are untouchable.** Never modify content inside sections delimited by the
markers `<!-- start: Packmind standards -->` and `<!-- end: Packmind standards -->`. Leave those
regions byte-for-byte unchanged and only edit content outside them. This outranks the deduplication
rules above, even if a skill appears to cover that content.

**The worklist bounds every write.** The only permitted writes are `Edit` on a `CLAUDE.md` that is on
the worklist, and `Write` to **create** a `CLAUDE.md` at a path that is on the worklist. Never delete
or rename any file, never write anywhere else — not to a `CLAUDE.md` outside the worklist, not to any
other file — and never move content from a `CLAUDE.md` into a new skill or doc.

## Step 6 — Report

End the run with a summary the pull-request reviewer can scan:

- the skill count and the worklist count from Steps 1-2;
- one line per file you **created**, saying in a sentence what the package does — these are new files
  with no diff to compare against, so this is the reviewer's only summary of them;
- one line per file you edited, with what you fixed;
- every deletion made for deduplication, naming the skill that justified it, so a reviewer can check
  none of them went too far;
- every package skipped as too thin to document, with its `src/` file count;
- anything you deliberately skipped as ambiguous.

Files you left unchanged need no more than a single closing line listing them.

**Reconcile against the worklist.** Every path printed in Step 2 must appear in this summary, as
created, edited, unchanged, or skipped — the counts have to add up. If any file went unaudited for
any reason (you ran out of room, a read failed, you lost track), do not paper over it: end the
report with a line
that starts `INCOMPLETE RUN:` and names every file you did not audit. A silently partial run is worse
than a loudly partial one, because the pull request it produces looks like a full audit.