WordPress Agent Kit

WordPress-focused AI agent starter kit for GitHub Copilot, Cursor, Claude, and Pi Coding Agent. Installs 13 specialized WordPress agent skills, an agent persona, workflow instructions, and AGENTS.md configuration — everything an AI coding agent needs to build WordPress plugins, themes, and blocks correctly.

Maintained by Kyle Brodeur.

---

Getting Started

Choose your scenario:

Scenario 1: Brand New WordPress Project

# 1. Install the kit (copies skills, agents, instructions, AGENTS.md template)
npx wp-agent-kit install /path/to/my-plugin --platform github

# 2. Run auto-setup (detects project type and configures AGENTS.md)
npx wp-agent-kit setup /path/to/my-plugin --auto

# 3. (Optional) Verify the triage report
node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs

What gets installed:

my-plugin/
├── AGENTS.md                  # Project-specific agent instructions
├── AGENTS.template.md         # Template reference for future updates
├── .github/
│   ├── agents/
│   │   └── wp-architect.agent.md    # WordPress Architect agent persona
│   ├── instructions/
│   │   └── wordpress-workflow.instructions.md
│   ├── prompts/
│   └── skills/                      # 17 WordPress skills
│       ├── wp-project-triage/       # Project detection
│       ├── wp-plugin-development/   # Plugin architecture
│       ├── wp-block-development/    # Gutenberg blocks
│       ├── wp-block-themes/         # Block themes
│       ├── wp-rest-api/             # REST API
│       ├── wp-interactivity-api/    # Interactivity API
│       ├── wp-abilities-api/        # Abilities API
│       ├── wp-performance/          # Performance profiling
│       ├── wp-phpstan/              # Static analysis
│       ├── wp-wpcli-and-ops/        # WP-CLI operations
│       ├── wp-playground/           # Testing environments
│       ├── wpds/                    # Design system
│       └── wordpress-router/        # Repo classification
└── .wp-agent-kit-manifest.github.json  # Safe-update tracking

Scenario 2: Existing WordPress Project

# 1. Install kit (preserves your existing AGENTS.md)
npx wp-agent-kit install /path/to/existing-plugin --platform github

# 2. Run triage to detect your project's type, tech stack, and tooling
node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs

# 3. Configure based on detection (headless)
npx wp-agent-kit setup /path/to/existing-plugin --auto

# Or specify explicitly
npx wp-agent-kit setup /path/to/existing-plugin \
  --project-type plugin \
  --tech-stack gutenberg,rest-api,wpcli,composer,npm \
  --package-manager pnpm \
  --yes

Key behavior:

• Your existing AGENTS.md is never overwritten — only new sections are added
• Triage inspects your codebase and returns structured JSON with project kind, signals, and tooling
• Setup updates only the tooling/configuration sections of AGENTS.md

Scenario 3: Upgrading an Existing Kit Installation

# Check if an update is available
npx wp-agent-kit upgrade --check-only

# Preview what would change (dry-run)
npx wp-agent-kit install --dry-run

# Apply safe update (preserves your modifications)
npx wp-agent-kit upgrade --force

Safe update behavior:

• Compares installed files against a manifest of original hashes
• Files you haven't modified → automatically updated
• Files you modified → skipped (preserved)
• Use --force to overwrite your modifications with upstream changes
• A backup is created at .wp-agent-kit-backup-{timestamp}/ before making changes

# Emergency: override all safety and replace everything
npx wp-agent-kit install --no-safe --force

---

Quick Reference

CLI Commands

Command	Purpose
install [dir]	Install kit into a project
setup [dir]	Interactive or headless configuration
sync-skills [ref]	Pull latest skills from WordPress/agent-skills
upgrade [dir]	Check or apply version upgrades
playground	Launch local WordPress Playground

Platform Flags

Platform	Flag	Target Directory
GitHub Copilot / VS Code	--platform github	.github/
Cursor IDE	--platform cursor	.cursor/
Claude Code	--platform claude	.claude/
Pi Coding Agent	--platform pi	.pi/agent/
Generic .agent	--platform agent	.agent/

Agent-Friendly Flags (All Commands)

Flag	Description
--json	Machine-readable JSON output
--dry-run	Preview changes without applying
--ndjson	Newline-delimited JSON for streaming
--quiet	Suppress non-error output

---

Pi Coding Agent Integration

This package is also a Pi extension — install it once and all WordPress skills and tools are available to Pi:

pi install npm:wordpress-agent-kit

Pi Tools (Callable by the Agent)

Tool	What it does
wp_triage	Detect WordPress project type, signals, and tooling
wp_install_kit	Install/update kit into a project (safe by default)
wp_sync_skills	Sync skills from WordPress/agent-skills upstream
wp_upgrade	Check and apply version upgrades

Pi Commands (Type / in Pi TUI)

Command	What it does
/wp-triage [dir]	Run project detection, show in status bar
/wp-install [dir]	Install kit into current project
/wp-sync-skills [ref]	Sync skills from upstream
/wp-upgrade	Show installed vs latest version

---

Programmatic API

Import directly into scripts, tests, or other tools:

import {
  installKitApi,         // Install/update kit
  syncSkillsApi,         // Sync skills from upstream
  runTriageApi,          // Run project detection
  configureAgentsMdApi,  // Configure AGENTS.md
  computeChanges,        // Preview file changes (dry-run)
  isKitInstalled,        // Check if kit is installed
  loadManifest,          // Read install manifest
  updateKit,             // Raw safe update
  ExitCode,              // Semantic exit codes
} from 'wordpress-agent-kit/api';

// Install with safe update
const result = await installKitApi({
  targetDir: '/path/to/my-plugin',
  platform: 'github',
  safe: true,     // Use manifest-based diff
  backup: true,   // Create backup before changes
  force: false,   // Don't overwrite user mods
});

// Dry-run preview
const preview = await installKitApi({
  targetDir: '/path/to/my-plugin',
  platform: 'github',
  dryRun: true,
});
// preview.data.actions → [{ type: 'create', target: '...', description: '...' }]

// Detect project type
const triage = await runTriageApi({ targetDir: '/path/to/project' });
console.log(triage.data.project.primary); // "plugin"

Semantic Exit Codes

Code	Meaning
0	Success
2	Invalid arguments
3	Not found
4	Permission denied
5	Already exists
6	Git error
7	Network error
8	Validation failed
130	Cancelled

---

Skills Reference

All 13 skills follow the AgentSkills.io specification:

Skill	When to Use
wp-project-triage	Run deterministic project detection (type, tooling, versions)
wp-plugin-development	Develop WordPress plugins (hooks, settings, security, release)
wp-block-development	Develop Gutenberg blocks (block.json, attributes, rendering)
wp-block-themes	Develop block themes (theme.json, templates, patterns, variations)
wp-rest-api	Build, extend, or debug REST API endpoints/routes
wp-interactivity-api	Build Interactive blocks with data-wp-* directives
wp-abilities-api	Register and consume WordPress Abilities API
wp-abilities-audit	Audit a plugin's REST surface for Abilities API opportunities
wp-abilities-verify	Verify registered Abilities match their annotations
wp-performance	Profile and optimize WordPress performance
wp-phpstan	Configure and run PHPStan static analysis
wp-wpcli-and-ops	WP-CLI commands, automation, multisite operations
wp-playground	Test in disposable WordPress Playground instances
blueprint	Write and edit WordPress Playground blueprint JSON
wpds	Build UIs with the WordPress Design System
wp-plugin-directory-guidelines	GPL compliance, naming, slug rules for WP.org submission

---

Development

# Install dependencies
pnpm install

# Run in dev mode
pnpm dev

# Type-check
pnpm check

# Lint & format
pnpm lint:check
pnpm format

# Run tests
pnpm test:run

# Build for distribution
pnpm build

# Full pre-publish check (build + lint + test)
pnpm prepublishOnly

---

Documentation

• CLI_REVIEW.md — Initial architecture review and design decisions
• CHANGELOG.md — Version history and release notes
• AGENTS.md — Agent instructions for this repository

---

Credits

• AgentSkills.io — The agent skills specification
• AGENTS.md — The agent configuration standard
• WordPress/agent-skills — Upstream skills repository