Athenian Plug-in Forge for WordPress

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

User Workflows

Admin Operator Workflow

1. Admin opens the Plug-in Forge dashboard in WordPress admin.
2. Admin enters the plugin request, touchpoints, rules, and delivery notes.
3. Admin chooses surfaces and planning mode.
4. Planner returns readiness lights, missing details, recommendations, and proposed file structure.
5. Admin refines the request until the build is ready or chooses to package a draft.
6. Plugin Forge generates scaffold files, writes a README and manifest, builds a ZIP, and exposes download controls.

Customer-Facing Workflow

1. A page embeds the [pif] shortcode.
2. Guest or signed-in customer enters a plugin request.
3. A browser session token or user ID ties the build to that viewer.
4. Customer reviews questions, recommendations, and build state.
5. Customer can refresh the plan or package the current build state when allowed by the interface.
6. Available ZIP builds appear in the build desk for the matching owner context.

Developer CLI Workflow

1. Developer runs wp pif plan with a prompt.
2. Plugin creates a manifest in uploads.
3. Developer runs wp pif generate to write scaffold files.
4. Developer runs wp pif zip to package the generated scaffold.
5. Developer checks wp pif status, wp pif list, or deletes older builds.

Technical Architecture

Bootstrap

Primary plugin file:

athenian-plugin-forge.php

The plugin initializes on plugins_loaded through PIF_Core::init().

Core Classes

| Class | File | Purpose | | --- | --- | --- | | PIF_Core | includes/class-pif-core.php | Loads dependencies, initializes customer context, workflow handlers, CLI, admin UI, and shortcode UI. | | PIF_Admin | includes/admin/class-pif-admin.php | Registers the admin menu and admin assets for the Plug-in Forge dashboard. | | PIF_Shortcode | includes/shortcodes/class-pif-shortcode.php | Registers [pif] and frontend assets for customer-facing plugin planning. | | PIF_UI | includes/class-pif-ui.php | Renders the shared planning interface used by both admin and frontend surfaces. | | PIF_Customer | includes/class-pif-customer.php | Maintains viewer ownership context for admins, logged-in users, and guest browser sessions. | | PIF_Workflow | includes/build/class-pif-workflow.php | Handles AJAX planning, build listing, scaffold packaging, downloading, scoring, questions, recommendations, and dashboard records. | | PIF_Build_State | includes/build/class-pif-build-state.php | Manages build directories, manifests, generated files, logs, ZIP paths, owner matching, and deletion. | | PIF_Mock_AI | includes/build/class-pif-mock-ai.php | Provides the current mock planning and file generation layer. | | PIF_Protocol | includes/build/class-pif-protocol.php | Parses tagged AI event and JSON structure payloads. | | PIF_Zip | includes/build/class-pif-zip.php | Packages generated build files into ZIP artifacts. | | PIF_CLI | includes/cli/class-pif-cli.php | Registers and implements WP-CLI commands for build operations. |

Asset Files

| Asset | Purpose | | --- | --- | | assets/app.css | Shared application styling for the planning interface. | | assets/app.js | Shared interface behavior, AJAX calls, readiness rendering, dashboard rendering, and packaging triggers. | | assets/admin.css | Admin-specific presentation adjustments. | | assets/frontend.css | Frontend-specific presentation adjustments. | | assets/admin.js | Admin-side script file included in the package. | | assets/frontend.js | Frontend-side script file included in the package. |

WordPress Integration Points

Admin Menu

The plugin registers a top-level admin page:

• Page title: Plug-in Forge
• Menu title: Plug-in Forge
• Capability: manage_options
• Slug: pif
• Icon: dashicons-hammer

Shortcode

[pif]

The shortcode renders the customer-facing planning studio.

AJAX Actions

The plugin registers authenticated and unauthenticated AJAX handlers:

| Action | Purpose | | --- | --- | | pif_plan_workflow | Creates a plan payload from request fields and stores a build manifest. | | pif_list_builds | Lists build dashboard records for the current owner context. | | pif_generate_build | Generates scaffold files and packages the current build into a ZIP. | | pif_download_build | Streams the completed ZIP artifact to the browser. |

Each AJAX route uses the pif_plan_workflow nonce.

WP-CLI Commands

| Command | Purpose | | --- | --- | | wp pif | Confirms CLI installation and prints usage. | | wp pif plan | Creates a build manifest and mock AI plan. | | wp pif generate | Generates scaffold files from the planned structure. | | wp pif zip | Packages generated files into a ZIP. | | wp pif status | Prints build status JSON. | | wp pif list | Lists recent builds in table format. | | wp pif delete | Deletes a build directory. | | wp pif protocol-test | Tests extraction of PIF event and structure protocol tags. |

Data Model and Storage

Plugin Forge does not register a custom database table, custom post type, taxonomy, option, or post meta model in the reviewed version. Instead, build state is file-backed under WordPress uploads.

Build Storage

Builds are stored under:

wp-content/uploads/pif/builds/<build_id>/

Each build directory can contain:

manifest.json
logs.txt
files/
output.zip

Manifest Structure

The manifest stores:

• build_id
• created_gmt
• mode
• prompt
• owner
• plugin
• structure
• features
• files
• review
• artifacts
• status

Owner Context

Build ownership is determined by:

• Admin viewer: full build access when the user can manage_options.
• Logged-in user: build access by WordPress user ID.
• Guest browser session: build access by pif_client_token cookie.

The guest token is generated with wp_generate_uuid4() and stored as an HTTP-only cookie for one year.

Security and Validation Notes

The reviewed implementation includes several important safeguards:

• defined('ABSPATH') || exit guard in PHP files.
• manage_options capability for the admin menu.
• Nonce validation for AJAX actions through check_ajax_referer().
• Sanitization for textarea input, keys, build IDs, owner labels, and cookie tokens.
• Owner checks before listing, packaging, or downloading builds.
• ZIP download responses include X-Content-Type-Options: nosniff.
• Guest builds are isolated by an HTTP-only session token.
• File write paths strip parent-directory traversal fragments before writing generated files.

Technical Summary

Athenian Plug-in Forge is a WordPress plugin with a shared admin/frontend UI, AJAX-based planning and packaging actions, file-backed build manifests, guest/customer ownership tracking, mock AI planning, scaffold file generation, ZIP packaging, and WP-CLI command support. It currently acts as a guided planning and mock-generation platform that can later be connected to a production AI provider or broader Athenian Platform services.