Improve Claude Md

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.