diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md new file mode 100644 index 0000000..0ae3c58 --- /dev/null +++ b/AGENT_INSTRUCTIONS.md @@ -0,0 +1,421 @@ +# Agent Instructions for cb341.dev Portfolio + +This file contains project-specific guidelines for AI agents working on this Astro portfolio site. + +## Project Overview + +- **Site**: https://cb341.dev +- **Framework**: Astro 4.x (static site generation) +- **Developer**: Dani Bengl - Full-Stack Developer +- **License**: CC-BY-4.0 +- **Package Manager**: npm (package-lock.json present) +- **Dev Server**: `localhost:4321` + +## Core Principles + +### Priorities (in order of importance) +1. **Consistency** - Match existing patterns and conventions throughout the codebase +2. **Performance** - Optimize for speed, minimal bundle size, fast load times +3. **Accessibility (a11y)** - ARIA labels, semantic HTML, keyboard navigation +4. **SEO** - Meta tags, structured data, semantic markup +5. **Developer Experience** - Readable, maintainable, clear patterns + +### Philosophy +- Keep it minimal and fast +- Static-first, avoid client-side JavaScript +- Semantic HTML over divs and classes +- Let it fail fast - minimal error handling except at system boundaries +- No unnecessary abstractions or over-engineering + +## File & Component Naming Conventions + +**Follow existing patterns:** +- Components: `PascalCase.astro` (e.g., `BlogPostCard.astro`, `NavLink.astro`) +- Layouts: `PascalCase.astro` (e.g., `BaseLayout.astro`) +- Pages: `kebab-case.astro` or `[...slug].astro` for dynamic routes +- Utilities: `camelCase.ts` (e.g., `dateHelpers.ts`) +- Directories: `lowercase` (e.g., `components/`, `layouts/`, `pages/`) + +## Code Structure + +### Directory Organization +``` +src/ +├── assets/ # Static assets (images, etc.) +│ └── blog/ # Blog post images (WebP format) +├── components/ # Reusable Astro components +├── content/ # Content collections +├── data/ # Data files +├── layouts/ # Layout components +├── pages/ # Routes (file-based routing) +└── utils/ # Utility functions +``` + +## Styling Guidelines + +### When to Add Styles +- **Only add CSS when explicitly requested** +- Don't add styling to components unless the user asks for it +- Rely on semantic HTML and existing styles when possible + +### How to Add Styles (when requested) +- **ONLY** use scoped ` +``` + +## JavaScript Guidelines + +### Rules +- **Minimize or avoid client-side JavaScript entirely** +- Prefer static generation over client-side interactivity +- **NEVER** add complex state management libraries +- If JavaScript is absolutely necessary, keep it minimal and vanilla +- Leverage Astro's server-side rendering capabilities + +## HTML & Accessibility + +### Semantic HTML +- **Always** use proper HTML5 semantic elements +- Prefer `
`, `
`, `