MPA Mandate: Rules & Guidelines for AI-Assisted Development Tools (v2)

AI-assisted coding tools are biased toward complexity. This changes that.

These Rules & Guidelines provide the context to deprogram the "SPA-by-default" bias in 15+ AI tools, restoring the native strengths of HTML, CSS, and server-rendered architecture.

The web has matured. Modern capabilities like View Transitions and Speculation Rules have rendered the SPA complexity tax unnecessary. These guidelines force a return to the platform capabilities that have been quietly had their enhancements perfected while the industry was distracted by frameworks.

💭 The Philosophy:

• MPA-First: Server-rendered architecture is the default.
• JavaScript is for enhancement, not enablement. Core functionality should work without it.
• Performance is native, not imported.

Integration: Designed for seamless integration with GitHub Copilot, Cursor, Windsurf, Gemini, Claude, Codex, and 10+ other assistants to automatically enforce MPA-first development practices.

---

Changelog

Last Update: Dec 2025

v2 Changes:

• Major assistant-specific instruction formats added.
• New subfolder organization and integration steps (see repository structure).
• Refined wording for clarity and emphasis on the MPA-first philosophy.

AI Models are biased toward complexity. We retrain them for resilience.

🌐 Overview

For over a decade, web development has trended towards complex, JavaScript-heavy Single-Page Applications (SPAs). The promise was a slick, "app-like" user experience. The reality, in most cases, has been bloated, fragile, and over-engineered websites that are slow to load, difficult to maintain, and hostile to users and search engines.

This document outlines a return to a more resilient, performant, and durable web. We are intentionally choosing a Multi-Page Application (MPA) architecture. The guiding principle is to use the platform. We build upon the native strengths of HTML, CSS, and the browser itself, which have evolved significantly. Modern features like CSS View Transitions and Speculation Rules now provide the fluid user experience that once required megabytes of JavaScript, but without the performance penalty.

We are choosing simplicity, speed, and maintainability over unnecessary complexity. We build for users and outcomes, not for developer experience (DX) or architectural novelty. JavaScript is a powerful tool for progressive enhancement, not the default foundation for every page.

💡 The Problem

Modern AI code generation tools (like GitHub Copilot, Cursor, Claude Code, Gemini CLI, etc.) and models (Claude Sonnet/Opus, Gemini Pro, GPT-5, etc.) are primarily trained on the prevailing web development paradigm: complex, JavaScript-heavy Single-Page Applications (SPAs). This often leads to generated code that is bloated, fragile, and contrary to principles of performance, resilience, and maintainability.

✨ The Solution: An MPA-First Philosophy

This repository provides a concise set of development rules championing a Multi-Page Application (MPA) architecture. We advocate leveraging the native strengths of HTML, PHP, CSS, and the browser itself, treating JavaScript as a tool for progressive enhancement only.

Performance is native, not imported.

This approach aims for: