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:

• Optimal Performance: Faster load times and smoother navigation.
• Enhanced Resilience: Less dependency on complex client-side logic.
• Superior Maintainability: Simpler architecture, fewer moving parts.
• Inherent SEO & Accessibility: Built upon modern web standards.

💡 Quick Start

1. Choose your AI assistant from the setup instructions below
2. Choose your version: Strict (vanilla JS) or Relaxed (jQuery allowed)
3. Copy/configure the appropriate file for your tool
4. Start coding with MPA-First principles enforced by your AI assistant

📝 Two Versions Available

Each AI assistant has two versions of the MPA guidelines:

1. Strict Rules - Vanilla JavaScript ES2020+ only, no libraries or frameworks
2. Relaxed Rules - Allows jQuery for progressive enhancement

Choose the version that best fits your project requirements.

🚀 Setup Instructions for Your AI Assistant

Getting Started

Step 1: Clone the Repository

First, clone this repository to get all the MPA-First guideline files:

git clone https://github.com/RealistSec/mpa-first-guidelines.git
cd mpa-first-guidelines

Step 2: Setup for Your AI Assistant

Choose your AI assistant below and follow the specific setup instructions.

For GitHub Copilot in VS Code

Expand for GitHub Copilot in VS Code

1. Copy the appropriate agent file to .github/agents/ in your project root:

   # For strict rules
   cp mpa-strict-agent.md .github/agents/mpa-strict-agent.md
   
   # For relaxed rules (jQuery allowed)
   cp mpa-relaxed-agent.md .github/agents/mpa-relaxed-agent.md
   

2. Add a reference to the agent file in your .github/copilot-instructions.md (create the file if it doesn't exist):

   # MPA-First Guidelines Reference
   
   For MPA-first development guidelines, reference the agent file:
   - Strict rules: @mpa-strict-agent
   - Relaxed rules: @mpa-relaxed-agent
   
   This ensures GitHub Copilot uses MPA-first principles throughout your project.
   

   If .github/copilot-instructions.md already contains custom instructions, append the agent reference instead of overwriting.

For GitHub Copilot CLI

For GitHub Copilot CLI setup

1. clone this repo or copy the appropriate agent file to your project:

   # For strict rules place the file
   cp .github/agents/mpa-strict-agent.md .github/agents/mpa-strict-agent.md
   
   # For relaxed rules
   cp .github/agents/mpa-relaxed-agent.md .github/agents/mpa-relaxed-agent.md
   

The agent files are n