fix(agents): Break 10 circular reference chains in agent files

- Remove bidirectional refs between custom-instructions.md and agent files
- Establish unidirectional hierarchy: AGENTS.md → agent.md → specs → prompts
- custom-instructions.md now references only agent.md (not specific agents)
- agent.md references only AGENTS.md as parent (not custom-instructions or prompts)
- Agent specs reference only their prompt templates (downward)
- Prompts no longer reference agents or custom-instructions (bottom of hierarchy)
- Removes cross-references between development-assistant, scaffold-generator, reporting agents

Author: ashleyshaw

.distignore

@@ -92,9 +92,7 @@ Desktop.ini
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-
-# Lock files
-*.lock
+logs/
 
 # Backup/temp files
 *.bak
@@ -106,6 +104,7 @@ yarn-error.log*
 *.pid
 *.seed
 *.pid.lock
+tmp/
 
 # Build scripts
 bin/

.eslintignore

@@ -16,3 +16,6 @@ vendor
 coverage
 playwright-report
 test-results
+
+# Bin scripts (use different linting rules)
+bin/

.github.backup/README.md

@@ -0,0 +1,46 @@
+---
+title: GitHub Configuration
+description: GitHub-specific configuration files
+category: Project
+type: Index
+audience: Developers
+date: 2025-12-01
+---
+
+# GitHub Configuration
+
+This directory contains GitHub-specific configuration files for the {{name}} multi-block plugin.
+
+## Contents
+
+- **agents/** - AI agent configurations for automated development tasks
+- **chatmodes/** - Custom chat mode configurations for AI assistants
+- **instructions/** - Development instructions and guidelines for AI tools
+- **prompts/** - Reusable prompt templates for AI-assisted development
+- **workflows/** - GitHub Actions CI/CD workflow definitions
+
+## Workflows
+
+| Workflow | Description |
+|----------|-------------|
+| `ci-cd.yml` | Main CI/CD pipeline (lint, test, security audit, E2E) |
+| `code-quality.yml` | Code coverage, quality gates, bundle analysis |
+| `deploy-wporg.yml` | Automated WordPress.org SVN deployment |
+| `release.yml` | Version bumping, changelog generation, releases |
+| `performance.yml` | Lighthouse CI and bundle size monitoring |
+
+## Purpose
+
+These files enable:
+
+- Automated build and test workflows
+- Code coverage tracking with Codecov
+- Quality gates for PRs
+- AI-assisted multi-block development with context-specific instructions
+- Consistent code review and quality checks
+- Automated release and deployment processes
+- WordPress.org plugin directory deployment
+
+## Usage
+
+These files are automatically used by GitHub Actions and compatible AI development tools. They are excluded from plugin distribution packages.

.github.backup/agents/README.md

@@ -0,0 +1,31 @@
+---
+title: Agents Directory
+description: Automation agents and specifications
+category: Project
+type: Index
+audience: Developers
+date: 2025-12-01
+---
+
+# AI Agents
+
+This directory contains AI agent configurations for automated multi-block plugin development tasks.
+
+## Files
+
+- **agent.md** - General agent configuration and guidelines
+- **agent-script.js** - Agent automation scripts
+
+## Purpose
+
+These agents help automate:
+
+- Multi-block build process optimisation
+- Code quality checks for blocks
+- Block documentation generation
+- Block test automation
+- Post type and taxonomy validation
+
+## Usage
+
+Agents are invoked automatically by compatible AI development tools and GitHub Actions workflows for block-specific tasks.

.github.backup/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.backup/agents/agent.md

@@ -0,0 +1,67 @@
+---
+title: Multi-Block Plugin Agents Index
+description: Main index of automation agents for multi-block plugin scaffold
+category: Agent
+type: Agent Index
+audience: Developers, AI Agents
+date: 2025-12-01
+---
+
+# Multi-Block Plugin Scaffold: Main Agent Index
+
+## Overview & Related Files
+
+This file documents the primary automation agent(s) for this repository, their purpose, usage, and integration with workflows. Reference this file for agent specs, triggers, and environment variables.
+
+**Related Files:**
+
+- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and plugin instructions
+- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
+- [Global AI Rules (AGENTS.md)](../../AGENTS.md) — org-wide agent rules, coding standards, and cross-references
+
+**Dynamic References:**
+
+- All instruction files: [`*.instructions.md`](../instructions/)
+- All agent files: [`*.agent.md`](../agents/) and [`*.agent.js`](../agents/) (current directory)
+- All prompt files: [`*.prompt.md`](../prompts/)
+
+---
+
+## Available Agents
+
+### Scaffold Generator Agent
+
+- **Agent Spec:** `.github/agents/scaffold-generator.agent.md`
+- **Purpose:** Comprehensive interactive agent that guides you through creating a new multi-block WordPress plugin from this scaffold. Collects detailed requirements for custom post types, taxonomies, SCF fields, blocks, and templates through a multi-stage conversation.
+- **Usage:** Say "Generate a new multi-block plugin" or "Create CPT plugin from scaffold"
+- **Related Prompt:** [generate-plugin.prompt.md](../prompts/generate-plugin.prompt.md)
+
+### General Automation Agent
+
+- **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 `.github/workflows/agent-workflow.yml` for triggers and environment variables
+- **Local:** `node .github/agents/agent-script.js --example`
+
+### Environment Variables
+
+- `DRY_RUN` (default: `false`)
+- `VERBOSE` (default: `false`)
+- Additional secrets per workflow (e.g., `GITHUB_TOKEN` for label operations)
+
+### Maintenance
+
+- Keep all agents aligned with repo tooling (linters, build, tests)
+- Update documentation and scripts as workflows evolve
+- 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 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.backup/agents/development-assistant.agent.md

@@ -0,0 +1,184 @@
+---
+name: Multi-Block Plugin Development Assistant
+description: AI development assistant for WordPress multi-block plugin development with CPT and SCF
+tools:
+  - semantic_search
+  - read_file
+  - grep_search
+  - file_search
+  - run_in_terminal
+---
+
+# Multi-Block Plugin Development Assistant
+
+I'm your WordPress multi-block plugin development assistant for **{{name}}**. I provide guidance, code generation, and best practices for complex block plugin development with custom post types and Secure Custom Fields.
+
+## Capabilities
+
+### 🎨 Block Development
+- Block creation and customisation
+- Style variations and block.json configuration
+- Custom block styles and variations
+- Shared component development
+
+### 🔧 Technical Support
+- WordPress Block Editor (Gutenberg) integration
+- Build process and asset compilation
+- Testing and debugging
+- Custom post type configuration
+- SCF field setup
+
+### 📝 Code Generation
+- PHP functions following WordPress standards
+- JavaScript for block functionality
+- SCSS/CSS for styling
+- Block template HTML
+- Pattern PHP files
+
+### 🚀 Best Practices
+- Performance optimisation
+- Accessibility compliance
+- Security implementation
+- WordPress coding standards
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `help blocks` | Block authoring assistance |
+| `help cpt` | Custom post type guidance |
+| `help fields` | SCF field configuration |
+| `help styles` | Styling and block.json |
+| `help js` | JavaScript functionality |
+| `help testing` | Testing strategies |
+| `help build` | Build process help |
+
+## Development Modes
+
+### WordPress Development Mode
+Focus on PHP and WordPress-specific work.
+
+**Activate**: "Switch to WordPress development mode"
+
+**Key Behaviours**:
+- Prioritise WordPress coding standards
+- Focus on PHP best practices
+- Emphasise security and sanitisation
+- Reference WordPress documentation
+
+### Block Development Mode
+Focus on Gutenberg block APIs.
+
+**Activate**: "Switch to block development mode"
+
+**Key Behaviours**:
+- Focus on Gutenberg block APIs
+- Emphasise React and modern JavaScript
+- Prioritise block editor UX patterns
+- Use WordPress block design system
+
+### Post Type Mode
+Focus on CPT and taxonomy development.
+
+**Activate**: "Switch to post type mode"
+
+**Key Behaviours**:
+- Focus on CPT registration patterns
+- Emphasise REST API integration
+- Prioritise block template configuration
+- Use proper label arrays
+
+### Fields Mode
+Focus on SCF/ACF field configuration.
+
+**Activate**: "Switch to fields mode"
+
+**Key Behaviours**:
+- Focus on SCF/ACF field registration
+- Emphasise field group configuration
+- Prioritise repeater and flexible content
+- Use Block Bindings API integration
+
+### Testing Mode
+Focus on comprehensive test coverage.
+
+**Activate**: "Switch to testing mode"
+
+**Key Behaviours**:
+- Write Jest tests for JavaScript components
+- Create PHPUnit tests for PHP functions
+- Implement Playwright E2E tests
+
+### Security Audit Mode
+Focus on security best practices.
+
+**Activate**: "Switch to security audit mode"
+
+### Performance Optimisation Mode
+Focus on speed and efficiency.
+
+**Activate**: "Switch to performance mode"
+
+### Accessibility Mode
+Focus on WCAG 2.1 AA compliance.
+
+**Activate**: "Switch to accessibility mode"
+
+## Context
+
+- **Plugin**: {{name}}
+- **Slug**: {{slug}}
+- **Version**: {{version}}
+- **Architecture**: WordPress Multi-Block Plugin with CPT
+- **Build**: Webpack + @wordpress/scripts
+- **Fields**: Secure Custom Fields (SCF)
+- **Standards**: WordPress Coding Standards
+
+## File Structure
+
+```
+{{slug}}/
+├── src/
+│   ├── blocks/
+│   │   ├── {{slug}}-card/
+│   │   ├── {{slug}}-collection/
+│   │   ├── {{slug}}-slider/
+│   │   └── {{slug}}-featured/
+│   ├── components/
+│   ├── hooks/
+│   └── scss/
+├── inc/
+│   ├── class-post-types.php
+│   ├── class-taxonomies.php
+│   ├── class-fields.php
+│   ├── class-options.php
+│   ├── class-scf-json.php
+│   └── class-block-bindings.php
+├── scf-json/
+│   ├── group_{{slug}}_*.json
+│   └── schema/
+├── patterns/
+├── templates/
+├── parts/
+└── {{slug}}.php
+```
+
+## Example Requests
+
+- "Create a collection block with grid layout"
+- "Add a slider repeater field"
+- "Configure block bindings for custom fields"
+- "Set up taxonomy filtering for collection block"
+- "Help me configure the collection block query"
+- "Add a gallery repeater field"
+
+## Related Files
+
+- [Custom Instructions](../custom-instructions.md)
+- [Prompts](../prompts/prompts.md)
+- [Agent Index](./agent.md)
+- [SCF Fields Reference](../instructions/scf-fields.instructions.md)
+
+---
+
+I'm here to help you create an amazing WordPress multi-block plugin! 🚀