diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bfa0604 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,206 @@ +# AGENTS.md + +Guidance for any coding agent working in this repository. This is the +primary, tool-agnostic context source for AI agents (Claude Code, Cursor, +Copilot, Codex, etc.); tool-specific files like `CLAUDE.md` defer to it. + +## What this repo is + +A Next.js (App Router) implementation of +[techtankto.com](https://www.techtankto.com/), Toronto's volunteer-run +tech community website. The redesign moves away from a flat "link-tree" +layout toward a conversion-oriented onboarding hub that funnels +visitors into specific roles — attendee, speaker, host, sponsor, or +volunteer. + +Specs live in `prd/` (see `prd/PRD.md`); application code lives in +`app/`, with shared pieces in `components/`, `constants/`, and +`public/`. The initial UI scaffold was generated from the PRD via v0 — +[original prompt and generation](https://v0.app/chat/website-generation-from-prd-eLek8w4RJMh). + +For developer-facing setup (scripts, directory tree, route map), see +[`README.md`](./README.md). + +## Repository layout + +``` +. +├── AGENTS.md # This file — primary agent context +├── CLAUDE.md # Claude Code stub that includes AGENTS.md +└── prd/ + ├── PRD.md # Top-level product requirements document + └── pages/ # One spec per route + ├── home.md # / + ├── about.md # /about + ├── events.md # /events + ├── press-kit.md # /press-kit + ├── get-involved/ # Onboarding hub (shared layout) + │ ├── index.md # /get-involved + │ ├── speaker.md # /get-involved/speaker + │ ├── host.md # /get-involved/host + │ ├── sponsor.md # /get-involved/sponsor + │ └── volunteer.md # /get-involved/volunteer + ├── resources/ # Resources folder + │ ├── media-kit.md # /resources/media-kit + │ └── design-system.md # /resources/design-system (brand guidelines + design token reference) + └── legal/ # Legal folder (shared layout) + ├── terms-of-service.md + ├── privacy-policy.md + └── code-of-conduct.md +``` + +`prd/PRD.md` is the top-level document. Each file in `prd/pages/` fully +describes one route. The file tree under `prd/pages/` mirrors the final +URL structure. + +## How the information architecture works + +The redesign replaces a flat "link-tree" layout with a +**conversion-oriented onboarding hub**: + +- `/` — social-proof-driven home (testimonials, event photos, logo cloud). +- `/about` — values manifesto built on four pillars: **Community, + Innovation, Teamwork, Respect**. +- `/get-involved` — onboarding hub with four role sub-pages (Speaker, + Host, Sponsor, Volunteer), each ending in an intake action (email us + at `techtankto@gmail.com`). +- `/events` — embedded Luma calendar. +- `/press-kit` — standalone brand assets and fast facts for media. +- `/legal` — grouped compliance documents. + +The `/get-involved` and `/legal` sections are designed for **Next.js +shared layouts** (sticky sub-nav, persistent CTA, consistent form/ +document styling). + +## Working conventions + +### Editing specs + +- Keep the per-page structure consistent: Purpose, Primary audience, + Key messages, Content sections, CTAs, Functional requirements, + Acceptance criteria. +- Internal links between PRD documents are relative (e.g. + `pages/home.md` from `prd/PRD.md`; `../about.md` from a + `prd/pages/legal/*.md` file). +- When the IA changes, update **both** `prd/PRD.md` §2 (Route map / + shared layouts / navigation) **and** the affected per-page files. + Keeping these in sync is the single most important maintenance task. +- Never introduce a URL in a page spec that isn't reflected in the + Route map in `prd/PRD.md`. + +### Tone in specs + +- Concrete, not aspirational. If organizers haven't confirmed a number + (attendance, tier, timing), flag it instead of inventing one. +- Conversion-oriented: every page spec must declare **one dominant + CTA**, and `/get-involved/*` must end in an intake action (email us). +- Social proof first: testimonials, real event photography, and + logo clouds are required patterns, not decoration. + +### Component conventions + +Components follow [shadcn/ui](https://ui.shadcn.com/) patterns with +[CVA](https://cva.style/) (`class-variance-authority`) for variant management: + +- Define visual variants (color, size, style) as CVA `variants` — never + as ad-hoc `className` overrides at the call site. +- Use `cn()` from `lib/utils.ts` (clsx + tailwind-merge) for all + className composition. +- Expose `asChild` via Radix `Slot` when a component needs to delegate + rendering to its child (e.g. `