marcus
5a80351d1f
Resolves #24 - Use fully qualified class name WPALLSTARS\FixPluginDoesNotExistNotices\Plugin in version management snippet - Replace misleading includes/Plugin.php entry (no version constant) with AGENTS.md as the fourth version location - Add note clarifying Plugin.php passes version via constructor - Add step 4 to bump-version checklist to update AGENTS.md version string
105 lines
5.1 KiB
Markdown
105 lines
5.1 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 WPALLSTARS\FixPluginDoesNotExistNotices\Plugin(__FILE__, '2.4.0')` (replace `2.4.0` with the new version)
|
|
2. `readme.txt` — `Stable tag:` and changelog section
|
|
3. `CHANGELOG.md` — top entry
|
|
4. `AGENTS.md` — this file, item 1 above (replace the hardcoded version string)
|
|
|
|
Note: `includes/Plugin.php` has no direct version constant; the version is passed in via the constructor call in the entry point file.
|
|
|
|
`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`.
|
|
4. Update the version string in `AGENTS.md` (item 1 of the Version Management list above).
|
|
|
|
### 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
|