Merge pull request #73 from Automattic/add/agents-md

Add AGENTS.md with structured agent guidance

Author: GaryJones

.claude/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

AGENTS.md

@@ -0,0 +1,88 @@
+# Rewrite Rules Inspector
+
+Debug and inspect WordPress rewrite rules.
+
+## Project Knowledge
+
+| Property | Value |
+|----------|-------|
+| **Main file** | `rewrite-rules-inspector.php` |
+| **Text domain** | `rewrite-rules-inspector` |
+| **Namespace** | `Automattic\RewriteRulesInspector` |
+| **Source directory** | `src/` |
+| **Version** | 1.6.0 |
+| **Requires PHP** | 7.4+ |
+| **Requires WP** | 6.4+ |
+
+### Directory Structure
+
+```
+rewrite-rules-inspector/
+├── src/
+│   ├── Plugin.php          # Main plugin class
+│   ├── Core/               # Core logic (UrlTester, RewriteRules)
+│   └── Admin/              # Admin UI (AdminPage, RewriteRulesTable)
+├── views/                  # PHP template files for admin pages
+├── assets/                 # CSS/JS assets
+├── tests/
+│   ├── Unit/               # Unit tests
+│   └── Integration/        # Integration tests (wp-env)
+├── languages/              # Translation files
+├── rector.php              # Rector configuration for code modernisation
+├── .github/workflows/      # CI: deploy, integration
+└── .phpcs.xml.dist         # PHPCS configuration
+```
+
+### Key Classes
+
+- `Plugin` — Main plugin bootstrap, registers hooks
+- `Core\RewriteRules` — Retrieves and analyses WordPress rewrite rules
+- `Core\UrlTester` — Tests URLs against rewrite rules
+- `Admin\AdminPage` — Admin tools page registration
+- `Admin\RewriteRulesTable` — WP_List_Table for displaying rewrite rules
+
+### Dependencies
+
+- **Dev**: `automattic/vipwpcs`, `yoast/wp-test-utils`, `rector/rector`
+
+## Commands
+
+```bash
+composer cs                # Check code standards (PHPCS)
+composer cs-fix            # Auto-fix code standard violations
+composer lint              # PHP syntax lint
+composer test:unit         # Run unit tests
+composer test:integration  # Run integration tests (requires wp-env)
+composer test:integration-ms  # Run multisite integration tests
+composer coverage          # Run tests with HTML coverage report
+composer rector            # Run Rector for code modernisation suggestions
+```
+
+## Conventions
+
+Follow the standards documented in `~/code/plugin-standards/` for full details. Key points:
+
+- **Commits**: Use the `/commit` skill. Favour explaining "why" over "what".
+- **PRs**: Use the `/pr` skill. Squash and merge by default.
+- **Branch naming**: `feature/description`, `fix/description` from `develop`.
+- **Testing**: Write integration tests for WordPress-dependent behaviour, unit tests for isolated logic. Use `Yoast\WPTestUtils\WPIntegration\TestCase` for integration, `Yoast\WPTestUtils\BrainMonkey\YoastTestCase` for unit.
+- **Code style**: WordPress coding standards via PHPCS. Tabs for indentation.
+- **i18n**: All user-facing strings must use the `rewrite-rules-inspector` text domain.
+
+## Architectural Decisions
+
+- **Separation of concerns**: Core logic (rewrite rule analysis, URL testing) is separated from admin UI. Keep this boundary — do not mix display logic into core classes.
+- **View templates**: Admin page HTML is in `views/` as separate template files, not inline in PHP classes. New admin views should follow this pattern.
+- **WordPress.org deployment**: Has a deploy workflow for WordPress.org SVN. Do not manually modify SVN assets.
+- **Rector available**: Includes Rector for automated code modernisation. Use `composer rector` to check for opportunities.
+- **Debugging tool**: This plugin is a developer tool, not an end-user feature. The UI prioritises information density and accuracy over visual polish.
+
+## Common Pitfalls
+
+- Do not edit WordPress core files or bundled dependencies in `vendor/`.
+- Run `composer cs` before committing. CI will reject code standard violations.
+- Integration tests require `npx wp-env start` running first.
+- Rewrite rules are generated by WordPress core, themes, and other plugins. Do not modify rewrite rules from this plugin — it is an inspector, not a modifier.
+- The `flush_rewrite_rules()` function is expensive. If adding a flush feature, it must only run on explicit user action, never on every page load.
+- WordPress rewrite rules can vary significantly between sites. Test with a variety of permalink structures, not just the default.
+- Admin list table extends `WP_List_Table`, which is a WordPress internal class marked as private. Be cautious with assumptions about its API stability.