Copilot instructions

1# Copilot Instructions: MPA-First Guidelines Repository
2 
3## Repository Purpose
4 
5This is a **reference documentation repository** containing MPA (Multi-Page Application) development guidelines for AI coding agents. Users copy these guidelines into their own projects to teach AI tools (GitHub Copilot, Cursor, Claude, Codex, etc.) to generate MPA-first code instead of defaulting to SPA frameworks.
6 
7## Key Files & Their Roles
8 
9**Base rule files:**
10- **`mpa-rules.md`** - Comprehensive, strict MPA-first mandate with strict PHP & vanilla JS only. This is the primary reference document.
11 
12- **`mpa-relaxed-rules.md`** - Variant ruleset allowing full use of PHP & jQuery for progressive enhancement while maintaining MPA architecture.
13 
14**Assistant-specific base instruction files:**
15- **`.github/agents/mpa-strict-agent.md`** - Copilot agent-specific instructions file based on `mpa-rules.md` for strict MPA adherence.
16 
17- **`.github/agents/mpa-relaxed-agent.md`** - Copilot agent-specific instructions file based on `mpa-relaxed-rules.md` for a more lenient MPA approach.
18 
19**Documentation:**
20- **`README.md`** - User-facing documentation explaining the problem, solution, and how to integrate these rules into AI coding workflows.
21 
22## Writing Style & Tone
23 
24When editing these guidelines:
25 
26- **Be authoritative and prescriptive** - Use "MUST" and "DO NOT" language. These are rules, not suggestions.
27- **Provide concrete examples** - Every principle should have a code snippet showing the correct pattern.
28- **Explain the "why"** - Help developers understand the philosophy, not just the mechanics.
29- **Stay opinionated** - The entire premise is rejecting the SPA-default paradigm. Don't hedge or equivocate.
30 
31## Content Maintenance Patterns
32 
33### Adding New Rules or Sections
34 
351. **Keep examples realistic** - Use patterns that would appear in actual projects
362. **Maintain parallelism** - Both `mpa-rules.*` with `.github/agents/mpa-strict-agent.md` and `mpa-relaxed-rules.*` with `.github/agents/mpa-relaxed-agent.md`
37 should cover the same topics in the same order
383. **Update the table of contents** - If you add major sections, ensure navigation is clear
39 
40### Updating Existing Content
41 
42- **Preserve the document structure** - The current flow (Prime Directive → HTML → CSS → PHP → JS → Security) is intentional
43- **Keep code examples modern** - Target current 2025-26 web standards (PHP 8.1+, ES2020+, modern CSS)
44- **Maintain accessibility focus** - A11Y is not optional in these guidelines
45- **Update agent files in parallel** - When modifying base rule files, ensure corresponding assistant-specific files are updated to maintain consistency, keeping them concise and directive for AI prompts
46 
47## Technical Constraints
48 
49- **Markdown formatting** - All rule files use standard markdown with fenced code blocks
50- **No dependencies** - This is a pure documentation repository with no build tools or runtime
51- **Git-friendly** - Keep line lengths reasonable for clean diffs
52 
53## Philosophy to Preserve
54 
55This repository champions:
56 
571. **Platform-first thinking** - HTML, CSS, PHP, and browser APIs over JavaScript frameworks
582. **Progressive enhancement** - Core functionality works without JS
593. **Performance as a feature** - Fast load times from server-rendered HTML
604. **SEO & accessibility by default** - Not bolted on as afterthoughts
615. **Simplicity over novelty** - Boring, proven technology over the latest trends
62 
63## Common Edits & How to Handle Them
64 
65### "Should we add framework X?"
66No. If it's a client-side SPA framework (React, Vue, Svelte, etc.), it's explicitly banned. Even if "everyone uses it."
67 
68### "Can we include framework-based SSR?"
69No. Next.js, Nuxt, SvelteKit, etc. are still SPA architectures at their core. True MPAs use traditional server-side rendering (PHP, Node.js + templates, Ruby, Python, etc.).
70 
71### "What about Htmx/Alpine.js/other minimal JS libraries?"
72These could be mentioned as acceptable enhancement tools since they embrace progressive enhancement, but only in the relaxed variant. The strict `mpa-rules.md` stays vanilla-only.
73 
74## When Users Request Changes
75 
76If a user wants to add content:
77- Ask what problem they're solving
78- Ensure it aligns with MPA-first principles
79- Add concrete examples, not abstract advice
80- Update both variants if applicable
81 
82If a user wants to make rules more lenient:
83- Consider whether it compromises the MPA architecture (banned)
84- Or just adds a helpful tool for enhancement (potentially allowed in relaxed variant)
85 
86## Documentation Standards
87 
88- **Use semantic HTML examples** - Always show proper `<header>`, `<main>`, `<article>`, etc.
89- **Include accessibility attributes** - `alt` text, `aria-label`, proper `<label>` associations
90- **Show security patterns** - CSRF tokens, parameterized queries, CSP headers
91- **Demonstrate modern CSS** - Grid, Flexbox, Custom Properties, View Transitions
92 
93## Adapting for Different AI Assistants
94 
95When integrating these guidelines into other AI tools (e.g., Cursor, Claude, Codex), prioritize the assistant-specific files (e.g., `.github/agents/mpa-strict-agent.md`) as the primary source of truth for prompts. These are condensed and directive, making them ideal for AI consumption. Fork and customize them for the target assistant's format, maintaining parallelism with the base rule files. Test integrations to ensure strict adherence to MPA principles and progressive enhancement.
96