AGENTS.md - Universal AI Agent Configuration

This file provides comprehensive guidance for AI agents working with code in this repository.

Project Context

This is Andrew's Notebook - a technical documentation site hosted on GitHub Pages covering science and technology topics. It's a single-maintainer project by @AndrewAltimit with a container-first philosophy:

• GitHub Pages Site: https://andrewaltimit.github.io/Documentation/
• Content Focus: Physics and Technology documentation
• Jekyll-based: Uses minimal-mistakes theme
• Self-hosted CI/CD: All workflows run on self-hosted runners
• Container-first: All Python operations run in Docker containers

AI Agent Ecosystem

Active Agents

• Claude Code: Primary development assistant for documentation, CI/CD, and automation
• Gemini CLI: Automated PR code reviews
• GitHub Copilot: In-PR code suggestions

Build/Lint/Test Commands

Core CI/CD Commands

# Full CI pipeline - ALWAYS run before committing
./automation/ci-cd/run-ci.sh full

# Individual stages
./automation/ci-cd/run-ci.sh format      # Check formatting
./automation/ci-cd/run-ci.sh lint-basic   # Basic linting
./automation/ci-cd/run-ci.sh lint-full    # Full linting suite
./automation/ci-cd/run-ci.sh autoformat   # Auto-format code

Jekyll Site Building

# Build site locally
docker-compose run --rm jekyll

# Serve locally for testing (http://localhost:4000)
cd github-pages
docker run --rm \
  --volume="$PWD:/srv/jekyll:Z" \
  --volume="$PWD/vendor/bundle:/usr/local/bundle:Z" \
  -p 4000:4000 \
  jekyll/jekyll:4.2.2 \
  jekyll serve --host 0.0.0.0

Link Checking

# Check all markdown links
python automation/analysis/check-markdown-links.py

# Check only internal links
python automation/analysis/check-markdown-links.py --internal-only

# Check specific directory
python automation/analysis/check-markdown-links.py --file github-pages/docs/

Code Style Guidelines

Formatting Standards

• Line Length: 127 characters (flake8, isort) or 88 (pylint)
• Python Formatter: Black with default settings
• Import Sorting: isort with Black-compatible profile
• YAML/JSON: 2-space indentation

Naming Conventions

• Variables/Functions: snake_case
• Classes: PascalCase
• Constants: UPPER_SNAKE_CASE
• Private Members: _leading_underscore

Documentation Style

• Markdown: GitHub-flavored markdown
• Wiki Format: Professional reference style, not tutorials
• Code Examples: Include working, tested examples
• Diagrams: Use Mermaid, TikZ, or images where helpful

Container Operations

Docker Commands

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f python-ci

# Stop services
docker-compose down

# Rebuild after changes
docker-compose build python-ci

# Run any command in CI container
docker-compose run --rm python-ci python --version

Container Architecture

• jekyll: Jekyll site building (jekyll/jekyll:4.2.2)
• python-ci: Python CI/CD tools (Python 3.11)
• mcp-content-creation: Manim animations, LaTeX compilation

Development Workflow

Before Starting Work

1. Pull latest changes: git pull
2. Verify Jekyll builds: docker-compose run --rm jekyll

During Development

1. Make changes to documentation or code
2. Run formatting: ./automation/ci-cd/run-ci.sh autoformat
3. Run linting: ./automation/ci-cd/run-ci.sh lint-basic
4. Check links: python automation/analysis/check-markdown-links.py

Before Committing

1. ALWAYS run full CI: ./automation/ci-cd/run-ci.sh full
2. Verify Jekyll builds successfully
3. Check that all internal links work

Project Structure

Documentation/
├── github-pages/           # Jekyll site source
│   ├── docs/              # Main documentation
│   │   ├── physics/       # Physics topics
│   │   ├── technology/    # Technology topics
│   │   └── ai-ml/         # AI/ML topics
│   ├── _data/             # Navigation data
│   ├── _layouts/          # Jekyll layouts
│   └── assets/            # Static assets
├── automation/            # CI/CD scripts
│   ├── ci-cd/            # Build and lint scripts
│   ├── analysis/         # Link checking tools
│   └── setup/            # Environment setup
├── docker/               # Dockerfiles
├── tools/                # Utilities
│   └── mcp/             # Content creation MCP server
└── outputs/              # Generated content

Documentation Topics

Physics

• Classical Mechanics
• Quantum Mechanics
• Quantum Field Theory
• Relativity
• Statistical Mechanics
• Thermodynamics
• Condensed Matter Physics
• String Theory

Technology

• Docker, Kubernetes
• Terraform, AWS
• Git, Branching Strategies
• Networking, Database Design
• Cybersecurity

AI/ML

• Stable Diffusion
• ComfyUI, LoRA Training
• Model Comparisons
• ControlNet

Security Best Practices

1. Never commit secrets: Use environment variables
2. Validate links: Ensure documentation links work
3. Container isolation: Keep services separated
4. Self-hosted control: Full control over CI/CD environment

Quick Reference

Essential Commands

# Full CI check
./automation/ci-cd/run-ci.sh full

# Auto-format code
./automation/ci-cd/run-ci.sh autoformat

# Build Jekyll site
docker-compose run --rm jekyll

# Check links
python automation/analysis/check-markdown-links.py

Key Files

• CLAUDE.md: Claude-specific instructions
• AGENTS.md: Universal agent configuration (this file)
• CRUSH.md: Crush agent configuration
• docker-compose.yml: Service definitions
• _config.yml: Jekyll configuration (in github-pages/)
• .github/workflows/: CI/CD workflows

Remember: This is a documentation site. Focus on clear, accurate technical writing with professional wiki-style presentation. Always use containers for consistency.