Update instruction files

Author: ashleyshaw

.github/agents/task-planner.agent.md

@@ -36,12 +36,12 @@ tools: [
   "context7"
 ]
 metadata:
-guardrails: |
-- Never skip research validation.
-- Never generate implementation without a plan.
-- Always provide detailed, actionable steps.
-- Plans MUST be based on validated research or documented repo conventions.
-- Stop immediately if research is missing and escalate to task-researcher agent.
+  guardrails: |
+    - Never skip research validation.
+    - Never generate implementation without a plan.
+    - Always provide detailed, actionable steps.
+    - Plans MUST be based on validated research or documented repo conventions.
+    - Stop immediately if research is missing and escalate to task-researcher agent.
 ---
 
 # Block Theme Planning Agent

.github/agents/task-researcher.agent.md

@@ -60,6 +60,6 @@ See the file list below for topic coverage. Open the relevant `*.instructions.md
 
 ## References
 
-- `.github/custom-instructions.md`
-- `.github/instructions/instructions.instructions.md`
-- `.github/agents/agent.md`
+- [../custom-instructions.md](../custom-instructions.md)
+- [./instructions.instructions.md](./instructions.instructions.md)
+- [../agents/agent.md](../agents/agent.md)

.github/instructions/README.md

@@ -1,12 +1,11 @@
----
-file_type: "instructions"
 description: "Comprehensive accessibility standards for WordPress block theme development"
-applyTo: "**"
-version: "v3.0"
-last_updated: "2025-12-07"
+applyTo: "\*\*"
+version: "3.0"
+lastUpdated: "2025-12-07"
 owners: ["LightSpeedWP Team"]
 tags: ["accessibility", "a11y", "wcag", "wordpress", "block-theme"]
 license: "GPL-3.0"
+
 ---
 
 # Accessibility Standards for WordPress Block Themes
@@ -47,27 +46,10 @@ Apply these instructions whenever adding or modifying markup, patterns, template
 - Automated: run axe-core or Lighthouse; ensure no critical violations.
 - Manual: keyboard navigation (Tab/Shift+Tab/Esc) and visible focus.
 - Screen readers: spot-check with VoiceOver/NVDA for form labels and landmarks.
+- Quick checklist: semantic HTML and headings, visible focus, sufficient contrast, labelled form controls, ARIA only when necessary.
 
 ## References
 
 - [WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/)
-- `.github/instructions/html-markup.instructions.md`
-- `.github/instructions/block-theme-development.instructions.md`
-
-## Quick Reference
-
-- ✅ Semantic HTML, proper heading hierarchy
-- ✅ Keyboard accessible (Tab/Shift+Tab, Esc)
-- ✅ ARIA only when needed
-- ✅ 4.5:1 text contrast, 3:1 graphics
-- ✅ Meaningful alt text
-- ✅ Form labels and error messages
-- ✅ Test with axe-core, Playwright, screen readers
-
-## Testing
-
-- **axe-core**: No critical violations
-- **Keyboard**: Tab order, focus visible
-- **Screen readers**: NVDA/VoiceOver test
-
-See [WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/) for complete guidelines.
+- [./html-markup.instructions.md](./html-markup.instructions.md)
+- [./block-theme-development.instructions.md](./block-theme-development.instructions.md)

.github/instructions/_index.instructions.md

@@ -93,8 +93,8 @@ Use this instruction file when drafting or reviewing any `.agent.md` in `.github
 
 ## References
 
-- `.github/agents/template.agent.md`
-- `.github/agents/agent.md`
-- `.github/instructions/instructions.instructions.md`
-- `.github/instructions/copilot-ai-agent.instructions.md`
-- `.github/workflows/block-theme-build-and-e2e.yml`
+- [../agents/template.agent.md](../agents/template.agent.md)
+- [../agents/agent.md](../agents/agent.md)
+- [./instructions.instructions.md](./instructions.instructions.md)
+- [./copilot-ai-agent.instructions.md](./copilot-ai-agent.instructions.md)
+- [../workflows/block-theme-build-and-e2e.yml](../workflows/block-theme-build-and-e2e.yml)

.github/instructions/a11y.instructions.md

@@ -363,9 +363,9 @@ Add `.editorconfig` for consistent indentation and formatting.
 
 ## References
 
-- `.github/instructions/theme-json.instructions.md`
-- `.github/instructions/wpcs-php.instructions.md`
-- `.github/instructions/javascript.instructions.md`
-- `.github/instructions/wpcs-css.instructions.md`
-- `.github/instructions/html-markup.instructions.md`
-- `.github/custom-instructions.md`
+- [./theme-json.instructions.md](./theme-json.instructions.md)
+- [./wpcs-php.instructions.md](./wpcs-php.instructions.md)
+- [./javascript.instructions.md](./javascript.instructions.md)
+- [./wpcs-css.instructions.md](./wpcs-css.instructions.md)
+- [./html-markup.instructions.md](./html-markup.instructions.md)
+- [../custom-instructions.md](../custom-instructions.md)

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

@@ -447,7 +447,7 @@ See: [generate-theme.agent.md](../agents/generate-theme.agent.md) for complete s
 1. Auto-fix if possible: `npm run lint -- --fix`
 2. Check config: `.eslintrc.js`, `.stylelintrc`
 3. Check affected files
-4. Review [FOLDER-STRUCTURE.md](../../docs/FOLDER-STRUCTURE.md) for conventions
+4. Review [FOLDER_STRUCTURE.md](../../docs/FOLDER_STRUCTURE.md) for conventions
 5. Check logs: `logs/lint/` for details
 
 ### Documentation Outdated
@@ -458,7 +458,7 @@ See: [generate-theme.agent.md](../agents/generate-theme.agent.md) for complete s
 
 1. Identify which docs are stale
 2. Update [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) if structure changed
-3. Update [FOLDER-STRUCTURE.md](../../docs/FOLDER-STRUCTURE.md) if conventions changed
+3. Update [FOLDER_STRUCTURE.md](../../docs/FOLDER_STRUCTURE.md) if conventions changed
 4. Update [LOGGING.md](../../docs/LOGGING.md) if logging changed
 5. Update API-REFERENCE.md for API changes
 6. Add note to CHANGELOG.md
@@ -547,7 +547,7 @@ npm run lighthouse        # Lighthouse score
 
 ### For Specific Questions
 
-**About code style?** → [FOLDER-STRUCTURE.md](../../docs/FOLDER-STRUCTURE.md)
+**About code style?** → [FOLDER_STRUCTURE.md](../../docs/FOLDER_STRUCTURE.md)
 
 **About structure?** → [ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
 
@@ -616,7 +616,10 @@ npm run lint -- --verbose
 
 ## References
 
-- `.github/custom-instructions.md`
-- `.github/instructions/reporting.instructions.md`
-- `.github/instructions/naming-conventions.instructions.md`
-- `docs/GOVERNANCE.md`, `docs/ARCHITECTURE.md`, `docs/FOLDER-STRUCTURE.md`, `docs/LOGGING.md`
+- [../custom-instructions.md](../custom-instructions.md)
+- [./reporting.instructions.md](./reporting.instructions.md)
+- [./naming-conventions.instructions.md](./naming-conventions.instructions.md)
+- [../../docs/GOVERNANCE.md](../../docs/GOVERNANCE.md)
+- [../../docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+- [../../docs/FOLDER_STRUCTURE.md](../../docs/FOLDER_STRUCTURE.md)
+- [../../docs/LOGGING.md](../../docs/LOGGING.md)

.github/instructions/block-theme-development.instructions.md

@@ -850,15 +850,6 @@ grep -r "{{" --exclude-dir=node_modules --exclude-dir=vendor .
 - [ ] Font families have proper fallbacks
 - [ ] No syntax errors in theme.json
 
-## References
-
-- [GENERATE-THEME.md](../../docs/GENERATE-THEME.md) - Complete generator system documentation
-- [generate-theme.prompt.md](../prompts/generate-theme.prompt.md) - User-facing generation prompt
-- [generate-theme.agent.md](../agents/generate-theme.agent.md) - Agent specification
-- [theme-json.instructions.md](./theme-json.instructions.md) - theme.json configuration guide
-- [theme-config.schema.json](../schemas/theme-config.schema.json) - JSON Schema for validation
-- [theme-config.template.json](../../theme-config.template.json) - Template config file
-
 ## Summary
 
 As an AI agent guiding theme generation:
@@ -871,3 +862,12 @@ As an AI agent guiding theme generation:
 6. **Guide post-generation** setup and next steps
 
 **Remember:** Mustache variables are simple string replacements. Your job is to collect valid values and pass them to the generator script. The script handles the actual replacement process.
+
+## References
+
+- [GENERATE_THEME.md](../../docs/GENERATE_THEME.md) - Complete generator system documentation
+- [generate-theme.prompt.md](../prompts/generate-theme.prompt.md) - User-facing generation prompt
+- [generate-theme.agent.md](../agents/generate-theme.agent.md) - Agent specification
+- [theme-json.instructions.md](./theme-json.instructions.md) - theme.json configuration guide
+- [theme-config.schema.json](../schemas/theme-config.schema.json) - JSON Schema for validation
+- [theme-config.template.json](../../theme-config.template.json) - Template config file

.github/instructions/copilot-ai-agent.instructions.md

@@ -2,8 +2,8 @@
 file_type: "instructions"
 description: "HTML markup and template standards for WordPress block themes"
 applyTo: "**/*.{html,htm,php}"
-version: "v2.0"
-last_updated: "2025-12-07"
+version: "2.0"
+lastUpdated: "2025-12-07"
 owners: ["LightSpeedWP Team"]
 tags: ["html", "template", "wordpress", "block-theme", "semantic"]
 license: "GPL-3.0"
@@ -58,5 +58,5 @@ Use these instructions whenever editing templates, template parts, or pattern ma
 ## References
 
 - [WordPress HTML Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/)
-- `.github/instructions/a11y.instructions.md`
-- `.github/instructions/block-theme-development.instructions.md`
+- [./a11y.instructions.md](./a11y.instructions.md)
+- [./block-theme-development.instructions.md](./block-theme-development.instructions.md)