wordpress-agent-kit 0.2.1 → 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/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm run format:check
+
+      - name: Run lint
+        run: pnpm run lint:check
+
+      - name: Type check
+        run: pnpm run check
+
+      - name: Run tests
+        run: pnpm run test:run
+
+      - name: Build
+        run: pnpm run build

package/.husky/pre-commit

@@ -0,0 +1,7 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+pnpm exec biome check --write .
+git add -A
+pnpm run lint:check
+pnpm run test:run

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

package/CLI_REVIEW.md

@@ -0,0 +1,250 @@
+# WordPress Agent Kit CLI - Accessibility & Agent-Friendly Review
+
+**Date**: 2026-06-08  
+**Version**: 0.2.1
+
+---
+
+## Executive Summary
+
+The current CLI is functional for **human developers** using interactive prompts (`@clack/prompts`), but lacks features for **programmatic/agent usage**:
+
+- ❌ No JSON output mode
+- ❌ No machine-readable result objects
+- ❌ No programmatic API (only CLI entrypoint)
+- ❌ No non-interactive "headless" mode for all commands
+- ❌ No structured logging/event streaming
+- ❌ Exit codes not consistently semantic
+
+---
+
+## Current Architecture
+
+```
+src/
+├── cli.ts                    # Entry point, Commander setup
+├── commands/
+│   ├── install.ts           # Non-interactive (args + flags only) ✓
+│   ├── setup.ts             # Interactive (prompts only) ✗
+│   ├── sync-skills.ts       # Non-interactive (args + flags only) ✓
+│   └── run-playground.ts    # Non-interactive ✓
+├── lib/
+│   ├── installer.ts         # Core logic (pure functions) ✓
+│   └── triage-mapper.ts     # Pure mappers ✓
+└── utils/
+    ├── paths.ts             # Path resolution
+    └── run.ts              # Command runner
+```
+
+**Good**: Core logic (`installKit`, mappers) is pure and testable.  
+**Gap**: `setup.ts` couples interactive prompts with business logic.
+
+---
+
+## Recommendations
+
+### 1. Add JSON Output Mode (--json)
+
+**Goal**: Every command outputs structured JSON to stdout when requested.
+
+```bash
+# Success
+wp-agent-kit install /path/to/project --platform github --json
+# {"success":true,"targetDir":"/path/to/project","platform":"github","filesCopied":["AGENTS.md",".github/..."],"durationMs":142}
+
+# Failure
+wp-agent-kit install /nonexistent --json
+# {"success":false,"error":"E_NOT_FOUND","message":"Target directory does not exist","code":"ENOENT"}
+```
+
+**Implementation**:
+- Add `--json` / `--output json` global flag in `cli.ts`
+- Create `OutputFormatter` utility: `json`, `human`, `quiet`
+- Return structured result objects from all command actions
+- Separate stdout (JSON) from stderr (human diagnostics)
+
+### 2. Add Machine-Readable Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments / usage |
+| 3 | Target not found / ENOENT |
+| 4 | Permission denied / EACCES |
+| 5 | Already exists (without --force) |
+| 6 | Git/submodule error |
+| 7 | Network/fetch error |
+| 8 | Validation failed |
+| 130 | Cancelled (SIGINT) |
+
+### 3. Extract Programmatic API
+
+Expose core functions for direct import by agents/scripts:
+
+```typescript
+// src/api.ts (new)
+export interface InstallOptions {
+  targetDir: string;
+  platform: Platform;
+  force?: boolean;
+  dryRun?: boolean;
+}
+
+export interface InstallResult {
+  success: boolean;
+  targetDir: string;
+  platform: Platform;
+  filesCreated: string[];
+  filesSkipped: string[];
+  errors: string[];
+  durationMs: number;
+}
+
+export async function installKit(options: InstallOptions): Promise<InstallResult>;
+export async function syncSkills(options: SyncOptions): Promise<SyncResult>;
+export async function runTriage(targetDir: string): Promise<TriageResult>;
+export async function configureAgentsMd(options: ConfigureOptions): Promise<ConfigureResult>;
+```
+
+**Benefits**:
+- Agents can import and call directly: `import { installKit } from 'wordpress-agent-kit'`
+- No subprocess overhead
+- Full TypeScript types
+- Testable in isolation
+
+### 4. Make `setup` Command Headless-Capable
+
+Current `setup.ts` is prompt-driven. Add non-interactive mode:
+
+```bash
+# Full non-interactive (requires all flags)
+wp-agent-kit setup /path/to/project \
+  --project-type plugin \
+  --tech-stack gutenberg,rest-api,composer \
+  --platform github \
+  --yes \
+  --json
+
+# Hybrid: run triage, apply detected values, no prompts
+wp-agent-kit setup /path/to/project --auto --json
+```
+
+**Flag Matrix for `setup`**:
+| Flag | Description |
+|------|-------------|
+| `--project-type <type>` | plugin \| theme \| block-theme \| site \| blocks \| other |
+| `--tech-stack <list>` | Comma-separated: gutenberg,interactivity,rest-api,wpcli,composer,phpstan,npm,playground |
+| `--platform <platform>` | github \| cursor \| claude \| agent \| pi |
+| `--package-manager <pm>` | npm \| pnpm \| yarn |
+| `--auto` | Run triage, apply detected values, skip prompts |
+| `--yes` / `-y` | Accept all confirmations (requires other flags) |
+| `--reset` | Overwrite existing |
+| `--dry-run` | Show what would be done |
+
+### 5. Add Structured Logging / Event Stream
+
+For long-running operations (sync-skills, playground), emit NDJSON events:
+
+```bash
+wp-agent-kit sync-skills --json-stream
+# {"event":"start","phase":"clone","timestamp":"..."}
+# {"event":"progress","phase":"fetch","message":"Fetching tags...","timestamp":"..."}
+# {"event":"complete","phase":"install","result":{"skillsSynced":42,"timestamp":"..."}}
+```
+
+**Events**: `start`, `progress`, `phase-change`, `warning`, `complete`, `error`
+
+### 6. Add Dry-Run / Preview Mode
+
+```bash
+wp-agent-kit install /path --dry-run --json
+# {"wouldCopy":[{"src":"AGENTS.template.md","dest":"/path/AGENTS.md"},{"src":".github/...","dest":"/path/.github/..."}],"wouldCreateDirs":[]}
+
+wp-agent-kit setup /path --dry-run --auto --json
+# {"wouldInstall":true,"detectedType":"plugin","detectedTech":["gutenberg","npm"],"wouldModify":["AGENTS.md"]}
+```
+
+### 7. Add Shell Completion (Modern CLI Standard)
+
+```bash
+# Generate completion scripts
+wp-agent-kit completion bash > /etc/bash_completion.d/wp-agent-kit
+wp-agent-kit completion zsh > ~/.zsh/completions/_wp-agent-kit
+wp-agent-kit completion fish > ~/.config/fish/completions/wp-agent-kit.fish
+```
+
+Commander.js supports this natively: `program.enablePositionalOptions().addHelpCommand().configureOutput({ writeOut: ... })`
+
+### 8. Add `--version` JSON Output
+
+```bash
+wp-agent-kit --version --json
+# {"name":"wp-agent-kit","version":"0.2.1","node":"20.18.0","platform":"linux"}
+```
+
+---
+
+## Priority Matrix
+
+| Priority | Feature | Effort | Impact |
+|----------|---------|--------|--------|
+| **P0** | JSON output (`--json`) | Low | High |
+| **P0** | Semantic exit codes | Low | High |
+| **P0** | Programmatic API export | Medium | High |
+| **P1** | Headless `setup` mode | Medium | High |
+| **P1** | Dry-run/preview | Low | Medium |
+| **P2** | NDJSON event streaming | Medium | Medium |
+| **P2** | Shell completions | Low | Medium |
+| **P3** | Man page generation | Low | Low |
+
+---
+
+## Example: Agent-Friendly Workflow
+
+```bash
+# 1. Agent detects WordPress project
+wp-agent-kit setup /workspace/my-plugin --auto --json
+# {"success":true,"applied":{"projectType":"plugin","techStack":["gutenberg","npm"]},"filesModified":["AGENTS.md"]}
+
+# 2. Agent syncs latest skills
+wp-agent-kit sync-skills --json
+# {"success":true,"skillsSynced":47,"source":"WordPress/agent-skills@trunk"}
+
+# 3. Agent installs for specific platform (e.g., Cursor)
+wp-agent-kit install /workspace/my-plugin --platform cursor --json
+# {"success":true,"platform":"cursor","targetDir":"/workspace/my-plugin","filesCreated":[".cursor/...","AGENTS.md"]}
+```
+
+---
+
+## Implementation Notes
+
+### Minimal Changes for P0
+
+1. **cli.ts**: Add global `--json` flag, result formatter
+2. **commands/*.ts**: Return structured results instead of `process.exit()`
+3. **lib/installer.ts**: Return `InstallResult` object (already close)
+4. **package.json**: Add `"exports": { ".": "./dist/cli.js", "./api": "./dist/api.js" }`
+
+### Testing Strategy
+
+```typescript
+// tests/api/install.api.test.ts
+import { installKit } from '../../src/api.js';
+
+it('returns structured result on success', async () => {
+  const result = await installKit({ targetDir: '/tmp/test', platform: 'github' });
+  expect(result.success).toBe(true);
+  expect(result.filesCreated).toContain('AGENTS.md');
+});
+```
+
+---
+
+## References
+
+- [Commander.js JSON output patterns](https://github.com/tj/commander.js/blob/master/Examples/options-json.ts)
+- [CLI Guidelines - Output](https://clig.dev/#output)
+- [12-factor CLI apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)
+- [GitHub CLI `gh` JSON patterns](https://cli.github.com/manual/gh_help_formatting)