wordpress-agent-kit 0.2.1 → 0.2.2

package/dist/utils/run.js

@@ -11,7 +11,7 @@ export function run(command, args, cwd = process.cwd()) {
     const result = spawnSync(command, args, {
         cwd,
         stdio: 'inherit',
-        shell: process.platform === 'win32'
+        shell: process.platform === 'win32',
     });
     if (result.status !== 0) {
         console.error(`Command failed with status ${result.status}: ${command} ${args.join(' ')}`);

package/kit-learnings.md

@@ -0,0 +1,192 @@
+# WordPress Agent Kit - Installation & Usage Learnings
+
+**Package:** `wordpress-agent-kit@0.2.1` (published on npm)
+**Author:** Kyle Brodeur
+**Repo:** https://github.com/kylebrodeur/wordpress-agent-kit
+
+---
+
+## Quick Start (What Actually Works)
+
+### For Pi (Recommended)
+```bash
+pnpm dlx wordpress-agent-kit@latest install --platform pi
+```
+- Installs skills to `.pi/agent/skills/` (17 skills)
+- Non-interactive, no TTY needed
+- Works in headless/CI environments
+
+### For Other Platforms
+```bash
+# GitHub Copilot / VS Code
+pnpm dlx wordpress-agent-kit@latest install --platform github
+
+# Cursor IDE
+pnpm dlx wordpress-agent-kit@latest install --platform cursor
+
+# Generic agent format
+pnpm dlx wordpress-agent-kit@latest install --platform agent
+
+# Claude (interactive - requires TTY)
+pnpm dlx wordpress-agent-kit@latest install --platform claude
+```
+
+---
+
+## What DOESN'T Work (Common Pitfalls)
+
+### `setup` command requires TTY
+```bash
+pnpm dlx wordpress-agent-kit@latest setup  # FAILS in non-interactive shells
+```
+**Error:** `ERR_TTY_INIT_FAILED: uv_tty_init returned EINVAL (invalid argument)`
+
+The `setup` command uses `@clack/prompts` for interactive prompts, which requires a real TTY. It fails in:
+- CI/CD pipelines
+- Docker containers without `-it`
+- Non-interactive SSH sessions
+- Most AI agent execution environments
+
+**Workaround:** Use `install --platform <platform>` instead.
+
+---
+
+## Platform Comparison
+
+| Platform | Target Dir | Interactive? | Best For |
+|----------|------------|--------------|----------|
+| `pi` | `.pi/agent/skills/` | ❌ No | **Pi Coding Agent** (this project) |
+| `github` | `.github/skills/` | ❌ No | GitHub Copilot, VS Code |
+| `cursor` | `.cursor/skills/` | ❌ No | Cursor IDE |
+| `agent` | `.agent/skills/` | ❌ No | Generic `.agent` workflows |
+| `claude` | `.claude/skills/` | ✅ Yes | Claude Code (interactive only) |
+
+---
+
+## Skills Installed (17 Total)
+
+All synced from `WordPress/agent-skills` trunk:
+
+1. `wp-abilities-api` - Abilities API registration & consumption
+2. `wp-abilities-audit` - Audit plugin REST surface for Abilities
+3. `wp-abilities-verify` - Verify Abilities registrations
+4. `wp-block-development` - Gutenberg blocks: block.json, attributes, rendering
+5. `wp-block-themes` - Block themes: theme.json, templates, patterns
+6. `wp-interactivity-api` - data-wp-* directives & stores
+7. `wp-performance` - Profiling, caching, DB optimization
+8. `wp-phpstan` - PHPStan config for WordPress
+9. `wp-playground` - WordPress Playground for instant environments
+10. `wp-plugin-development` - Plugin architecture, hooks, Settings API, security
+11. `wp-plugin-directory-guidelines` - WP Plugin Directory requirements
+12. `wp-project-triage` - Auto-detect project type, tooling, versions
+13. `wp-rest-api` - REST API routes, schema, auth, response shaping
+14. `wp-wpcli-and-ops` - WP-CLI commands, automation, multisite
+15. `wpds` - WordPress Design System
+16. `blueprint` - Playground Blueprints for declarative setup
+17. `wordpress-router` - Classifies WP repos, routes to right workflow
+
+---
+
+## Verification Commands
+
+After installation, verify everything works:
+
+```bash
+# 1. Check skills installed
+ls -la .pi/agent/skills/
+
+# 2. Run project triage (detects WP project type)
+node .pi/agent/skills/wp-project-triage/scripts/detect_wp_project.mjs
+
+# 3. Run design-system tests (if applicable)
+cd design-system && pnpm test && pnpm run typecheck
+
+# 4. PHP syntax check
+find wpaos wpaos-blocks -name '*.php' -exec php -l {} \;
+```
+
+---
+
+## Key Files & Locations
+
+```
+wordpress-agent-kit/
+├── package.json                 # Package definition (name: wordpress-agent-kit)
+├── src/
+│   ├── cli.ts                   # Main CLI entry
+│   ├── commands/
+│   │   ├── install.ts           # Non-interactive install (USE THIS)
+│   │   ├── setup.ts             # Interactive setup (NEEDS TTY)
+│   │   ├── sync-skills.ts       # Pulls from WordPress/agent-skills
+│   │   └── playground.ts        # Local WP Playground
+│   └── utils/
+│       └── platforms.ts         # Platform definitions (pi, github, cursor, agent, claude)
+├── dist/bundles/                # Pre-built tarballs (legacy method)
+└── vendor/wp-agent-skills/      # Synced upstream skills (gitignored)
+```
+
+---
+
+## Syncing Latest Upstream Skills
+
+The kit bundles skills at release time. To get latest:
+
+```bash
+# From kit repo (if contributing)
+pnpm sync:skills
+pnpm build:bundles
+
+# Or just reinstall (pulls latest from npm)
+pnpm dlx wordpress-agent-kit@latest install --platform pi --force
+```
+
+---
+
+## Integration with This Project (wp-agent-os)
+
+### AGENTS.md References
+The project's `AGENTS.md` still references `.github/skills/` but we use `.pi/agent/skills/`. The skills are the same - just different install locations.
+
+### wp-abilities-api Verification
+Verified that `wpaos/includes/abilities.php` uses correct arg keys per the skill:
+- `label`, `description`, `category`, `input_schema`, `output_schema`
+- `permission_callback`, `execute_callback`, `meta`
+- `meta.show_in_rest: true`, `meta.mcp.public: true`
+
+### CI/CD Usage
+```yaml
+# GitHub Actions example
+- name: Install WordPress Agent Kit
+  run: pnpm dlx wordpress-agent-kit@latest install --platform github
+```
+
+---
+
+## Troubleshooting
+
+### "Command not found" / 404 on npm
+- Package name is `wordpress-agent-kit` (NOT `wp-agent-kit`)
+- Published to npm as `kylebrodeur` scope would be `@kylebrodeur/wordpress-agent-kit` but it's unscoped
+
+### Skills not showing up
+- Check install location matches your agent's config (`.pi/agent/skills/` for Pi)
+- Run with `--force` to overwrite existing
+
+### Old placeholder skills remain
+- Delete old skill directories before reinstall:
+  ```bash
+  rm -rf .claude/skills .github/skills .cursor/skills .agent/skills
+  pnpm dlx wordpress-agent-kit@latest install --platform pi
+  ```
+
+---
+
+## Summary: Recommended Workflow for This Project
+
+```bash
+# One-liner for clean install in any environment
+rm -rf .claude/skills .github/skills .cursor/skills .agent/skills .pi/agent/skills && \
+pnpm dlx wordpress-agent-kit@latest install --platform pi
+```
+
+Then the skills live in `.pi/agent/skills/` and are available to Pi automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress-agent-kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "WordPress-focused AGENTS.md + Agent Skills starter kit for AI coding agents.",
   "license": "GPL-2.0-or-later",
   "author": "Kyle Brodeur <kyle@brodeur.me> (https://brodeur.me)",
@@ -26,10 +26,12 @@
     "commander": "^13.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "1.9.4",
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.1",
     "@vitest/coverage-v8": "^2.1.8",
     "eslint": "^9.16.0",
+    "husky": "^9.1.6",
     "prettier": "^3.4.1",
     "ts-node": "^10.9.2",
     "tsx": "^4.19.2",
@@ -42,7 +44,10 @@
     "dev": "tsx src/cli.ts",
     "build": "tsc",
     "check": "tsc --noEmit",
-    "lint": "eslint src/ --fix",
+    "lint": "eslint src/ tests/ --fix && biome check --write .",
+    "lint:check": "eslint src/ tests/ && biome check .",
+    "format": "prettier --write . && biome format --write .",
+    "format:check": "prettier --check . && biome format --check .",
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",