Complete agent specs and audit documentation standards

CHANGELOG.md

@@ -24,6 +24,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Comprehensive unit tests in `scripts/__tests__/wceu-validation-scripts.test.js` validating script structure, syntax, and completeness
   - Updated `scripts/README.md` with usage examples and feature documentation ([#13](https://github.com/lightspeedwp/.github/issues/13), [#16](https://github.com/lightspeedwp/.github/issues/16))
 
+- **Complete Agent Specifications & Documentation Audit** — Completed specification documentation for tracking agents and audited documentation cross-references:
+  - Completed `agents/template.agent.md` with canonical agent specification template, usage guidelines, structure documentation, and best practices ([#488](https://github.com/lightspeedwp/.github/issues/488))
+  - Enhanced `agents/testing.agent.md` with comprehensive role/responsibilities, capabilities, configuration, examples, and related agent references ([#490](https://github.com/lightspeedwp/.github/issues/490))
+  - Audited documentation cross-references to CONTRIBUTING.md, GOVERNANCE.md, coding standards, and linting instructions ([#22](https://github.com/lightspeedwp/.github/issues/22))
+  - Verified CONTRIBUTING.md has adequate Quick Start section and workflow diagram ([#18](https://github.com/lightspeedwp/.github/issues/18))
+  - Verified PR template includes comprehensive accessibility and security checklists ([#21](https://github.com/lightspeedwp/.github/issues/21))
+
+- **Wave 4C: Branding Agent Current-State Audit** — Added `.github/projects/active/ISSUE_48_CURRENT_STATE_AUDIT.md` comprehensive audit specification ([#48](https://github.com/lightspeedwp/.github/issues/48), [#562](https://github.com/lightspeedwp/.github/pull/562)):
+  - Current-state inventory catalogs ~750 Markdown files with branding implementations
+  - Frontmatter compliance analysis (90.6% compliant, 70 files with missing required fields)
+  - Category mapping accuracy audit (98%+ correct, specific gaps identified)
+  - Header and footer pattern analysis (84.5% coverage gap identified)
+  - Badge usage assessment (1.9% adoption, 40% non-standard values)
+  - WCAG AA accessibility audit (95%+ compliance with specific improvement areas)
+  - Detailed gap analysis against new schema/config standards
+  - Prioritized remediation roadmap with effort estimates (16–23 hours across 5 phases)
+  - Automated remediation scripts scoped and designed
+  - Risk assessment with comprehensive mitigation strategies
+  - Success criteria and measurable outcomes for agent rollout
+  - Unblocks Wave 4E (Agent merge/refactor) and Wave 4F (Bulk remediation & validation)
+
 - **Comprehensive 25-Slide Deck Prompt Suite** — Added `.github/wceu-2026/agent-slides/` directory with 25 NotebookLM and Figma-ready presentation prompts covering the complete .github automation ecosystem:
   - **7 Agent Prompts**: Release, Branding, Meta, Reviewer, Linting, Labelling, and Planner agents with capabilities, integration points, and use cases
   - **3 Infrastructure Prompts**: Plugin/Agents/Skills/Hooks integration, Scripts & Automation orchestration, and Workflows architecture

agents/template.agent.md

@@ -6,7 +6,7 @@ description: 'Standard specification for defining a LightSpeed Copilot Agent: ro
   behaviours, tooling, schemas, and safety constraints.'
 version: v1.2
 last_updated: '2026-05-29'
-status: draft
+status: active
 tags:
 - agent
 - spec
@@ -15,3 +15,110 @@ tags:
 owners:
 - LightSpeedWP Engineering
 ---
+
+# Agent Specification Template
+
+This document provides the canonical template for defining LightSpeed Copilot agents. Use this specification to document agent role, responsibilities, capabilities, tooling, and safety constraints.
+
+## Usage
+
+Copy this template when creating a new agent specification. Replace placeholder sections with concrete details specific to your agent.
+
+## Structure
+
+```markdown
+---
+file_type: agent
+name: [unique agent identifier]
+title: [human-readable agent name]
+description: [one-sentence purpose]
+version: v1.0
+last_updated: 'YYYY-MM-DD'
+status: [draft|active|deprecated]
+tags:
+- [category tags]
+authors:
+- [team or person]
+---
+
+# [Agent Name]
+
+## Role & Responsibilities
+
+Brief summary of what this agent does and when it should be invoked.
+
+## Capabilities
+
+- **Primary:** List primary capabilities
+- **Secondary:** List secondary capabilities
+
+## Required Inputs
+
+- Input format and constraints
+
+## Expected Outputs
+
+- Output format and examples
+
+## Tools & Permissions
+
+- Required GitHub tools
+- File system access
+- External API integrations
+
+## Safety Constraints
+
+- Guardrails and limits
+- What the agent must NOT do
+- Error handling approach
+
+## Configuration
+
+- Required environment variables
+- Optional settings with defaults
+- Performance tuning parameters
+
+## Examples
+
+### Example 1: [Scenario]
+
+Input → Agent Action → Output
+
+## Related Agents
+
+- Links to related agent specifications
+- Handoff patterns if applicable
+```
+
+## Key Sections Explained
+
+### Role & Responsibilities
+
+Clearly state what this agent is responsible for. Include the primary use cases and scenarios where the agent should be invoked.
+
+### Capabilities
+
+List both primary and secondary capabilities. Be specific about what the agent can and cannot do.
+
+### Tools & Permissions
+
+Document all tools the agent needs access to. Include GitHub tools, file system permissions, and any external APIs.
+
+### Safety Constraints
+
+Define guardrails and constraints that protect against misuse. Include specific prohibitions and error handling behaviour.
+
+## Best Practices
+
+1. **Be Specific:** Avoid vague descriptions; include concrete examples
+2. **Document Constraints:** Explicitly state what the agent will NOT do
+3. **Define Inputs/Outputs:** Be precise about expected formats and constraints
+4. **Include Examples:** Show realistic usage scenarios
+5. **Keep Updated:** Review and update specs as agent capabilities evolve
+6. **Link Related:** Cross-reference related agents and workflows
+
+## See Also
+
+- [Agents Directory](./README.md) – Directory of all agent specifications
+- [Agent Creation Guide](../docs/AGENT_CREATION.md) – Building and testing new agents
+- [AGENTS.md](../AGENTS.md) – Organization-wide agent guidelines

agents/testing.agent.md

@@ -1,5 +1,6 @@
 ---
 name: Testing
+title: 'Testing Agent: Test Execution and Coverage Analysis'
 description: Comprehensive test execution agent for running unit tests, integration
   tests, and generating coverage reports across all supported testing frameworks.
 target: vscode
@@ -73,3 +74,109 @@ metadata:
     all test results. Provide clear failure diagnostics. Ensure minimum coverage thresholds
     are met.
 ---
+
+# Testing Agent
+
+Comprehensive test execution and coverage analysis agent for LightSpeed projects. Supports multiple testing frameworks and provides detailed failure diagnostics.
+
+## Role & Responsibilities
+
+The Testing Agent is responsible for:
+
+- Running unit, integration, and end-to-end tests across all supported frameworks
+- Generating and analysing test coverage reports
+- Identifying test failures and root causes
+- Recommending fixes for failing tests (via handoff to test-fixer agent)
+- Ensuring minimum coverage thresholds are met before merge
+
+## Capabilities
+
+### Primary
+
+- Execute Jest unit tests (JavaScript/TypeScript)
+- Execute PHPUnit tests (PHP)
+- Execute Playwright browser tests (E2E)
+- Execute pytest tests (Python)
+- Generate coverage reports in multiple formats
+- Analyse test failures and provide diagnostics
+
+### Secondary
+
+- Track test trends over time
+- Identify flaky tests
+- Suggest improvements to test structure
+- Validate test coverage against thresholds
+
+## Required Inputs
+
+- **Project path:** Root directory of project to test
+- **Test framework(s):** Which test runners to execute (jest, phpunit, playwright, pytest)
+- **Coverage threshold:** Minimum coverage percentage (default: 80%)
+- **Optional flags:** Specific test files, watch mode, debug options
+
+## Expected Outputs
+
+- **Test results:** Pass/fail status for each test
+- **Coverage report:** Line, branch, function coverage metrics
+- **Failure summary:** List of failed tests with error messages
+- **Recommendations:** Suggested fixes and coverage improvements
+
+## Tools & Permissions
+
+- **File system:** Read access to source and test files; write access for coverage reports
+- **Shell execution:** Run npm, php, python test commands
+- **GitHub:** Read access to repo, actions for CI context
+
+## Safety Constraints
+
+- **Never skip tests:** Always execute complete test suites unless explicitly scoped
+- **Always log results:** Capture full test output and coverage metrics
+- **Clear diagnostics:** Provide actionable error messages for failures
+- **Respect thresholds:** Block merge if coverage falls below configured minimum
+- **No destructive actions:** Do not delete test files or modify source code without explicit approval
+
+## Configuration
+
+### Environment Variables
+
+- `MIN_COVERAGE_THRESHOLD=80` – Minimum coverage percentage (default: 80%)
+- `JEST_CONFIG_PATH=jest.config.cjs` – Jest configuration file
+- `PHPUNIT_CONFIG_PATH=phpunit.xml` – PHPUnit configuration file
+
+### Supported Frameworks
+
+- **Jest:** JavaScript/TypeScript unit tests
+- **PHPUnit:** PHP unit tests with WPCS standards
+- **Playwright:** End-to-end browser testing
+- **pytest:** Python test framework
+
+## Examples
+
+### Example 1: Run all tests and generate coverage
+
+```
+Agent: Run all tests in this project and generate a coverage report.
+Output: 
+- Jest: 125 tests pass, 2 fail (coverage: 82%)
+- Playwright: 8 tests pass, 0 fail
+- Overall: 96% of tests passing, coverage above threshold
+```
+
+### Example 2: Identify and fix failing test
+
+```
+Agent: Fix the failing test in /src/components/Button.test.js
+Output:
+- Identified: Missing mock for localStorage API
+- Recommended fix: Mock window.localStorage before test
+- Handoff: Passed to test-fixer agent
+```
+
+## Related Agents
+
+- [Release Agent](./release.agent.md) – Ensures tests pass before release
+
+## See Also
+
+- [Quality Assurance Standards](../instructions/quality-assurance.instructions.md)
+- [Testing Strategy](../docs/TESTING.md)

instructions/copilot-operations.instructions.md

@@ -50,7 +50,7 @@ Defines operational standards for AI-driven work in LightSpeedWP repositories. C
 
 ### Session Start Protocol
 
-1. **Load context:** Read CLAUDE.md, AGENTS.md, .github/instructions/coding-standards.instructions.md
+1. **Load context:** Read CLAUDE.md, AGENTS.md, instructions/coding-standards.instructions.md
 2. **Identify scope:** Determine which files, directories, and changes are in scope
 3. **Declare assumptions:** State what you're assuming about project structure, conventions, and permissions
 4. **Ask for clarification:** If any instruction is ambiguous, use AskUserQuestion before proceeding