Add README.md to all folders and update .distignore to exclude markdown files except main README

Author: ashleyshaw

.distignore

@@ -15,6 +15,7 @@ Thumbs.db
 .env.*
 *.md
 !README.md
+!README.txt
 !CHANGELOG.md
 package.json
 package-lock.json

.github/README.md

@@ -0,0 +1,24 @@
+# GitHub Configuration
+
+This directory contains GitHub-specific configuration files for the {{theme_name}} theme.
+
+## 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
+
+## Purpose
+
+These files enable:
+
+- Automated build and test workflows
+- AI-assisted development with context-specific instructions
+- Consistent code review and quality checks
+- Automated release and deployment processes
+
+## Usage
+
+These files are automatically used by GitHub Actions and compatible AI development tools. They are excluded from theme distribution packages via `.distignore`.

.github/agents/README.md

@@ -0,0 +1,23 @@
+# AI Agents
+
+This directory contains AI agent configurations for automated development tasks.
+
+## Files
+
+- **agent.md** - General agent configuration and guidelines
+- **agent-script.js** - Agent automation scripts
+- **block-theme-build.agent.js** - Build automation agent script
+- **block-theme-build.agent.md** - Build agent documentation
+
+## Purpose
+
+These agents help automate:
+
+- Build process optimization
+- Code quality checks
+- Documentation generation
+- Test automation
+
+## Usage
+
+Agents are invoked automatically by compatible AI development tools and GitHub Actions workflows.

.github/chatmodes/README.md

@@ -0,0 +1,20 @@
+# Chat Modes
+
+This directory contains custom chat mode configurations for AI assistants.
+
+## Files
+
+- **chatmodes.md** - Chat mode definitions and usage guidelines
+
+## Purpose
+
+Chat modes provide context-specific AI assistance for:
+
+- Theme development
+- Block pattern creation
+- WordPress coding standards
+- Troubleshooting and debugging
+
+## Usage
+
+Chat modes are automatically recognized by compatible AI development tools and provide specialized assistance based on the development context.

.github/instructions/README.md

@@ -0,0 +1,25 @@
+# Development Instructions
+
+This directory contains detailed instructions and guidelines for AI-assisted development.
+
+## Files
+
+- **index.md** - Instructions directory index
+- **block-theme.instructions.md** - Block theme development guidelines
+- **php-wordpress.instructions.md** - WordPress PHP coding standards
+- **playwright-tests.instructions.md** - E2E testing guidelines
+- **testing.instructions.md** - General testing guidelines
+- **theme-json.instructions.md** - theme.json configuration guidelines
+
+## Purpose
+
+These instructions help AI tools understand:
+
+- WordPress theme development best practices
+- Coding standards and conventions
+- Testing requirements and patterns
+- Configuration file structures
+
+## Usage
+
+Instructions are automatically loaded by AI development tools to provide context-aware assistance throughout the development process.

.github/prompts/README.md

@@ -0,0 +1,20 @@
+# AI Prompts
+
+This directory contains reusable prompt templates for AI-assisted development.
+
+## Files
+
+- **prompts.md** - Prompt template definitions and examples
+
+## Purpose
+
+Prompt templates provide:
+
+- Consistent AI interaction patterns
+- Reusable code generation templates
+- Standardized documentation formats
+- Common development task workflows
+
+## Usage
+
+Prompts are referenced by AI development tools to generate consistent, high-quality code and documentation that follows WordPress and theme development standards.

.github/workflows/README.md

@@ -0,0 +1,31 @@
+# GitHub Actions Workflows
+
+This directory contains GitHub Actions workflow definitions for CI/CD automation.
+
+## Workflows
+
+- **agent-workflow.yml** - AI agent automation workflow
+- **block-theme-build-and-e2e.yml** - Build and end-to-end testing workflow
+- Additional workflows for testing, linting, and deployment
+
+## Purpose
+
+These workflows automate:
+
+- Building theme assets on push/PR
+- Running automated tests (unit, integration, E2E)
+- Code quality checks (linting, formatting)
+- Version management and releases
+
+## Triggers
+
+Workflows typically run on:
+
+- Push to main/develop branches
+- Pull request creation/updates
+- Manual workflow dispatch
+- Scheduled intervals (for maintenance tasks)
+
+## Usage
+
+GitHub Actions automatically executes these workflows based on configured triggers. Check individual workflow files for specific configuration details.

.husky/README.md

@@ -0,0 +1,39 @@
+# Husky Git Hooks
+
+This directory contains Git hook scripts managed by Husky.
+
+## Hooks
+
+- **pre-commit** - Runs before each commit to ensure code quality
+
+## Purpose
+
+Git hooks enforce:
+
+- Code linting before commits
+- Code formatting standards
+- Test execution for changed files
+- Preventing commits with errors
+
+## Pre-commit Hook
+
+The pre-commit hook typically runs:
+
+- ESLint for JavaScript files
+- Stylelint for CSS/SCSS files
+- PHP_CodeSniffer for PHP files
+- Prettier formatting checks
+
+## Configuration
+
+Hooks are automatically installed when running `npm install` and are configured through Husky settings in `package.json`.
+
+## Bypassing Hooks
+
+In special cases (like scaffold repositories), you can bypass hooks with:
+
+```bash
+git commit --no-verify -m "commit message"
+```
+
+**Note**: Only bypass hooks when absolutely necessary.