AGENTS.md - Instructions for Grok Build (Composer 2.5) and Other AI Agents

Project Overview

This is the official Physicsy website for Jason Olson (Gulf Breeze High School science teacher).
Purpose: Professional, clean, fast-loading site for students, parents, and colleagues featuring class resources, blog posts, robotics club info, writing projects, and AI/philosophy content.
Stack: Jekyll + GitHub Pages (static site). Goal = maximum maintainability with weekly updates.
Tone: Professional yet approachable, clear, encouraging for students. Emphasize excellence, first-principles thinking, and curiosity.

Build command: bundle exec jekyll build (or jekyll build).
Never commit the _site/ folder or .jekyll-cache/.
Use only GitHub Pages supported plugins by default. For advanced plugins, we will use GitHub Actions.
All blog/news posts go in _posts/ with filename format YYYY-MM-DD-descriptive-title.md.
Use proper YAML front matter on every page/post.
Relative links preferred. Optimize all images.

Semantic HTML5, mobile-first responsive design.
Minimal, clean CSS (Tailwind or plain if we choose).
Markdown with proper headings, lists, tables, and code blocks.
All new content must be high-quality, accurate, and aligned with teaching/STEM values.
Before committing major changes: Run local build and suggest testing.

Always output a clear PLAN first before editing files.
Show diffs/summaries of changes.
Use feature branches for layout redesigns or major refactors (git checkout -b feature/new-design).
After changes, remind to run bundle exec jekyll serve for local preview.
Respect existing content — improve organization without losing information.

Prioritize clarity and educational value.
Include calls to action for students (e.g., “Try this practice problem”, links to resources).
Update copyright/year dynamically where possible.
SEO-friendly titles and descriptions.

This file evolves — suggest improvements when needed.