Add project agent skills and privacy guidance

Author: Tsvetan Stoychev

.agents/skills/audit-basicrum-privacy/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: audit-basicrum-privacy
+description: Audit Basicrum's privacy implementation and disclosures. Use for GDPR, ePrivacy, cookies, consent, telemetry data flows, collector roles, retention, transfers, privacy-policy text, plugin descriptions, or release privacy reviews.
+---
+
+# Audit Basicrum Privacy
+
+## Purpose
+
+Perform an evidence-based privacy engineering and compliance-readiness review of
+the WordPress plugin, its bundled browser code, and its documented collector
+relationship. Do not certify the plugin or a site as "GDPR compliant" and do not
+replace advice from qualified counsel.
+
+## Establish Scope
+
+1. Identify the deployment model: hosted or self-hosted collector, applicable
+   jurisdictions, target visitors, and enabled Basicrum features.
+2. Identify the likely roles of the site operator, Basicrum, hosting providers,
+   and other recipients. Record unknown controller, processor, joint-controller,
+   subprocessor, contract, transfer, retention, and lawful-basis questions as
+   `NEEDS LEGAL DECISION`; do not guess.
+3. Review current official primary sources. At minimum, consult the WordPress
+   Plugin Handbook privacy guidance, GDPR text, ePrivacy Article 5(3), and EDPB
+   consent guidance. Record source links, jurisdiction, and access date.
+4. Treat ePrivacy storage or terminal-access rules separately from GDPR lawful
+   basis. Do not assume that a GDPR lawful basis automatically permits cookies.
+
+## Trace the Real Data Flow
+
+Inspect code and runtime behavior rather than relying on documentation alone.
+Include `src/Assets.php`, `src/Admin/Privacy.php`, settings and validation code,
+both loader variants, bundled Boomerang code and plugins, consent adapters,
+uninstall behavior, PHP tests, browser tests, and an intercepted representative
+beacon.
+
+Create an inventory with one row per data element or storage operation:
+
+- source and trigger;
+- exact field, identifier, URL component, or cookie/storage key;
+- purpose and feature dependency;
+- recipient and onward recipient;
+- transmission security and access boundary;
+- retention and deletion path;
+- behavior before consent, after opt-in, after denial, and after withdrawal;
+- corresponding public disclosure and unresolved legal decision.
+
+Pay particular attention to full page and resource URLs, query strings,
+referrers, IP addresses observed by the collector, user agents, device and
+network attributes, performance and interaction timings, Brum Site ID, page
+type, cross-page identifiers, and accidental sensitive data in URLs. Minimize or
+remove collection that is not necessary for the documented purpose.
+
+## Audit Cookies and Consent
+
+1. Enumerate every cookie and browser-storage value read, created, refreshed,
+   or removed by Basicrum or bundled code. Record name, host/domain, path,
+   lifetime, Secure, SameSite, purpose, and proposed essential/non-essential
+   classification.
+2. Verify that a new installation uses the privacy-protective loading default.
+3. In consent-controlled mode, verify that no monitoring request, identifier,
+   or non-essential storage occurs before the external tool's authoritative
+   opt-in callback.
+4. Verify opt-in is idempotent and cannot load duplicate instrumentation.
+5. Verify denial and withdrawal stop future collection and remove Basicrum
+   cookies across the supported host and parent-domain cases. Clearly document
+   any collection that cannot be undone without a page reload.
+6. Verify immediate mode is intentional, plainly warned, and never described as
+   automatically lawful.
+7. Test granted, denied, unknown, and region-dependent consent states for each
+   supported adapter, using both readable and minified production loaders.
+
+## Audit WordPress Integration and Disclosures
+
+Compare actual behavior with all public and administrator-facing statements:
+
+- the plugin header `Description`;
+- the `readme.txt` short and long descriptions and FAQ;
+- repository documentation and consent integration examples;
+- settings labels, warnings, and help text;
+- editable WordPress Privacy Policy Guide content registered through
+  `wp_add_privacy_policy_content()`.
+
+Require an explicit privacy-first statement in the plugin header and WordPress
+readme, but reject blanket compliance claims. Disclose the actual data
+categories, purposes, recipients, cookies, consent modes, withdrawal limits,
+and site-operator responsibilities in language a webmaster can act on.
+
+Determine from evidence whether WordPress personal-data exporter and eraser
+callbacks apply. If the plugin stores no visitor personal data in WordPress,
+mark them `NOT APPLICABLE` with evidence and separately assess rights handling
+at the remote collector. Verify uninstall removes plugin settings without
+silently claiming that remote telemetry was erased.
+
+## Verify With Tests
+
+Add or run proportionate tests for every changed privacy boundary:
+
+- PHP tests for privacy-safe defaults, disabled/missing-setting runtime gates,
+  settings validation, and Privacy Policy Guide content;
+- browser tests for pre-consent silence, one-time opt-in, denial, withdrawal,
+  cookie cleanup, HTTP/HTTPS behavior, subdomains, and both loader variants;
+- runtime interception that records the actual request URL, headers, payload,
+  cookies, and browser storage without contacting a production collector;
+- packaging checks that confirm the reviewed privacy text and production
+  assets are present in the release ZIP.
+
+Run the narrow tests first, then the repository checks affected by the change.
+Never treat a passing automated test as legal approval.
+
+## Report the Audit
+
+Use only these statuses:
+
+- `PASS` - code, runtime evidence, tests, and disclosure agree.
+- `FAIL` - a concrete privacy, consent, cookie, security, or disclosure defect.
+- `NEEDS LEGAL DECISION` - the answer depends on jurisdiction, contracts,
+  purpose, legal basis, retention, transfers, or operator configuration.
+- `NOT APPLICABLE` - supported by evidence, not assumption.
+
+For each item, report requirement or risk, status, code/runtime evidence,
+current official source, remediation, and owner. Separate plugin engineering
+work from collector/backend work and site-operator or counsel decisions. End
+with residual risks and the exact tests run. Never conclude with an unqualified
+claim of GDPR or cookie-law compliance.

.agents/skills/audit-basicrum-privacy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Audit Basicrum Privacy"
+  short_description: "Audit privacy, cookies, consent, and disclosures"
+  default_prompt: "Use $audit-basicrum-privacy to audit Basicrum's data flows, cookies, consent behavior, and public privacy disclosures."

.agents/skills/change-basicrum-settings/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: change-basicrum-settings
+description: Change Basicrum WordPress settings across defaults, admin UI, validation, migrations, and runtime gates. Use for Beacon URL, Brum Site ID, monitoring enablement, HTTP Strictness, Script Position, or any basicrum_settings option.
+---
+
+# Change Basicrum Settings
+
+Treat a setting as one behavior spanning storage, administration, validation,
+runtime use, upgrades, tests, documentation, and translations.
+
+## Map the setting
+
+1. Inspect `plugins/basicrum/src/Helpers.php` for keys and defaults.
+2. Inspect `Admin/Settings/Page.php` and `Validate.php` for rendering,
+   sanitization, validation, and error messages.
+3. Inspect `Admin/Upgrades.php` before changing an existing stored value.
+4. Find every runtime consumer and existing test with `rg`.
+5. Define behavior for new installs, existing installs, enabled monitoring, and
+   disabled monitoring before editing.
+
+## Implement the complete behavior
+
+- Keep the `basicrum_settings` schema synchronized across defaults, UI,
+  validation, migrations, runtime code, tests, docs, and translations.
+- Make server-side validation authoritative. Client-side disabled states and
+  invalid-field styling are usability aids, not security controls.
+- Require a valid Beacon URL and Brum Site ID when monitoring is enabled. Keep
+  frontend injection gated when either required value is absent.
+- Disable dependent controls when monitoring is disabled, and preserve a clear
+  visual hierarchy between general, performance, privacy, and developer fields.
+- Keep Script Position outside Developer Settings. Keep HTTP Strictness disabled
+  by default and describe it as local HTTP testing support, not a production
+  mode.
+- Use WordPress Settings API errors and accessible field associations. Align any
+  invalid icon with the field it describes and render it only while invalid.
+- Sanitize by data type, escape for the final output context, and preserve
+  capability and nonce protections already supplied by the settings flow.
+- Add a version-gated migration when stored data must change. Make migrations
+  idempotent.
+
+If user-facing text changes, also apply `$update-basicrum-copy`.
+
+## Verify
+
+Run focused tests while iterating, then run:
+
+```bash
+make lint-php
+make lint
+make analyse
+make unit
+make conventions
+```
+
+Run `make translations` for changed strings and require a second generation to
+produce no diff. Manually verify enabled, disabled, invalid, and valid form
+states when layout or browser behavior changes.

.agents/skills/change-basicrum-settings/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Change Basicrum Settings"
+  short_description: "Change and verify Basicrum administrator settings"
+  default_prompt: "Use $change-basicrum-settings to implement and verify a Basicrum administrator setting change."

.agents/skills/extend-basicrum-page-types/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: extend-basicrum-page-types
+description: Add and test Basicrum p_type detection for WordPress and WooCommerce. Use for PageTypeDetector.php or shop, product, cart, checkout, order-pay, order-received, account, archive, and other page classifications.
+---
+
+# Extend Basicrum Page Types
+
+Treat `p_type` as a public analytics taxonomy whose names and precedence must be
+stable, observable in real beacons, and safe when optional plugins are absent.
+
+## Define the classification
+
+1. Inspect `plugins/basicrum/src/PageTypeDetector.php` and its unit tests.
+2. Confirm the platform's official conditional functions and the lifecycle point
+   at which the main query makes them reliable.
+3. Choose a stable `p_type` label and place the condition in specificity order.
+   WooCommerce order-received and order-pay checks must precede general checkout;
+   product checks must precede general WordPress single-page checks.
+4. Guard optional plugin classes and functions so Basicrum works without
+   WooCommerce.
+5. Preserve the `basicrum_page_type` filter and the `unknown` fallback.
+
+Use external projects only to inform taxonomy ideas. Implement the Basicrum
+logic independently and acknowledge inspiration accurately when adding a new
+external source.
+
+## Cover three layers
+
+- Add unit coverage for the new condition, false path, overlapping-condition
+  precedence, optional-plugin absence, and filter behavior when applicable.
+- Confirm `Assets` serializes the value into inline configuration.
+- For commerce routes, extend the isolated WooCommerce browser suite so it
+  visits the real page anonymously and asserts the actual emitted beacon.
+
+The E2E assertion must verify `p_type`, `p_gen=wp`, and `brum_site_id`, not only
+DOM markup. Seed the minimum product, cart, or order state needed for the route.
+Keep Coming soon mode disabled so anonymous storefront visibility is part of the
+test.
+
+## Verify
+
+```bash
+make lint-php
+make lint
+make analyse
+make unit
+make woocommerce-e2e
+make conventions
+git diff --check
+```
+
+When changing the WooCommerce environment, keep its version and checksum paired
+in `tools/setup-woocommerce-e2e.sh` and keep Docker tags paired with immutable
+digests in `docker/woocommerce-e2e.yml`.

.agents/skills/extend-basicrum-page-types/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Extend Basicrum Page Types"
+  short_description: "Add and test WordPress page classifications"
+  default_prompt: "Use $extend-basicrum-page-types to add and verify a Basicrum page type."

.agents/skills/integrate-basicrum-consent/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: integrate-basicrum-consent
+description: Integrate and test external consent tools with Basicrum's opt-in and opt-out wrappers. Use for Borlabs Cookie, WP Consent API, Complianz, CookieYes, consent events, regional defaults, withdrawal, cookie cleanup, or adapter tests.
+---
+
+# Integrate Basicrum Consent
+
+Keep Basicrum as a small execution gate around an external consent tool's
+authoritative decision.
+
+## Establish the provider contract
+
+1. Read the provider's current official documentation and shipped public source.
+2. Use community reports to identify initialization, caching, aggregation, and
+   version edge cases, not as the sole contract source.
+3. Record the supported provider version and review date in documentation when
+   behavior can change.
+4. Confirm initial state, stored state on later page loads, event names, payload
+   shapes, category IDs, callback timing, regional defaults, withdrawal, and
+   whether the provider signals on every page.
+5. Separate an explicit visitor opt-in from a provider reporting that monitoring
+   is allowed under an opt-out regional policy.
+
+## Build the adapter
+
+- Keep exactly two Basicrum public callbacks:
+  `OPT_IN_BASICRUM_LOADER_WRAPPER()` and
+  `OPT_OUT_BASICRUM_LOADER_WRAPPER()`.
+- Make the provider adapter call exactly one callback on every page after the
+  consent loader is available. Check that the selected callback exists before
+  calling it.
+- Do not add a second Basicrum consent state, `BRUM_CONSENT` API, cookie, or
+  state lookup inside the Boomerang loader.
+- Keep opt-in loading idempotent. Keep opt-out idempotent, disable collection,
+  and remove the documented Boomerang cookies for the current host and parent
+  domains.
+- Put webmaster adapters in `examples/integrations/`, outside the installable
+  plugin. Do not modify a production loader merely to accommodate a test.
+- Document script ordering and cache/minification exclusions. Do not claim that
+  an adapter replaces legal review or consent-tool configuration.
+
+## Test the real boundary
+
+- Execute the exact example adapter against a thin test double that models only
+  the provider's documented public API, defaults, events, and payloads.
+- Cover adapter-before-provider and provider-before-adapter initialization,
+  saved grant, saved denial, new grant, withdrawal, duplicate events, and
+  irrelevant categories.
+- Cover opt-in and opt-out regional defaults for region-aware APIs.
+- Run the privacy-critical loader suite against both minified and unminified
+  loader variants while intercepting Boomerang and blocking unexpected network
+  requests.
+
+```bash
+make js-test
+make unit
+make conventions
+git diff --check
+```
+
+Update `examples/integrations/README.md`, the main README, plugin readme, privacy
+guidance, and translations when the administrator-visible contract changes.

.agents/skills/integrate-basicrum-consent/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Integrate Basicrum Consent"
+  short_description: "Integrate and test external consent tools"
+  default_prompt: "Use $integrate-basicrum-consent to add or review a Basicrum consent-tool adapter and its contract tests."

.agents/skills/release-basicrum-plugin/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: release-basicrum-plugin
+description: Build and verify installable Basicrum WordPress releases. Use for packaging, Composer production autoloading, version metadata, Tested up to, compatibility matrices, action pins, permissions, checksums, ZIP smoke tests, or release gates.
+---
+
+# Release Basicrum Plugin
+
+Test the artifact users install, not only the source checkout.
+
+## Preserve the package boundary
+
+- Treat `plugins/basicrum/` as the installable plugin and repository root files
+  as development tooling unless explicitly copied by the release builder.
+- Build through `tools/build-release.sh`. Install Composer production
+  dependencies in a temporary tree with an optimized authoritative autoloader;
+  do not replace normal Composer PSR-4 loading with a handwritten runtime
+  autoloader.
+- Include referenced runtime PHP, JavaScript, CSS, images, translations, readme,
+  license, and production vendor files.
+- Exclude tests, Playwright and Node files, examples, Docker files, agent skills,
+  local configuration, caches, and development dependencies.
+- Generate the SHA-256 checksum from the exact ZIP that passed smoke testing.
+
+## Keep release metadata and support claims honest
+
+Keep the plugin header Version, `BASICRUM_VERSION`, `Stable tag`, top changelog
+version, and `v<version>` release tag identical. Advance `Tested up to` only
+after blocking integration rows for that stable WordPress train pass. Never use
+beta, nightly, trunk, or a patch version for that field.
+
+Keep PHP unit coverage continuous from 7.4 through the newest supported release.
+Keep minimum WordPress, current stable, and non-blocking trunk integration roles
+explicit and use combinations supported by WordPress core.
+
+## Harden release automation
+
+- Pin third-party GitHub Actions to reviewed full commit SHAs and keep adjacent
+  release-tag comments synchronized.
+- Review Dependabot release notes, permissions, runtime changes, and CI before
+  merging updates.
+- Keep default workflow permissions read-only. Grant `contents: write` only to
+  release jobs that attach artifacts.
+- Run Composer validation, auditing, PHPStan, translation reproducibility,
+  repository conventions, and generated-asset checks.
+
+## Exercise the artifact
+
+```bash
+make package
+make package-verify
+make package-smoke
+```
+
+Inspect the ZIP listing, install it into clean WordPress, activate through
+WP-CLI, render an admin and frontend request, confirm the loader appears with
+valid settings, and reject PHP warnings or fatals.
+
+Before a production release, run every check listed in `AGENTS.md`, confirm the
+blocking CI matrix is green, and exercise release-workflow-only dependency
+updates through a prerelease. Report any gate not actually run.

.agents/skills/release-basicrum-plugin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Basicrum Plugin"
+  short_description: "Build and verify installable Basicrum releases"
+  default_prompt: "Use $release-basicrum-plugin to prepare and verify an installable Basicrum WordPress release."