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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Generated plugins get `guidelines/` (BPS-10, adapted from ThisOneTimeOnAcidCom): CSS architecture, an accessibility checklist, the testing strategy, and prompt and report guides. `compare-toolchain.js` compares `guidelines/`.
- Generated plugins get Spec Kit 1.0.13 (BPS-10, from ThisOneTimeOnAcidCom) with Claude Code, Codex and Gemini integrations, branch checks through `bin/check-branch-name.js`, and a constitution written for a block plugin. The generator keeps file permissions, copies `.gemini/commands/` and `.specify/workflows/` without rendering their `{{args}}` placeholders, and in template mode replaces the scaffold's own `.specify/`. `compare-toolchain.js` compares `.specify/`.
- Generated plugins get a Claude Code branch guard (BPS-10, adapted from the `lightspeedwp/.github` hook): `.claude/settings.json` runs `.claude/hooks/check-branch.mjs`, which refuses edits, commits, pushes and new branches that break the branching strategy, using `bin/check-branch-name.js`.
- Generated plugins get ten agent roles in `.agents/roles/` (BPS-10, adapted from ThisOneTimeOnAcidCom: testing, Playwright, reviewer, document reviewer, pull request, release, changelog, branches, issue and labelling) with adapters for Claude Code, Codex and Gemini CLI. `compare-toolchain.js` compares `.codex/` and `.gemini/`.
- Generated plugins get agent skills in `.agents/skills/` (BPS-10, adapted from ThisOneTimeOnAcidCom): `test`, `validate`, `changelog` and `branch-validation`, linked into `.claude/skills/`, and `bin/check-branch-name.js`, one branch check with the organisation's rules that the pre-commit hook now calls. The generator copies symlinks as links (template mode leaves them alone), and `compare-toolchain.js` compares `.agents/`, `.claude/`, `AGENTS.md`, `CLAUDE.md` and `.gitignore`, with links compared by target.
- Generated plugins get `AGENTS.md` and `CLAUDE.md` (BPS-10, adapted from ThisOneTimeOnAcidCom): agent instructions that defer to the LightSpeed organisation rules and add the plugin's commands, checks, standards and agent layout. `.gitignore` ignores `.claude/settings.local.json`.
- Generated plugins get `{{slug}}.code-workspace` (VS Code settings, extensions and tasks), their own `.coderabbit.yml` (plugin review rules on top of the organisation settings) and `docs/`, with an index and the Interactivity API and DataViews guide that `DEVELOPMENT.md` links to (BPS-10).
- Generated plugins get the build configuration from the Gutenberg layout (BPS-10): `.browserslistrc`, `postcss.config.mjs`, `tsconfig.json`, `tsconfig.build.json`, `jsconfig.json` and `tools/webpack/extra-entries.js`, which `webpack.config.js` uses. CSS now targets the WordPress browser list; JavaScript output is unchanged.
- Generated plugins get the lint configuration from the Gutenberg layout (BPS-10): `.stylelintignore`, `.jshintignore`, `.markdownlintignore`, `.markdownlint.json`, `.npmpackagejsonlintrc.json` and `tools/eslint/`, plus `npm run lint:md:docs` in `npm run lint`. Stylelint requires BEM class names. `check:generation` runs `lint:md:docs`, and `compare-toolchain.js` compares the new files and `tools/`.
Expand Down
10 changes: 8 additions & 2 deletions docs/GENERATE_PLUGIN.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ Templates are rendered with [mustache.js](https://github.com/janl/mustache.js/),
| `{{snakeCase.slug}}` | snake_case | `tour-operator` | `tour_operator` |
| `{{title.cpt_singular}}` | Title Case | `tour` | `Tour` |

Every tag in a template must have a value: generation fails and lists the file and tag of any that does not, rather than writing an empty string. Files in `plugin-template/.github/workflows/` are copied without rendering, because mustache.js would also read GitHub Actions `${{ ... }}` expressions as tags; workflows read plugin values such as the slug from `package.json` at run time.
Every tag in a template must have a value: generation fails and lists the file and tag of any that does not, rather than writing an empty string. Files in `plugin-template/.github/workflows/`, `.gemini/commands/` and `.specify/workflows/` are copied without rendering, and every file keeps its permissions (Spec Kit's scripts stay executable), because mustache.js would also read GitHub Actions `${{ ... }}` expressions as tags; workflows read plugin values such as the slug from `package.json` at run time.

**Usage in code:**

Expand Down Expand Up @@ -736,12 +736,18 @@ tour-operator/
├── test/unit/ & test/e2e/ # Starter Vitest and Playwright tests
├── phpunit/ # PHPUnit tests and the PHPStan bootstrap
├── docs/ # Project-specific documentation
├── AGENTS.md / CLAUDE.md # Agent instructions (defer to the organisation rules)
├── .agents/ # Shared agent skills and roles
├── .claude/ # Claude Code skill links, agents and hooks
├── .codex/ / .gemini/ # Codex and Gemini CLI adapters for the shared roles
├── .specify/ # Spec Kit: templates, scripts and the plugin constitution
├── guidelines/ # CSS, accessibility, testing, prompt and report guidelines
├── tour-operator.code-workspace # VS Code settings, extensions and tasks
├── patterns/ # Block patterns
└── scf-json/ # SCF field groups
```

Every file in a generated plugin comes from `plugin-template/`, apart from `package.json`, `composer.json`, `README.md` and `CHANGELOG.md`, which the generator writes, and the per-post-type collection blocks, which it renders from `plugin-template/src/blocks/collection/`. Everything else in the scaffold (the generator, its tests, AI tool settings, Lighthouse, size-limit, the scaffold's `AGENTS.md`) is tooling and is never copied. In template mode (`--in-place`), the rendered `plugin-template/` files are moved up to the repository root. Generated plugins get their own `.coderabbit.yml` (which inherits the LightSpeed organisation settings), `SECURITY.md` and `CONTRIBUTING.md`; the code of conduct and support files are inherited from the organisation.
Every file in a generated plugin comes from `plugin-template/`, apart from `package.json`, `composer.json`, `README.md` and `CHANGELOG.md`, which the generator writes, and the per-post-type collection blocks, which it renders from `plugin-template/src/blocks/collection/`. Everything else in the scaffold (the generator, its tests, its own AI tool settings and `AGENTS.md`, Lighthouse, size-limit) is tooling and is never copied; generated plugins get their own `AGENTS.md`, `CLAUDE.md` and agent folders from `plugin-template/`. In template mode (`--in-place`), the rendered `plugin-template/` files are moved up to the repository root. Generated plugins get their own `.coderabbit.yml` (which inherits the LightSpeed organisation settings), `SECURITY.md` and `CONTRIBUTING.md`; the code of conduct and support files are inherited from the organisation.

### 2. Install Dependencies

Expand Down
21 changes: 21 additions & 0 deletions plugin-template/.agents/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Shared Skills and Agent Roles

Instructions shared by Claude Code, Codex and Gemini CLI. Root [AGENTS.md](../AGENTS.md) comes first, and the LightSpeed organisation rules it links to come before it.

| Location | Purpose |
| --- | --- |
| `skills/<name>/SKILL.md` | Skills: `test`, `validate`, `changelog`, `branch-validation` |
| `skills/speckit-*/SKILL.md` | Spec Kit skills for Codex, generated by Spec Kit |
| `roles/<name>.md` | Role instructions; see the [role inventory](roles/INVENTORY.md) |

## How Each Tool Finds Them

- **Claude Code**: each folder in `.claude/skills/` (other than `speckit-*`) is a relative symlink to the folder here. `.claude/agents/<role>.md` tells the agent to read `roles/<role>.md`.
- **Codex**: reads `skills/` here directly. `.codex/agents/<role>.toml` loads the role.
- **Gemini CLI**: reads `skills/` here directly. `.gemini/agents/<role>.md` loads the role.

Edit behaviour here. Change an adapter only when its name, description or tools change. Keep the symlinks: Git stores them, so do not replace them with copies.

## Limits

A skill or role describes how to do the work. It does not grant permission to push, publish, label, release or contact anyone; that comes from the user, and the organisation's rules still apply.
18 changes: 18 additions & 0 deletions plugin-template/.agents/roles/INVENTORY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Role Inventory: {{name}}

Each role lives here as `<name>.md`. The adapters in `.claude/agents/`, `.codex/agents/` and `.gemini/agents/` only tell each tool to read it.

| Role | Domain | Purpose | Required skills | When asked | Edits files |
| --- | --- | --- | --- | --- | --- |
| [testing-agent](testing-agent.md) | Testing | Decide which tests a change needs, add or update them, run them and report the results. | `test` | — | Yes |
| [playwright-agent](playwright-agent.md) | Testing | Cover the plugin in the editor and on the front end with Playwright, using the WordPress end-to-end utilities. | `test` | — | Yes |
| [reviewer-agent](reviewer-agent.md) | Quality | Review a diff and report findings, most severe first, without changing the code. | `validate` | — | No |
| [document-reviewer-agent](document-reviewer-agent.md) | Documentation | Check that the documentation matches what the plugin does and reads clearly. | `validate` | — | No |
| [pr-agent](pr-agent.md) | Delivery | Get a branch ready for review and write its pull request description. | `branch-validation`, `validate` | `changelog` | Yes |
| [release-agent](release-agent.md) | Delivery | Prepare a release so that the tag-driven `release.yml` workflow can build and publish it. | `validate`, `test`, `changelog` | — | Yes |
| [changelog-agent](changelog-agent.md) | Delivery | Keep `CHANGELOG.md` accurate, so commits pass the pre-commit hook and pull requests pass the changelog workflow. | `changelog` | — | Yes |
| [branches-agent](branches-agent.md) | Repository | Make sure work happens on a correctly named branch from the right base. | `branch-validation` | — | Yes |
| [issue-agent](issue-agent.md) | Repository | Turn a bug report or request into a clear issue, and triage existing ones. | — | — | Yes |
| [labeling-agent](labeling-agent.md) | Repository | Apply the organisation's labels consistently. | — | — | Yes |

Roles left out of the ThisOneTimeOnAcidCom set, because they cover website work rather than a plugin: BugHerd, client website discovery, content strategy, website content, design partner, SEO metadata, metrics, PageSpeed, PRD and reporting.
33 changes: 33 additions & 0 deletions plugin-template/.agents/roles/branches-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Branches Agent: {{name}}

## Purpose

Make sure work happens on a correctly named branch from the right base.

## Instructions

Required skills, read before the action they cover:

- `.agents/skills/branch-validation/SKILL.md`

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Branch names (`{type}/{scope}-{title}`, organisation types)
- Base branches: `develop` for work, `main` only for releases and hotfixes
- Keeping uncommitted work when moving to a new branch

## Steps

1. Check the current or proposed branch with `branch-validation`.
2. Propose a name when it fails, and wait for approval before creating or renaming a branch.
3. Never delete branches or force-push.

## References

- Organisation branch naming: `CLAUDE.md` in `lightspeedwp/.github`

## Not in Scope

- Changing the branch rules in `bin/check-branch-name.js` to let a name through
34 changes: 34 additions & 0 deletions plugin-template/.agents/roles/changelog-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Changelog Agent: {{name}}

## Purpose

Keep `CHANGELOG.md` accurate, so commits pass the pre-commit hook and pull requests pass the changelog workflow.

## Instructions

Required skills, read before the action they cover:

- `.agents/skills/changelog/SKILL.md`

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Entries under `## [Unreleased]`, by section
- Checking a branch's entries against its diff
- Release sections, on a release task

## Steps

1. Read the diff.
2. Write or correct the entries with the `changelog` skill.
3. Report entries that do not match the change.

## References

- `CHANGELOG.md`
- `.github/workflows/changelog.yml`

## Not in Scope

- Editing past release sections outside a release task
36 changes: 36 additions & 0 deletions plugin-template/.agents/roles/document-reviewer-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Document Reviewer Agent: {{name}}

## Purpose

Check that the documentation matches what the plugin does and reads clearly.

## Instructions

Required skills, read before the action they cover:

- `.agents/skills/validate/SKILL.md`

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- `README.md`, `readme.txt`, `DEVELOPMENT.md`, `USAGE.md`, `CONTRIBUTING.md`, `docs/` and `guidelines/`
- Commands, paths and settings named in the docs, checked against the repository
- `readme.txt` headers (`Stable tag`, `Requires at least`, `Tested up to`) against the plugin header
- Markdown lint (`npm run lint:md:docs`)

## Steps

1. Read the document and check each command, path and claim against the code.
2. Run `npm run lint:md:docs`.
3. Report inaccuracies first, then unclear passages, with a suggested rewrite.

## References

- `.markdownlint.json`
- `guidelines/report-creation-guidelines.md`

## Not in Scope

- Rewriting documents without being asked
- Organisation-wide documentation in `lightspeedwp/.github`
30 changes: 30 additions & 0 deletions plugin-template/.agents/roles/issue-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Issue Agent: {{name}}

## Purpose

Turn a bug report or request into a clear issue, and triage existing ones.

## Instructions

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Reproduction steps, expected and actual behaviour, versions (WordPress, PHP, plugin)
- The organisation's issue types and templates
- Duplicates and related issues in this repository

## Steps

1. Search existing issues for duplicates.
2. Draft the issue with the matching organisation template and show it to the user.
3. Create or update issues only when the user approves.

## References

- Organisation issue templates and types in `lightspeedwp/.github`

## Not in Scope

- Adding issue templates or issue types to this repository
- Closing issues without the user's approval
30 changes: 30 additions & 0 deletions plugin-template/.agents/roles/labeling-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Labelling Agent: {{name}}

## Purpose

Apply the organisation's labels consistently.

## Instructions

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Prefixed labels only: `type:*`, `status:*`, `priority:*`, `area:*`, `meta:*`
- `meta:no-changelog` for pull requests that need no changelog entry
- Label suggestions for new issues and pull requests

## Steps

1. Read the issue or pull request.
2. Choose labels from the organisation set; never invent a bare or new label.
3. Show the labels to the user, and apply them only when they approve. If no label fits, suggest a `[LABEL-UPDATE-REQUEST]` issue in `lightspeedwp/.github`.

## References

- Organisation label rules: `AGENTS.md` in `lightspeedwp/.github`

## Not in Scope

- Creating, renaming or deleting labels
- Adding `.github/labels.yml` to this repository
37 changes: 37 additions & 0 deletions plugin-template/.agents/roles/playwright-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Playwright Agent: {{name}}

## Purpose

Cover the plugin in the editor and on the front end with Playwright, using the WordPress end-to-end utilities.

## Instructions

Required skills, read before the action they cover:

- `.agents/skills/test/SKILL.md`

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Specs in `test/e2e/`, using `@wordpress/e2e-test-utils-playwright` (`admin`, `editor`, `requestUtils`)
- Block insertion, settings and front-end rendering
- Accessibility: `test/e2e/accessibility.spec.js` runs axe-core (WCAG 2.2 AA) at mobile, tablet and desktop widths
- wp-env, with Docker or the Playground runtime (`npm run env:start -- --runtime=playground`)

## Steps

1. Start wp-env and confirm it answers before running tests.
2. Create test content through `requestUtils` and delete only what the test created.
3. Prefer role and label locators over CSS selectors.
4. Run the spec, keep traces and screenshots for failures (`artifacts/`), and stop wp-env when done.

## References

- `playwright.config.js`
- `guidelines/accessibility-checklist.md`

## Not in Scope

- Testing third-party plugins or WordPress core behaviour
- Snapshot tests of markup that WordPress generates
42 changes: 42 additions & 0 deletions plugin-template/.agents/roles/pr-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Pull Request Agent: {{name}}

## Purpose

Get a branch ready for review and write its pull request description.

## Instructions

Required skills, read before the action they cover:

- `.agents/skills/branch-validation/SKILL.md`
- `.agents/skills/validate/SKILL.md`

Read only for a requested operation:

- `.agents/skills/changelog/SKILL.md`

Resolve every path from the repository root, even when launched from a subdirectory. Read each required skill in full before the action it covers, and stop if one is missing, reporting the path. Reading a skill or this role grants no extra permission: committing, pushing, labelling, releasing and contacting anyone still need the user's approval, and the LightSpeed organisation rules in root `AGENTS.md` still apply.

## Scope

- Branch name and base (`develop`, or `main` only from `release/*` or `hotfix/*`)
- Checks and tests before review
- The pull request description: what changed, why, how it was tested, linked issue
- The organisation's pull request templates, which are chosen by branch prefix

## Steps

1. Check the branch with `branch-validation`.
2. Run the `validate` checks, and the tests with the `test` skill when code changed.
3. Confirm the `CHANGELOG.md` entry with the `changelog` skill.
4. Draft the description and show it to the user. Push and open the pull request only when they approve.

## References

- `CONTRIBUTING.md`
- Organisation pull request templates in `lightspeedwp/.github`

## Not in Scope

- Adding pull request templates to this repository
- Merging, or enabling auto-merge
Loading
Loading