Skip to content

AGENTS.md

Latest commit

 

History

History
155 lines (118 loc) · 5.91 KB

AGENTS.md

File metadata and controls

155 lines (118 loc) · 5.91 KB

Agent Instructions — brackenw3.github.io

This file is read automatically by Gemini, Jules, Claude, and other AI agents. It provides operational context for this repo AND the broader willbracken.com platform.

Platform status and task tracking: See PLATFORM_STATUS.md API endpoints and credentials: See GEMINI.md Architecture diagrams: See GEMINI.md → Platform Architecture Summary

This Repository

brackenw3.github.io — Will Bracken's portfolio and developer hub, undergoing dramatic reconstruction.

Currently hosted at: brackenw3.github.io (GitHub Pages) Target deployment: Migrate to Cloudflare Pages at brackenw3.willbracken.com or keep on GitHub Pages Domain: willbracken.com points to a separate CF Pages site (force graph landing page)

Existing pages (do not delete, refactor/integrate):

index.html          — main portfolio (46KB, primary entry point)
ai-lab.html         — AI lab demos and experiments
analytics.html      — data analytics showcase
data-science.html   — data science projects
go-systems.html     — Go language projects
ms-teams-demo.html  — Microsoft Teams integration demo
code-galaxy.html    — code visualization
projects.html       — projects listing
login.html          — authentication page

Tech Stack

  • Frontend: HTML5, Bootstrap 5, Chart.js, Three.js, D3.js
  • Design system: Midnight Terminal (dark, professional)
  • Backend API: Cloudflare Workers (see Cloudflare_Workers/)
  • CF Pages Functions: functions/ directory — serverless endpoints, no separate deployment
  • CI/CD: GitHub Actions (.github/workflows/)
  • Data: Python scripts in scripts/

Live Platform APIs Available to This Site

All are callable from CF Pages Functions or directly from the frontend. Full API reference: see GEMINI.md.

AI chat:      POST https://ai-router.will-i-bracken.workers.dev/chat
Site assist:  POST https://site-assistant.will-i-bracken.workers.dev/chat
Status data:  GET  https://analytics-dashboard.will-i-bracken.workers.dev/api/health
AI agents:    POST https://agent-{code|research|data|writing|gemini}.will-i-bracken.workers.dev/

Use the ai-router for all AI features — it handles tier selection, rate limiting, and fallback. Don't call OpenAI/Anthropic/Gemini APIs directly; route through ai-router.

Design Direction

Style

  • Dark theme (space / terminal aesthetic)
  • Accent: #60a5fa (blue), #34d399 (green), #a78bfa (purple)
  • Font: Inter or system-ui, clean, minimal
  • Mobile-first, works on all screen sizes

Key UI goals

  • Non-technical accessible — family members should understand it
  • Live data — pull real metrics from analytics-dashboard worker, not dummy data
  • Interactive — force graph, hoverable elements, not static
  • Fast — no heavy framework bloat; vanilla JS or lightweight libs preferred

Force graph (willbracken.com landing)

  • Separate site at BrackenW3/Cloudflare/apps/willbracken-landing (React + Vite)
  • Shows platform architecture as animated network graph
  • This repo (brackenw3.github.io) is the PORTFOLIO — separate from the landing page
  • Portfolio should showcase projects with live status, not duplicate the graph

What Gemini Should Build

Phase 1 (current focus)

  1. Redesign index.html — portfolio hero, project cards, skills
  2. Live status integration — fetch from analytics-dashboard worker
  3. GitHub repos showcase — use GitHub API via CF Pages Function, cached
  4. AI demo chat widget — connects to site-assistant worker
  5. Clean navigation linking all existing pages

Phase 2 (after Phase 1 stable)

  1. LinkedIn widget or custom "about" section
  2. Project detail pages (individual apps, demos)
  3. Integrate Jira project tracking (family goals visibility, sanitized)
  4. SSO via Cloudflare Access (no app-level auth needed)

Backend approach

  • Use CF Pages Functions (functions/api/*.ts) for dynamic data — no Docker needed
  • Functions have access to same CF bindings as Workers
  • Docker only for complex local dev of separate backend services
  • Keep portfolio API calls simple: GitHub API, analytics-dashboard, n8n webhooks

Security Rules

  • Never hardcode secrets in any file
  • API keys go in CF Pages environment variables or GitHub Secrets
  • Use GEMINI.md → Key Environment Variables section for CF Pages env var names
  • CORS: enforce same-origin or willbracken.com only for POST endpoints
  • Sanitize all user input with DOMPurify before rendering

GitHub Actions Policy

  • Single AI reviewer only (ai-pr-review.yml) — only on PRs ≥50 lines changed
  • No PR summaries — read the PR description yourself
  • Max 5 bullets in any review comment
  • Cache npm/pip on every CI run
  • Deploy only on main branch push
  • Do not add additional AI review workflows

Testing

node --test tests/test_cors.mjs   # Worker CORS tests
npm test                          # JS tests if applicable

Directory Structure

brackenw3.github.io/
├── AGENTS.md                # ← You are here. Platform context for all agents.
├── GEMINI.md                # Full API reference + architecture + credentials guide
├── PLATFORM_STATUS.md      # Live task tracking (done/in-progress/backlog)
├── .github/workflows/       # CI/CD (optimized — single AI reviewer, caching)
├── assets/
│   ├── css/styles.css         # Midnight Terminal design system
│   ├── js/                    # Dashboard and portfolio scripts
│   └── data/                  # Featured project definitions (JSON)
├── Cloudflare_Workers/      # Edge worker code and wrangler config
├── functions/               # CF Pages Functions (serverless API endpoints)
├── scripts/                 # Python data generation
├── tests/                   # Node.js worker tests
└── *.html                   # Portfolio pages (preserve all existing)