chore: staged changes after release v0.2.1

Author: ashleyshaw

.github/agents/README.md

@@ -12,13 +12,6 @@ license: "GPL-3.0"
 domain: "governance"
 stability: "stable"
 tags: ["lightspeed", "agents", "automation", "workflows", "github-actions"]
-references:
-  - path: ./agent.md
-    description: "Main agent index"
-  - path: ../workflows/README.md
-    description: "Workflows directory"
-  - path: ../instructions/agents.instructions.md
-    description: "Agent development instructions"
 ---
 
 ## 🚀 Quick Start
@@ -102,7 +95,7 @@ graph TB
 
 | Agent                                                              | Description                                                    | Status        | Tests                                                                          |
 | ------------------------------------------------------------------ | -------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------ |
-| [meta.agent.js](./meta.agent.js)                                   | Applies front matter, badges, human references, quirky footers | ✅ Active     | -                                                                              |
+| [meta.agent.js](./meta.agent.js)                                   | Applies front matter, badges, quirky footers                    | ✅ Active     | -                                                                              |
 | [badges.agent.js](./badges.agent.js)                               | Manages repository badges and automation status indicators     | ❌ Deprecated | -                                                                              |
 | [header-footer.agent.js](./header-footer.agent.js)                 | Maintains consistent headers and footers across documentation  | ❌ Deprecated | -                                                                              |
 | [issue-type.agent.js](./issue-type.agent.js)                       | Automatically assigns issue types based on content analysis    | ✅ Active     | [✅ Tests](../../scripts/agents/__tests__/issue-type.agent.test.js)            |
@@ -146,7 +139,7 @@ These GitHub Actions workflows integrate with and trigger our agents:
 | **[labeling.yml](../workflows/labeling.yml)**             | `push`, `pull_request`, `issues` events | `labeling.agent.js`                   | Unified labeling for issues and PRs with status enforcement |
 | **[reviewer.yml](../workflows/reviewer.yml)**             | `push`, `pull_request` on `develop`     | `reviewer.agent.js`                   | Automated code review and feedback                          |
 | **[planner.yml](../workflows/planner.yml)**               | `push`, `pull_request` on `develop`     | Internal planner logic                | Project planning automation                                 |
-| **[meta.yml](../workflows/meta.yml)**                     | File changes, `workflow_dispatch`       | `meta.agent.js`                       | Apply front matter, badges, references, quirky footers      |
+| **[meta.yml](../workflows/meta.yml)**                     | File changes, `workflow_dispatch`       | `meta.agent.js`                       | Apply front matter, badges, quirky footers                   |
 | **[badges.yml](../workflows/badges.yml)**                 | Path changes, `workflow_dispatch`       | `badges.agent.js` (Deprecated)        | Badge status updates                                        |
 | **[manage-readmes.yml](../workflows/manage-readmes.yml)** | Path changes, `workflow_dispatch`       | `manage-readmes.agent.js`             | README maintenance                                          |
 | **[header-footer.yml](../workflows/header-footer.yml)**   | File changes                            | `header-footer.agent.js` (Deprecated) | Documentation consistency                                   |

.github/agents/adr.agent.md

@@ -2,6 +2,10 @@
 name: ADR Generator
 description: Expert agent for creating comprehensive Architectural Decision Records (ADRs) with structured formatting optimized for AI consumption and human readability.
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker"]
+metadata:
+  guardrails: "Only draft ADRs when the decision context is complete, do not revise existing ADR numbers without approval, and preserve the published template."
+
+
 ---
 
 # ADR Generator Agent

.github/agents/issues.agent.md

@@ -16,6 +16,11 @@ stability: "stable"
 visibility: "public"
 target: "github-copilot"
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker", "github/*", "read", "search", "edit"]
+permissions:
+  - "read"
+  - "write"
+  - "github:repo"
+  - "github:issues"
 domain: "governance"
 metadata:
   guardrails: "Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity."

.github/agents/labeling.agent.md

@@ -2,7 +2,6 @@
 name: "Labeling"
 description: "Unified agent for dynamic, canonical, and automated labeling of issues and PRs. Handles status, type, priority, and project-field enforcement, label standardization, and migration based on .github/labels.yml."
 target: "github-copilot"
-tools: ["github/*", "edit", "search"]
 handoffs:
   - label: "Start Implementation"
     agent: "implementation"
@@ -17,6 +16,11 @@ category: "automation"
 status: "active"
 visibility: "public"
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker", "github/*", "read", "search", "edit"]
+permissions:
+  - "read"
+  - "write"
+  - "github:repo"
+  - "github:issues"
 tags:
   [
     "lightspeed",
@@ -27,6 +31,8 @@ tags:
     "github",
   ]
 owners: ["lightspeedwp/maintainers"]
+metadata:
+  guardrails: "Only apply types/labels from canonical configs, never overwrite without warning, validate content before labeling, and log every action."
 ---
 
 # LightSpeed Unified Labeling Agent

.github/agents/linting.agent.md

@@ -2,7 +2,6 @@
 name: "Linting"
 description: "Enforces code quality and linting standards across all supported languages and file types. Validates JavaScript/TypeScript, CSS/SCSS, HTML, JSON, Markdown, YAML, PHP, Python, and Shell scripts against canonical standards."
 target: "vscode"
-tools: ["read", "edit", "search", "shell"]
 handoffs:
   - label: "Fix Lint Issues"
     agent: "lint-fixer"
@@ -30,6 +29,14 @@ tags:
 language: "en"
 owners: ["lightspeedwp/maintainers"]
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker", "github/*", "read", "search", "edit"]
+permissions:
+  - "read"
+  - "write"
+  - "filesystem"
+  - "github:repo"
+  - "github:actions"
+  - "github:workflows"
+  - "shell"
 metadata:
   guardrails: "Reference canonical config files only (.eslintrc.json, stylelint.json, etc). Never bypass failing linting checks. Log all linting actions and results. Provide clear, actionable error messages."
 ---

.github/agents/meta.agent.md

@@ -1,12 +1,11 @@
 ---
 name: "Meta"
-description: "Agent for applying documentation metadata in Markdown files: front matter validation/enrichment, badges, human references, and category-specific footers."
+description: "Agent for applying documentation metadata in Markdown files: front matter validation/enrichment, badges, and category-specific footers."
 target: "github-copilot"
-tools: ["read", "edit", "search", "shell"]
 handoffs:
   - label: "Validate Meta Application"
     agent: "doc-validator"
-    prompt: "Validate that all metadata blocks (front matter, badges, human references, footers) have been correctly applied to the documentation."
+    prompt: "Validate that all metadata blocks (front matter, badges, footers) have been correctly applied to the documentation."
     send: false
 version: "v1.1"
 last_updated: "2025-12-05"
@@ -21,14 +20,18 @@ tags:
     "meta",
     "frontmatter",
     "badges",
-    "references",
     "footers",
     "automation",
     "documentation",
   ]
 language: "en"
 owners: ["lightspeedwp/maintainers"]
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker", "github/*", "read", "search", "edit"]
+permissions:
+  - "read"
+  - "write"
+  - "filesystem"
+  - "github:repo"
 metadata:
   guardrails: "Never overwrite content outside designated blocks. Always create backups before modifications. Validate configuration schema before applying. Respect file-specific opt-out markers."
 ---
@@ -37,7 +40,7 @@ metadata:
 
 ## Purpose
 
-Automate the application of documentation metadata to Markdown files (front matter, badges, human references, and category-specific quirky footers) using a unified schema-driven config.
+Automate the application of documentation metadata to Markdown files (front matter, badges, and category-specific quirky footers) using a unified schema-driven config.
 
 ## Triggers
 
@@ -48,17 +51,16 @@ Automate the application of documentation metadata to Markdown files (front matt
 ## Inputs/Outputs
 
 - **Input:** File path, metadata config, schema
-- **Output:** Updated doc with validated front matter, badge block, human references, and category-specific footer
+- **Output:** Updated doc with validated front matter, badge block, and category-specific footer
 
 ## Actions
 
-- Read unified metadata config (front matter guardrails, badges, references, footer variants) in JSON/YAML
+- Read unified metadata config (front matter guardrails, badges, footer variants) in JSON/YAML
 - Validate config against [agent-config.schema.json](../../schemas/header-footer-agent/agent-config.schema.json)
 - Select appropriate category/variant (random or by file type/tag)
 - Insert/update metadata blocks in the doc:
   - Front matter verification and enrichment
   - Badge block placement under the H1
-  - Human references block above the footer
   - Category-specific quirky footer selection
 - Maintain and update README.md files:
   - Ensure proper structure and formatting
@@ -71,5 +73,5 @@ Automate the application of documentation metadata to Markdown files (front matt
 - Never overwrite main content
 - Validate config before applying
 - Always backup before changes
-- Only update designated blocks (front matter, badges, references, footers)
+- Only update designated blocks (front matter, badges, footers); the legacy `references` block is retired
 - Preserve user-generated content in READMEs while updating metadata

.github/agents/metrics.agent.md

@@ -2,7 +2,6 @@
 name: "Metrics"
 description: "Automates collection, aggregation, and reporting of repository health metrics including issue/PR activity, response times, and project health indicators. Generates actionable insights and trend analysis."
 target: "github-copilot"
-tools: ["github/*", "read", "search"]
 handoffs:
   - label: "Generate Report"
     agent: "report-writer"
@@ -19,6 +18,12 @@ visibility: "public"
 tags: ["lightspeed", "metrics", "agents", "analytics", "reporting"]
 owners: ["lightspeedwp/maintainers"]
 tools:  ["file_system", "markdown_generator", "input_collector", "adr_naming_helper", "quality_checker", "template_filler", "context_analyzer", "decision_rationale_extractor", "alternative_evaluator", "consequence_analyzer", "implementation_planner", "reference_manager", "date_manager", "stakeholder_identifier", "status_manager", "tag_manager", "supersession_tracker", "yaml_front_matter_generator", "markdown_saver", "language_enforcer", "structure_enforcer", "completeness_verifier", "clarity_checker", "consistency_checker", "timeliness_checker", "connection_checker", "contextual_accuracy_checker", "github/*", "read", "search", "edit"]
+permissions:
+  - "read"
+  - "write"
+  - "filesystem"
+  - "network"
+  - "github:repo"
 metadata:
   guardrails: "Do not expose sensitive data or credentials in metrics. Log all collection runs. Support multi-repository aggregation. Validate data before reporting."
 ---

.github/agents/mode-demonstrate-understanding.agent.md

@@ -2,6 +2,8 @@
 name: "Demonstrate Understanding"
 description: "Validate user understanding of code, design patterns, and implementation details through guided questioning."
 tools: ["codebase", "fetch", "findTestFiles", "githubRepo", "search", "usages"]
+metadata:
+  guardrails: "Ask only one probing question at a time, confirm understanding before moving on, never jump to solutions, and document all reasoning."
 ---
 
 # Demonstrate Understanding mode instructions

.github/agents/mode-document-reviewer.agent.md

@@ -13,6 +13,8 @@ tools:
     "runSubagent",
   ]
 model: Claude Sonnet 4.5 (copilot)
+metadata:
+  guardrails: "Complete the mandatory analysis, compute the Documentation Wrapper Score before responding, and never skip the editorial standards described in the spec."
 ---
 
 Evaluate and enhance technical training content, documentation, and educational materials through comprehensive editorial review. Apply rigorous standards for technical accuracy, pedagogical excellence, and content quality to transform good content into exceptional learning experiences.

.github/agents/mode-prd.agent.md

@@ -16,6 +16,9 @@ tools:
     "get_issue",
     "search_issues",
   ]
+metadata:
+  guardrails: "Ask clarifying questions first, confirm scope before drafting any PRD, only create docs with user approval, and never write issues without explicit consent."
+
 ---
 
 # Create PRD Agent