Skip to content

Wave 3C: README Update Workflow & Wave 4 Specification #536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ashleyshaw merged 10 commits into from
May 28, 2026
Merged

Wave 3C: README Update Workflow & Wave 4 Specification #536

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
72f3540
migration: move plugin-structure.instructions.md to top-level
claude May 28, 2026
fd7f477
feat(wave-3c): implement readme-update workflow and Wave 4 specification
claude May 28, 2026
e500d2f
fix: correct Wave 4 specification frontmatter
claude May 28, 2026
8b3358d
fix: remove broken anchor links in Wave 4 specification
claude May 28, 2026
c3d825c
chore: update frontmatter metadata for modified files
claude May 28, 2026
c9122d2
chore: update frontmatter metadata for modified files
claude May 28, 2026
249bcef
docs: add Wave 3C changelog entry for readme-update workflow and Wave…
claude May 28, 2026
220b27a
refactor: move embedded JavaScript to separate scripts
claude May 28, 2026
ae143f5
fix: remove excess blank lines and temporary file
claude May 28, 2026
70349de
chore: update frontmatter metadata for README.md
claude May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/PULL_REQUEST_TEMPLATE/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
file_type: "documentation"
title: "Pull Request Templates Directory"
description: "Standardized pull request templates for the LightSpeedWP organization"
version: "v1.1"
version: "v1.2"
created_date: "2025-10-20"
last_updated: "2025-11-25"
last_updated: "2026-05-28"
author: "LightSpeed Team"
maintainer: "Ash Shaw"
owners: ["lightspeedwp/maintainers"]
Expand Down
24 changes: 5 additions & 19 deletions .github/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
file_type: "documentation"
title: "LightSpeed .github Community Health Repository"
description: "Central hub for all shared GitHub templates, Copilot instructions, workflow automation, labeling systems, and community health files across the LightSpeed WordPress organisation"
version: "3.1"
version: "3.2"
created_date: "2025-01-15"
last_updated: "2025-12-04"
last_updated: "2026-05-28"
authors: ["LightSpeed Team"]
maintainer: "LightSpeed Team"
license: "GPL-3.0"
Expand Down Expand Up @@ -477,19 +477,6 @@ Have questions, feedback, or want to propose an idea? Visit our [GitHub Discussi
For all contributors, please reference these key guidelines and indexes:

- [LightSpeed General Copilot Instructions](https://github.com/lightspeedwp/.github/blob/HEAD/.github/custom-instructions.md)
- [Coding Standards](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/coding-standards.instructions.md)
- [HTML Templates](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/html-template.instructions.md)
- [Pattern Development](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/pattern-development.instructions.md)
- [PHP Block Instructions](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/php-block.instructions.md)
- [Theme JSON](https://github.com/lightspeedwp/.github/blob/HEAD/.github/instructions/block-theme/theme-json.instructions.md)
- When generating a summary for pull requests, use this [pull request template](https://github.com/lightspeedwp/.github/blob/HEAD/.github/PULL_REQUEST_TEMPLATE.md).

---

## For Contributors & Maintainers

- **Always start here** when onboarding, contributing, or reviewing.
- Reference **instructions** for standards, **templates** for issues/PRs, and **automation** docs for workflows and governance.
- Use **saved replies** for common support scenarios; update them as needed.
- For agent/Copilot questions, see the agent guides and custom instructions.
- Update this folder when org-wide standards, workflows, or automation rules change.
Expand Down Expand Up @@ -575,10 +562,9 @@ This repository and all its contents are licensed under the GNU General Public L

## 🔧 Development Standards

- [💻 Coding Standards](./instructions/coding-standards.instructions.md) - Unified development guidelines
- [🎨 Linting Instructions](./instructions/linting.instructions.md) - Code quality and formatting
- [🏗️ Pattern Development](./instructions/block-theme/pattern-development.instructions.md) - WordPress block patterns
- [🌐 HTML Templates](./instructions/block-theme/html-template.instructions.md) - Semantic markup standards
- [💻 Coding Standards](../instructions/coding-standards.instructions.md) - Unified development guidelines
- [🎨 Linting Instructions](../instructions/linting.instructions.md) - Code quality and formatting
- [🏗️ Plugin Structure](../instructions/plugin-structure.instructions.md) - WordPress block plugin development

---

Expand Down
57 changes: 37 additions & 20 deletions .github/docs/workflow-coordination.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: "Workflow Coordination Patterns"
description: "Canonical reference for GitHub Actions workflow patterns: always-run vs. agent-triggered, coordination between agents and workflows, and orchestration strategies."
created_date: "2026-05-28"
last_updated: "2026-05-28"
version: "v1.0.0"
version: "v1.1.0"
file_type: "documentation"
maintainer: "LightSpeed Team"
tags: ["workflows", "automation", "agents", "coordination", "ci-cd"]
Expand Down Expand Up @@ -80,14 +80,15 @@ Agent-triggered workflows are invoked **on demand** via `workflow_dispatch` or c

### Agent-Triggered Workflow Registry

| Workflow | Primary Trigger | Agent | Purpose |
| Workflow | Primary Trigger | Agent/Caller | Purpose |
| --- | --- | --- | --- |
| `release.yml` | workflow_dispatch + workflow_call | Release Agent | Orchestrate semantic versioning, tag, publish |
| `planner.yml` | workflow_dispatch | Planner Agent | Generate implementation plans |
| `reporting.yml` | workflow_dispatch | Reporting Agent | Generate audit/metric reports |
| `reviewer.yml` | workflow_dispatch (manual) | Reviewer Agent | Post PR review summaries |
| `metrics.yml` | workflow_dispatch ± scheduled | Metrics Agent | Collect repo health metrics |
| `project-meta-sync.yml` | workflow_dispatch | Project Meta Sync Agent | Sync GitHub Project board fields |
| `readme-update.yml` | workflow_dispatch + workflow_call | Release Agent (post-release) | Apply README & Mermaid diagram fixes |

### When to Use

Expand Down Expand Up @@ -139,37 +140,53 @@ Release Agent (Orchestrator)

---

## Proposed New Workflows (Wave 3C)
## Implemented Workflows (Wave 3C & Beyond)

Wave 3C (Workflow & Agent Coordination Setup) will introduce two new agent-triggered workflows for README audits:
Wave 3C (Workflow & Agent Coordination Setup) introduces new agent-triggered workflows for README management:

### `readme-audit.yml`
### `readme-update.yml`

**Trigger**: `workflow_dispatch` (via README Review Agent)
**Trigger**: `workflow_dispatch` (manual) or `workflow_call` (from Release Agent)

**Purpose**: Run Mermaid diagram syntax validation, WCAG compliance checks, and staleness detection
**Purpose**: Apply automated fixes to README files and embedded Mermaid diagrams

**Calls**:
**Capabilities**:

- Mermaid validator (external or custom)
- WCAG contrast checker
- Staleness detector (compare `last_updated` to current date)
- Fix Mermaid diagram formatting and add accessibility attributes (`accTitle`, `accDescr`)
- Update stale frontmatter dates for files exceeding 6-month threshold
- Support selective scope: `all` (default), `mermaid` (diagrams only), or `staleness` (dates only)
- Dry-run mode for safe preview before applying changes
- Generate audit report with change summary

**Output**: `.github/reports/mermaid-audit/audit-results.json`
**Input Parameters**:

### `readme-update.yml`
- `scope`: "all" | "mermaid" | "staleness" (default: "all")
- `dry_run`: "true" | "false" (default: "false" — applies changes)

**Output**:

**Trigger**: `workflow_dispatch` (via README Review Agent)
- Updated README files (if not dry-run)
- Report: `.github/reports/mermaid-audit/update-report.md`
- Artifact: `readme-update-report` (always)

**Purpose**: Apply fixes to README files and embedded Mermaid diagrams
**Integration Points**:

**Calls**:
- Called by Release Agent in post-release phase
- Can be manually triggered via GitHub UI for ad-hoc updates
- Non-blocking: failures do not prevent release completion

- Mermaid formatter (auto-fix syntax)
- Accessibility enhancer (add `accTitle`, `accDescr`)
- Link validator and updater
**Example Release Agent Invocation**:

**Output**: PR with fixes grouped by category
```yaml
- name: Apply README updates
uses: actions/workflow_dispatch@v4
with:
workflow: readme-update.yml
ref: main
inputs:
scope: all
dry_run: 'false'
Comment on lines +181 to +188
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example uses actions/workflow_dispatch@v4 which is not an official or valid GitHub Action. Since readme-update.yml supports workflow_call, it should be invoked directly as a reusable workflow using the standard uses syntax. Additionally, please rename this file to WORKFLOW_COORDINATION.md to comply with the rule that documentation and governance files in the docs/ directory must use UPPERCASE naming with underscores.

Suggested change
- name: Apply README updates
uses: actions/workflow_dispatch@v4
with:
workflow: readme-update.yml
ref: main
inputs:
scope: all
dry_run: 'false'
- name: Apply README updates
uses: ./.github/workflows/readme-update.yml
with:
scope: all
dry_run: 'false'
References
  1. Documentation and governance files in the docs/ directory must use UPPERCASE naming with underscores (e.g., GOVERNANCE_REVISION_LOG.md), as the lowercase-with-hyphens naming convention applies to other asset types and not to docs/ files.

```
Comment on lines +180 to +189
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Correct the workflow invocation syntax in the example.

The example uses actions/workflow_dispatch@v4, but that action doesn't exist. To call a workflow from another workflow, use uses: with the workflow path; to trigger via script/agent, use the GitHub API or gh workflow run.

🔧 Proposed fix for workflow_call pattern 
 **Example Release Agent Invocation**:
 
 ```yaml
-- name: Apply README updates
-  uses: actions/workflow_dispatch@v4
-  with:
-    workflow: readme-update.yml
-    ref: main
-    inputs:
-      scope: all
-      dry_run: 'false'
+- name: Apply README updates (post-release)
+  uses: ./.github/workflows/readme-update.yml
+  with:
+    scope: all
+    dry_run: 'false'
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/docs/workflow-coordination.md around lines 180 - 189, The example
workflow invocation "Apply README updates" incorrectly uses
actions/workflow_dispatch@v4; replace that with a direct workflow call by
setting uses: ./.github/workflows/readme-update.yml and keep the with inputs
(scope and dry_run) while removing the invalid workflow and ref keys, or
alternatively document using the GitHub API or gh workflow run if you intend to
trigger a workflow remotely; update the example to use uses:
./.github/workflows/readme-update.yml and preserve inputs scope and dry_run
accordingly.


---

Expand Down
Loading
Loading