wordpress-agent-kit 0.2.2 → 0.3.0

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

@@ -1,6 +1,7 @@
 ---
 name: WordPress Architect
 description: Expert developer that orchestrates Agent Skills, official Handbooks, and project-specific instructions.
+license: GPL-2.0-or-later
 ---
 
 # Role

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

@@ -1,6 +1,7 @@
 ---
 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)."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 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."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-block-development/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-block-development
 description: "Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-block-themes/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-block-themes
 description: "Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching)."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 name: wp-interactivity-api
 description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-performance/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-performance
 description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
 ---
 

package/.github/skills/wp-phpstan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-phpstan
 description: "Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines, WordPress-specific typing, and handling third-party plugin classes."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires Composer-based PHPStan."
 ---
 

package/.github/skills/wp-playground/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-playground
 description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
 ---
 

package/.github/skills/wp-plugin-development/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-plugin-development
 description: "Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-project-triage/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-project-triage
 description: "Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 name: wp-rest-api
 description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-wpcli-and-ops/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-wpcli-and-ops
 description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
 ---
 

package/.github/skills/wpds/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wpds
 description: "Use when building UIs leveraging the WordPress Design System (WPDS) and its components, tokens, patterns, etc."
+license: GPL-2.0-or-later
 compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 6.9+ (PHP 7.2.24+)."
 ---
 

package/AGENTS.md

@@ -8,32 +8,55 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Prompting**: `@clack/prompts`
 - **Build**: `tsc` (TypeScript Compiler)
 - **Test**: `vitest`
+- **Lint/Format**: Biome + ESLint
 
 ## Architecture
 - **Entry Point**: `src/cli.ts`
-- **Commands**: `src/commands/*.ts` (e.g., `install`, `setup`, `sync-skills`, `playground`)
-- **Core Logic**: `src/lib/*.ts` (e.g., `installer.ts` for file copying, `triage-mapper.ts` for project detection)
-- **Utilities**: `src/utils/*.ts` (e.g., `paths.ts`, `run.ts`)
+- **Commands**: `src/commands/*.ts` (e.g., `install`, `setup`, `sync-skills`, `playground`, `upgrade`)
+- **Core Logic**: `src/lib/*.ts` (e.g., `installer.ts` for file copying, `triage-mapper.ts` for project detection, `api.ts` for programmatic API)
+- **Utilities**: `src/utils/*.ts` (e.g., `paths.ts`, `run.ts`, `output.ts`, `exit-codes.ts`)
 - **Assets**: 
   - `AGENTS.template.md`: The template file copied to user projects.
-  - `.github/`: The source of skills and instructions copied to user projects.
+  - `.github/`: The source of skills (14 WordPress skills), instructions, agents, and prompts copied to user projects.
   - `vendor/wp-agent-skills/`: Submodule containing upstream skills.
 
+## Package Exports
+- `wordpress-agent-kit` → CLI entry (`dist/cli.js`)
+- `wordpress-agent-kit/api` → Programmatic API (`dist/lib/api.js`)
+
 ## Development Workflow
 - **Run locally**: `npm run dev` (uses `tsx src/cli.ts`)
 - **Build**: `npm run build` (outputs to `dist/`)
+- **TypeCheck**: `npm run check` (no-emit type checking)
 - **Test**: `npm test` (runs Vitest)
-- **Lint**: `npm run lint`
+- **Lint**: `npm run lint:check` (ESLint + Biome)
+- **Format**: `npm run format` (Prettier + Biome)
+- **Pre-commit**: Husky runs lint:check + test:run
 
 ## Key Commands
-- `install`: Copies `.github` and `AGENTS.md` template to a target directory.
-- `setup`: Interactive wizard that detects project type and configures the kit.
-- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.github/skills`.
+- `install`: Copies `.github` and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`.
+- `setup`: Interactive wizard that detects project type and configures the kit. Supports `--auto`, `--project-type`, `--tech-stack`, `--yes`.
+- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.github/skills`. Supports `--json`, `--dry-run`.
 - `playground`: Launches a local WordPress Playground instance using a blueprint.
-- `build-release`: Packages the CLI for release.
+- `upgrade`: Checks for and applies newer versions. Supports `--check-only`, `--force`, `--json`.
+
+## Agent-Friendly Features (v0.3.0+)
+- `--json`: Structured JSON output with success/data/error/time fields
+- `--dry-run`: Preview mode showing what would happen without making changes
+- `--ndjson`: Newline-delimited JSON for streaming long operations
+- `--quiet`: Suppress non-essential output
+- **Semantic exit codes**: 0=OK, 2=Invalid Args, 3=Not Found, 4=Permission Denied, 5=Already Exists, 6=Git Error, 7=Network Error, 8=Validation Error, 130=Cancelled
+- **Programmatic API**: `import { installKitApi, syncSkillsApi, runTriageApi, configureAgentsMdApi } from 'wordpress-agent-kit/api'`
 
 ## Notes for Agents
 - When modifying commands, ensure you update the corresponding JSDoc comments.
 - The `src/lib/installer.ts` file is critical as it handles the file copying logic.
 - The `src/lib/triage-mapper.ts` file contains logic for mapping project detection results to configuration options.
-- The `vendor` directory is gitignored and populated via submodule or script.
+- The `src/lib/api.ts` file exposes the programmatic API — all changes to command logic should flow through to the API.
+- The `vendor` directory is gitignored and populated via submodule or script.
+- The `.github/skills/` directory contains 14 WordPress skills following the AgentSkills.io spec.
+- CI runs on every push: lint, typecheck, test, build. No publish workflow (manual npm publish only).
+
+## Pi Extension (Package)
+- `pi.extensions`: `./extensions/wp-agent-kit` — registers WordPress agent tools
+- `pi.skills`: `./.github/skills` — 14 WordPress skills discoverable by Pi

package/AGENTS.template.md

@@ -1,31 +1,76 @@
 # Project: WordPress Codebase
 
-This repository is WordPress-centric (plugin, theme, or site). Agents should prioritize local skills and official WordPress standards.
+This repository is WordPress-centric (plugin, theme, block theme, or site). Agents should prioritize local skills and official WordPress standards.
 
 ## Onboarding
 
-- Core agent: `.github/agents/wp-architect.agent.md`
-- Workflow: `.github/instructions/wordpress-workflow.instructions.md`
-- Skills live in: `.github/skills/`
+- **Core Agent**: `.github/agents/wp-architect.agent.md` — the primary agent persona
+- **Workflow Instructions**: `.github/instructions/wordpress-workflow.instructions.md` — project-specific conventions
+- **Skills**: `.github/skills/` — specialized agent skills for WordPress development
 
-## Project Discovery (required before changes)
+## Project Discovery (Required Before Changes)
 
-1. Run project triage:
-   - `node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs`
-2. If routing is unclear, use the router decision tree:
-   - `.github/skills/wordpress-router/references/decision-tree.md`
-3. Update repo-specific guidance:
-   - Choose the project prefix based on existing code (functions/classes/constants).
-   - Confirm folder structure (single-file plugin vs `includes/`, blocks, theme, full site).
-   - Confirm target WordPress/PHP versions if relevant.
+1. **Run project triage** to classify the codebase:
+   ```bash
+   node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
+   ```
+   This outputs a JSON report with project kind, signals, and tooling.
+
+2. **Route to the right skill**:
+   - If routing is unclear, consult `.github/skills/wordpress-router/references/decision-tree.md`
+   - For plugins: `wp-plugin-development`
+   - For block themes: `wp-block-themes`
+   - For Gutenberg blocks: `wp-block-development`
+   - For REST API work: `wp-rest-api`
+   - For WP-CLI operations: `wp-wpcli-and-ops`
+
+3. **Update repo-specific guidance** based on triage results:
+   - Confirm the project prefix (functions, classes, constants)
+   - Confirm the folder structure (single-file plugin, `includes/`, blocks, theme, full site)
+   - Confirm target WordPress and PHP versions
+
+## Architecture
+
+<!-- Populated by project triage — do not remove -->
+
+- **Project Type**: <!-- plugin | theme | block-theme | site | gutenberg -->
+- **PHP Version**: <!-- minimum PHP version -->
+- **WP Version**: <!-- minimum WordPress version -->
+- **Build Tool**: <!-- webpack | @wordpress/scripts | vite | none -->
+- **Test Framework**: <!-- PHPUnit | Jest | Cypress | none -->
+
+## Commands
+
+<!-- Populated by project triage — do not remove -->
+
+| Purpose | Command |
+|---------|---------|
+| Build | <!-- e.g., npm run build --> |
+| Lint (PHP) | <!-- e.g., composer lint --> |
+| Lint (JS/CSS) | <!-- e.g., npm run lint --> |
+| Test | <!-- e.g., npm test, composer test --> |
+| Dev server | <!-- e.g., npm start --> |
+
+## Code Conventions
+
+<!-- Populated by project triage — do not remove -->
+
+- **Prefix**: <!-- e.g., myplugin_ for functions, MyPlugin\ for namespaces -->
+- **Indentation**: Tabs for PHP, <!-- 2 spaces for JS -->
+- **PHP Standards**: [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
+- **JS Standards**: <!-- WordPress JS standards -->
 
 ## Security Baseline
 
-- Sanitize input early, escape output late.
-- Use nonces for state-changing requests.
-- Enforce capabilities for privileged actions.
+- **Sanitize Early**: Validate and sanitize all user input (`sanitize_text_field`, `sanitize_email`, etc.)
+- **Escape Late**: Escape all output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- **Use Nonces**: All state-changing requests must include nonce verification (`wp_nonce_field`, `check_admin_referer`)
+- **Check Capabilities**: Privileged actions require capability checks (`current_user_can`)
+- **Validate AJAX/REST**: Use `permission_callback` for REST endpoints and capability checks for AJAX handlers
 
 ## Output Requirements
 
-- Prefer minimal, standards-compliant changes.
-- Follow existing conventions in the codebase.
+- Prefer minimal, standards-compliant changes over large rewrites
+- Follow existing conventions in the codebase (naming, patterns, architecture)
+- Cite which skill or handbook informed the solution
+- Cross-check against this file (`AGENTS.md`) before finalizing output