Generated agent wrappers are committed and have already drifted — sync-uploads is missing from a fresh clone

[Schmandarine]

The agent wrappers in .claude/commands/, .cursor/rules/ and .windsurf/rules/ are generated from AGENTS/*.md, but they are also committed to git. They have already drifted.

Evidence of drift, right now

.claude/commands:  disk=10  tracked=9
.cursor/rules:     disk=10  tracked=9
.windsurf/rules:   disk=10  tracked=9

untracked:
  .claude/commands/sync-uploads.md
  .cursor/rules/sync-uploads.mdc
  .windsurf/rules/sync-uploads.md

AGENTS/sync-uploads.md is committed. Its three wrappers were generated locally and never committed. Anyone cloning this repo today gets 9 of the 10 skills wired up — /sync-uploads is invisible to their agent unless they happen to run brmbh add skills.

This is not hypothetical drift. It already shipped.

Why it happens

Wrappers are derived data. generateSkillWrappers() (brmbh/cli src/commands/add.js:199) reads each AGENTS/<name>.md, derives a description from its first prose line, and writes three files. Committing the output of a generator means every change to AGENTS/ requires remembering to regenerate and stage 3 extra files per skill. That will be forgotten — it just was.

The trade-off

Wrappers cannot simply be gitignored without thinking it through:

• Via the CLI (brmbh create) → wrappers are generated at scaffold time (step 4, src/commands/create.js:73-77). Committing them is redundant.
• Via a direct git clone of this repo → no CLI involved, so an ignored wrapper means the agent sees no skills at all until someone runs brmbh add skills.

So the question is whether a direct clone is a supported way to use this theme. If it is, wrappers must stay committed and need a guard. If the CLI is the only supported path, ignore them.

Options

1. Keep committed + add a CI check that regenerates and fails if the working tree changes. Catches exactly this bug. Needs .github/workflows/ (this repo has no CI at all yet).
2. Gitignore them, make brmbh create / brmbh add skills the only way they appear, and document that a direct clone must run brmbh add skills first.
3. Keep committed + a pre-commit hook that regenerates. Local-only, easy to bypass.

Recommend 1 — it preserves the direct-clone path and makes the failure loud.

Immediate fix, independent of which option wins

Commit the three missing sync-uploads wrappers so the repo is at least correct today.

Acceptance

A fresh git clone of this repo exposes all 10 skills to Claude / Cursor / Windsurf, and there is a mechanism that fails loudly when AGENTS/ and the wrappers disagree.

Related: brmbh/cli#3, brmbh/cli#6

[Schmandarine]

Resolved by #6: direct git clone of this theme is a supported install path, alongside the skill-first route.

That settles the trade-off in the "Options" section above — wrappers cannot be gitignored, because a direct clone never runs the CLI and would expose zero skills to the agent.

So: option 1. Keep the wrappers committed, add a CI job that regenerates them and fails if the working tree changes. This repo has no .github/workflows/ yet, so that job is the first one.

The immediate fix is unchanged and independent: commit the three missing sync-uploads wrappers so a fresh clone gets all 10 skills.

[Schmandarine]

Dissolved by #8. Wrappers stop being committed content and become build output: generated from node_modules/@brmbh/cli/AGENTS/, gitignored, regenerated on postinstall (with npx brmbh skills sync as the explicit fallback). Generated files cannot drift from their source when they are regenerated on every install.

Still do the immediate fix now, before the migration: commit the three missing sync-uploads wrappers. Until #8 ships, a fresh clone of this repo exposes 9 of 10 skills, and #8 is not a quick change.

[Schmandarine]

Fixed in fe2aafc, pushed to main.

Correction to this issue's premise: AGENTS/sync-uploads.md was not committed either — the entire uploads-sync feature was uncommitted, not just its generated wrappers. The user-facing effect was identical (a fresh clone exposed 9 of 10 skills), but the cause was simpler than described.

Now verified:

.claude/commands: disk=10 tracked=10
.cursor/rules:    disk=10 tracked=10
.windsurf/rules:  disk=10 tracked=10
AGENTS:           disk=10 tracked=10

The structural question this issue raised — should generated wrappers be committed at all? — is answered by #8: they become build output from node_modules/@brmbh/cli/AGENTS/, gitignored, regenerated on install. Until that lands, committed is correct, since a direct git clone is a supported path (#6).