wordpress-agent-kit 0.2.1

package/.github/agents/wp-architect.agent.md

@@ -0,0 +1,42 @@
+---
+name: WordPress Architect
+description: Expert developer that orchestrates Agent Skills, official Handbooks, and project-specific instructions.
+---
+
+# Role
+
+You are the **WordPress Architect**. Your purpose is to build secure, scalable, and standards-compliant WordPress solutions by strictly following the project's specialized intelligence hierarchy.
+
+# Information Hierarchy (Strict Order)
+
+When a task is assigned, you must retrieve information in this sequence:
+
+1.  **Local Project Instructions**: Read `.github/instructions/wordpress-workflow.instructions.md` to understand the specific prefix, folder structure, and dev workflow for this repo.
+
+2.  **Agent Skills**: Consult the `.github/skills/` directory.
+
+    - Reference `wp-project-triage` to confirm if you are in a Plugin or Theme context.
+    - Reference `wp-block-development` for any Gutenberg/React tasks.
+    - Reference `wp-playground` to provide testable blueprints for your code.
+
+3.  **Official Manuals**: If local skills are insufficient, use the [WordPress Developer Handbooks](https://developer.wordpress.org) (Plugin, Theme, or Block Editor).
+
+4.  **Community Knowledge**: Use [WordPress Stack Exchange](https://wordpress.stackexchange.com) only as a final fallback for edge cases or legacy bugs.
+
+# Technical Requirements
+
+- **Standards**: Adhere strictly to [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) (e.g., tabs for indentation, Yoda conditions).
+
+- **Security**: Mandatory data validation on input (sanitization) and late-escaping on output (`esc_html`, `esc_attr`, `wp_kses`, etc.). Use nonces for all state-changing actions.
+
+- **Hooks**: Always prefer the Plugin API (Actions/Filters) over overriding global variables.
+
+- **Modernity**: Default to Block-first patterns and PHP 8.0+ features unless the project triage indicates otherwise.
+
+# Response Protocol
+
+- **Cite Your Source**: Briefly state which skill or handbook section informed your solution.
+
+- **Testability**: Whenever possible, provide a [WordPress Playground](https://playground.wordpress.net) link or JSON blueprint to demonstrate the code.
+
+- **Verification**: Cross-check your code against the `AGENTS.md` file in the root directory before finalized output.

package/.github/copilot-instructions.md

@@ -0,0 +1,2 @@
+@workspace /AGENTS.md
+@workspace / .github/instructions/wordpress-workflow.instructions.md

package/.github/instructions/wordpress-workflow.instructions.md

@@ -0,0 +1,41 @@
+\# WordPress Agent Skills Workflow
+
+This repo uses a local, filesystem-based set of WordPress agent skills under `.github/skills/`. Follow these procedures for every interaction.
+
+\## 1. Skill Discovery & Activation
+
+\- \*\*Always start by scanning \`.github/skills/\`\*\* to see which specialized modules are active.
+
+\- If the user asks for a Block, explicitly activate the \`wp-block-development\` skill.
+
+\- If the task involves environment setup, use the \`wp-playground\` skill patterns to provide a \`blueprint.json\` or a [Playground link]\(https://playground.wordpress.net).
+
+\## 2. Directory Mapping (Triage)
+
+Follow the \`wp-project-triage\` skill to identify where to place code:
+
+\- \*\*PHP Logic\*\*: Prefer the repo\'s existing structure first. If you\'re introducing structure to a single-file plugin, use \`includes/\` for PHP modules/classes.
+
+\- \*\*Blocks/Assets\*\*: Use the \`src/\` directory for development and \`build/\` for compiled assets.
+
+\- \*\*Tests\*\*: Locate existing tests in \`tests/phpunit/\` or \`tests/pest/\` before writing new ones.
+
+\## 3. Mandatory Implementation Standards
+
+When generating code, you must merge \*\*General Skills\*\* with \*\*Project Rules\*\*:
+
+\- \*\*Hooks\*\*: Use the \`wordpress-router\` skill logic to determine if a hook belongs in \`init\`, \`admin_init\`, or \`wp_enqueue_scripts\`.
+
+\- \*\*Naming\*\*: Prefix all PHP functions and classes with the existing project prefix (determine it from the codebase during triage). If there is no established prefix, pick one and apply it consistently.
+
+\- \*\*Documentation\*\*: Every function must include a [PHPDoc block]\(https://developer.wordpress.org) as defined in the WordPress Handbook.
+
+\## 4. Validation Step
+
+Before finalizing a response:
+
+1\. Cross-reference the code against the WordPress PHP Coding Standards (and keep indentation consistent with the existing file).
+
+2\. Check if a [WordPress.org Plugin Handbook]\(https://developer.wordpress.org) rule supersedes a generic community pattern.
+
+3\. State which skill was used (e.g., \*"Applied patterns from wp-block-development"\*).

package/.github/prompts/plan-smartDetectionSetup.prompt.md

@@ -0,0 +1,189 @@
+# Plan: Smart Detection-First Setup Flow
+
+Run triage before asking ANY questions. Only prompt when detection is unclear or user wants to override. Add "Not sure" options everywhere.
+
+**TL;DR:** Flip the current flow - detect first, ask later. The script becomes intelligent: if it confidently detects your project type and tech stack, it just shows you what it found and asks for confirmation. Only falls back to questions if needed. Makes setup feel magical instead of interrogative.
+
+**Key Changes from Current:**
+
+Current: Ask → Run triage → Customize
+**New:** Run triage → Show detection → Confirm or Override → Customize
+
+## Steps
+
+### 1. Restructure main flow in scripts/setup.mjs
+
+- Move triage execution to run BEFORE any project questions (currently line 113)
+- Place it right after kit installation check (after line 73)
+- Actually call real triage script: `vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs`
+- Parse JSON output into `triageResult` object
+
+### 2. Create detection mapper
+
+Map `triageResult.project.primary` to setup's project type options:
+- `wp-block-theme` → `block-theme`
+- `wp-block-plugin` → `blocks`
+- `wp-plugin` → `plugin`
+- `wp-theme` → `theme`
+- `wp-site` → `site`
+
+Map `triageResult.signals.*` to tech stack:
+- `blockJsonFiles.length > 0` → add `gutenberg`
+- `usesInteractivityApi` → add `interactivity`
+- `hasRestEndpoints` → add `rest-api`
+- `hasWpCliCommands` → add `wpcli`
+
+Map `triageResult.tooling.*`:
+- `tooling.php.hasComposerJson` → add `composer`
+- `tooling.node.packageManager` → add `npm`
+- `tooling.php.hasPhpStan` → add `phpstan`
+- `signals.hasPlaygroundBlueprint` → add `playground`
+
+### 3. Add confidence check and smart prompting
+
+If `detectedType` exists AND `detectedTech` has items:
+- Show `p.note()` with detected values in nice format
+- Single confirm: "Use these detected values? (y/n)"
+- If yes → skip all questions, use detected values
+- If no → proceed to manual questions with detected values as defaults
+
+If detection fails or finds nothing:
+- Proceed directly to manual questions (no confirmation prompt)
+
+### 4. Enhance question options
+
+Add to project type select:
+```javascript
+{ value: 'unsure', label: "I'm not sure" }
+```
+
+Update tech stack message:
+- Change "Select technologies used" → "Select technologies (or skip if unsure):"
+
+Add `initialValue` / `initialValues` to all prompts:
+- Use detected values if available
+- Undefined otherwise (no pre-selection)
+
+### 5. Remove redundant triage prompt
+
+- Delete the old "Run project triage?" question (currently in `p.group` after techStack)
+- Triage now always runs automatically
+- Include graceful fallback if triage script missing/fails
+
+### 6. Handle edge cases
+
+- Wrap triage in try/catch - if fails, show "Auto-detection unavailable" and continue
+- Check if triage script exists before attempting to run
+- If user selects "I'm not sure" for type → default to `other` for AGENTS.md generation
+- If tech stack is empty → generate minimal AGENTS.md with generic setup
+
+## Verification
+
+**Test detection works:**
+```bash
+# Should auto-detect and only confirm:
+cd test-block-plugin
+npm run setup
+
+# Should detect partially and pre-fill:
+cd test-theme-with-composer
+npm run setup
+
+# Should fall back to questions:
+cd empty-directory
+npm run setup
+```
+
+**Expected UX:**
+- Fast projects (has clear WP structure): 1 confirmation prompt only
+- Ambiguous projects: Questions with smart defaults pre-selected
+- Empty/new projects: All questions, no pre-selection
+
+## Decisions
+
+**Decision: Triage runs unconditionally**
+- Always attempt triage before questions
+- Graceful degradation: if fails → proceed with questions
+- User never sees errors, just "detection unavailable"
+
+**Decision: Single confirmation vs detailed review**
+- Chose: Single yes/no confirm on detection
+- Alternative considered: Show detection, then let user edit each field
+- Reasoning: Faster UX, user can override by saying "no"
+
+**Decision: "I'm not sure" is an option, not required**
+- Some users want to explore options
+- Others know nothing about their project
+- Giving them an explicit "unsure" choice prevents wrong guesses
+
+**Decision: Keep tech stack optional**
+- `required: false` stays
+- Empty array is valid (means "detect later" or "none yet")
+- AGENTS.md can still generate with minimal tech
+
+---
+
+## Phase 2: AI Enhancement Layer (Future)
+
+### Optional Local AI for Natural Language Explanations
+
+**Options:**
+- **Transformers.js** (Xenova/transformers.js) - Runs ONNX models in Node
+- **llama.cpp via llama-node** - Tiny local models (Phi-3.5-mini, TinyLlama)
+- **Recommended:** Phi-3.5-mini-instruct (3.8B quantized → ~2GB) via llama.cpp
+
+**Use Cases:**
+- Convert triage JSON → friendly paragraph: "I detected a WordPress block plugin with Interactivity API usage across 3 blocks..."
+- Explain recommendations: "I suggest adding PHPStan because..."
+- Answer simple Q&A during setup
+
+**Implementation:**
+- New module: `scripts/lib/ai-explainer.mjs`
+- Lazy-load model (only if user opts in with env var: `AI_EXPLAIN=1`)
+- Fallback to templates if model loading fails
+- Keep deterministic as default, AI as opt-in enhancement
+
+**Interactive Q&A:**
+- After showing recommendations, offer: "Have questions? (y/n)"
+- Simple REPL-style Q&A using RAG over skill files
+- Knowledge sources: All SKILL.md files + references
+- Exit Q&A → continue setup
+
+---
+
+## Architecture Philosophy
+
+**Core Principle:** Deterministic first, AI is additive
+
+**Phase 1 (Implement Now):**
+- Zero new dependencies
+- Works offline
+- Fast execution (< 5 seconds typical)
+- Smart use of structured triage data
+
+**Phase 2 (Optional Future):**
+- Feature flag: `AI_EXPLAIN=1`
+- Lazy-loaded AI models
+- Graceful degradation always
+- No cloud APIs, all local
+
+**Aligns with project principles:**
+- Prefer deterministic checks (see vendor/wp-agent-skills/docs/principles.md)
+- Filesystem-based intelligence
+- No "agent guesswork"
+
+---
+
+## Implementation Checklist
+
+- [x] Create new branch: `feature/smart-detection`
+- [x] Step 1: Restructure flow, call real triage
+- [x] Step 2: Implement detection mapper
+- [x] Step 3: Add confidence check and smart prompting
+- [x] Step 4: Enhance question options with "unsure"
+- [x] Step 5: Remove redundant triage question
+- [x] Step 6: Add error handling for edge cases
+- [x] Test on multiple project types
+- [x] Document new behavior in README
+- [x] Optional: Create lib/triage-mapper.mjs module for clean separation
+- [x] Optional: Create lib/agents-generator.mjs for template-based AGENTS.md generation

package/.github/skills/wordpress-router/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: wordpress-router
+description: "Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WordPress Router
+
+## When to use
+
+Use this skill at the start of most WordPress tasks to:
+
+- identify what kind of WordPress codebase this is (plugin vs theme vs block theme vs WP core checkout vs full site),
+- pick the right workflow and guardrails,
+- delegate to the most relevant domain skill(s).
+
+## Inputs required
+
+- Repo root (current working directory).
+- The user’s intent (what they want changed) and any constraints (WP version targets, WP.com specifics, release requirements).
+
+## Procedure
+
+1. Run the project triage script:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Read the triage output and classify:
+   - primary project kind(s),
+   - tooling available (PHP/Composer, Node, @wordpress/scripts),
+   - tests present (PHPUnit, Playwright, wp-env),
+   - any version hints.
+3. Route to domain workflows based on user intent + repo kind:
+   - For the decision tree, read: `skills/wordpress-router/references/decision-tree.md`.
+4. Apply guardrails before making changes:
+   - Confirm any version constraints if unclear.
+   - Prefer the repo’s existing tooling and conventions for builds/tests.
+
+## Verification
+
+- Re-run the triage script if you create or restructure significant files.
+- Run the repo’s lint/test/build commands that the triage output recommends (if available).
+
+## Failure modes / debugging
+
+- If triage reports `kind: unknown`, inspect:
+  - root `composer.json`, `package.json`, `style.css`, `block.json`, `theme.json`, `wp-content/`.
+- If the repo is huge, consider narrowing scanning scope or adding ignore rules to the triage script.
+
+## Escalation
+
+- If routing is ambiguous, ask one question:
+  - “Is this intended to be a WordPress plugin, a theme (classic/block), or a full site repo?”

package/.github/skills/wordpress-router/references/decision-tree.md

@@ -0,0 +1,55 @@
+# Router decision tree (v1)
+
+This is a lightweight routing guide. It assumes you can run `wp-project-triage` first.
+
+## Step 1: classify repo kind (from triage)
+
+Use `triage.project.kind` and the strongest signals:
+
+- `wp-core` → treat as WordPress core checkout work (core patches, PHPUnit, build tools).
+- `wp-site` → treat as a full site repo (wp-content present; changes might be theme + plugins).
+- `wp-block-theme` → theme.json/templates/patterns workflows.
+- `wp-theme` → classic theme workflows (templates PHP, `functions.php`, `style.css`).
+- `wp-block-plugin` → Gutenberg block development in a plugin (block.json, build pipeline).
+- `wp-plugin` / `wp-mu-plugin` → plugin workflows (hooks, admin, settings, cron, REST, security).
+- `gutenberg` → Gutenberg monorepo workflows (packages, tooling, docs).
+
+If multiple kinds match, prefer the most specific:
+`gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plugin` > `wp-theme` > `wp-plugin`.
+
+## Step 2: route by user intent (keywords)
+
+Route by intent even if repo kind is broad (like `wp-site`):
+
+- **Interactivity API / data-wp-* directives / @wordpress/interactivity / viewScriptModule**
+  - Route → `wp-interactivity-api`.
+- **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
+  - Route → `wp-abilities-api`.
+- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
+  - Route → `wp-playground`.
+- **Blocks / block.json / registerBlockType / attributes / save serialization**
+  - Route → `wp-block-development`.
+- **theme.json / Global Styles / templates/*.html / patterns/**
+  - Route → `wp-block-themes`.
+- **Plugins / hooks / activation hook / uninstall / Settings API / admin pages**
+  - Route → `wp-plugin-development`.
+- **REST endpoint / register_rest_route / permission_callback**
+  - Route → `wp-rest-api`.
+- **WP-CLI / wp-cli.yml / commands**
+  - Route → `wp-wpcli-and-ops`.
+- **Build tooling / @wordpress/scripts / webpack / Vite / npm scripts**
+  - Route → `wp-build-tooling` (planned).
+- **Testing / PHPUnit / wp-env / Playwright**
+  - Route → `wp-testing` (planned).
+- **PHPStan / static analysis / phpstan.neon / phpstan-baseline.neon**
+  - Route → `wp-phpstan`.
+- **Performance / caching / query profiling / editor slowness**
+  - Route → `wp-performance`.
+- **Security / nonces / capabilities / sanitization/escaping / uploads**
+  - Route → `wp-security` (planned).
+
+## Step 3: guardrails checklist (always)
+
+- Verify detected tooling before suggesting commands (Composer vs npm/yarn/pnpm).
+- Prefer existing lint/test scripts if present.
+- If version constraints aren’t detectable, ask for target WP core and PHP versions.

package/.github/skills/wp-abilities-api/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: wp-abilities-api
+description: "Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Abilities API
+
+## When to use
+
+Use this skill when the task involves:
+
+- registering abilities or ability categories in PHP,
+- exposing abilities to clients via REST (`wp-abilities/v1`),
+- consuming abilities in JS (notably `@wordpress/abilities`),
+- diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.
+
+## Inputs required
+
+- Repo root (run `wp-project-triage` first if you haven’t).
+- Target WordPress version(s) and whether this is WP core or a plugin/theme.
+- Where the change should live (plugin vs theme vs mu-plugin).
+
+## Procedure
+
+### 1) Confirm availability and version constraints
+
+- If this is WP core work, check `signals.isWpCoreCheckout` and `versions.wordpress.core`.
+- If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.
+
+### 2) Find existing Abilities usage
+
+Search for these in the repo:
+
+- `wp_register_ability(`
+- `wp_register_ability_category(`
+- `wp_abilities_api_init`
+- `wp_abilities_api_categories_init`
+- `wp-abilities/v1`
+- `@wordpress/abilities`
+
+If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.
+
+### 3) Register categories (optional)
+
+If you need a logical grouping, register an ability category early (see `references/php-registration.md`).
+
+### 4) Register abilities (PHP)
+
+Implement the ability in PHP registration with:
+
+- stable `id` (namespaced),
+- `label`/`description`,
+- `category`,
+- `meta`:
+  - add `readonly: true` when the ability is informational,
+  - set `show_in_rest: true` for abilities you want visible to clients.
+
+Use the documented init hooks for Abilities API registration so they load at the right time (see `references/php-registration.md`).
+
+### 5) Confirm REST exposure
+
+- Verify the REST endpoints exist and return expected results (see `references/rest-api.md`).
+- If the client still can’t see the ability, confirm `meta.show_in_rest` is enabled and you’re querying the right endpoint.
+
+### 6) Consume from JS (if needed)
+
+- Prefer `@wordpress/abilities` APIs for client-side access and checks.
+- Ensure build tooling includes the dependency and the project’s build pipeline bundles it.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesAbilitiesApi: true` after your change (if applicable).
+- REST check (in a WP environment): endpoints under `wp-abilities/v1` return your ability and category when expected.
+- If the repo has tests, add/update coverage near:
+  - PHP: ability registration and meta exposure
+  - JS: ability consumption and UI gating
+
+## Failure modes / debugging
+
+- Ability never appears:
+  - registration code not running (wrong hook / file not loaded),
+  - missing `meta.show_in_rest`,
+  - incorrect category/ID mismatch.
+- REST shows ability but JS doesn’t:
+  - wrong REST base/namespace,
+  - JS dependency not bundled,
+  - caching (object/page caches) masking changes.
+
+## Escalation
+
+- If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.
+- For canonical details, consult:
+  - `references/rest-api.md`
+  - `references/php-registration.md`

package/.github/skills/wp-abilities-api/references/php-registration.md

@@ -0,0 +1,67 @@
+# PHP registration quick guide
+
+Key concepts and entrypoints for the WordPress Abilities API:
+
+- Register ability categories and abilities in PHP.
+- Use the Abilities API init hooks to ensure registration occurs at the right lifecycle time.
+
+## Hook order (critical)
+
+**Categories must be registered before abilities.** Use the correct hooks:
+
+1. `wp_abilities_api_categories_init` — Register categories here first.
+2. `wp_abilities_api_init` — Register abilities here (after categories exist).
+
+**Warning:** Registering abilities outside `wp_abilities_api_init` triggers `_doing_it_wrong()` and the registration will fail.
+
+```php
+// 1. Register category first
+add_action( 'wp_abilities_api_categories_init', function() {
+    wp_register_ability_category( 'my-plugin', [
+        'label' => __( 'My Plugin', 'my-plugin' ),
+    ] );
+} );
+
+// 2. Then register abilities
+add_action( 'wp_abilities_api_init', function() {
+    wp_register_ability( 'my-plugin/get-info', [
+        'label'       => __( 'Get Site Info', 'my-plugin' ),
+        'description' => __( 'Returns basic site information.', 'my-plugin' ),
+        'category'    => 'my-plugin',
+        'callback'    => 'my_plugin_get_info_callback',
+        'meta'        => [ 'show_in_rest' => true ],
+    ] );
+} );
+```
+
+## Common primitives
+
+- `wp_register_ability_category( $category_id, $args )`
+- `wp_register_ability( $ability_id, $args )`
+
+## Key arguments for `wp_register_ability()`
+
+| Argument | Description |
+|----------|-------------|
+| `label` | Human-readable name for UI (e.g., command palette) |
+| `description` | What the ability does |
+| `category` | Category ID (must be registered first) |
+| `callback` | Function that executes the ability |
+| `input_schema` | JSON Schema for expected input (enables validation) |
+| `output_schema` | JSON Schema for returned output |
+| `permission_callback` | Optional function to check if current user can execute |
+| `meta.show_in_rest` | Set `true` to expose via REST API |
+| `meta.readonly` | Set `true` if ability is informational only |
+
+## Recommended patterns
+
+- Namespace IDs (e.g. `my-plugin:feature.edit`).
+- Treat IDs as stable API; changing IDs is a breaking change.
+- Use `input_schema` and `output_schema` for validation and to help AI agents understand usage.
+- Always include a `permission_callback` for abilities that modify data.
+
+## References
+
+- Abilities API handbook: https://developer.wordpress.org/apis/abilities-api/
+- Dev note: https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/
+

package/.github/skills/wp-abilities-api/references/rest-api.md

@@ -0,0 +1,13 @@
+# REST API quick guide (`wp-abilities/v1`)
+
+The Abilities API exposes endpoints under the REST namespace:
+
+- `wp-abilities/v1/abilities`
+- `wp-abilities/v1/categories`
+
+Debug checklist:
+
+- Confirm the route exists under `wp-json/wp-abilities/v1/...`.
+- Verify the ability/category shows in REST responses.
+- If missing, confirm `meta.show_in_rest` is enabled for that ability.
+