portfolio-next/AGENTS.md

portfolio-next

The next lucaswinther.info: a two-gate personal site (work / off the clock). Pre-code: only docs and HTML mockups exist. Planned stack: Bun 1.3, TypeScript, React, Astro (static), Docker (see docs/DECISIONS.md). Sister repo with the same stack and conventions: commission-compass (Gitea, lucasw89/); copy its patterns before inventing new ones.

AGENTS.md is the single source of truth for agents here. CLAUDE.md and GEMINI.md only point here. Deeper context on demand: docs/ARCHITECTURE.md, docs/DECISIONS.md, docs/TODO.md.

Commands

Verified in the scaffold task:

• bun install --frozen-lockfile — install from the lockfile
• bun run typecheck — tsc --noEmit
• bun test — whole suite (bunfig.toml roots it at test/)
• bun test test/x.test.ts — one file
• bun test -t 'name' — tests matching a name Bun is the runtime and package manager, never Node, npm, pnpm or yarn: bun <file> not node, bun test not jest/vitest, bun install / bun run <script>, bunx not npx. Bun loads .env itself; don't add dotenv. Prefer Bun built-ins (Bun.serve, Bun.file, Bun.$`…`, Bun.YAML). Exception: the site is Astro (built on Vite). bun init's "HTML imports, don't use vite" advice does not apply to it.

Workflow

Required skills: superpowers, impeccable. Check at session start; install if missing. Specs → docs/specs/NNN-slug.md (permanent). Plans → docs/plans/NNN-slug.md while in progress; git rm them before opening a merge request — the spec is the record. (Overrides the superpowers default paths, e.g. docs/superpowers/specs/.)

Anything beyond a trivial fix: brainstorm → spec (sign-off) → plan → TDD → review. TDD means failing test first, watch it fail, minimal code, watch it pass, commit. Tick plan checkboxes as you go so an interrupted session is resumable. Trivial changes (typo, version bump, one-line config): say "trivial, skipping spec" and proceed.

Use impeccable for user-facing UI — craft for new, audit/polish on existing, harden before shipping. Design context: PRODUCT.md, DESIGN.md.

Rules

• The chosen mockups are the visual source of truth: mockups/nav-d.html (start page), mockups/tech-r3-c.html (work), mockups/personal-r2-b.html (off the clock). Match them; don't drift towards a generic template. Every other file in mockups/ is a rejected or reference round.
• docs/inspiration.md records the owner's taste in his own words. Read its principles before any visual change. Hard lines: no loading screens, nothing moves unless the visitor acts, no canvas/game feel, nothing that sells, no purple/blue "AI" gradients.
• Every project carries an AI level: ai-made | some-ai | by-hand | unknown. Never guess one; unknown stays unknown and is shown as such.
• Never invent facts about the owner (jobs, dates, life events, opinions). Use a visibly marked placeholder and list it for him to fill in. Real work history: extra_info.txt.

Architecture

mockups/ -> throwaway HTML prototypes (one self-contained file each) + shots/ screenshots docs/inspiration.md -> taste log, mockup verdicts, decisions so far extra_info.txt -> owner's real work history

Full picture: docs/ARCHITECTURE.md — read it before your first change in a session.

Boundaries

Never touch: .superpowers/ (local brainstorm sessions, gitignored), extra_info.txt (owner-maintained). Never commit .env, secrets, or credentials. Never force-push, rewrite pushed history, or commit directly to main.

Ask first: new runtime dependencies · deployment, containers or the owner's homelab config · anything destructive (rm -rf, git reset --hard) · work the approved plan does not cover.

If the task turns out much larger than the plan assumed: stop, report, re-plan.

Docs duties

Same commit as the code, not "later":

• docs/ARCHITECTURE.md — when a module, boundary, or data flow changes.
• docs/DECISIONS.md — append-only; any choice a future maintainer would reverse-engineer.
• docs/TODO.md — anything noticed and deliberately not fixed. No TODO comments in source.
• docs/PERMISSIONS.md — together with .claude/settings.json, .codex/, .gemini/settings.json, in one commit.

Git

Branches: feat|fix|chore/<slug>. Commits: Conventional Commits. Small, each leaving tests green. Merge to main locally, and only when the owner asks and approves. No pull requests.

Done means verified

Do not report success on work you have not run. Before saying done: tests run in this session and seen passing · lint and typecheck clean · matches the approved spec · UI changes rendered and looked at (headless Chrome works: google-chrome --headless=new --no-sandbox --screenshot=out.png --window-size=1440,900 file://$PWD/page.html) · docs duties complete · git status clean and the diff is only what you intended.