Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .claude/skills/init/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ test -f .wp-scaffold.json && echo manage || echo setup
No `.wp-scaffold.json` → **setup**. Present → **manage** (read it for current identity; `npm run init -- --list` shows feature status).

### 2. Setup: offer the pilot bootstrap
The rtCamp tooling packages are private/unpublished during the pilot. If `npm install` can resolve `@rtcamp/wp-tooling` from the registry and `composer install` resolves `rtcamp/wp-framework` from its VCS repo, no bootstrap is needed - skip to step 3. Otherwise ask: "Bootstrap local dependencies now? (clones the tooling engine, points npm at it, installs). y/n". On **yes**, with consent, run in order (tell the developer each step in <=30 words):
The rtCamp tooling packages are private/unpublished during the pilot. If `npm install` can resolve `@rtcamp/wp-tooling` from the registry and `composer install` resolves `rtcamp/wp-primitives` from its VCS repo, no bootstrap is needed - skip to step 3. Otherwise ask: "Bootstrap local dependencies now? (clones the tooling engine, points npm at it, installs). y/n". On **yes**, with consent, run in order (tell the developer each step in <=30 words):

```bash
nvm use # Node from .nvmrc
Expand All @@ -49,10 +49,10 @@ git clone git@github.com:rtCamp/wp-tooling.git ../wp-tooling
# Local-only npm ref: this theme's only @rtcamp/* dependency is @rtcamp/wp-tooling.
npm pkg set devDependencies.@rtcamp/wp-tooling=file:../wp-tooling/node-packages/wp-tooling

# wp-framework already resolves from the VCS "repositories" entry in composer.json (dev-main);
# wp-primitives already resolves from the VCS "repositories" entry in composer.json (dev-main);
# composer update pulls it. For local framework development, optionally add a path repo instead:
# { "type": "path", "url": "../wp-framework", "options": { "symlink": false } }
composer update rtcamp/wp-framework
# { "type": "path", "url": "../wp-primitives", "options": { "symlink": false } }
composer update rtcamp/wp-primitives
# --install-links is REQUIRED: it copies the file: @rtcamp package into node_modules instead of
# symlinking, so its peer deps resolve from this theme. Add --legacy-peer-deps on ERESOLVE.
npm install --install-links
Expand Down
4 changes: 2 additions & 2 deletions .claude/skills/scaffold/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Result: `{ scaffolds: [{ id, slug, category, kind, origin, counts }, ...] }`. Pi

### 2. Introspect once per session (cache result)

**Reuse `/init`'s findings if it handed off to you in this session.** When `/init` chained here, you already established the resolved identity and conventions while running init - root namespace, base path (`inc/`), tests namespace + path (`<Root>\Tests` -> `tests/php/`), text domain, and constant prefix. They are facts you set, not guesses: reuse them and SKIP the `composer.json` / `style.css` / `Main.php` reads below that only recover them. You still read a sample implementation for the registration pattern (next paragraph); sample it from a remaining example under `inc/Modules/` or from the framework abstract for the kind (`vendor/rtcamp/wp-framework/inc/Contracts/Abstracts/Abstract<Kind>.php`); do not guess.
**Reuse `/init`'s findings if it handed off to you in this session.** When `/init` chained here, you already established the resolved identity and conventions while running init - root namespace, base path (`inc/`), tests namespace + path (`<Root>\Tests` -> `tests/php/`), text domain, and constant prefix. They are facts you set, not guesses: reuse them and SKIP the `composer.json` / `style.css` / `Main.php` reads below that only recover them. You still read a sample implementation for the registration pattern (next paragraph); sample it from a remaining example under `inc/Modules/` or from the framework abstract for the kind (`vendor/rtcamp/wp-primitives/inc/Contracts/Abstracts/Abstract<Kind>.php`); do not guess.

**The graph saves tokens for orientation only; read the file for any data you copy.** This repo commits a queryable graph (`graphify-out/graph.json`). Use it to LOCATE things cheaply so you open fewer files: which classes implement a kind, what references a symbol, the path between two classes - `graphify query "..."`, `graphify explain "<Class>"`, `graphify affected "<Class>"`, `graphify path "A" "B"`. The graph is structural (not the full source), so it is NOT a source of truth for the patterns you act on. For registration shape, exact namespace, how `Main::CLASSES` lists classes, and wiring location, **read the actual file** - 100% accuracy beats a few saved tokens. (If you or init changed code this session, refresh the local slice first with `graphify update .`, seconds - AGENTS.md graphify policy.)

Expand Down Expand Up @@ -132,7 +132,7 @@ Result shape: `{ scaffold, engine, developer, ai, warnings }`.
| Block | Action |
|---|---|
| `engine.wrote` / `engine.skipped` | Already on disk. Report. |
| `developer.install.composer` / `developer.install.npm` | Print as copy-paste command. **Never run `composer require` / `npm install`.** Pilot notes: npm installs need `npm install --install-links`; the framework (`rtcamp/wp-framework`) already ships, so ignore a `composer require rtcamp/wp-framework` suggestion. |
| `developer.install.composer` / `developer.install.npm` | Print as copy-paste command. **Never run `composer require` / `npm install`.** Pilot notes: npm installs need `npm install --install-links`; the framework (`rtcamp/wp-primitives`) already ships, so ignore a `composer require rtcamp/wp-primitives` suggestion. |
| `developer.secrets` | Print as `gh secret set` checklist. **Never read/write/log/transmit values.** |
| `ai.wiring` | Adaptive wiring with consent (see 6a). |
| `ai.tests` | Mandatory expansion under TDD loop (see 7). |
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ Deduplicate packages. Sort alphabetically within each block. Pinned packages use

| Scaffold ID | When to use | Ruleset |
|---|---|---|
| `lint/phpcs/full` | Most rtCamp projects (recommended default) | `vendor/rtcamp/wp-framework/phpcs.xml.dist`, WordPress-Core + Extra + Docs + VIP-Go |
| `lint/phpcs/full` | Most rtCamp projects (recommended default) | `vendor/rtcamp/wp-primitives/phpcs.xml.dist`, WordPress-Core + Extra + Docs + VIP-Go |
| `lint/phpcs/vip` | WordPress VIP platform projects | `WordPress-VIP-Minimum` + `WordPress-Docs` |
| `lint/phpcs/core` | Projects explicitly opting out of VIP-Go rules | `WordPress` - Core + Extra + Docs only |

Expand Down
6 changes: 3 additions & 3 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Copilot instructions — Theme Elementary

A custom WordPress **block theme** (PHP 8.2+) built on `rtcamp/wp-framework` (`rtCamp\WPFramework`, installed in gitignored `vendor/`: not visible at review).
A custom WordPress **block theme** (PHP 8.2+) built on `rtcamp/wp-primitives` (`rtCamp\WPPrimitives`, installed in gitignored `vendor/`: not visible at review).

Detailed, path-scoped rules live in `.github/instructions/`:
- `framework-php.instructions.md` (generated by `npm run sync-ai` from the framework; absent until then): all `**/*.php` framework architecture, security, testing, review flags.
- `primitives-php.instructions.md` (generated by `npm run sync-ai` from the framework; absent until then): all `**/*.php` framework architecture, security, testing, review flags.
- `structure.instructions.md`: theme layout and wiring.

## Stack
Expand All @@ -16,7 +16,7 @@ Detailed, path-scoped rules live in `.github/instructions/`:
## Universal rules

- **TDD**: write the failing test first, then the implementation. Never ship code without a test.
- **Do not default to Singleton.** Hook WordPress through the framework `Loader` + `Registrable`; use `Shareable` only when an instance must be retrieved later. Full decision tree in `framework-php.instructions.md`.
- **Do not default to Singleton.** Hook WordPress through the framework `Loader` + `Registrable`; use `Shareable` only when an instance must be retrieved later. Full decision tree in `primitives-php.instructions.md`.
- Prefer official WordPress / `@wordpress/*` APIs and block-theme mechanisms (`theme.json`, patterns, template parts) over custom PHP.
- Never modify WordPress core or anything under `vendor/`; extend via actions and filters.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
applyTo: "**/*.php"
description: "Framework + WordPress rules for PHP. Canonical source, shipped by rtcamp/wp-framework."
description: "Framework + WordPress rules for PHP. Canonical source, shipped by rtcamp/wp-primitives."
---

# PHP rules: framework, WordPress, security, tests

`rtcamp/wp-framework` (`rtCamp\WPFramework`) is in gitignored `vendor/` (invisible at review). These rules ARE its contract.
`rtcamp/wp-primitives` (`rtCamp\WPPrimitives`) is in gitignored `vendor/` (invisible at review). These rules ARE its contract.

## Architecture

Expand Down Expand Up @@ -51,6 +51,6 @@ Flag genuine contract/security violations, not style. Allow any correct implemen
5. 🚩 A class calling `register_post_type`/`register_taxonomy`/`register_rest_route`/`add_menu_page`/`add_shortcode`/`register_block_type` directly instead of extending the matching `Abstract*` (`AbstractPostType`, `AbstractRESTController`, `AbstractAdminPage`, …). Name the abstract to extend.
6. 🚩 Missing `strict_types`/types/docblocks; PSR-4 mismatch; `self::` for LSB.
7. 🚩 Missing escape/sanitize/nonce/capability; raw `$wpdb` without `prepare()`; REST without a real `permission_callback`; inline assets; wrong/absent text domain.
8. 🚩 Edit under `vendor/rtcamp/wp-framework` or WordPress core.
8. 🚩 Edit under `vendor/rtcamp/wp-primitives` or WordPress core.

<!-- GENERATED by rtcamp/wp-framework; edit the source, not here. -->
<!-- GENERATED by rtcamp/wp-primitives; edit the source, not here. -->
2 changes: 1 addition & 1 deletion .github/instructions/structure.instructions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
applyTo: "inc/**"
description: "Theme structure. Merges with framework-php.instructions.md and copilot-instructions.md."
description: "Theme structure. Merges with primitives-php.instructions.md and copilot-instructions.md."
---

# Theme structure
Expand Down
8 changes: 4 additions & 4 deletions .github/prompts/init.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,17 +33,17 @@ Copilot must gather inputs BEFORE acting. Do not assume any value.
Run: `test -f .wp-scaffold.json && echo manage || echo setup`. No file → **setup**. Present → **manage** (`npm run init -- --list` shows feature status).

### 2. Setup: offer the pilot bootstrap
The rtCamp tooling packages are private/unpublished during the pilot. If `npm install` resolves `@rtcamp/wp-tooling` and `composer install` resolves `rtcamp/wp-framework` from its VCS repo, skip this. Otherwise ask: "Bootstrap local dependencies now? (clones the tooling engine, points npm at it, installs). y/n". On **yes**, with consent, run in order (explain each step in <=30 words):
The rtCamp tooling packages are private/unpublished during the pilot. If `npm install` resolves `@rtcamp/wp-tooling` and `composer install` resolves `rtcamp/wp-primitives` from its VCS repo, skip this. Otherwise ask: "Bootstrap local dependencies now? (clones the tooling engine, points npm at it, installs). y/n". On **yes**, with consent, run in order (explain each step in <=30 words):

```bash
nvm use
git clone git@github.com:rtCamp/wp-tooling.git ../wp-tooling
( cd ../wp-tooling && git checkout release/v1.0.0 )
npm pkg set "devDependencies.@rtcamp/wp-tooling=file:../wp-tooling/node-packages/wp-tooling"
# wp-framework resolves from the VCS "repositories" entry already in composer.json.
# wp-primitives resolves from the VCS "repositories" entry already in composer.json.
# For local framework dev, optionally swap it for a path repo:
# { "type": "path", "url": "../wp-framework", "options": { "symlink": false } }
composer update rtcamp/wp-framework
# { "type": "path", "url": "../wp-primitives", "options": { "symlink": false } }
composer update rtcamp/wp-primitives
npm install --install-links # fallback: add --legacy-peer-deps
```
Add the `@rtcamp/tailwind-config` `file:` ref too only if Tailwind will be enabled. The `file:`/`path` edits are local-only: tell the developer to revert ONLY those dependency-source lines before committing (keep the identity changes init wrote). On **no**, skip to step 3 and surface installs as developer actions.
Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/scaffold.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ npx wp-tooling add wp/<kind> --non-interactive --json \
Always pass this theme's conventions (the engine defaults target a different layout). Apply project-sampled details (class suffix, sub-namespace, vendor prefix, build dir). `--dry-run` to preview. There is no `wp/module` step (no per-kind module file); each artifact wires into `Main::CLASSES`. Multi-kind: run in dependency order; re-read `ai.wiring` after each call. Result: `{ scaffold, engine, developer, ai, warnings }`.

### 6. Process the result
- `engine.wrote/skipped` → report. `developer.install.*` → print as copy-paste; **never run** `composer require`/`npm install` (the framework already ships - ignore a `composer require rtcamp/wp-framework` suggestion). `developer.secrets` → print as `gh secret set` checklist; **never read/write values**.
- `engine.wrote/skipped` → report. `developer.install.*` → print as copy-paste; **never run** `composer require`/`npm install` (the framework already ships - ignore a `composer require rtcamp/wp-primitives` suggestion). `developer.secrets` → print as `gh secret set` checklist; **never read/write values**.
- `ai.wiring`: the engine miscomputes `targetFile` as a module file; the real target is `inc/Main.php`. Translate the snippet to a `<Class>::class,` line in `Main::CLASSES` plus the matching `use` import, mirroring the sampled entries. Show file + line + rendered snippet, get consent, insert idempotently.

### 7. TDD loop (mandatory)
Expand Down
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# AGENTS.md — Theme Elementary

Tool-agnostic brief for AI coding agents (Claude Code, Copilot coding agent, Codex). A custom WordPress **block theme** built on `rtcamp/wp-framework` (in `vendor/`).
Tool-agnostic brief for AI coding agents (Claude Code, Copilot coding agent, Codex). A custom WordPress **block theme** built on `rtcamp/wp-primitives` (in `vendor/`).

## Authoritative rules

The review rules ARE the coding rules: the same files Copilot reviews against. Follow them when writing code; they hold the full detail:

- `.github/instructions/framework-php.instructions.md`: framework architecture, security, testing, and the do/don't flags. Shipped from `rtcamp/wp-framework`, generated locally by `npm run sync-ai` (absent until then).
- `.github/instructions/primitives-php.instructions.md`: framework architecture, security, testing, and the do/don't flags. Shipped from `rtcamp/wp-primitives`, generated locally by `npm run sync-ai` (absent until then).
- `.github/instructions/structure.instructions.md`: theme layout and wiring.
- `.github/copilot-instructions.md`: overview + conventions.

Expand Down Expand Up @@ -36,7 +36,7 @@ feature, TDD-first), exist for both assistants and must stay in step:

## Knowledge graph (graphify)

The repo keeps a queryable code graph in `graphify-out/` (`graph.json` + `GRAPH_REPORT.md`) covering this theme (and, optionally, the `wp-framework`/`wp-tooling` it builds on). Use it to understand the codebase, and keep it current. Tell the user each graphify step in <=30 words (50 max). Only the `init`/`scaffold` agentic tools run these commands; Copilot review does not. Setup detail: `docs/knowledge-graph.md`.
The repo keeps a queryable code graph in `graphify-out/` (`graph.json` + `GRAPH_REPORT.md`) covering this theme (and, optionally, the `wp-primitives`/`wp-tooling` it builds on). Use it to understand the codebase, and keep it current. Tell the user each graphify step in <=30 words (50 max). Only the `init`/`scaffold` agentic tools run these commands; Copilot review does not. Setup detail: `docs/knowledge-graph.md`.

**Graph-first: do not read source files to understand them when the graph can answer.** Before opening a file to learn what a symbol does, how a subsystem works, or how the theme wires together - including `wp-tooling` engine internals (token derivation, capability removal, etc.) - query the graph (`/graphify query "<q>"`, `explain "<symbol>"`, `path "A" "B"`). You almost never need to read engine source: the engine is a black box these skills invoke, and the skill already documents the outcome (how a theme name becomes namespace/package/prefixes). Read a file only when the graph does not answer, or when you need exact code to edit.

Expand All @@ -46,12 +46,12 @@ The repo keeps a queryable code graph in `graphify-out/` (`graph.json` + `GRAPH_
2. graphify installed but no graph? → offer to build (`/graphify .`), say what + rough cost in one line, build on consent.
3. graphify not installed (`command -v graphify` fails)? → ask "install graphify? (y/n)". On yes: run `scripts/graphify/install.sh`, then `scripts/graphify/verify.sh`, then build. On no: proceed without it.

**After any task that adds, edits, or deletes code or files**, before the final report: refresh the **local** graph with `graphify update .` (re-extracts only changed files; tree-sitter, no API, seconds) so later queries stay accurate. The committed `graphify-out/graph.json` is this theme's own single-repo artifact: regenerating and committing it (`graphify update .` + `graphify cluster-only . --no-label --no-viz`) is a deliberate step when the structure changes meaningfully, not churn on every edit. The optional cross-repo `merge-graphs` (with `wp-framework`/`wp-tooling`) is a maintainer task - do not run it as part of a routine change. If graphify is not installed or no graph exists, say so in one line; never block the task on it.
**After any task that adds, edits, or deletes code or files**, before the final report: refresh the **local** graph with `graphify update .` (re-extracts only changed files; tree-sitter, no API, seconds) so later queries stay accurate. The committed `graphify-out/graph.json` is this theme's own single-repo artifact: regenerating and committing it (`graphify update .` + `graphify cluster-only . --no-label --no-viz`) is a deliberate step when the structure changes meaningfully, not churn on every edit. The optional cross-repo `merge-graphs` (with `wp-primitives`/`wp-tooling`) is a maintainer task - do not run it as part of a routine change. If graphify is not installed or no graph exists, say so in one line; never block the task on it.

## Guardrails (all AI tools) - BASE, non-negotiable

- **Never run history- or remote-affecting `git`/`gh`.** No `commit`, `push`, `branch -D`, `reset --hard`, `rebase`, `tag`, `git add` for a commit, PR create/merge, issue/PR comment, `gh secret set`, or any write to a remote or to git history. Surface every one of those as a developer action: print the exact command for the developer to run. Read/setup git is allowed: `git clone`, `git checkout`, `git status`, `git diff` (e.g. the pilot bootstrap's sibling clone) may run with consent.
- **Never do a destructive operation outside this theme directory.** Do not delete or overwrite existing files in sibling repos (`../wp-tooling`, `../wp-framework`, ...) or anywhere else on disk. Cloning a NEW sibling that does not already exist is additive and allowed; modifying or removing existing out-of-repo content is not.
- **Never do a destructive operation outside this theme directory.** Do not delete or overwrite existing files in sibling repos (`../wp-tooling`, `../wp-primitives`, ...) or anywhere else on disk. Cloning a NEW sibling that does not already exist is additive and allowed; modifying or removing existing out-of-repo content is not.
- Never run a package manager (`npm install`, `composer require/update`) or `npm run build` without explicit consent; print the command instead. The one consented exception is `npm run init` (the theme's own setup script, on a clean tree). In-repo install steps and the pilot bootstrap (sibling clone + `file:`/`path` ref edits + installs) may run with consent.
- Never read, log, or transmit secret values.
- Never apply cross-file wiring without showing the diff and getting consent.
Loading