DECISION: should @brmbh/cli continue to exist?

[Schmandarine]

Open question, blocking most other work in this repo: should @brmbh/cli continue to exist?

What prompted it

Auditing the theme repo turned up that none of the ten in-theme AGENTS/*.md skills invoke this CLI. They call:

• tools/*.sh in the theme — deploy.sh, db-pull.sh, db-push.sh, sync-plugins.sh, uploads-*.sh, version-check.sh, sync-tokens.mjs
• wp brmbh … — the theme's own WP-CLI subcommand (inc/cli.php)
• npm run build / npm run watch

Meanwhile npx skills add brmbh/wordpress — the one install path verified working — resolves against the theme repo, not this one. So the theme is already both the runtime and the distribution hub. This CLI sits beside that arrangement rather than inside it.

What this CLI uniquely provides

Command	Unique?
create	Yes — genesis. Before a theme exists, no theme tooling exists.
doctor	Partly — spans node/theme/wp/SCF, and must work when wp-cli is absent (which it checks for), so it cannot be a wp brmbh command.
add block / add cpt	No — deterministic file generation; could be wp brmbh make-block in PHP, or a script in tools/.
dev	No — wraps npm run build / watch.
deploy, db, uploads	No — wrap tools/*.sh, which the skills already call directly.

Roughly: one genuinely CLI-shaped command, one arguable, and five wrappers.

And create decomposes further. It is git clone → rename → npm install → npm run build → wire wrappers → wp theme activate. Every step after the clone happens inside a directory that now contains the theme's own tooling. A tools/init.sh <name> shipped in the theme could do all of it. The agent's instructions become: clone, then run init. Both deterministic. No npm package required.

The case for retiring it

• The distribution problem dissolves. npx create-brmbh has 404'd for real users since 2026-06-22 (create-brmbh is only a bin alias, not a published package). Retiring removes the decision instead of forcing it.
• One repo instead of two. Kills the duplicate-file problem (skills.sh.json and skills/wordpress/SKILL.md are duplicated across both repos with no sync #5), the two-layer ownership question (Adopt the two-layer skills model as an explicit rule (CLI owns pre-scaffold, theme owns in-project) #6), the cross-repo URL drift (Stale pre-migration repo URLs: THEME_REPO relies on a redirect, README clone URL is dead #4), and the version-coupling design in No way to pull improved agent skills into an already-scaffolded site #3 — the theme would carry its own tooling at its own commit, by construction.
• Matches where the code already lives. The theme owns the env-file definition, the deploy scripts, the WP-CLI namespace. This repo's envfile.js exists purely to compose a command the theme already defines — a boundary that has already caused one shipped bug.
• Less to maintain and publish. No npm token rotation, no version skew between package and theme, no second repo to keep clean. This repo currently has unpushed commits, a dirty tree, and an unmerged worktree; the theme repo is clean.
• The code-first principle survives intact. Deterministic work stays in scripts — it just moves from a published npm package into tools/. Same determinism, one less distribution surface.

The case for keeping it

• Cross-platform. Node runs on Windows; tools/*.sh does not. Though deploy/db/uploads are already bash-only, so the theme is effectively Unix-only today — retiring exposes that rather than causing it.
• --json envelopes and brmbh schema. The L1/L2/L3 envelope design is the sharpest agent-legibility work in the project. Shell scripts can emit JSON, but the introspection (brmbh schema listing every command, flag, and level) would be lost unless reimplemented.
• Future scope. If brmbh ever ships more than one starter, or needs to manage sites it did not create, a standalone CLI becomes justified again.
• Sunk work. ~1,400 lines, already published, already smoke-tested.

Recommendation

Retire it. Fold create into a theme-side tools/init.sh, keep doctor as a theme-side script that emits the same JSON envelope, move add block/add cpt into wp brmbh. Collapse to one repo.

The strongest argument is not effort saved — it is that the theme is already the product, and every cross-repo seam so far has produced a bug: the env-loading bug, the duplicated skill files, the stale THEME_REPO URL, the drifting wrappers. Removing the seam removes the class.

Retiring should not mean deleting: archive this repo, and publish a final @brmbh/cli with a deprecation notice pointing at npx skills add brmbh/wordpress.

If it stays instead

Shrink it to create + doctor only, and delete dev, deploy, db, uploads, since the skills bypass them anyway. A two-command CLI is defensible; a seven-command one where five are unused wrappers is not.

This blocks

#1, #3, #5, #6, #7 all assume this repo continues. Decide this first — several of them disappear either way.

Related: brmbh/wordpress#6 · vault: Automatic-Brain/Projects/brmbh-agentic-wp-suite/Development/Alignment-Plan.md item 1

[Schmandarine]

DECIDED 2026-07-29 — not retired. Relocated, and the dependency direction inverts.

Resolution tracked at brmbh/wordpress#8.

The retirement case in this issue was wrong on the decisive point: moving the tooling into theme-side tools/*.sh does not make it updatable. Copied scripts freeze at scaffold time exactly like copied skills do. Retiring would have traded a maintenance cost for a permanent staleness problem.

What was right: this repo should not exist as a separate unit. What changes is the relationship, not the existence.

• Old: CLI (npm) clones the theme (git), then is irrelevant to it.
• New: the theme depends on @brmbh/cli (npm) as a devDependency, and stays connected — npm update refreshes tooling and the AGENTS/ skills, which move into the package.

The package moves to brmbh/wordpress/packages/cli/ and continues to publish as @brmbh/cli. npx skills add brmbh/wordpress is unaffected.

This repo will be archived once the migration in brmbh/wordpress#8 completes, with a deprecation notice published on the current npm entry.

Rule adopted: theme = what you own and edit; package = what you consume and update.