Purpose: Route requests to the best agents, enforce predictable workflows, and produce consistent deliverables.
This index serves as the central router for the wp-dev-prompts agent library. It:
- Classifies incoming requests by domain and risk level
- Selects optimal agent teams (3–6 agents preferred)
- Enforces phase-based execution: Plan → Implement → Verify → Document
- Produces artifacts that meet the Output Contract
- Resolves conflicts between competing concerns
- Start with Orchestrators — Always consider qa-director for quality gates
- Add Primary Specialists — Based on task category (1–2 per domain)
- Add Supporting Agents — Only for missing outputs (reports, fixtures, CI)
- Keep Teams Lean — 3–6 agents unless work clearly spans more domains
- Run Phases — Plan → Implement → Verify → Document
| Agent | Owns | When Required |
|---|---|---|
| qa-director | Quality gates, test matrix, PR/nightly/release strategy | Any change affecting tests or gates |
| repo-template-architect | Structure, profiles, commands, template consistency | Structural changes, new project setup |
| test-architecture | Test boundaries, fixtures, mocks, determinism | Test infrastructure changes |
| risk-manager | Risk register, threat model, prioritization | High-risk changes, security, data handling |
Primary Agents:
- unit-testing — Isolated PHP unit tests with WP_Mock
- integration-testing — Tests against real WordPress
- e2e-playwright — Browser automation and user flows
- regression-suite-curator — Regression test organization
- visual-regression — Screenshot comparison testing
Supporting Agents:
- test-data-and-fixtures — Factories, seeds, fixtures
- flaky-test-tamer — Stabilizing unreliable tests
- reporting-and-artifacts — JUnit, coverage, traces
Mandatory Checks:
- Deterministic seeds and stable selectors
- Artifacts uploaded on failure
- Quarantine policy for flaky tests
- Test isolation (no shared state)
Primary Agents:
- a11y-tree-and-aria-auditor — Accessibility tree assertions
- keyboard-and-focus-specialist — Focus management, traps
- storybook-a11y-specialist — Component-level a11y
Supporting Agents:
- manual-a11y-protocol — Screen reader testing scripts
- i18n-l10n-rtl-specialist — RTL layout testing
Mandatory Checks:
- axe-core scans on all routes
- Explicit name/role/state assertions
- Focus trap testing for modals
- RTL run for critical routes
- Keyboard-only navigation validation
Primary Agents:
- threat-modeling — STRIDE analysis, attack surfaces
- wp-security-patterns — Nonces, caps, sanitization
- secrets-and-supply-chain — Gitleaks, dependency audit
Supporting Agents:
- pentest-playbook — Manual security testing
- security-advisory — Existing security specialist
Mandatory Checks:
- Nonce verification on all forms
- Capability checks before actions
- Input sanitization, output escaping
- Semgrep rules for WP patterns
- SARIF output for security findings
- SBOM generation for dependencies
Primary Agents:
- multisite-specialist — Network admin, site scoping
- i18n-l10n-rtl-specialist — Translations, RTL
Supporting Agents:
- data-model-and-migrations — Schema across sites
- visual-regression — RTL snapshots
Mandatory Checks:
- Network activation/uninstall hooks
get_optionvsget_site_optionusage- Super-admin capability boundaries
- Locale matrix tests per site
- RTL visual regression for critical screens
Primary Agents:
- performance — Existing performance specialist
- e2e-playwright — Lighthouse integration
Supporting Agents:
- packaging-and-dist-builder — Asset optimization
- reporting-and-artifacts — LHCI reports
Mandatory Checks:
- Performance budgets defined
- Cold and warm run measurements
- Lighthouse CI artifacts
- Core Web Vitals thresholds
Primary Agents:
- packaging-and-dist-builder — Build, bundle, exclude
- wporg-readme-and-assets — readme.txt, screenshots
- plugin-header-and-metadata — Version consistency
- release-manager — Release process, changelog
Supporting Agents:
- contributing-and-pr-gates — PR requirements
- reporting-and-artifacts — Release artifacts
Mandatory Checks:
- No dev files in distribution
- Version consistency across files
- Changelog entry for each release
- ZIP artifact creation and validation
Primary Agents:
- github-actions-architect — Workflow design
- linting-and-static-analysis — PHPCS, PHPStan, ESLint
- reporting-and-artifacts — Output formats
Supporting Agents:
- compatibility-matrix — PHP/WP version matrix
- flaky-test-tamer — CI stability
Mandatory Checks:
- Cache strategy for dependencies
- Job isolation (no cross-job state)
- Matrix design for versions
- Fast lane (PR) vs slow lane (nightly)
- Artifact retention policy
Primary Agents:
- data-model-and-migrations — Schema, upgrades
- backward-compatibility — Deprecation, BC breaks
Supporting Agents:
- integration-testing — Migration tests
- regression-suite-curator — Upgrade scenarios
Mandatory Checks:
- Upgrade-from-N-1 tests
- Idempotent migrations
- Deprecation policy documented
- Contract tests for data structures
Primary Agents:
- onboarding-and-quickstart — First-run experience
- makefile-justfile-designer — CLI commands
- documentation-quality-auditor — Docs validation
Supporting Agents:
- repo-template-architect — Structure consistency
Mandatory Checks:
- "One command" setup works
- Docs are executable (examples compile)
- README is current and accurate
Before selecting agents, classify the task:
| Signal | T1 | T2 | T3 |
|---|---|---|---|
| Files | 1-2 | 3-5 | 6+ |
| Existing tests | Yes | Partial | No |
| Risk | Low | Medium | High |
| Architecture change | No | Minor | Yes |
Tool Assignment:
- T1 (Routine): Copilot — inline suggestions, constrained scope
- T2 (Analytical): Cursor/ChatGPT — code review, refactoring analysis
- T3 (Complex): Claude Code — full-context, architecture decisions
Then proceed to Step 1.
- Code: New features, bug fixes, refactoring
- Tests: Test creation, test infrastructure
- CI: Workflow changes, job configuration
- Packaging: Build, release, distribution
- Security: Auth, data handling, secrets
- A11y: Accessibility improvements
- Perf: Performance optimization
- Multisite: Network-aware changes
- i18n: Localization, RTL
- Docs: Documentation updates
- Mixed: Spans multiple domains
| Level | Scope | Examples |
|---|---|---|
| Low | Formatting, docs, comments | README update, code style |
| Medium | Config, lint rules, minor features | ESLint config, new utility |
| High | Auth, data, REST, files, multisite, release | Login flow, database schema, API endpoints |
- Always include qa-director for anything affecting gates
- Add 1–2 primary specialists per domain involved
- Add supporting agents only for missing outputs
- Cap at 6 agents unless truly necessary
| Phase | Activities | Outputs |
|---|---|---|
| A: Plan | Analyze, checklist, acceptance criteria | Plan document |
| B: Implement | Write code, configs, tests | Source files |
| C: Verify | Run tests, validate gates | Test results, artifacts |
| D: Document | Update docs, handoff notes | Documentation |
When agents disagree, apply this priority order:
- Security > Performance > Accessibility > Correctness > DX > Style
- Multisite correctness > Single-site convenience
- Determinism > "Fast but flaky"
- Ship safe > "Ship fast"
| Conflict | Resolution |
|---|---|
| Performance vs Security | Security wins; optimize safely |
| Fast tests vs Thorough tests | Fast on PR, thorough on nightly |
| DX vs Correctness | Correctness wins; improve DX separately |
| New feature vs BC | Maintain BC; deprecate gracefully |
Every routed task must produce:
Primary Agents:
- agent-name: one-line justification
Supporting Agents:
- agent-name: one-line justification
- Files to create/modify (paths)
- Commands to add
- CI jobs to add
- Documentation to write
- What blocks PR merge
- What runs on nightly
- What runs on release-candidate
- Report locations (JUnit, SARIF, screenshots, traces, LHCI)
- Retention policy
- Upload conditions
- Local commands to validate
- CI validation steps
- Manual verification if needed
- What remains manual
- What may be noisy/flaky
- Known limitations
agents/
├── AGENT_INDEX.md # This file
├── orchestrators/
│ ├── qa-director.md
│ ├── repo-template-architect.md
│ ├── test-architecture.md
│ └── risk-manager.md
├── specialists/
│ ├── testing/
│ │ ├── unit-testing.md
│ │ ├── integration-testing.md
│ │ ├── e2e-playwright.md
│ │ ├── visual-regression.md
│ │ ├── regression-suite-curator.md
│ │ └── test-data-and-fixtures.md
│ ├── accessibility/
│ │ ├── a11y-tree-and-aria-auditor.md
│ │ ├── keyboard-and-focus-specialist.md
│ │ ├── storybook-a11y-specialist.md
│ │ └── manual-a11y-protocol.md
│ ├── security/
│ │ ├── threat-modeling.md
│ │ ├── wp-security-patterns.md
│ │ ├── pentest-playbook.md
│ │ └── secrets-and-supply-chain.md
│ ├── wordpress/
│ │ ├── multisite-specialist.md
│ │ ├── data-model-and-migrations.md
│ │ ├── backward-compatibility.md
│ │ ├── wp-hooks-architecture.md
│ │ └── i18n-l10n-rtl-specialist.md
│ ├── release/
│ │ ├── packaging-and-dist-builder.md
│ │ ├── wporg-readme-and-assets.md
│ │ ├── plugin-header-and-metadata.md
│ │ └── release-manager.md
│ ├── ci/
│ │ ├── github-actions-architect.md
│ │ ├── reporting-and-artifacts.md
│ │ ├── linting-and-static-analysis.md
│ │ └── compatibility-matrix.md
│ ├── dx/
│ │ ├── onboarding-and-quickstart.md
│ │ ├── makefile-justfile-designer.md
│ │ └── contributing-and-pr-gates.md
│ └── extras/
│ ├── flaky-test-tamer.md
│ ├── failure-injection-chaos-lite.md
│ ├── legal-and-licensing-checker.md
│ └── documentation-quality-auditor.md
| Concern | Go-To Agent |
|---|---|
| "Tests are flaky" | flaky-test-tamer |
| "Need multisite support" | multisite-specialist |
| "RTL is broken" | i18n-l10n-rtl-specialist |
| "Preparing a release" | release-manager + packaging-and-dist-builder |
| "Security review needed" | wp-security-patterns + threat-modeling |
| "CI is slow" | github-actions-architect |
| "Accessibility audit" | a11y-tree-and-aria-auditor |
| "Database schema change" | data-model-and-migrations |
| "New contributor setup" | onboarding-and-quickstart |
| "Quality gates unclear" | qa-director |