wp-fix-plugin-does-not-exist-notices/AGENTS.md

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