@ai-kits/wp-ag-kit 1.0.0

package/ANTIGRAVITY-README.md

@@ -0,0 +1,47 @@
+# Antigravity Agent Kit
+
+A global CLI tool to easily install and use WordPress agent skills in your Antigravity IDE projects.
+
+## Installation
+
+```bash
+npm install -g /path/to/this/agent-skills
+# or from a published package:
+npm install -g antigravity-agent-kit
+```
+
+## Usage
+
+### Initialize a project
+
+```bash
+cd your-antigravity-project
+ag-agent init
+```
+This creates a `.agent` folder and copies all available skills, agents, workflows, and rules from this kit into your project.
+
+### List available items
+
+```bash
+ag-agent list-skills
+ag-agent list-agents
+```
+
+### Check installed items
+
+```bash
+ag-agent list-installed
+```
+
+## How it works
+- **Skills**: Portable instruction modules for specific WordPress tasks.
+- **Agents**: Specialized AI personas (e.g., WordPress Expert, Frontend Expert).
+- **Workflows**: Semi-automated procedures for common tasks (e.g., linting, block creation).
+- **Rules**: Global behavior guidelines (GEMINI.md) optimized for WordPress development.
+
+## Contributing
+See the main README for details on authoring and contributing skills.
+
+---
+
+For more details, see the main [README.md](README.md).

package/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to Agent Skills
+
+We welcome contributions! This project is a great opportunity to share your WordPress expertise with the community in a unique way.
+
+## Why Contribute Here?
+
+**You don't need to be a coding wizard.** Unlike typical open source projects, Agent Skills is primarily about capturing *knowledge* and *best practices* in a structured format. If you understand WordPress deeply—whether that's block development, performance optimization, plugin security, or any other domain—you can make a meaningful contribution.
+
+Most of our skills are written in Markdown. The "code" is mostly procedural checklists, decision trees, and reference documentation. If you can explain a WordPress concept clearly, you can contribute here.
+
+## Ways to Contribute
+
+### 1. Improve Existing Skills
+
+The easiest way to start:
+
+- **Fix outdated information** — WordPress evolves quickly. If you spot something that's changed, open a PR.
+- **Add missing edge cases** — Did you hit a gotcha that isn't documented? Add it to the "Failure modes" section.
+- **Clarify procedures** — If a step confused you, it'll confuse others. Make it clearer.
+- **Expand references** — Add deeper documentation on specific topics.
+
+### 2. Create New Skills
+
+Have expertise in a WordPress area we don't cover yet? Consider adding a new skill.
+
+Before starting:
+1. Check [existing skills](skills/) to avoid overlap
+2. Review the [Authoring Guide](docs/authoring-guide.md) for structure requirements
+3. Open an issue to discuss scope (optional but recommended for larger skills)
+
+Scaffold a new skill:
+
+```bash
+node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"
+```
+
+### 3. Add Evaluation Scenarios
+
+Every skill needs test scenarios under `eval/scenarios/`. These are simple markdown files describing:
+- A realistic prompt/task
+- What the AI should do
+- How to verify it worked
+
+This is a great low-barrier contribution—you're essentially writing "what should happen when someone asks X?"
+
+### 4. Report Issues
+
+Found a skill giving bad advice? AI following a procedure that doesn't work? Open an issue with:
+- Which skill
+- What went wrong
+- What the correct behavior should be
+
+## Skill Structure
+
+Each skill follows this structure:
+
+```
+skills/<skill-name>/
+├── SKILL.md              # Main instructions (short, procedural)
+├── references/           # Deep-dive docs on specific topics
+│   └── *.md
+└── scripts/              # Deterministic helpers (optional)
+    └── *.mjs
+```
+
+### SKILL.md Requirements
+
+Every `SKILL.md` needs:
+
+1. **YAML frontmatter** with `name`, `description`, and `compatibility`
+2. **When to use** — Conditions that trigger this skill
+3. **Inputs required** — What the AI needs to gather first
+4. **Procedure** — Step-by-step checklist
+5. **Verification** — How to confirm it worked
+6. **Failure modes / debugging** — Common problems and fixes
+7. **Escalation** — When to ask for human help
+
+See any existing skill for examples.
+
+## Guidelines
+
+### Keep It Practical
+
+- Focus on what developers actually need to do
+- Include concrete examples, not abstract theory
+- Link to official docs for deep dives
+
+### Keep It Current
+
+- Target WordPress 6.9+ and PHP 7.2.24+
+- Avoid legacy patterns (Classic themes, pre-Gutenberg APIs)
+- Update compatibility frontmatter when requirements change
+
+### Keep It Testable
+
+- Add at least one eval scenario for new skills
+- Run `node eval/harness/run.mjs` before submitting
+
+### Keep It Small
+
+- Prefer small, focused skills over mega-skills
+- Keep `SKILL.md` short—push depth into `references/`
+- One skill should do one thing well
+
+## Submitting Changes
+
+1. Fork the repo
+2. Create a branch (`git checkout -b improve-block-dev-skill`)
+3. Make your changes
+4. Run validation: `node eval/harness/run.mjs`
+5. Commit with a clear message
+6. Open a pull request
+
+For significant changes, consider opening an issue first to discuss the approach.
+
+## Questions?
+
+Open an issue or start a discussion. We're happy to help you get started.
+
+---
+
+*Your WordPress knowledge can help thousands of developers get better AI assistance. Thank you for contributing!*

package/README.md

@@ -0,0 +1,135 @@
+# WordPress Antigravity Kit
+
+**Complete WordPress development environment for Antigravity IDE**
+
+[![npm version](https://img.shields.io/npm/v/@ai-kits/wp-ag-kit.svg)](https://www.npmjs.com/package/@ai-kits/wp-ag-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Quick Install
+
+```bash
+# Quick start with npx (no installation needed)
+npx @ai-kits/wp-ag-kit init
+
+# Or install globally
+npm install -g @ai-kits/wp-ag-kit
+wpag init
+```
+
+## 📦 What You Get
+
+This kit provides a complete WordPress development environment for Antigravity IDE:
+
+- **13 WordPress Skills** - Expert instruction modules for blocks, themes, plugins, performance, and more
+- **2 Specialized Agents** - WordPress Expert and Frontend Expert AI personas
+- **2 Workflows** - Automated linting and block creation procedures
+- **Global Rules** - GEMINI.md for consistent, high-quality behavior
+- **Shared Resources** - WordPress/Gutenberg version maps and utility scripts
+
+## 💡 Usage
+
+### Initialize Your Project
+
+```bash
+cd your-wordpress-project
+wpag init
+```
+
+This creates a `.agent/` folder with:
+```
+.agent/
+├── agents/          # AI personas specialized for WordPress
+├── workflows/       # Semi-automated task procedures
+├── rules/          # Global behavior guidelines
+├── skills/         # 13 WordPress instruction modules
+└── shared/         # Version maps and utilities
+```
+
+### Available Commands
+
+```bash
+wpag init              # Initialize .agent folder
+wpag list-skills       # Show available skills
+wpag list-agents       # Show available agents
+wpag list-installed    # Show what's in your project
+wpag use-skill <name>  # Add a specific skill
+wpag help              # Show help
+```
+
+## 📚 Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `wp-project-triage` | Automatic project detection and classification |
+| `wp-block-development` | Gutenberg block creation and management |
+| `wp-block-themes` | Block theme development with theme.json |
+| `wp-plugin-development` | Plugin architecture, hooks, and security |
+| `wp-rest-api` | REST API endpoints and controllers |
+| `wp-interactivity-api` | Frontend interactivity with data-wp-* directives |
+| `wp-abilities-api` | Capability-based permissions |
+| `wp-wpcli-and-ops` | WP-CLI automation and operations |
+| `wp-performance` | Backend performance profiling and optimization |
+| `wp-phpstan` | Static analysis with PHPStan |
+| `wp-playground` | WordPress Playground workflows |
+| `wpds` | WordPress Design System |
+| `wordpress-router` | Smart project routing |
+
+## 🤖 Specialized Agents
+
+### WordPress Expert
+Master WordPress developer that uses all 13 skills for comprehensive WordPress development.
+
+### WordPress Frontend Expert
+Specialist for Block Themes, Interactivity API, and modern WordPress UI/UX.
+
+## 🔄 Workflows
+
+- `/wp-lint` - Run WordPress-specific linting (PHPStan + @wordpress/scripts)
+- `/create-block` - Scaffold a new Gutenberg block
+
+## 🎯 Requirements
+
+- Node.js 16 or higher
+- WordPress 6.9+ (for skills compatibility)
+- PHP 7.2.24+ (for WordPress compatibility)
+
+## 📖 Documentation
+
+- [Complete Structure Guide](./STRUCTURE.md) - Detailed breakdown of all components
+- [Contributing Guide](./CONTRIBUTING.md) - How to add skills or improve the kit
+- [Antigravity README](./ANTIGRAVITY-README.md) - Kit-specific documentation
+
+## 🛠️ Development
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/wp-ag-kit.git
+cd wp-ag-kit/agent-skills
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build distribution
+npm run build
+```
+
+## 🤝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+MIT © Anikesh Kumar
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/@ai-kits/wp-ag-kit)
+- [GitHub Repository](https://github.com/ai-kits/wp-ag-kit)
+- [Issues](https://github.com/ai-kits/wp-ag-kit/issues)
+
+---
+
+**Made with ❤️ for the WordPress and Antigravity communities**

package/STRUCTURE.md

@@ -0,0 +1,200 @@
+# WordPress Antigravity Kit - Complete Structure
+
+## 📦 What Gets Installed
+
+When a user runs `ag-agent init`, the following complete structure is copied to their project's `.agent/` folder:
+
+```
+.agent/
+├── agents/              ✅ WordPress-specialized AI personas
+├── workflows/           ✅ Semi-automated task procedures
+├── rules/               ✅ Global behavior guidelines (GEMINI.md)
+├── skills/              ✅ 13 WordPress instruction modules
+└── shared/              ✅ Common resources and utilities
+    ├── references/      ✅ Version maps and data files
+    └── scripts/         ✅ Build and maintenance scripts
+```
+
+---
+
+## 📂 Kit Components Breakdown
+
+### 1. **Skills** (13 WordPress-specific modules)
+Located in: `skills/`
+
+Each skill contains:
+- `SKILL.md` - Main instruction file with procedures
+- `references/` - Deep-dive documentation
+- `scripts/` - Deterministic helper scripts (Node.js)
+
+**Available Skills:**
+1. `wordpress-router` - Project classification and routing
+2. `wp-project-triage` - Automatic project detection
+3. `wp-block-development` - Gutenberg block creation
+4. `wp-block-themes` - Block theme development
+5. `wp-plugin-development` - Plugin architecture and security
+6. `wp-rest-api` - REST API endpoints and controllers
+7. `wp-interactivity-api` - Frontend interactivity (data-wp-*)
+8. `wp-abilities-api` - Capability-based permissions
+9. `wp-wpcli-and-ops` - WP-CLI automation
+10. `wp-performance` - Backend performance profiling
+11. `wp-phpstan` - Static analysis configuration
+12. `wp-playground` - WordPress Playground workflows
+13. `wpds` - WordPress Design System
+
+---
+
+### 2. **Agents** (Specialized AI Personas)
+Located in: `agents/`
+
+**Current Agents:**
+- `wordpress-expert.md` - Master WordPress developer (uses all 13 skills)
+- `wp-frontend-expert.md` - Block Theme and Interactivity specialist
+
+**Agent Structure:**
+```yaml
+---
+name: agent-name
+description: "What this agent specializes in"
+skills:
+  - skill-1
+  - skill-2
+---
+# Agent behavior and guidelines
+```
+
+---
+
+### 3. **Workflows** (Semi-Automated Procedures)
+Located in: `workflows/`
+
+**Current Workflows:**
+- `/wp-lint` - Run WordPress linting (PHPStan + @wordpress/scripts)
+- `/create-block` - Scaffold a new Gutenberg block
+
+**Workflow Features:**
+- `// turbo` annotations for auto-executable steps
+- Step-by-step guidance
+- Integration with skills
+
+---
+
+### 4. **Rules** (Global Behavior)
+Located in: `rules/`
+
+**File:** `GEMINI.md`
+
+Contains:
+- Agent routing protocol
+- Socratic questioning gates
+- Clean code standards
+- Project type routing
+- Testing and deployment rules
+
+This ensures consistent, high-quality behavior across all WordPress projects.
+
+---
+
+### 5. **Shared Resources**
+Located in: `shared/`
+
+#### `shared/references/`
+Version mapping data for WordPress and Gutenberg:
+- `wordpress-core-versions.json` - WordPress release data
+- `gutenberg-releases.json` - Gutenberg plugin versions
+- `wp-gutenberg-version-map.json` - Core ↔ Gutenberg mapping
+
+#### `shared/scripts/`
+Maintenance and build utilities:
+- `scaffold-skill.mjs` - Create new skills
+- `skillpack-build.mjs` - Build distribution packages
+- `skillpack-install.mjs` - Install skills to projects
+- `ai-generate-updates.mjs` - AI-assisted updates
+- `update-upstream-indices.mjs` - Sync version data
+
+---
+
+## 🔧 Development Components (Not Installed to User Projects)
+
+These remain in the kit repository for development and testing:
+
+### **eval/** - Evaluation and Testing
+- `eval/harness/run.mjs` - Skill validation runner
+- `eval/scenarios/` - Test scenarios for each skill
+
+### **docs/** - Documentation
+- `authoring-guide.md` - How to create skills
+- `principles.md` - Design philosophy
+- `packaging.md` - Distribution guidelines
+- `compatibility-policy.md` - Version targeting
+
+### **dist/** - Build Output
+Generated by `skillpack-build.mjs`:
+- `dist/codex/` - For OpenAI Codex
+- `dist/vscode/` - For VS Code / GitHub Copilot
+- `dist/claude/` - For Claude Code
+
+### **bin/** - CLI Tool
+- `bin/antigravity-agent.js` - The `ag-agent` command
+
+---
+
+## ✅ What's Included vs. What's Not
+
+| Component | Installed to User Projects | Purpose |
+|-----------|---------------------------|---------|
+| **skills/** | ✅ Yes | WordPress instruction modules |
+| **agents/** | ✅ Yes | AI personas for specialized tasks |
+| **workflows/** | ✅ Yes | Semi-automated procedures |
+| **rules/** | ✅ Yes | Global behavior (GEMINI.md) |
+| **shared/references/** | ✅ Yes | Version maps and data |
+| **shared/scripts/** | ✅ Yes | Build and utility scripts |
+| **eval/** | ❌ No | Testing framework (dev only) |
+| **docs/** | ❌ No | Authoring guides (dev only) |
+| **dist/** | ❌ No | Build artifacts (dev only) |
+| **bin/** | ❌ No | CLI is globally installed |
+
+---
+
+## 🚀 Usage Flow
+
+1. **User installs the kit globally:**
+   ```bash
+   npm install -g /path/to/wp-ag-kit
+   ```
+
+2. **User initializes their WordPress project:**
+   ```bash
+   cd my-wordpress-plugin
+   ag-agent init
+   ```
+
+3. **Kit copies everything needed:**
+   - All 13 skills → `.agent/skills/`
+   - 2 agents → `.agent/agents/`
+   - 2 workflows → `.agent/workflows/`
+   - GEMINI.md → `.agent/rules/`
+   - Shared resources → `.agent/shared/`
+
+4. **Antigravity IDE automatically discovers:**
+   - Skills from `.agent/skills/`
+   - Agents from `.agent/agents/`
+   - Workflows from `.agent/workflows/`
+   - Rules from `.agent/rules/`
+
+---
+
+## 🎯 Summary
+
+**YES, everything is used and properly integrated:**
+
+✅ **Skills** - All 13 WordPress modules are copied and functional  
+✅ **Agents** - WordPress Expert and Frontend Expert personas  
+✅ **Workflows** - Linting and block creation procedures  
+✅ **Rules** - GEMINI.md for consistent behavior  
+✅ **Shared** - Version maps and utility scripts  
+✅ **Eval** - Testing harness (for kit development)  
+✅ **Docs** - Authoring guides (for contributors)  
+✅ **Bin** - CLI tool (`ag-agent` command)  
+
+Your kit is **complete and self-contained**. Users get everything they need for professional WordPress development in Antigravity IDE!

package/agents/wordpress-expert.md

@@ -0,0 +1,36 @@
+---
+name: wordpress-expert
+description: "Expert WordPress developer specializing in Block Editor, Plugins, Themes, and Performance."
+skills:
+  - wp-project-triage
+  - wp-block-development
+  - wp-block-themes
+  - wp-plugin-development
+  - wp-rest-api
+  - wp-interactivity-api
+  - wp-abilities-api
+  - wp-wpcli-and-ops
+  - wp-performance
+  - wp-phpstan
+  - wp-playground
+  - wpds
+---
+
+# WordPress Expert Agent
+
+I am a specialized agent for WordPress development. I follow modern WordPress standards (Gutenberg, Block Themes, Interactivity API) and ensure security and performance.
+
+## Core Directives
+
+1. **Triage First**: Always run `wp-project-triage` to understand the project structure and tooling.
+2. **Block-First**: Prefer Block Themes and Gutenberg blocks over classic PHP templates when appropriate.
+3. **Security**: Always escape output, validate/sanitize input, and use nonces for all actions.
+4. **Performance**: Use `wp-performance` to audit and optimize data fetching and database queries.
+5. **Modern Build**: Use `@wordpress/scripts` and `block.json` for block development.
+
+## Specialized Skills
+
+- **Blocks**: I can build complex nested blocks with `wp-block-development`.
+- **Interactivity**: I use the Interactivity API for high-performance frontend behavior.
+- **Ops**: I use WP-CLI for automation and site management.
+- **Testing**: I use PHPStan and Playwright for quality assurance.

package/agents/wp-frontend-expert.md

@@ -0,0 +1,21 @@
+---
+name: wp-frontend-expert
+description: "WordPress frontend specialist focused on Interactivity API, Block Themes, and modern UI/UX."
+skills:
+  - wp-block-themes
+  - wp-interactivity-api
+  - wpds
+  - frontend-design
+  - tailwind-patterns
+---
+
+# WordPress Frontend Expert
+
+I specialize in building stunning, high-performance WordPress frontends. I leverage the Interactivity API for dynamic features without the bloat of traditional jQuery-based solutions.
+
+## Guidelines
+
+1. **Interactivity API**: Use `data-wp-*` directives for custom interactive components.
+2. **WPDS**: Use the WordPress Design System components and tokens whenever possible to maintain native feel.
+3. **Theme JSON**: Use `theme.json` for global styles and settings to ensure consistency across the Site Editor.
+4. **Performance**: Optimize LCP and CLS by avoiding heavy scripts and using native WordPress image optimizations.