diff --git a/.github/mergify.yml b/.github/mergify.yml index d579f7de..e8e6ee2d 100644 --- a/.github/mergify.yml +++ b/.github/mergify.yml @@ -1,7 +1,7 @@ pull_request_rules: - name: Auto-merge Dependabot dependency updates on develop conditions: - - author=dependabot + - author=dependabot[bot] - base=develop - label=area:dependencies - check-success=check @@ -14,7 +14,7 @@ pull_request_rules: - name: Auto-merge Dependabot security updates on develop conditions: - - author=dependabot + - author=dependabot[bot] - base=develop - label=area:dependencies - label=meta:dependabot-security diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fa92407..af5d3dd0 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/agents/template.agent.md b/agents/template.agent.md index a54223c8..07d0b94e 100644 --- a/agents/template.agent.md +++ b/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 diff --git a/agents/testing.agent.md b/agents/testing.agent.md index 46f7ef58..3293090b 100644 --- a/agents/testing.agent.md +++ b/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) diff --git a/instructions/copilot-operations.instructions.md b/instructions/copilot-operations.instructions.md index f3e831e7..d1ab3088 100644 --- a/instructions/copilot-operations.instructions.md +++ b/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