Skip to content

[scaffolds] Rename rtcamp/wp-framework to rtcamp/wp-primitives across wp-tooling #69

Closed

Description

@Adi-ty

Why we need this

rtcamp/wp-framework is being renamed to rtcamp/wp-primitives in rtCamp/wp-primitives#98. The rename ships as v2.0.0 and moves the PHP namespace from rtCamp\WPFramework\ to rtCamp\WPPrimitives\. Class names stay the same.

Every PHP scaffold in @rtcamp/wp-tooling still targets the old name. Once 2.0.0 is out, a project on rtcamp/wp-primitives that runs wp-tooling add wp/cpt is told to install rtcamp/wp-framework:^1.0. The generated class also imports rtCamp\WPFramework\Contracts\Abstracts\AbstractPostType, which fails with "Class not found" because 2.x has no such namespace.

This issue moves wp-tooling to the new name everywhere it appears: scaffold manifests, templates, the setup skill, docs and tests.


Before you start

When this can merge

Work can start now. Merge only after rtCamp/wp-primitives#98 is merged, the GitHub repo is renamed to rtCamp/wp-primitives, and v2.0.0 is tagged. Before then, the rtcamp/wp-primitives:^2.0 dependency these scaffolds report will not resolve for consumers.

Worth reading first


The rename at a glance

What Old New
Composer package rtcamp/wp-framework rtcamp/wp-primitives
Version constraint ^1.0 ^2.0
PHP namespace root rtCamp\WPFramework\ rtCamp\WPPrimitives\
Namespace inside JSON strings rtCamp\\WPFramework\\ rtCamp\\WPPrimitives\\
Repository URL https://github.com/rtCamp/wp-framework https://github.com/rtCamp/wp-primitives
Vendor path vendor/rtcamp/wp-framework/ vendor/rtcamp/wp-primitives/

Only the namespace root changes. For example, rtCamp\WPFramework\Contracts\Abstracts\AbstractPostType becomes rtCamp\WPPrimitives\Contracts\Abstracts\AbstractPostType.


What you're changing

All paths are relative to node-packages/wp-tooling/. To list every current hit (64 files), run this from the repo root:

grep -rnE 'wp-framework|WPFramework' node-packages/wp-tooling --exclude-dir=node_modules

1. Scaffold manifests (scaffold.json, 22 files)

Scaffolds What to change
wp/* (13): admin-page, block-dynamic, block-interactive, cli, cpt, cron, module, registrable, rest, settings-page, shortcode, taxonomy, user-role The composer_dependencies entry "rtcamp/wp-framework": "^1.0" becomes "rtcamp/wp-primitives": "^2.0". Also update any description that names the package, e.g. wp/cpt: "Adds a CPT class extending AbstractPostType from rtcamp/wp-framework."
wp-api/* (3): block-bindings, script-module, speculation The composer_dependencies entry, same as above.
utility/* (5): cache, feature-selector, logger, timer, transients The composer_dependencies entry, the description, the module_class (e.g. rtCamp\\WPFramework\\Utils\\Cache), and every class reference in the wiring[] entry. Each snippet names the class three times: the @return docblock, the method return type, and the new expression.
lint/phpcs/full The composer_dev_dependencies entry and the description ("…via wp-framework.").

2. Scaffold templates (templates/*.mustache, 33 files)

  • Class and test templates of every wp/* and wp-api/* scaffold above (32 files):
    • use rtCamp\WPFramework\…; becomes use rtCamp\WPPrimitives\…;
    • The file docblock line @link https://github.com/rtCamp/wp-framework becomes @link https://github.com/rtCamp/wp-primitives
  • lint/phpcs/full/templates/phpcs.xml.dist.mustache: the ruleset include <rule ref="vendor/rtcamp/wp-framework/phpcs.xml.dist"/> and the comment above it change to vendor/rtcamp/wp-primitives/phpcs.xml.dist. The file ships at the same path in 2.0.0.

3. Setup skill (2 files, keep them identical)

  • skills/setup/SKILL.md and its bundled copy scaffolds/setup/claude-skills/templates/setup-SKILL.md, lines 135 and 338.
  • The two files are byte-identical today. Keep them that way.

4. Docs (4 files)

  • docs/wp-framework-contract.md: rename it to docs/wp-primitives-contract.md with git mv so its history follows. Inside, update:
    • the title and intro (lines 1, 3 and 5)
    • the history note (line 7). It should now say the package shipped as rtcamp/wp-framework for 1.0.x and was renamed to rtcamp/wp-primitives in 2.0.0.
    • the Composer coordinates block (line 15), to "rtcamp/wp-primitives": "^2.0"
    • the namespace root (line 19)
    • the three section intros that name the namespace (lines 37, 159 and 195)
  • Links to the renamed file: AGENTS.md line 46 (the file tree) and docs/authoring-scaffolds.md line 427.
  • docs/authoring-scaffolds.md: the example use line (line 93), the module_class example (line 226), and the "When to involve wp-framework" section (lines 425–427). Its "open an issue on wp-framework" pointer should name rtCamp/wp-primitives.
  • docs/examples.md: the three references to rtcamp/wp-framework:^1.0 (lines 92, 356, 393).

5. Tests (1 file)

  • tests/scaffolds/bundled-manifests.test.js: lines 709, 717, 735 and 774 hard-code the old package, version and namespace. Update them to the new values.
  • Add a guard test in the same file that reads every file under scaffolds/ and fails if any of them matches wp-framework or WPFramework. New scaffolds are usually started by copying an existing one, so a branch that predates this rename would otherwise bring the old name back without anyone noticing.

6. Changelog

  • The existing [Unreleased] entry for utility/* (line 13) names rtcamp/wp-framework. It hasn't shipped yet, so update it in place.
  • Add a ### Changed section under ## [Unreleased] with a BREAKING entry: scaffolds now generate code for rtcamp/wp-primitives ^2.0 and the rtCamp\WPPrimitives\ namespace. Projects still on rtcamp/wp-framework ^1.0 must migrate first. Link to the wp-primitives upgrade guide.

Out of scope

  • The generic word "framework" in prose, such as "the framework's Loader" or the wp/module display name "Framework Module". These words describe what the package does, not its name, and wp-primitives' own docs still use them.
  • Projects that already contain code generated under the old name. The wp-primitives upgrade guide covers their migration.
  • Consumer repos (features-plugin-skeleton, theme-elementary). The wp-primitives rollout in Rename rtcamp/wp-framework to rtcamp/wp-primitives wp-primitives#98 covers them.

Checked: nothing in wp-tooling depends on these

2.0.0 also changes the items below. They need no work here, because wp-tooling never references them:

  • The asset handle prefix wp-framework- (now wp-primitives-)
  • The wp-framework text domain (now wp-primitives)
  • The AI rules file framework-php.instructions.md (now primitives-php.instructions.md)
  • A Composer repositories VCS entry. wp-tooling never writes one, so there's no URL to update.

How to verify your work

Run these from the repo root:

# Both must print nothing. CHANGELOG.md is excluded because the rename entry names the old package on purpose.
grep -rnE 'wp-framework|WPFramework' node-packages/wp-tooling --exclude-dir=node_modules --exclude=CHANGELOG.md
git ls-files node-packages/wp-tooling | grep wp-framework

# Must exit 0.
npm run check

Quick smoke test

This generates three scaffolds into a throwaway project and checks what they produce. Run it from the repo root:

SMOKE="$(mktemp -d)"
printf '{"name":"acme/demo","autoload":{"psr-4":{"Acme\\\\Demo\\\\":"inc/"}}}\n' > "$SMOKE/composer.json"
CLI=node-packages/wp-tooling/bin/wp-tooling.js

node "$CLI" add wp/cpt --cwd "$SMOKE" --json --slug=book --singular=Book --plural=Books > "$SMOKE/cpt.json"
node "$CLI" add utility/cache --cwd "$SMOKE" --json > "$SMOKE/cache.json"
node "$CLI" add lint/phpcs/full --cwd "$SMOKE" --json > "$SMOKE/phpcs.json"

# Must print nothing.
grep -rnE 'wp-framework|WPFramework' "$SMOKE"

# Must print "rtcamp/wp-primitives":"^2.0" twice (once for wp/cpt, once for utility/cache).
grep -hoE '"rtcamp/wp-primitives":"[^"]+"' "$SMOKE/cpt.json" "$SMOKE/cache.json"

# Must show the new namespace in the generated class.
grep -n 'WPPrimitives' "$SMOKE/inc/PostTypes/Book.php"

On main today, the first grep lists six files (cpt.json, cache.json, phpcs.json, Book.php, BookTest.php, phpcs.xml.dist) and the last two print nothing.


Acceptance criteria

Runtime behavior

  • Every wp/*, wp-api/* and utility/* scaffold reports rtcamp/wp-primitives: ^2.0 as its Composer dependency.
  • Generated PHP classes and tests import from rtCamp\WPPrimitives\ and link to https://github.com/rtCamp/wp-primitives.
  • utility/* wiring snippets build \rtCamp\WPPrimitives\Utils\… classes.
  • lint/phpcs/full no longer references rtcamp/wp-framework, in its dependency or in its rendered phpcs.xml.dist.
  • The smoke test above prints what it says it must.

Code quality

  • Both repo-wide checks above print nothing.
  • npm run check passes.
  • The guard test fails when any file under scaffolds/ mentions the old name.

Docs

  • docs/wp-framework-contract.md is renamed to docs/wp-primitives-contract.md, and every link to it is updated.
  • skills/setup/SKILL.md and scaffolds/setup/claude-skills/templates/setup-SKILL.md are updated and still identical.

Housekeeping

  • CHANGELOG.md has a BREAKING entry under ## [Unreleased], and the existing utility/* entry uses the new name.

Blocked by (for merge): rtCamp/wp-primitives#98

Activity

  1. added
    Type: TaskSelf-contained unit of work for a milestone
    Scope: ScaffoldsScaffoldRegistry + scaffold.json schema
    BC: BreakingBreaking change — targets release/vNext
    on Oct 1, 2026
  2. self-assigned this
    on Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

BC: BreakingBreaking change — targets release/vNextScope: ScaffoldsScaffoldRegistry + scaffold.json schemaType: TaskSelf-contained unit of work for a milestone

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions