feat: Initial Claude skills for websimple-devops
This commit is contained in:
155
references/wp-assets.md
Normal file
155
references/wp-assets.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# WP Assets
|
||||
|
||||
Use this skill for Websimple WordPress theme asset source, build, and enqueue conventions.
|
||||
|
||||
Use `references/wp-theme-dev.md` for general PHP/theme structure, `references/wp-code-style.md` for PHP linting, and `references/wp-browser.md` for visual smoke tests.
|
||||
|
||||
## Core principles
|
||||
|
||||
- Keep build-time source assets under `src/`.
|
||||
- Do not edit compiled/generated assets unless the user explicitly asks and there is no source available.
|
||||
- Detect the project's actual pipeline before changing files.
|
||||
- Preserve the existing asset toolchain unless the user asks for migration.
|
||||
- Keep PHP enqueue integration aligned with the build output and manifest strategy.
|
||||
|
||||
## Source structure
|
||||
|
||||
Theme source assets should live under `src/` with clear subdirectories for frontend concerns.
|
||||
|
||||
Common structure:
|
||||
|
||||
```text
|
||||
src/
|
||||
styles/ # CSS/SCSS source
|
||||
scripts/ # JavaScript/TypeScript entrypoints and modules
|
||||
components/ # Vue/React or shared frontend components
|
||||
images/ # source images/icons when processed by the build
|
||||
fonts/ # source fonts when processed by the build
|
||||
```
|
||||
|
||||
Follow the existing project structure first. Do not reorganize assets broadly without approval.
|
||||
|
||||
## Detect the pipeline
|
||||
|
||||
Before editing assets, inspect the theme root for signals:
|
||||
|
||||
```text
|
||||
package.json
|
||||
vite.config.*
|
||||
webpack.config.*
|
||||
webpack.mix.js
|
||||
postcss.config.*
|
||||
tailwind.config.*
|
||||
tsconfig.json
|
||||
src/
|
||||
assets/
|
||||
dist/
|
||||
```
|
||||
|
||||
Use `package.json` scripts as the source of truth for build/dev commands.
|
||||
|
||||
Common signals:
|
||||
|
||||
- Vite: `vite.config.ts`, scripts like `dev`, `build`, `preview`.
|
||||
- Legacy webpack/Mix: `webpack.config.js`, `webpack.mix.js`, scripts using `webpack`, `mix`, or older build tooling.
|
||||
- Plain scripts/styles: source under `src/` with minimal bundler config.
|
||||
|
||||
If signals conflict, report the ambiguity before changing build config.
|
||||
|
||||
## Build output
|
||||
|
||||
Treat build output as generated unless the project clearly uses checked-in compiled assets.
|
||||
|
||||
Common output directories:
|
||||
|
||||
```text
|
||||
assets/
|
||||
dist/
|
||||
```
|
||||
|
||||
Compiled/generated assets should normally be excluded from Git. For new or modernized projects, prefer ignoring generated build output and committing only source/config files.
|
||||
|
||||
Legacy projects may already commit compiled assets. Do not remove those generated files or change `.gitignore` behavior without approval. For those projects, keep the committed-build convention and make sure to run the build before committing so generated assets stay in sync with source changes.
|
||||
|
||||
Do not edit minified files, hashed files, generated manifests, compiled CSS/JS, source maps, or copied vendor assets directly when source files exist.
|
||||
|
||||
If compiled assets are committed in the project, update them by running the project build instead of manual edits.
|
||||
|
||||
## Vite conventions
|
||||
|
||||
For Vite-based themes:
|
||||
|
||||
- inspect `vite.config.*` before adding entrypoints;
|
||||
- keep entrypoints under `src/`;
|
||||
- preserve existing manifest/output settings;
|
||||
- use the manifest when PHP enqueue code relies on hashed filenames;
|
||||
- run the project build after changing source assets when verification requires compiled output.
|
||||
|
||||
Do not rewrite Vite config or migrate legacy projects to Vite unless explicitly requested.
|
||||
|
||||
## Legacy webpack conventions
|
||||
|
||||
For legacy webpack/Mix themes:
|
||||
|
||||
- inspect `webpack.config.*` or `webpack.mix.js` first;
|
||||
- preserve existing entrypoint names and output paths;
|
||||
- avoid modernizing syntax or build tooling as part of unrelated changes;
|
||||
- run the existing build script when compiled assets must be refreshed.
|
||||
|
||||
Do not convert webpack/Mix to Vite without an explicit migration request.
|
||||
|
||||
## Enqueue integration
|
||||
|
||||
Asset enqueue logic usually belongs under theme PHP includes, often `includes/core/assets.php` or the existing project equivalent.
|
||||
|
||||
Before changing enqueue code:
|
||||
|
||||
1. Identify the build output path.
|
||||
2. Identify whether filenames are stable or hashed.
|
||||
3. Identify whether the theme uses a manifest.
|
||||
4. Preserve existing handles, dependencies, script type/module settings, and localization/global variables unless changing them is required.
|
||||
|
||||
For stable filenames, filemtime-based cache busting is acceptable when already used by the project:
|
||||
|
||||
```php
|
||||
wp_enqueue_style(
|
||||
'example-theme',
|
||||
get_stylesheet_directory_uri() . '/dist/css/theme.css',
|
||||
[],
|
||||
filemtime( get_stylesheet_directory() . '/dist/css/theme.css' )
|
||||
);
|
||||
```
|
||||
|
||||
For hashed filenames, read from the manifest rather than hardcoding generated names.
|
||||
|
||||
## Vue and React source
|
||||
|
||||
Vue/React source should still live under `src/`, typically under `src/components/` or an existing frontend app directory.
|
||||
|
||||
Keep this skill focused on source placement and build integration. For component architecture, state management, app mounting, or framework-specific conventions, use dedicated future `wp-vue` or `wp-react` guidance.
|
||||
|
||||
## Styling conventions
|
||||
|
||||
- Keep styles under `src/styles/` or the existing style source directory.
|
||||
- Preserve the project's CSS methodology and naming conventions.
|
||||
- Avoid broad restyling when the user asked for a targeted fix.
|
||||
- Prefer source-level changes over compiled CSS edits.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inspect theme root, `package.json`, build config, source directories, output directories, and enqueue PHP.
|
||||
2. Determine whether the project uses Vite, webpack/Mix, or another pipeline.
|
||||
3. Edit source files under `src/` or the established source directory.
|
||||
4. Do not touch generated output manually.
|
||||
5. Run the smallest relevant check: build, typecheck, lint, or targeted frontend smoke test.
|
||||
6. If compiled assets are committed, run the build before committing and inspect generated diffs.
|
||||
7. Use `references/wp-browser.md` to verify visible frontend changes.
|
||||
8. Report changed source files, generated files, and any build/verification blockers.
|
||||
|
||||
## Safety
|
||||
|
||||
- Do not run package installs or major upgrades without approval.
|
||||
- Do not migrate build tools without explicit request.
|
||||
- Do not edit compiled/minified/generated assets directly when source exists.
|
||||
- Do not remove legacy build config just because a newer tool would be nicer.
|
||||
- Watch for large generated diffs and call them out before committing.
|
||||
Reference in New Issue
Block a user