AI Assistant Context Index

🤖 Purpose: Central entry point for AI assistants working on this Astro project

Quick Start for AI Assistants

When working on this project, follow this priority order:

1. Understand the Track: Check if working on MVP or Showcase version
2. Review Current Phase: Identify which implementation phase is active
3. Check Performance Budgets: Ensure changes stay within limits
4. Follow Design System: Use established tokens and patterns
5. Maintain Type Safety: TypeScript strict mode is required

Project Overview

This is a modern Astro static site with:

• Framework: Astro 7.2.2 with zero JavaScript by default
• Styling: Tailwind CSS 4.3.3 with design tokens
• Content: MDX with Astro Content Collections
• Performance: Lighthouse 95+ target
• Deployment: GitHub Pages (via the starter’s deploy.yml workflow)

Key Directories

src/
├── components/     # UI components (atomic design)
├── content/        # Content collections (blog, projects)
├── layouts/        # Page layouts
├── pages/          # Routes
├── styles/         # Global CSS
└── utils/          # Helper functions

docs/
├── implementation-guides/  # Phase-by-phase guides
├── adr/                   # Architecture decisions
└── ai-context/           # AI assistant docs

Current Implementation Status

The current active phase is defined in the current_phase frontmatter value of the starter’s docs/ai-context/INDEX.md (currently 6).

To determine the status of any phase:

1. Consult the Implementation Guides overview for the full, ordered list of phases (0-12).
2. Compare a phase’s number to the current_phase value:
   • If phase_number < current_phase, it is Completed.
   • If phase_number == current_phase, it is Active.
   • If phase_number > current_phase, it is Pending.

Update this value manually when a phase is complete, then run pnpm run roadmap:update to sync the roadmap checkboxes in docs/README.md.

Critical Constraints

Performance Budgets

• JavaScript: < 160KB total (raw, uncompressed — enforced in CI)
• CSS: < 50KB total
• Images: < 200KB each (after optimization)
• Lighthouse Scores: Performance 95+, Accessibility 98+ (CI floors: 90 performance, 95 accessibility)

Note on Budget Strictness: These budgets are intentionally strict to maintain excellent Core Web Vitals and ensure a high-quality user experience. For instance, the project’s INP/FID goals (target < 100ms) are more demanding than Google’s ‘good’ threshold of 200ms. While this is beneficial for outcomes like a developer portfolio, it’s important to communicate to stakeholders that CI may fail even on seemingly small regressions that exceed these tight budgets. This proactive communication helps manage expectations around development velocity and quality gates.

Technical Rules

1. client:load is forbidden without ADR justification (ADR-001). The starter uses no client:load anywhere — islands use client:idle or client:visible.
2. Prefer CSS solutions over JavaScript
3. Use Astro Image component for all images
4. TypeScript strict mode required
5. Biome for linting/formatting (not ESLint/Prettier)

Common AI Tasks

Component Creation

"Create an accessible [component] with:
- TypeScript interfaces
- Tailwind styling using our tokens
- ARIA labels and keyboard navigation
- MVP version (no JS) and Showcase version (minimal JS)"

Performance Optimization

"Optimize [feature] to:
- Reduce bundle size
- Improve Core Web Vitals
- Lazy load appropriately
- Stay within our budgets"

Content Modeling

"Create Astro content collection for [type] with:
- Zod schema
- TypeScript types
- Draft mechanism
- SEO fields"

Key Configuration Files

Always Reference These

1. astro.config.mjs - Astro configuration (Tailwind runs CSS-first via @tailwindcss/vite — there is no tailwind.config.*)
2. tsconfig.json - TypeScript settings
3. biome.json - Linting/formatting rules
4. src/content.config.ts - Content schemas

Performance Monitoring

1. performance-baseline.json (repo root, generated by pnpm run perf:baseline) - Target metrics
2. lighthouserc.json + lighthouserc.mobile.json - Lighthouse CI configs (desktop + mobile)
3. public/_headers - Security headers

Design System Reference

Color Tokens

• Semantic: background, foreground, border, primary, etc.
• Format: HSL values in CSS variables
• Dark Mode: Automatic with .dark class

Typography Scale

• Sizes: xs, sm, base, lg, xl, 2xl, 3xl, 4xl
• Font: Inter Variable (self-hosted)
• Line heights: Included in tokens

Spacing System

• Scale: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24
• Usage: Consistent padding/margin

Content Types

Projects Collection

• Fields: title, description, date, technologies, outcomes
• Features: Draft mode, featured flag, custom sorting

Blog Collection

• Fields: title, description, date, tags, author
• Features: MDX support, related posts, reading time

Navigation Collection

• Type: Data collection (JSON)
• Usage: Header/footer navigation items

Development Workflow

Before Making Changes

1. Run pnpm run check - Ensure types are correct
2. Run pnpm run tokens:build - If design tokens changed
3. Check current Git branch - Follow branch strategy

While Developing

1. Use pnpm run dev - Local development
2. Test on mobile - Mobile-first approach
3. Check accessibility - Keyboard navigation

Before Committing

1. Pre-commit hooks run automatically
2. Validates formatting and types
3. Ensure CI will pass

Common Pitfalls to Avoid

1. Adding unnecessary JavaScript - Prefer CSS solutions
2. Hardcoding values - Use design tokens
3. Skipping accessibility - Always include ARIA
4. Ignoring performance - Check bundle size
5. Breaking types - Run TypeScript checks

Getting Help

Internal Documentation

• Implementation Guides overview - Chronological build sequence.
• Detailed Phase Guides: /implementation-guides/
• Architecture Decisions: ADR-000 onwards
• Component Patterns: /patterns/component-patterns/

External Resources

• Astro Docs
• Tailwind Docs
• MDN Web Docs

Maintenance Notes

This context should be updated when:

• Completing a new phase
• Making architecture decisions
• Changing performance budgets
• Adding new content types
• Updating dependencies

Self-Maintenance Checklist

When any of the following occur, update this file immediately:

1. Phase Completion

   • [ ] Check the box for the completed phase
   • [ ] Update “Active Phase” to the next phase
   • [ ] Add any new constraints or rules discovered

2. New ADR Accepted

   • [ ] Add to “Critical Constraints” if it affects development
   • [ ] Update relevant sections (e.g., new performance budgets)
   • [ ] Link to the ADR in the appropriate section

3. Dependency Changes

   • [ ] Update version numbers in “Project Overview”
   • [ ] Add migration notes if breaking changes
   • [ ] Update any affected code examples

4. Content Model Changes

   • [ ] Update “Content Types” section
   • [ ] Add new fields or collections
   • [ ] Note any migration requirements

5. New Patterns or Anti-patterns

   • [ ] Add to “Common Pitfalls to Avoid”
   • [ ] Update “Common AI Tasks” with new examples
   • [ ] Create new pattern documents if needed

Maintenance Commands

# After completing a phase: bump `current_phase` in docs/ai-context/INDEX.md,
# then sync the roadmap checkboxes in docs/README.md
pnpm run roadmap:update

Review Schedule

• Weekly: Quick check during team sync
• Phase Completion: Full review and update
• Monthly: Comprehensive accuracy audit
• Quarterly: Structure and organization review

Last reviewed: 2026-07-02 Next review due: 2026-12-31