feat(ci): add GitHub Actions workflow for markdown linting and valida…

.github/workflows/validate.yml

@@ -0,0 +1,72 @@
+name: Validate AGENTS.md
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Validate
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint Markdown files
+        run: npm run lint
+
+      - name: Check formatting
+        run: npx prettier --check '**/*.md'
+
+      - name: Check markdown code fences
+        run: |
+          errors=0
+          while IFS= read -r -d '' file; do
+            opens=$(grep -c '^\s*```' "$file" || true)
+            if [ $((opens % 2)) -ne 0 ]; then
+              echo "ERROR: Unclosed code fence in $file (found $opens fence markers)"
+              errors=$((errors + 1))
+            fi
+          done < <(find . -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -print0)
+          exit $errors
+
+      - name: Validate YAML code blocks
+        run: |
+          errors=0
+          while IFS= read -r -d '' file; do
+            python3 -c "
+          import re, sys, yaml
+          content = open('$file').read()
+          blocks = re.findall(r'\`\`\`yaml\n(.*?)\`\`\`', content, re.DOTALL)
+          for i, block in enumerate(blocks):
+            try:
+              yaml.safe_load(block)
+            except yaml.YAMLError as e:
+              print(f'  ERROR in $file YAML block {i+1}: {e}')
+              sys.exit(1)
+          if blocks:
+            print(f'  OK: $file — {len(blocks)} YAML blocks')
+          " || errors=$((errors + 1))
+          done < <(find . -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -print0)
+          exit $errors
+
+      - name: Check all variants exist
+        run: |
+          for variant in DDEV Vanilla Lagoon; do
+            if [ ! -f "$variant/AGENTS.md" ]; then
+              echo "ERROR: Missing $variant/AGENTS.md"
+              exit 1
+            fi
+            lines=$(wc -l < "$variant/AGENTS.md")
+            echo "OK: $variant/AGENTS.md ($lines lines)"
+          done

.gitignore

@@ -1,3 +1,13 @@
 # Drupal AGENTS.md Project .gitignore
 
 .claude
+.cursor
+.DS_Store
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+node_modules/
+package-lock.json
+.pi

.markdownlint.json

@@ -0,0 +1,15 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD034": false,
+  "MD036": false,
+  "MD040": false,
+  "MD041": false,
+  "MD051": false,
+  "MD060": false,
+  "MD025": { "front_matter_title": "title" },
+  "MD022": false,
+  "MD031": false,
+  "MD032": false
+}

.markdownlintignore

@@ -0,0 +1 @@
+node_modules/

.prettierignore

@@ -0,0 +1 @@
+node_modules

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "proseWrap": "never",
+  "printWidth": 120
+}

CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased] — 2025-04-23
+
+### Added
+
+- **Lagoon/AGENTS.md**: New variant for amazee.io Lagoon (Kubernetes-based hosting)
+  - Lagoon CLI commands and configuration
+  - lagoon-sync for database and file synchronization
+  - Environment variables (`LAGOON_PROJECT`, `LAGOON_ENVIRONMENT_TYPE`, etc.)
+  - Drush alias integration for remote operations
+  - Post-rollout task configuration
+  - Redis and Varnish configuration for Lagoon
+- **CONTRIBUTING.md**: Structured contributing guide with PR template and review criteria
+- **CHANGELOG.md**: This file
+- **CI workflow**: GitHub Actions for markdown linting, YAML validation, and link checking
+- **Internal table of contents** in all AGENTS.md variants for quick navigation
+- **Module scaffolding template**: Full file structure with minimal module files (info.yml, composer.json)
+- **Anti-patterns section**: 14 "Never Do This" guidelines across all variants
+- **Concrete code examples** for all major patterns:
+  - Services with dependency injection (YAML + PHP)
+  - Entity queries with `accessCheck(TRUE)`
+  - Block plugin with annotations
+  - Hooks: `hook_form_alter`, `hook_theme`, `hook_entity_presave`, `hook_cron`
+  - Forms: simple form with AJAX + config form
+  - Routes with custom access checker
+  - EventSubscriber with service tag
+  - Batch API with `BatchBuilder`
+  - QueueWorker plugin
+  - Render API with caching
+  - Migration source/process/destination
+  - Drupal behaviors (JavaScript)
+  - Configuration schema and install files
+- **New development topics** across all variants:
+  - Events & EventSubscribers
+  - Configuration Management (schema, install, optional, config split)
+  - Render API deep dive
+  - Migration API with custom process plugin
+  - Composer management best practices
+  - JavaScript & Drupal behaviors
+  - Content Moderation & Workflows
+- **Complete test examples**:
+  - Unit test with Prophecy mocking
+  - Kernel test with entity schema
+  - Functional test with browser assertions
+- **Version compatibility table** in README
+
+### Changed
+
+- Updated PHP requirement from 8.1+ to **8.3+**
+- Updated Drupal version from "10.x+" to **"10.x / 11.x"**
+- Updated Drush version from 12+ to **13+**
+- DDEV config updated to use PHP 8.3
+- README updated with Lagoon variant, version compatibility table, and improved structure
+
+### Fixed
+
+- Fixed broken markdown code fence in Vanilla/AGENTS.md (Performance Issues section)
+- Expanded `.gitignore` with `.cursor`, `.DS_Store`, and `*.swp`

CONTRIBUTING.md

@@ -0,0 +1,141 @@
+# Contributing to Drupal AGENTS.md
+
+Thank you for your interest in improving the Drupal AI Agent Development Guides! This document provides guidelines and instructions for contributing.
+
+## How to Contribute
+
+### Reporting Issues
+
+- Open a [GitHub Issue](https://github.com/amazeeio/drupal-agents-md/issues) with a clear title and description
+- Specify which AGENTS.md variant is affected (DDEV, Vanilla, or Lagoon)
+- Include the section heading where the issue occurs
+- If suggesting a change, explain **why** the current content is incorrect or incomplete
+
+### Making Changes
+
+1. **Fork the repository** and create a feature branch:
+
+   ```bash
+   git checkout -b feature/my-improvement
+   ```
+
+2. **Make your changes** following the guidelines below
+
+3. **Test your changes** — Verify that:
+   - Markdown renders correctly (no broken fences, tables, or links)
+   - Code examples are syntactically valid PHP/YAML/Twig/JavaScript
+   - Commands are accurate for the target environment
+   - Content follows the existing structure and tone
+
+4. **Commit with a descriptive message**:
+
+   ```bash
+   git commit -m "feat: add Recipe system section to all variants"
+   ```
+
+5. **Open a Pull Request** against the `main` branch
+
+## Commit Message Convention
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` New content or sections
+- `fix:` Corrections to existing content
+- `docs:` README, CONTRIBUTING, or meta-documentation changes
+- `refactor:` Restructure without changing content
+- `chore:` CI, gitignore, or tooling changes
+
+## Content Guidelines
+
+### Code Examples
+
+- All code examples must be **syntactically valid** and **copy-pasteable**
+- Use `my_module` as the placeholder module name
+- Follow Drupal coding standards in all PHP examples
+- Include `use` statements for all referenced classes
+- Show dependency injection patterns, not static calls
+
+### Environment-Specific Content
+
+When adding content that applies to all variants:
+
+- Add it to **all three** files: DDEV, Vanilla, and Lagoon
+- Adapt commands to the environment:
+  - DDEV: `ddev exec drush <command>`
+  - Vanilla: `drush <command>`
+  - Lagoon: `drush @lagoon.<env> <command>` or `lagoon-sync` commands
+- Maintain consistency across variants
+
+### Style
+
+- Use `**bold**` for emphasis on key terms
+- Use fenced code blocks with language identifiers (`php,`yaml, ```bash)
+- Use markdown tables for command references
+- Keep paragraphs concise — AI agents benefit from density over prose
+- Add concrete code examples rather than abstract descriptions
+
+### What to Add
+
+Contributions are especially welcome for:
+
+- **New Drupal patterns** — Recipe system, Typed Data, new plugin types
+- **More code examples** — Real-world patterns that agents frequently need
+- **Drupal version-specific notes** — Changes between Drupal 10 and 11
+- **Performance patterns** — Profiling, optimization, and caching
+- **Security patterns** — Common vulnerability prevention
+- **Testing patterns** — More test type examples (FunctionalJavascript, etc.)
+- **Decoupled/headless** — JSON:API, REST, GraphQL patterns
+
+### What Not to Add
+
+- Basic Drupal tutorials (installation, site building)
+- Server infrastructure guides (Apache/Nginx config)
+- Content that duplicates the official Drupal documentation without adding value
+- Drupal 7, 8, or 9 specific guidance
+
+## Pull Request Template
+
+When opening a PR, please include:
+
+```markdown
+## Description
+
+Brief description of what this PR changes and why.
+
+## Affected Files
+
+- [ ] DDEV/AGENTS.md
+- [ ] Vanilla/AGENTS.md
+- [ ] Lagoon/AGENTS.md
+- [ ] README.md
+- [ ] Other: \_\_\_
+
+## Type of Change
+
+- [ ] New content/section
+- [ ] Correction/fix
+- [ ] Code example addition
+- [ ] Documentation/meta
+- [ ] CI/tooling
+
+## Testing
+
+How did you verify the changes?
+
+- [ ] Rendered markdown preview
+- [ ] Checked code syntax
+- [ ] Verified commands work in target environment
+```
+
+## Review Criteria
+
+PRs will be reviewed against:
+
+1. **Accuracy** — Code examples and commands are correct
+2. **Consistency** — Changes applied to all relevant variants
+3. **Style** — Follows existing structure and formatting conventions
+4. **Value** — Adds useful information for AI agents working on Drupal projects
+
+## Questions?
+
+Open an issue with the `question` label, or start a discussion in GitHub Discussions.