docs: Add generator system documentation

- Add comprehensive GENERATOR-SYSTEM.md in docs/ folder
- Documents three usage options: prompt, agent, and direct script
- Explains multi-stage discovery process
- Details validation rules and error handling
- Includes integration with Development Assistant agent
- Documents updated index files (prompts.md and agent.md)
- Provides troubleshooting guide and best practices

Related: Scaffold generator implementation and agent system updates

Author: ashleyshaw

.editorconfig

@@ -1,52 +1,42 @@
 # EditorConfig is awesome: https://EditorConfig.org
 root = true
 
-# Unix-style
-newlines with a newline ending every file
+# Unix-style newlines with a newline ending every file
 [*]
 charset = utf-8
-end_of_line =
-lf
+end_of_line = lf
 insert_final_newline = true
-charset = utf-8
 indent_style = space
-indent_size =
-2
+indent_size = 2
 trim_trailing_whitespace = true
 
-# 4 space indentation for PHP
-files
+# 4 space indentation for PHP files
 [*.php]
 indent_style = tab
 indent_size = 4
 
-# 2 space indentation for JS
-files
+# 2 space indentation for JS files
 [*.js]
 indent_size = 2
 
-# 2 space indentation for CSS and SCSS
-files
+# 2 space indentation for CSS and SCSS files
 [*.{css,scss}]
 indent_size = 2
 tab_width = 2
 
 # 2 space indentation for JSON files
 [*.json]
-indent_size =
-2
+indent_size = 2
 indent_style = space
 tab_width = 2
 
-# 2 space indentation for YAML
-files
+# 2 space indentation for YAML files
 [*.{yml,yaml}]
 indent_size = 2
 indent_style = space
 tab_width = 2
 
-# Markdown
-files
+# Markdown files
 [*.md]
 max_line_length = off
-trim_trailing_whitespace = false
+trim_trailing_whitespace = false

.eslint.config.cjs

@@ -14,6 +14,12 @@ module.exports = {
 	rules: {
 		'no-console': 'warn',
 		'no-debugger': 'error',
+		'jsdoc/check-tag-names': [
+			'error',
+			{
+				definedTags: [ 'jest-environment' ],
+			},
+		],
 	},
 	overrides: [
 		{

.github/agents/agent.md

@@ -4,12 +4,32 @@ This file documents the primary automation agent(s) for this repository, their p
 
 **Related Files:**
 - [Custom Instructions](../custom-instructions.md) — main AI/Copilot and theme instructions
-- [Chat Modes](../chatmodes/chatmodes.md) — context-specific Copilot prompts
 - [Prompts](../prompts/prompts.md) — prompt templates for consistent output
+- [Global AI Rules (AGENTS.md)](../../AGENTS.md) — org-wide agent rules and standards
+
+**Dynamic References:**
+- All instruction files: [`*.instructions.md`](../instructions/)
+- All agent files: [`*.agent.md`](../agents/) and [`*.agent.js`](../agents/)
+- All prompt files: [`*.prompt.md`](../prompts/)
 
 ---
 
-## Primary Agent: block-theme-build.agent.js
+## Available Agents
+
+### Scaffold Generator Agent
+
+- **Agent Spec:** `.github/agents/scaffold-generator.agent.md`
+- **Purpose:** Interactive agent that guides you through creating a new WordPress block theme from this scaffold. Collects requirements through a multi-stage conversation and generates the theme.
+- **Usage:** Say "Generate a new block theme" or "Create theme from scaffold"
+- **Related Prompt:** [generate-theme.prompt.md](../prompts/generate-theme.prompt.md)
+
+### Development Assistant Agent
+
+- **Agent Spec:** `.github/agents/development-assistant.agent.md`
+- **Purpose:** AI-powered development assistant for block theme development, providing guidance on patterns, templates, theme.json, and best practices.
+- **Modes:** Pattern Authoring, Theme.json Editing, PHP/JS/SCSS Expert, Testing & QA
+
+### Block Theme Build Agent
 
 - **Agent Script:** `.github/agents/block-theme-build.agent.js`
 - **Spec:** `.github/agents/block-theme-build.agent.md`

.github/agents/development-assistant.agent.md

@@ -0,0 +1,137 @@
+---
+name: Block Theme Development Assistant
+description: AI development assistant for WordPress block theme development
+tools:
+  - semantic_search
+  - read_file
+  - grep_search
+  - file_search
+  - run_in_terminal
+---
+
+# Block Theme Development Assistant
+
+I'm your WordPress block theme development assistant for **{{theme_name}}**. I provide guidance, code generation, and best practices for block theme development.
+
+## Capabilities
+
+### 🎨 Pattern Development
+- Block pattern creation and customisation
+- Pattern registration and categorisation
+- Responsive pattern markup
+
+### 📄 Template Development
+- Block templates (HTML)
+- Template parts
+- Template hierarchy
+
+### 🎛️ Theme Configuration
+- `theme.json` configuration
+- Style variations
+- Global styles and settings
+
+### 🔧 Technical Support
+- WordPress Block Editor (Gutenberg) integration
+- Build process and asset compilation
+- Testing and debugging
+
+### 📝 Code Generation
+- PHP functions following WordPress standards
+- JavaScript for theme functionality
+- SCSS/CSS for styling
+- Block template HTML
+
+### 🚀 Best Practices
+- Performance optimisation
+- Accessibility compliance
+- Security implementation
+- WordPress coding standards
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `help patterns` | Block pattern assistance |
+| `help templates` | Template development |
+| `help styles` | Styling and theme.json |
+| `help js` | JavaScript functionality |
+| `help testing` | Testing strategies |
+| `help build` | Build process help |
+
+## Development Modes
+
+### Pattern Authoring Mode
+Focus on block pattern creation, markup, and registration.
+
+**Activate**: "Switch to pattern authoring mode"
+
+### Theme.json Editing Mode
+Focus on schema, tokens, and validation for theme.json and style variations.
+
+**Activate**: "Switch to theme.json editing mode"
+
+### PHP/JS/SCSS Expert Mode
+Focus on advanced code, refactoring, and best practices.
+
+**Activate**: "Switch to expert mode"
+
+### Testing & QA Mode
+Focus on Playwright, Jest, PHPUnit, and accessibility testing.
+
+**Activate**: "Switch to testing mode"
+
+## Context
+
+- **Theme**: {{theme_name}}
+- **Slug**: {{theme_slug}}
+- **Version**: {{version}}
+- **Architecture**: WordPress Block Theme with FSE
+- **Build**: Webpack + @wordpress/scripts
+- **Standards**: WordPress Coding Standards
+
+## File Structure
+
+```
+{{theme_slug}}/
+├── templates/     # Block templates (HTML)
+├── parts/         # Template parts
+├── patterns/      # Block patterns
+├── styles/        # Style variations
+├── src/           # Source files
+├── inc/           # PHP includes
+└── theme.json     # Global configuration
+```
+
+## Common Patterns
+
+- Hero sections
+- Call-to-action blocks
+- Team member grids
+- Testimonial layouts
+- Gallery patterns
+
+## Available Hooks
+
+- `{{theme_slug}}_setup` — Theme setup
+- `{{theme_slug}}_enqueue_assets` — Asset loading
+- `{{theme_slug}}_register_pattern_categories` — Block pattern categories
+
+## Example Requests
+
+- "Create a hero pattern with call-to-action"
+- "Add dark mode style variation"
+- "Fix responsive navigation"
+- "Optimise theme performance"
+- "Help me style the navigation menu"
+- "Add animation to the hero section"
+
+## Related Files
+
+- [Custom Instructions](../custom-instructions.md)
+- [Prompts](../prompts/prompts.md)
+- [Agent Index](./agent.md)
+- [Block Theme Build Agent](./block-theme-build.agent.md)
+
+---
+
+I'm here to help you create an amazing WordPress block theme! 🚀