Add general agent script, workflow, and documentation

Introduces a functional Node.js agent script (.github/agents/agent-script.js) that lists files and outputs environment info, along with a corresponding GitHub Actions workflow (.github/workflows/agent-workflow.yml) for automation and artifact upload. Updates agent documentation to reference the new agent and workflow as templates for future automation. Adds generate-plugin.md to document plugin generation and build/test scripts.

Author: ashleyshaw

.github/agents/agent-script.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// agent-script.js
+// Functional agent script: lists files in the current directory and writes output to a file.
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const env = {
+	DRY_RUN: process.env.DRY_RUN,
+	VERBOSE: process.env.VERBOSE,
+	GITHUB_TOKEN: process.env.GITHUB_TOKEN ? '***' : undefined
+};
+
+console.log('Agent Script Running');
+console.log('Arguments:', args);
+console.log('Environment:', env);
+
+// List files in the current directory
+const files = fs.readdirSync(process.cwd());
+console.log('Files in current directory:', files);
+
+// Write output to a file for workflow artifact
+const output = {
+	args,
+	env,
+	files
+};
+const outputPath = path.join(process.cwd(), 'agent-output.json');
+fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+console.log('Output written to', outputPath);
+
+process.exit(0);

.github/agents/agent.md

@@ -14,17 +14,30 @@ This file documents the primary automation agent(s) for this repository, their p
 
 ---
 
-## Primary Agent: wp-block-build.agent.js
+## Primary Agents
 
--   **Agent Script:** `.github/agents/wp-block-build.agent.js`
--   **Spec:** `.github/agents/wp-block-build.agent.md`
--   **Workflow:** `.github/workflows/block-plugin-build-and-e2e.yml`
--   **Purpose:** Automate build, lint, test, and validation for this block plugin using WordPress and org standards.
+-   **Block Plugin Build Agent:**
+
+    -   **Agent Script:** `.github/agents/wp-block-build.agent.js`
+    -   **Spec:** `.github/agents/wp-block-build.agent.md`
+    -   **Workflow:** `.github/workflows/block-plugin-build-and-e2e.yml`
+    -   **Purpose:** Automate build, lint, test, and validation for this block plugin using WordPress and org standards.
+
+-   **General Automation Agent Example:**
+    -   **Agent Script:** `.github/agents/agent-script.js`
+    -   **Workflow:** `.github/workflows/agent-workflow.yml`
+    -   **Purpose:** Demonstrates a functional Node.js agent and workflow for file listing, environment echo, and artifact upload. Use as a template for new automation agents.
 
 ### Usage
 
--   **GitHub Actions:** See the workflow file for triggers and environment variables
--   **Local:** `node .github/agents/wp-block-build.agent.js`
+-   **Block Plugin Build Agent:**
+
+    -   **GitHub Actions:** See `.github/workflows/block-plugin-build-and-e2e.yml` for triggers and environment variables
+    -   **Local:** `node .github/agents/wp-block-build.agent.js`
+
+-   **General Automation Agent Example:**
+    -   **GitHub Actions:** See `.github/workflows/agent-workflow.yml` for triggers and environment variables
+    -   **Local:** `node .github/agents/agent-script.js --example`
 
 ### Environment Variables
 
@@ -34,10 +47,15 @@ This file documents the primary automation agent(s) for this repository, their p
 
 ### Maintenance
 
--   Keep the agent aligned with repo tooling (linters, build, tests)
+-   Keep all agents aligned with repo tooling (linters, build, tests)
 -   Update documentation and scripts as workflows evolve
 -   See [WP Block Build Agent Spec](./wp-block-build.agent.md) for detailed build process and requirements
+-   Use `.github/agents/agent-script.js` and `.github/workflows/agent-workflow.yml` as a starting point for new automation agents. Update references in this file and in all AI ops/instruction files as new agents are added.
 
 ---
 
+---
+
+> **Note:** The files `.github/agents/agent-script.js` and `.github/workflows/agent-workflow.yml` are now functional examples. Use them as templates for new agents. All AI ops and instruction files (see Related Files above) should reference these agents and workflows as appropriate for discoverability and onboarding.
+
 For more information on agent usage, see [Custom Instructions](../custom-instructions.md), [Workflows](../../workflows/), and [Global AI Rules (AGENTS.md)](../../AGENTS.md).

.github/workflows/agent-workflow.yml

@@ -0,0 +1,26 @@
+jobs:
+name: Agent Workflow
+
+on:
+    workflow_dispatch:
+
+    agent-job:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '18.x'
+            - name: Run agent script
+              run: |
+                  node .github/agents/agent-script.js --from-workflow
+              env:
+                  DRY_RUN: false
+                  VERBOSE: true
+            - name: Upload agent output
+              uses: actions/upload-artifact@v4
+              with:
+                  name: agent-output
+                  path: agent-output.json

docs/generate-plugin.md

@@ -0,0 +1,135 @@
+# Single Block Plugin Generation & Build Scripts
+
+This document explains how to use the scripts in the `bin/` directory to generate, build, and test a new single block plugin from this scaffold.
+
+## Overview
+
+The `bin/` directory contains utility scripts for:
+
+- Generating a new single block plugin from the scaffold with custom metadata
+- Building the plugin for production
+- Running all tests and static analysis
+- Updating the plugin version across all files
+- Setting up the WordPress PHPUnit test environment
+
+## Scripts
+
+### 1. `generate-single-block-plugin.js`
+
+Generates a new plugin by copying the scaffold and replacing all mustache placeholders with your provided values.
+
+**Usage:**
+
+```sh
+node bin/generate-single-block-plugin.js --slug my-block --name "My Block" --description "Description here" --author "Your Name" --author_uri "https://yourdomain.com" --version "1.0.0"
+```
+
+- The generated plugin will be placed in an `output-plugin/` directory in your current working directory.
+- All placeholders like `{{slug}}`, `{{name}}`, etc., will be replaced with your values.
+- You can safely edit the generated plugin independently of the scaffold.
+
+**Arguments:**
+
+- `--slug` (required): Plugin slug (e.g., `my-block`)
+- `--name`: Plugin display name
+- `--description`: Plugin description
+- `--author`: Author name
+- `--author_uri`: Author website
+- `--version`: Plugin version
+
+### 2. `build.sh`
+
+Builds the plugin, installs dependencies, lints, and runs tests.
+
+**Usage:**
+
+```sh
+bin/build.sh
+```
+
+- Installs Node.js and Composer dependencies
+- Builds plugin assets
+- Runs linting and tests
+- Outputs a summary and next steps
+
+### 3. `test.sh`
+
+Runs all plugin tests (JS, PHP, E2E) and static analysis.
+
+**Usage:**
+
+```sh
+bin/test.sh
+```
+
+- Installs dependencies if needed
+- Runs JavaScript and PHP unit tests
+- Runs PHP static analysis and linting
+- Runs E2E tests if `wp-env` is available
+
+### 4. `update-version.js`
+
+Updates the plugin version across all relevant files.
+
+**Usage:**
+
+```sh
+node bin/update-version.js <new-version>
+```
+
+- Updates `package.json`, `composer.json`, main plugin file, block.json, and README.md
+- Prints a summary and next steps
+
+### 5. `install-wp-tests.sh`
+
+Shell script to set up the WordPress PHPUnit test environment. Used internally for CI and local test setup.
+
+**Usage:**
+
+```sh
+bin/install-wp-tests.sh <wp-version> <db-name> <db-user> <db-pass> [db-host]
+```
+
+- Downloads and configures the WordPress test suite for PHP unit testing.
+
+## Workflow Example
+
+1. Generate a new plugin:
+
+   ```sh
+   node bin/generate-single-block-plugin.js --slug my-block --name "My Block" --description "A custom block" --author "Jane Doe"
+   ```
+
+2. Enter the generated plugin directory:
+
+   ```sh
+   cd output-plugin
+   ```
+
+3. Build the plugin:
+
+   ```sh
+   bin/build.sh
+   ```
+
+4. Run all tests:
+
+   ```sh
+   bin/test.sh
+   ```
+
+5. Update the version:
+
+   ```sh
+   node bin/update-version.js 1.2.0
+   ```
+
+## Notes
+
+- The `build.sh` and `test.sh` scripts expect a valid `package.json` and `composer.json` in the plugin root.
+- The `generate-single-block-plugin.js` script will not overwrite an existing `output-plugin/` directory.
+- For advanced usage, see comments in each script.
+
+---
+
+For more details, see the inline documentation in each script in the `bin/` directory.