wp-mnemon

name	wp-mnemon
description	Step-by-step instructions for deep analysis of a WordPress plugin — architecture, execution flows, hook chains, data lifecycle, and extensibility — from a local path or GitHub URL. Writes structured documentation into agent memory.

wp-mnemon — WordPress Plugin Deep Analyzer

You are performing a deep architectural analysis of a WordPress plugin. Your goal is not just to catalog hooks and data structures, but to understand what the plugin does, how it works, what triggers what, and how data flows through the system.

Follow every phase below in order. Do not skip phases even if the plugin seems simple.

---

Phase 0: Determine Source

Check what the user provided:

Local path (e.g. /wp-content/plugins/my-plugin or ~/plugins/my-plugin):

• Use Glob and Read tools directly on the filesystem
• Use the bash scripts in ~/.claude/skills/wp-mnemon/scripts/ for fast scanning

GitHub URL (e.g. https://github.com/org/repo):

• Extract {owner} and {repo} from the URL
• Set GITHUB_API=https://api.github.com/repos/{owner}/{repo}
• If the user provided a token, use Authorization: Bearer {token} header on all requests
• Fetch the full file tree: GET {GITHUB_API}/git/trees/HEAD?recursive=1
• Read individual files on demand: GET {GITHUB_API}/contents/{path}
• GitHub API returns file content as base64 — decode it before reading

---

Phase 1: Identify the Plugin

Find the main plugin file (contains the plugin header comment):

Plugin Name:
Plugin URI:
Description:
Version:
Author:

• For local: Glob for *.php in the root, read each until you find the header
• For GitHub: look at the file tree for root-level .php files, fetch and scan them

Extract and record:

• Plugin name, slug, version, author
• Text domain
• Main file path
• Constants defined (PLUGIN_VERSION, PLUGIN_DIR, PLUGIN_URL, etc.)
• Read the plugin's README or readme.txt to understand its stated purpose and features

---

Phase 2: Map the File Structure

Build a complete map of the plugin. Categorize every directory:

Directory	Purpose
includes/ or src/	Core classes and logic
admin/	Admin-only code
public/ or frontend/	Frontend-facing code
templates/ or views/	Template files
assets/	JS, CSS, images
languages/	i18n .pot files
vendor/	Third-party dependencies
tests/	Test suite

Note the architectural pattern: procedural, OOP singleton, OOP dependency injection, service container, or mixed.

Count total PHP files and estimate plugin complexity.

---

Phase 3: Architecture & Class Map

For local plugins, run:

bash ~/.claude/skills/wp-mnemon/scripts/scan_classes.sh /path/to/plugin

For GitHub, read key PHP files and scan for the same patterns.

Build a class architecture map:

1. Namespaces — what namespace structure is used?
2. Autoloading — how are classes loaded? (Composer PSR-4, custom autoloader, manual requires)
3. Core classes — identify the main plugin class, admin class, frontend class, and any base/abstract classes
4. Class hierarchy — map extends and implements relationships as a tree
5. Traits — what shared behavior is mixed in via traits?
6. Singletons & factories — how are key objects instantiated and accessed?
7. Service container — if there's a DI container, how does it wire things together?

Read the main plugin class and any bootstrap/loader files thoroughly. These reveal the overall architecture better than any grep.

---

Phase 4: Bootstrap & Initialization Flow

Trace the complete loading sequence starting from the main plugin file. Read the actual code — don't just grep. Answer:

1. What happens when WordPress loads this plugin file?

   • What files are required/included immediately?
   • What classes are instantiated?
   • What hooks are registered at load time?

2. What happens at each WordPress lifecycle stage? Trace the chain through key hooks in order:

   • plugins_loaded — what runs here?
   • init — what gets registered? (CPTs, taxonomies, shortcodes, etc.)
   • wp_loaded — any late initialization?
   • admin_init — admin-specific setup?
   • admin_menu — menu/page registration?
   • wp_enqueue_scripts / admin_enqueue_scripts — asset loading?
   • rest_api_init — REST route registration?
   • widgets_init — widget registration?

3. Dependency chain — what must load before what? Are there conditional loads (e.g., admin-only classes, frontend-only classes)?

Document this as a sequential flow with clear arrows/steps.

---

Phase 5: Scan All Hooks

For local plugins, run:

bash ~/.claude/skills/wp-mnemon/scripts/scan_hooks.sh /path/to/plugin

For GitHub, scan PHP files for hook patterns.

Look for ALL of these:

• add_action(, add_filter( — hooks the plugin listens to
• do_action(, apply_filters( — hooks the plugin exposes
• do_action_ref_array(, apply_filters_ref_array(
• remove_action(, remove_filter( — hooks intentionally removed
• has_action(, has_filter( — conditional hook checks

For each hook, document:

• Hook name, type (action/filter), file, line, priority, accepted args
• Callback function/method
• What it does — read the callback to understand purpose, not just its name
• For filters: what value is being filtered and what return is expected
• For exposed hooks: what parameters are passed and what use cases they enable

Group hooks into:

• Registered (add_action, add_filter) — what WP/plugin hooks it listens to
• Exposed (do_action, apply_filters) — extension points for other plugins
• Removed (remove_action, remove_filter) — intentional overrides and why

---

Phase 6: Scan Data Structures

For local plugins, run:

bash ~/.claude/skills/wp-mnemon/scripts/scan_data.sh /path/to/plugin

For GitHub, scan PHP files for data patterns.

For each data structure found, go beyond the grep match — read surrounding code to understand context:

Custom Post Types & Taxonomies

• Full registration args (supports, capabilities, rewrite, visibility, menu position)
• What admin UI is associated with each CPT?

Meta Keys (post, user, term, comment)

• What stores each key, what reads it, what deletes it
• Data type and expected format
• Which post type / object type each key belongs to

Options

• Default values, what settings page controls them
• Whether they're autoloaded

Custom Database Tables

• Full schema (capture dbDelta SQL or CREATE TABLE statements)
• Columns, indexes, foreign key relationships to WP core tables
• What CRUD operations exist for each table

Transients & Cache

• Key patterns, expiry times, what triggers invalidation

---

Phase 7: Scan Integrations

REST API

• register_rest_route( — namespace, route pattern, methods, permission callback
• Read the endpoint callbacks to understand request/response shapes

Shortcodes

• add_shortcode( — tag, accepted attributes and defaults, what it renders

Blocks (Gutenberg)

• register_block_type( — block name, attributes, supports, render callback
• Check for block.json files in the plugin

WP-CLI Commands

• WP_CLI::add_command( — command name, subcommands, what they do

Enqueued Assets

• Scripts and styles: handle, source, dependencies, version
• Conditions: admin only, frontend only, specific pages/post types

Cron Jobs

• Hook name, schedule interval, what the callback does

Third-party Integrations

Look for conditional checks:

• WooCommerce, ACF, WPML, Elementor, Yoast, Gravity Forms, etc.
• Document what each integration adds or modifies

---

Phase 8: Execution Flow Tracing

This is the most important analytical phase. For each major feature of the plugin, trace the complete execution flow from trigger to outcome.

Identify major features from:

• The plugin's stated purpose (readme/description)
• Admin pages and their functionality
• Frontend-facing shortcodes/blocks
• AJAX/REST endpoints
• Cron jobs

For each major flow, trace:

Trigger -> Entry point -> Processing chain -> Data operations -> Output/Side effects

Example format:

### Form Submission Flow
1. User submits form on frontend (JS event listener in `assets/js/public.js`)
2. AJAX POST to `admin-ajax.php` action `my_plugin_submit`
3. Handler: `Ajax_Handler::process_submission()` (`includes/class-ajax-handler.php:45`)
4. Validates nonce and fields via `Validator::validate()` (`includes/class-validator.php:22`)
5. Calls `apply_filters('my_plugin_pre_save', $data)` — extension point
6. Stores data: `$wpdb->insert()` into `{prefix}my_plugin_entries` table
7. Fires `do_action('my_plugin_after_save', $entry_id, $data)` — extension point
8. Sends email notification via `Notification::send()` if enabled in settings
9. Returns JSON response to frontend

Read the actual code for each step. Do not guess flow from function names alone.

---

Phase 9: Admin & Frontend Map

Admin Interface

• What menu pages / submenu pages exist?
• What does each admin page do? (settings, list tables, editors, dashboards)
• What metaboxes are registered and on which screens?
• What admin notices or pointers are shown?
• What AJAX operations does the admin UI trigger?

Frontend Interface

• What does the plugin render on the frontend? (shortcode output, block output, template overrides)
• What JavaScript behavior is added? (event handlers, AJAX, DOM manipulation)
• What CSS/styles does it inject?

User-facing Workflow

Describe the typical user workflow:

• Admin: "To create a new X, go to Menu > Submenu, fill in fields A/B/C, click Save"
• Frontend: "Visitors see X rendered via shortcode [foo], which displays Y"

---

Phase 10: Extensibility Patterns

Based on everything found, document:

1. Template overrides — can templates be copied to the theme? What's the lookup path?
2. Class extension — are main classes instantiated in a way that allows replacement?
3. Filter-based configuration — which apply_filters calls are meant as config points?
4. Action hooks for developers — which do_action calls are documented extension points?
5. Common patterns — what's the idiomatic way to extend this plugin?

Write 3-5 concrete, practical code examples of how a developer would extend this plugin. Focus on the most common real-world use cases.

---

Phase 11: Write Memory Files

Create a directory for the plugin and write multiple focused files:

Directory structure

~/.claude/agent-memory/wp-mnemon/plugins/{plugin-slug}/
├── overview.md
├── architecture.md
├── hooks.md
├── data.md
└── extending.md

overview.md — What it does & how it works

# {Plugin Name} — v{version}

**Slug**: {slug} | **Author**: {author} | **Analyzed**: {date}

## What This Plugin Does
{Clear description of the plugin's purpose, target users, and main features.
Write this for a developer who has never seen the plugin.}

## File Structure
{Directory map with purpose annotations}

## Bootstrap Flow
{Step-by-step initialization sequence from plugin load through WordPress lifecycle.
Show what loads when and what triggers what.}

## Major Execution Flows
{For each key feature, the full trigger -> processing -> output chain.
This is the most valuable section. Be specific with file paths and line references.}

## Admin Workflow
{What admins see and do — pages, settings, editors}

## Frontend Output
{What visitors see — rendered shortcodes, blocks, templates}

architecture.md — How it's built internally

# {Plugin Name} — Architecture

## Architectural Pattern
{OOP/procedural/mixed, design patterns used, DI approach}

## Class Map
{Class hierarchy with inheritance and interface relationships.
For each key class: responsibility, file path, key methods.}

## Namespace Structure
{Namespace tree if applicable}

## Autoloading
{How classes are loaded}

## Dependency Chain
{What depends on what, conditional loading}

hooks.md — All hooks with context

# {Plugin Name} — Hooks Reference

## Hooks Registered (listens to WP/others)
{For each: hook name, callback, file:line, priority, what it does}

## Hooks Exposed (extension points)
{For each: hook name, file:line, parameters passed, use case, expected return for filters}

## Hooks Removed
{For each: hook name, why it's removed}

data.md — Data structures & integrations

# {Plugin Name} — Data & Integrations

## Custom Post Types
{Slug, labels, supports, capabilities, admin UI}

## Taxonomies
{Slug, associated CPTs, hierarchical}

## Meta Keys
{Key, object type, data type, where set/read/deleted}

## Options
{Key, default, autoload, what controls it}

## Custom DB Tables
{Table name, full schema, what CRUD operations exist}

## REST API Routes
{Method, route, permission, request/response shape}

## Shortcodes & Blocks
{Tag/name, attributes, what it renders}

## Assets
{Handle, type, conditions, dependencies}

## Cron Jobs
{Hook, interval, what it does}

## Transients
{Key pattern, expiry, invalidation trigger}

## Third-party Integrations
{Plugin, what the integration does, conditional check used}

extending.md — How to extend it

# {Plugin Name} — Extensibility Guide

## Extension Patterns
{Template overrides, class replacement, filter-based config, action hooks}

## Key Extension Points
{The most useful hooks for developers, with context on when/why to use each}

## Code Examples
{3-5 practical, real-world examples of extending this plugin}

## Data Lifecycle
{How data is created, updated, read, deleted — and where to hook in}

Update index: ~/.claude/agent-memory/wp-mnemon/MEMORY.md

Add or update the plugin entry in the table:

| {name} | {slug} | {version} | {date} |

Add a note under Cross-Plugin Patterns if you observe patterns shared with other analyzed plugins.

---

Phase 12: Confirm to User

Tell the user:

• What was analyzed
• Where memory was written (list all files)
• Key stats: hook count, CPTs, DB tables, REST routes, major flows traced
• Any gaps: files that couldn't be read, areas that were unclear
• A brief summary of the plugin's architecture and main flows