feat: Add comprehensive testing documentation and agent permissions system

## Testing Documentation

### PHP Testing Instructions (php-tests.instructions.md)
- Complete PHPUnit testing guide for WordPress plugins (891 lines)
- Test environment setup and configuration
- Testing custom post types, taxonomies, and SCF
- WordPress test framework utilities and factories
- Mocking strategies and test fixtures
- Code coverage configuration
- Best practices and CI integration examples

### Playwright Testing Instructions (playwright-tests.instructions.md)
- Comprehensive Playwright E2E testing guide (721 lines)
- WordPress block editor testing patterns
- Test file organization and configuration
- Locator strategies and web-first assertions
- Block insertion, configuration, and rendering tests
- Debugging techniques and troubleshooting
- Accessibility testing with aria snapshots
- Page object model patterns

## Agent Permissions System

### Frontmatter Schema (frontmatter.schema.json)
- Complete JSON schema for agent specification frontmatter
- Permissions vocabulary with 12 approved values:
  - Core: read, write, execute, shell, filesystem, network
  - GitHub: github:repo, github:issues, github:pulls, github:workflows, github:checks, github:actions
- Validation rules for all frontmatter fields
- Metadata support for guardrails, rate limits, and dry-run capabilities

### Agent Spec Instructions Updates
- Added comprehensive Permissions Vocabulary section (65 lines)
- Documented each permission with use cases and examples
- Permission-to-tool mapping guidelines
- Principle of least privilege enforcement
- Updated validation checklist with permissions requirements

### Agent Spec Updates
- template.agent.md: Added permissions field, updated to v1.2
- generate-plugin.agent.md: Added permissions [read, write, execute, shell, filesystem]

## Documentation Alignment
- All new instructions reference existing docs (jest-tests, testing-e2e, a11y)
- Consistent formatting and structure across all testing guides
- Cross-referenced with WPCS instructions and custom-instructions.md

Phase 6.5: Testing Documentation & Permissions Framework

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ashleyshaw

.github/agents/generate-plugin.agent.md

@@ -2,6 +2,7 @@
 name: "Plugin Generator Agent"
 description: Interactive agent that collects comprehensive requirements and generates a WordPress multi-block plugin with CPT, taxonomies, and SCF fields
 tools: ["semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "create_file", "update_file", "delete_file", "move_file"]
+permissions: ["read", "write", "execute", "shell", "filesystem"]
 ---
 
 # Multi-Block Plugin Scaffold Generator

.github/agents/template.agent.md

@@ -1,14 +1,15 @@
 ---
 name: "Template: Agent Specification"
 description: "Standard specification template for LightSpeed multi-block plugin scaffold agents, covering role, tooling, inputs, outputs, and guardrails."
-version: "v1.1"
-last_updated: "YYYY-MM-DD"
+version: "v1.2"
+last_updated: "2025-12-16"
 owners: ["LightSpeedWP Engineering"]
 status: "draft"
 apply_to: [".github/agents/*.agent.md"]
 file_type: "template"
 tags: ["agent", "spec", "template", "copilot"]
 tools: ["Copilot Agents"]
+permissions: ["read"]
 metadata:
   guardrails: "Agents must never perform destructive or irreversible actions without explicit confirmation and must follow AGENTS.md."
 ---

.github/instructions/agent-spec.instructions.md

@@ -29,15 +29,85 @@ Use this file when creating or updating `*.agent.md` files inside `.github/agent
 ## Detailed Guidance
 
 - **Template & metadata:** Copy the latest `.github/agents/template.agent.md`, update frontmatter values, and ensure references include `AGENTS.md` and `.github/instructions/agent-spec.instructions.md`. Use ISO `YYYY-MM-DD` dates.
-- **Role & scope first:** Clearly state the agent’s purpose, persona, supported workflows (blocks, generator, release), and explicit boundaries (no deployments, no production writes, no git pushes unless specified).
-- **Responsibilities & capabilities:** List only actions the team can support. Make limitations explicit (for example, “read-only for generated plugins”, “no database migrations”).
-- **Allowed tools:** Enumerate every tool, script, API, or CLI command the agent may call. Note required environment variables without revealing real values.
+- **Role & scope first:** Clearly state the agent's purpose, persona, supported workflows (blocks, generator, release), and explicit boundaries (no deployments, no production writes, no git pushes unless specified).
+- **Responsibilities & capabilities:** List only actions the team can support. Make limitations explicit (for example, "read-only for generated plugins", "no database migrations").
+- **Allowed tools:** Enumerate every tool, script, API, or CLI command the agent may call. Note required environment variables without revealing real values. Tools are explicitly listed in the `tools` frontmatter array.
+- **Permissions:** Define fine-grained permissions using the approved vocabulary (see Permissions Vocabulary section below). Grant permissions conservatively based on agent's actual needs. Include the `permissions` field in frontmatter alongside `tools`.
 - **Inputs & outputs:** Define accepted natural language prompts and structured inputs (JSON/YAML). Provide examples and, when useful, JSON Schema. Specify output formats, required fields, and error conventions for deterministic parsing.
 - **Safety guardrails:** Include confirmation rules, non-destructive defaults, rate limits, and escalation paths to humans. Align with OWASP practices and repository security expectations.
 - **Failure & rollback:** Document how to handle invalid input, tool failures, partial success, and any rollback or manual follow-up steps.
 - **Test tasks & observability:** Provide at least three validation tasks (normal, edge, failure). State logging expectations (timestamps, tool calls, external interactions) and privacy considerations.
 - **Changelog discipline:** Keep a changelog section in each spec. Update `version`, `last_updated`, and changelog entries whenever behaviour, tools, or guardrails change.
 
+## Permissions Vocabulary
+
+The `permissions` field gates what agents can access and modify. Use the approved enum values from `.github/schemas/frontmatter.schema.json`. Grant permissions conservatively and document why each is needed.
+
+### Core Permissions
+
+- **`read`** - Read files, directories, and repository content. Required for most agents that need to inspect code, configuration, or documentation.
+- **`write`** - Create, update, or delete files in the repository. Required for agents that generate code, update configurations, or modify documentation.
+- **`execute`** - Execute scripts, commands, or binaries. Required for agents that run build tools, tests, or generation scripts.
+- **`shell`** - Access to shell/terminal operations. Required for agents that need to run command-line tools like npm, composer, or git.
+- **`filesystem`** - Full filesystem access including directory operations. Required for agents that need to create/manage directory structures.
+- **`network`** - Make network requests to external services. Required for agents that fetch data from APIs, check URLs, or integrate with external tools.
+
+### GitHub Permissions
+
+- **`github:repo`** - Access repository information, read branches, tags, and commits. Required for agents working with repository metadata.
+- **`github:issues`** - Create, read, update GitHub issues. Required for reporting agents or issue triage automation.
+- **`github:pulls`** - Create, read, update pull requests. Required for release agents or PR automation.
+- **`github:workflows`** - Trigger or manage GitHub Actions workflows. Required for CI/CD integration agents.
+- **`github:checks`** - Read or create status checks. Required for quality gate agents.
+- **`github:actions`** - Manage GitHub Actions. Required for workflow management agents.
+
+### Permission Examples
+
+```yaml
+# Read-only documentation agent
+permissions: ["read"]
+
+# Code quality agent (reads code, writes reports)
+permissions: ["read", "write", "execute", "filesystem"]
+
+# Plugin generator agent (full file system access, runs scripts)
+permissions: ["read", "write", "execute", "shell", "filesystem"]
+
+# Release agent (GitHub integration, runs commands)
+permissions: ["read", "write", "execute", "shell", "filesystem", "github:repo", "github:pulls", "github:workflows"]
+
+# Reporting agent (reads data, creates issues)
+permissions: ["read", "github:repo", "github:issues"]
+```
+
+### Permission Guidelines
+
+1. **Principle of least privilege** - Only grant permissions actually needed
+2. **Document justification** - Explain why each permission is required in agent spec
+3. **Review regularly** - Audit permissions when agent capabilities change
+4. **Network access** - Requires explicit justification (external API calls, URL validation)
+5. **GitHub permissions** - Must document which GitHub features are accessed and why
+6. **Shell access** - Document which commands/tools are executed
+
+### Adding Permissions to Specs
+
+When updating or creating agent specifications, add the `permissions` field to frontmatter:
+
+```markdown
+---
+name: "Example Agent"
+description: "Agent description"
+tools: ["read_file", "update_file", "run_in_terminal"]
+permissions: ["read", "write", "execute", "shell"]
+---
+```
+
+The permissions array should align with the tools array:
+- `read_file` → requires `read` permission
+- `update_file`, `create_file` → requires `write` permission
+- `run_in_terminal` → requires `execute` and `shell` permissions
+- `github_api` → requires appropriate `github:*` permissions
+
 ## Examples
 
 - **Frontmatter skeleton:**
@@ -64,10 +134,13 @@ Use this checklist before merging a new or updated agent spec:
 
 - [ ] **Role & scope** – Purpose is unambiguous; boundaries are clear.
 - [ ] **Capabilities** – Actions are supportable; no implied powers.
-- [ ] **Tools** – All tools/APIs are explicitly listed with required permissions noted.
+- [ ] **Tools** – All tools/APIs are explicitly listed in `tools` frontmatter array.
+- [ ] **Permissions** – Permissions field is present with appropriate values from approved vocabulary; justification is clear.
+- [ ] **Tool-Permission alignment** – Permissions match the capabilities required by listed tools.
 - [ ] **Input/Output** – Schemas or formats are clear with examples; error handling is defined.
 - [ ] **Safety** – Guardrails reference AGENTS.md/SECURITY.md; confirmation rules exist for risky actions.
 - [ ] **Failure/Rollback** – Behaviour for partial failure and recovery is documented.
 - [ ] **Testing** – Includes at least one normal task, one edge case, and one failure case.
 - [ ] **Observability** – Logging and audit expectations are stated.
 - [ ] **Changelog & metadata** – Version, `last_updated`, owners, and status fields are current; changelog updated.
+- [ ] **Schema validation** – Run `npm run validate:agents` to ensure frontmatter passes schema validation.