boblandingpage

Imported from matthudsoncode/boblandingpage (AGENTS.md). Install upstream with npx skills add matthudsoncode/boblandingpage. Copyright stays with the author.

AGENTS.md

This file tells agents and contributors how to work in this repository. Default, choose the simplest correct solution, with clean boundaries and minimal surface area.

0) Setup Questions (answer when convenient, defaults assumed below)

1. Package manager, choose one: (A) pnpm [assumed], (B) npm, (C) yarn
2. Audio format for SFX, choose one: (A) .mp3, (B) .wav, (C) both [assumed both allowed]
3. Sprite sheet layout, choose one: (A) horizontal strip, (B) grid sheet [assumed], (C) separate PNG frames
4. Accessibility preference, choose one: (A) honor prefers-reduced-motion by skipping intro, (B) keep intro mandatory but reduce intensity [assumed B], (C) ignore prefers-reduced-motion
5. Linting, choose one: (A) next lint only [assumed], (B) add prettier, (C) add eslint + prettier + lint-staged
6. Deploy previews, choose one: (A) Vercel preview on PRs [assumed], (B) manual deploy only

If any answer differs, update the “Commands” and “Project Specific Rules” sections accordingly.

1) Project Snapshot

• What this repo is: A Next.js (App Router) pixel themed landing page called Bob.The.Buildas with a mandatory retro intro overlay, plus a simple home page and a placeholder /projects route.
• Primary users: The owner, as a builder portfolio for “projects I am building for fun.”
• Core outcomes: Memorable pixel intro, fast reveal, crisp pixel art, three placeholder project cards, and outbound links to GitHub and Instagram.
• Non-goals: No CMS, blog, auth, payments, database, analytics, API routes, or complex multi-page site.
• Constraints: Minimal dependencies, no heavy animation libraries, intro length target 2.5 to 3.5 seconds, 64x64 PNG assets, integer-only scaling, mobile and desktop performance, Vercel hosting.

2) Senior Engineer Standards (Universal)

2.1 API and Encapsulation (Least Privilege)

• Write code like it is an API used by someone else tomorrow.
• Expose only what is needed, do not leak internal dependencies.
• Prefer narrow getters or small interfaces over exposing entire services or objects.
• Keep internal state truly internal, keep the public surface small.

2.2 Code Quality (No Debt)

• Zero technical debt, no hacks, no “fix later” code, no TODOs.
• Prefer clarity over cleverness.
• Keep changes minimal and scoped to the request.

2.3 Reuse and Loose Coupling

• Design components to be reusable and portable when complexity is equal.
• Depend on abstractions (interfaces, types), not concrete implementations.
• Use dependency injection, pass dependencies explicitly, avoid global state and singletons.
• Avoid “dumping ground” modules like utils/, helpers/, common/ unless truly cohesive.

2.4 Architecture Boundaries

• Keep boundaries clear, UI vs application logic vs domain logic vs infrastructure.
• Do not mix concerns (example, sound playback and DOM event wiring inside unrelated UI).
• Hide implementation details behind small modules (example, SoundController).

2.5 Confidence Before Change

• Do not implement until confident on types, signatures, and expected behavior.
• Read existing code before writing new code.
• If requirements are ambiguous, ask questions rather than guessing.

3) Repo Map (Project Filled)

3.1 Important paths

• app/: Next.js App Router routes and layout shell.
• components/: UI components, including intro overlay and shared controls.
• data/: Static data for placeholder project cards.
• public/: Assets only, sprites and sound effects, no code.
  • public/sprites/: bob-sheet.png, block-intact.png, block-cracked.png, block-broken.png (placeholders acceptable)
  • public/sfx/: hammer.(mp3|wav), break.(mp3|wav) (optional placeholders)
• styles/: Global styles such as globals.css (or app/globals.css depending on setup).
• tailwind.config.*, postcss.config.*: Styling config.

3.2 Key entry points

• App entry: app/layout.tsx
• Home route: app/page.tsx
• Projects route: app/projects/page.tsx
• Shared styling: styles/globals.css (or app/globals.css)
• Placeholder data: data/projects.ts

3.3 Dependency direction (one line)

• [UI Components] → [Local Controllers, data modules] → [Browser APIs]

No server, no services, no DB.

4) Development Workflow

4.1 Commands

Assuming pnpm and standard Next scripts.

• Install: pnpm install
• Dev: pnpm dev
• Build: pnpm build
• Start: pnpm start
• Lint: pnpm lint

If any script is missing, add it in package.json rather than guessing alternatives.

4.2 Definition of done

A change is done only when:

• It meets the requested behavior and acceptance criteria.
• It is tested (manual when automated tests are not present).
• pnpm build passes locally (or in CI).
• There is no dead code left behind.

4.3 Change discipline

• Keep PRs small and focused.
• Do not introduce dependencies unless they materially reduce time or risk.
• Delete unused code when a new approach replaces it.

5) Error Handling and UX (Project Specific)

• Autoplay failures must be silent and non-blocking.
• The intro must not “hang” if audio is blocked or missing.
• If sprite assets are slow to load, show a stable overlay with fixed sizing, start the animation only after required images are ready.
• No layout shift after reveal, landing content must already be rendered under the overlay.

6) Logging and Observability (Minimal)

• Avoid console noise in production.
• If logging is needed for debugging, keep it behind a simple dev guard and remove before merge.

7) Critical Rules (Must Follow)

7.1 Protocol, Interface, Contract Update Rule (Mandatory)

If you change a TypeScript type, props contract, or module interface:

• Find every implementation and every usage.
• Update all conformers and call sites in the same change.
• Verify by building and linting.

7.2 No Guessing Types

• Never guess parameter names, types, or signatures, read definitions first.

7.3 Avoid Race Conditions

• Ensure dependent steps complete before proceeding, especially asset preloads and intro timing.
• Keep the IntroOverlay as a small state machine with explicit states and transitions.

8) Style and Maintainability (Project Specific)

• Prefer CSS keyframes and steps() for sprite animation, avoid heavy animation libraries.
• Keep pixel art crisp:
  • integer-only scaling (2x, 3x, 4x),
  • image-rendering: pixelated,
  • avoid subpixel transforms.
• Keep the intro snappy:
  • target total duration 2.5 to 3.5 seconds,
  • minimal pauses,
  • smooth fade-out while home content is already painted behind.

9) Project Specific Rules (Filled)

9.1 Locked decisions

• Stack: Next.js (App Router) + React + TypeScript + Tailwind CSS
• Hosting: Vercel
• Data: none (static placeholder data only)
• Auth, payments, analytics: none
• External integrations: outbound links only, optional font via next/font (Press Start 2P)

9.2 Mandatory behavior

• Intro overlay must show on every visit, every refresh, no persistence.
• Home page must render:
  • Hero title: Bob.The.Buildas in a pixel font,
  • Exactly 3 project cards, all “Coming soon” placeholders,
  • Header and footer links to:
    • GitHub: https://github.com/matthudsoncode
    • Instagram: https://www.instagram.com/mattthewhudson/
• /projects route must exist and load as a placeholder page.

9.3 Audio rules

• Attempt autoplay on intro start.
• If blocked, remain silent without errors.
• Mute toggle:
  • toggling On retries audio (requires user interaction),
  • no persistence across refresh (no localStorage, no cookies).

9.4 Dependency policy

• Default, no new dependencies.
• Allowed additions only if clearly justified:
  • tiny utility library for classNames, optional,
  • no animation frameworks unless strictly necessary (prefer CSS).

10) Implementation Notes (Guidance for agents)

10.1 Modules to keep separate

• components/IntroOverlay.tsx: overlay UI and state machine (hammering → break → debris → fade → unmount).
• components/SoundToggle.tsx: presentational toggle, receives state and callbacks.
• lib/sound/SoundController.ts (or similar): thin wrapper around HTMLAudioElement, handles auto-try and retry-on-toggle logic.
• data/projects.ts: exports ProjectCard[] with 3 placeholders.
• styles/globals.css: pixel utilities, scanlines (optional), keyframes.

10.2 Acceptance criteria checklist

• Visiting / always shows the intro overlay, then reveals landing without jank.
• Title Bob.The.Buildas is prominent in a pixel font.
• Exactly 3 project cards render, all placeholders.
• GitHub and Instagram links work in header and footer.
• Sound auto-try does not crash if blocked, mute toggle works, no persistence across refresh.
• /projects route exists and loads.

10.3 Verification workflow (run before commit)

• pnpm lint
• pnpm build
• pnpm start, then manually verify / and /projects in the browser.

11) Rule-set Style Options (for this repo)

Option A, Lightweight (recommended)

• Keep only critical guardrails, keep velocity high.
• Strict on: intro must be mandatory, no persistence, minimal deps, crisp pixels, build passes.

Option B, Strict

• Adds stronger enforcement: Prettier, lint-staged, CI checks, structured PR checklist enforcement.
• Better for teams, slightly more setup and overhead.

Recommendation: Option A. This is a small, static portfolio page, the main risks are animation jank, pixel blurring, and accidental scope creep. Lightweight rules keep momentum while still preventing the common failure modes.