Imported from FernleafSystems/Shield-Security-for-WordPress (AGENTS.md). Install upstream with npx skills add FernleafSystems/Shield-Security-for-WordPress. Copyright stays with the author.

Repository Guidelines

Product Snapshot

Shield Security is an enterprise-grade WordPress plugin delivering defense-in-depth protection through eight coordinated security modules (Security Admin, Firewall, Login Guard, IPs, HackGuard, Comments Filter, Audit Trail, Traffic). It targets security-conscious site owners, agencies, and MSPs who need scalable protection, compliance-ready auditing, and integrations with MainWP, WP-CLI, and threat-intel services such as CrowdSec and Have I Been Pwned.

Knowledge Base

This repository has a repo-local knowledge base under kb/. Treat it as a reference point when the task would benefit from accumulated repo knowledge, prior synthesis, terminology, planning notes, or source summaries.

Read these in order when the KB is relevant:

• kb/AGENTS.md - universal wiki rules and page contract
• kb/REPO_WIKI_SPEC.md - repo-local wiki configuration and active topic categories
• kb/wiki/index.md - wiki page catalog
• kb/wiki/log.md - recent wiki activity

Do not treat the KB as the default target for every task. Use it as shared context first. Only add to or modify the KB when the task is explicitly about wiki work or when durable knowledge capture is clearly part of the requested work.

Project Structure

Core PHP lives in src/, organised by module (for example Modules/Login_Protect, Rules, Controller). Prefixed third-party libraries generated by Strauss reside in vendor_prefixed/. Asset sources are under assets/ (webpack entry points in assets/js/app and assets/scss), with compiled bundles emitted to assets/dist. WordPress bootstrap files (icwp-wpsf.php, plugin_init.php, plugin.json) wire modules and option schemas. plugin.json is generated from the modular JSON sources in plugin-spec/ via bin/build-config.php; edit plugin-spec/* instead of hand-editing plugin.json. Tests sit in tests/ with Unit/, Integration/, Docker harness, fixtures, and smoke-test playbooks.

Bootstrap & Architecture

Plugin bootstrap flows from icwp-wpsf.php into plugin_init.php, then into src/Controller/Controller.php, which loads configuration, modules, and shared services before delegating routed requests to src/ActionRouter/ActionRoutingController.php. Treat that path as the quickest way to orient on startup and request execution.

Core architectural anchors:

• src/Controller/ owns plugin lifecycle, configuration loading, and shared service access.
• src/Modules/ contains feature modules and their option/event wiring.
• src/Rules/ contains rule evaluation and security decision logic.
• src/ActionRouter/ is the central request/action dispatch surface for Shield, AJAX, and REST handling.
• src/Components/ComponentLoader.php is the entry point for lazy-loaded shared components.

Build, Test & Verification

• npm install && npm run build - install and compile production assets (required before packaging).
• npm run dev - watch-mode compilation for UI work.
• composer install - resolve dependencies.
• TESTING.md - single source of truth for current testing commands, CI-equivalent validation paths, and workflow roles.
• Manual WordPress test bootstrap scripts exist in bin/install-wp-tests.ps1 and bin/install-wp-tests.sh for exceptional local setup outside the documented TESTING.md flows.
• PHPCS is not part of the active repository tooling or verification surface.

Coding Standards & Naming

All PHP files declare strict types, follow PSR-4 namespaces rooted at FernleafSystems\Wordpress\Plugin\Shield, and use tabs for indentation. Classes are PascalCase, services lean on trait-based dependency injection (for example PluginControllerConsumer), and WordPress option keys/hooks stay snake_case. Twig templates in templates/twig must escape output; JavaScript modules under assets/js use ES6 modules and camelCase exports.

JavaScript Tooling

• For JavaScript changes, TypeScript is currently checker-only via checkJs and noEmit; it is not part of the webpack build output.
• Do not add .ts or .tsx source files under assets/js, do not add TypeScript build integration, and do not widen JS lint/type coverage unless explicitly asked.
• When touching the checked JS slice or its companion declarations, run npm run test:js. This command is static-only and must stay separate from browser/runtime verification.

Workflow Guardrails

• Inspect surrounding and impacted code before planning or implementing changes.
• Reuse existing code, services, and patterns wherever possible instead of recreating equivalent logic.
• Follow the conventions, structure, and style already established in the codebase; do not introduce custom conventions without a clear need.
• When changing plugin configuration, events, or option schemas, update plugin-spec/* and regenerate plugin.json; do not treat plugin.json as the source of truth.
• Keep changes within scope. Prefer the simplest solution that fully satisfies the requirement; do not add fallback-driven complexity or oversimplify in ways that miss the real objective.
• After implementation, verify that the delivered code still matches the approved plan and has not drifted beyond scope or introduced unplanned complexity.
• Ignore all repository changes that were not made by you or are not directly related to the work you are doing.
• If existing repository changes do not directly conflict with the files or code you need to change, leave them alone and continue.
• If existing repository changes do directly conflict with the files or code you need to change, report the conflict and stop rather than overwriting, reverting, or working around them silently.
• When working from a numbered plan or task document, only mark items complete once the implementation and any required verification for that item are actually complete.
• When a plan or Linear queue spans multiple feature areas or cannot be confidently implemented, verified, tracked, and closed in one rigorous pass, split it into independently completable slices before coding. Each slice must have one coherent outcome and per-item acceptance evidence; mapping, scaffolding, or partial status alone never counts as completion.
• For UI changes, preserve the existing rendering, data flow, and presentation mechanisms wherever possible; change only the specific logic required for the approved behaviour.

Testing Practices

Unit tests live in tests/Unit/*Test.php using Brain Monkey for WordPress mocks; integration tests under tests/Integration bootstrap full WordPress (see tests/bootstrap). Package validation scripts confirm prefixed dependencies stay intact - run them when touching build tooling. Update fixtures in tests/fixtures whenever configuration changes affect serialized data. Prefer tests that verify code behaviour rather than documentation or test theatre. Never add tests against documentation. Avoid fragile user-interface, DOM, or string-matching tests unless there is no more robust way to verify the behaviour. Do not add metadata or implementation noise whose only purpose is to support brittle UI testing. When touching fragile or low-value tests, prefer improving or removing them rather than extending them. Prefer assertions and failure output that stay high-signal rather than brittle exact text checks or noisy dumps. Integration tests may be added where they materially improve coverage, but running them is not a default requirement for every task.

Commit & PR Workflow

When committing, stage and commit only the files you directly changed for the current task; do not take action on unrelated repository changes. If a Markdown or documentation file contains both your edits and unrelated existing edits, stage the whole file rather than trying to hunk-stage around them. Write imperative, present-tense commit subjects under 72 characters; expand motivation in the body when touching security-sensitive code. Keep commit messages concise, precise, and accurate. Do not enumerate files in commit messages, do not mention AI or agent involvement, and do not reference ephemeral task item numbers that will not be meaningful later. Reference issues with GH-### and document security impacts in changelog.md when behaviour changes. PRs should summarise scope, list automated/manual test evidence, and include before/after media for admin UI tweaks or user-facing flows.

Security & Operational Notes

Never commit credentials, license keys, or customer data. Ensure production builds run composer package-plugin (via bin/package-plugin.php, supersedes deprecated bin/build-package.sh) so prefixed libraries and strict asset versions ship correctly.