AI Agent Instructions for Ricardo A S Frantz Personal Website

⚠️ IMPORTANT NOTE: This file is linked to claude.md via a symbolic link. Always edit this file (agents.md) and never edit claude.md directly. The symbolic link ensures compatibility across different development environments and AI tools.

This is a single-page personal website for Ricardo A S Frantz, a computational scientist, researcher, and engineer.

⚠️ CRITICAL: Single-Page Website Only

This website MUST remain a single-page site with NO additional pages or routes.

URL Structure Requirements:

Content Strategy:

Purpose:

This serves as a personal professional portfolio - a comprehensive single-page showcase of Ricardo’s work, publications, projects, and contact information.

Project Overview

Development Commands

Start Development Server

bundle exec jekyll serve

This starts the local development server at http://localhost:4000 with live reload enabled.

Build for Production

bundle exec jekyll build

Generates static files in the _site directory for deployment.

Install Dependencies

bundle install

Installs Ruby gems specified in Gemfile.

Update Dependencies

bundle update

Updates all gems to their latest compatible versions.

Project Structure

├── _config.yml          # Jekyll configuration (optimized for single-page)
├── _assets/            # CSS, JS, images, fonts
├── _layouts/           # Page templates (minimal set)
├── _publications/      # Academic papers data (not rendered as pages)
├── _site/              # Generated static files (gitignored)
├── index.md           # Main page content (ONLY content file)
├── agents.md          # AI agent instructions (linked to claude.md)
├── claude.md          # Symbolic link to agents.md
└── Gemfile            # Ruby dependencies

Content Guidelines

Single-Page Content Structure

File Organization

Styling and Design

CSS Organization

Color Scheme

Performance and SEO

Image Optimization

SEO Best Practices

Deployment

GitHub Pages with GitHub Actions

This site uses the latest GitHub Pages deployment standards with GitHub Actions. The deployment workflow is located in .github/workflows/pages.yml and uses the modern GitHub Actions deployment method.

Current Deployment Setup:

Latest GitHub Actions Workflow Structure (2024/2025 Standards):

name: Deploy GitHub Pages

on:
  push:
    branches: [ main ]  # or master if using legacy branch
  pull_request:
    branches: [ main ]  # For CI validation
  workflow_dispatch:   # Allow manual triggers

# Prevent concurrent deployments
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  # Build job (runs on push and PR)
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5  # Latest version

      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
          # Optional: include future posts for testing
          # future: true

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4  # Latest version

  # Deploy job (only runs on push to main branch)
  deploy:
    if: github.ref == 'refs/heads/main'  # Only deploy from main branch
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4  # Latest version

Build Requirements

Deployment Best Practices (2024/2025 Standards)

  1. Environment Management: Use the github-pages environment for deployment tracking and URL output
  2. Concurrency Control: Prevent multiple simultaneous deployments with cancel-in-progress: true
  3. Latest Action Versions:
    • actions/configure-pages@v5
    • actions/upload-pages-artifact@v4
    • actions/deploy-pages@v4
  4. Security: Use minimal required permissions (contents: read, pages: write, id-token: write) and OIDC token authentication
  5. CI/CD Integration: Run build job on both push and pull requests for validation, deploy only from main branch
  6. Manual Deployment: Include workflow_dispatch trigger for manual deployment capability
  7. Monitoring: Deployment status and URLs are tracked in GitHub’s deployment dashboard
  8. Rollback: GitHub Pages maintains deployment history for easy rollbacks

Local Development Testing

# Install dependencies
bundle install

# Start local server
bundle exec jekyll serve

# Update GitHub Pages gem to match production
bundle update github-pages

Code Quality

Markdown

Liquid Templates

Accessibility

Agent Guidelines

When Working on This Project:

  1. Always test locally before committing changes
  2. Respect the existing design system and don’t break responsiveness
  3. Follow the established naming conventions for files and classes
  4. Keep performance in mind - optimize images and minimize CSS/JS
  5. Maintain accessibility standards in all changes
  6. Use proper Git commit messages that follow conventional commits
  7. Never modify _site/ directory directly - it’s auto-generated

Common Tasks:

Dependencies and Versions

Important Notes

CSS Utility Classes - Critical Note

⚠️ IMPORTANT: When using custom CSS utility classes (like spacing, margins, padding), ensure they are properly defined in _sass/_utilities.scss before using them in HTML.

Common Issue: If you use utility classes in HTML (like mt-8, mb-8, etc.) but they don’t exist in the CSS utilities file, browsers will silently ignore them with no errors, resulting in unexpected styling behavior.

Example: The mt-8 and mb-8 classes were missing from the utilities file, causing spacing issues. They were added with:

.mt-6 { margin-top: $spacing-2xl; }
.mt-7 { margin-top: 2.5rem; }
.mt-8 { margin-top: 2rem; }

.mb-6 { margin-bottom: $spacing-2xl; }
.mb-7 { margin-bottom: 2.5rem; }
.mb-8 { margin-bottom: 2rem; }

Rule: Always check _sass/_utilities.scss to verify a utility class exists before using it in HTML markup. Remember to check class definitions when working with CSS utilities.