marcus
18cf60c2a4
* fix: correct case-sensitive require_once paths and add AGENTS.md for AI guidance - Fix includes/plugin.php -> includes/Plugin.php in main plugin file - Fix includes/core.php -> includes/Core.php in includes/Plugin.php (Linux case-sensitive filesystems fail silently on macOS; runtime bug on production) - Fix .ai-workflows/folder-structure.md: update class files to PascalCase, remove references to non-existent admin/ subdirectories (images/, partials/, settings/, tools/) that caused read:file_not_found errors in AI sessions - Add AGENTS.md with authoritative file map to reduce AI agent errors: edit:not_read_first, bash:other, edit:edit_stale_read, read:file_not_found Resolves #13 * fix: markdown formatting in AGENTS.md (Codacy MD022/MD032)
102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# AGENTS.md — AI Agent Guide for wp-fix-plugin-does-not-exist-notices
|
|
|
|
This file provides precise, verified guidance for AI agents working in this repository. Read it before editing any file to avoid `read:file_not_found` and `edit:not_read_first` errors.
|
|
|
|
## Repository Purpose
|
|
|
|
**Fix 'Plugin file does not exist' Notices** — a WordPress plugin that detects active plugins whose files are missing, adds them to the Plugins list with a "Remove Notice" action link, and safely removes their database references.
|
|
|
|
- GitHub: `wpallstars/wp-fix-plugin-does-not-exist-notices`
|
|
- Namespace: `WPALLSTARS\FixPluginDoesNotExistNotices`
|
|
- Text domain: `wp-fix-plugin-does-not-exist-notices`
|
|
- Current version: see `wp-fix-plugin-does-not-exist-notices.php` header
|
|
|
|
## Exact File Map (authoritative — verified against git ls-files)
|
|
|
|
**CRITICAL**: PHP class files in `includes/` use PascalCase. The docs and `require_once` paths must match exactly. On Linux (case-sensitive), wrong case = fatal error.
|
|
|
|
```
|
|
wp-fix-plugin-does-not-exist-notices.php # Plugin entry point — sets Version, requires includes/Plugin.php
|
|
includes/Plugin.php # Main Plugin class — loads dependencies, inits components
|
|
includes/Core.php # Core class — all WordPress hooks and plugin logic
|
|
includes/Updater.php # Updater class — handles Git Updater / WP.org update sources
|
|
admin/lib/admin.php # Admin\Admin class — admin page rendering, enqueues
|
|
admin/lib/modal.php # Admin\Modal class — update source selector modal
|
|
admin/css/admin-styles.css # General admin styles
|
|
admin/css/update-source-selector.css # Styles for the update source modal
|
|
admin/js/admin-scripts.js # General admin JS
|
|
admin/js/update-source-selector.js # JS for the update source modal
|
|
languages/wp-fix-plugin-does-not-exist-notices.pot # Translation template
|
|
build.sh # Build/release script
|
|
scripts/deploy-local.sh # Local deployment helper
|
|
composer.json # Composer config (no vendor/ committed)
|
|
README.md # Developer readme
|
|
readme.txt # WordPress.org readme (keep in sync with README.md)
|
|
CHANGELOG.md # Changelog (keep in sync with README.md and readme.txt)
|
|
```
|
|
|
|
**Directories that DO NOT exist** (do not attempt to read or create files here):
|
|
|
|
- `admin/images/` — does not exist
|
|
- `admin/partials/` — does not exist
|
|
- `admin/settings/` — does not exist
|
|
- `admin/tools/` — does not exist
|
|
- `vendor/` — not committed; loaded at runtime if present
|
|
|
|
## Before Editing Any File
|
|
|
|
1. Read the file first: `Read includes/Core.php` — not `includes/core.php` (wrong case fails).
|
|
2. Re-read the file if another tool call may have modified it since your last read.
|
|
3. Verify the file path with `git ls-files '<pattern>'` when uncertain.
|
|
|
|
## Version Management
|
|
|
|
Version appears in **four places** — all must be updated together:
|
|
|
|
1. `wp-fix-plugin-does-not-exist-notices.php` — `Version:` header and `new Plugin(__FILE__, 'X.Y.Z')`
|
|
2. `includes/Plugin.php` — no direct version constant; version passed via constructor
|
|
3. `readme.txt` — `Stable tag:` and changelog section
|
|
4. `CHANGELOG.md` — top entry
|
|
|
|
`README.md` changelog section must also stay in sync with `CHANGELOG.md`.
|
|
|
|
## Common Tasks
|
|
|
|
### Fix a bug in core plugin logic
|
|
|
|
Edit `includes/Core.php`. All WordPress hooks are registered in the constructor.
|
|
|
|
### Change admin UI or settings
|
|
|
|
Edit `admin/lib/admin.php` (Admin class) and/or `admin/lib/modal.php` (Modal class).
|
|
CSS: `admin/css/admin-styles.css` or `admin/css/update-source-selector.css`.
|
|
JS: `admin/js/admin-scripts.js` or `admin/js/update-source-selector.js`.
|
|
|
|
### Bump version for a release
|
|
|
|
1. Update version in `wp-fix-plugin-does-not-exist-notices.php` (both header and constructor call).
|
|
2. Update `Stable tag:` in `readme.txt`.
|
|
3. Add changelog entry to `readme.txt`, `CHANGELOG.md`, and `README.md`.
|
|
|
|
### Add or fix update source logic
|
|
|
|
Edit `includes/Updater.php`.
|
|
|
|
## Git Workflow
|
|
|
|
- Branch naming: `feature/`, `fix/`, `patch/`, `refactor/` prefixes
|
|
- One branch per issue; one PR per issue
|
|
- Push to both `github` and `gitea` remotes
|
|
- Do not include version numbers in branch names during development
|
|
|
|
## AI Workflow Documentation
|
|
|
|
Extended guidance is in `.ai-workflows/`:
|
|
|
|
- `folder-structure.md` — directory layout with correct filenames
|
|
- `git-workflow.md` — branching, commit messages, remote management
|
|
- `feature-development.md` — feature development process
|
|
- `bug-fixing.md` — bug investigation and fix process
|
|
- `release-process.md` — full release checklist including Git Updater notes
|
|
- `dev-prefs-memory.md` — persistent developer preferences
|