0 Fork 0

Files

T

Lucas WintherandClaude Opus 5.5 843b6d32bc chore: bootstrap agent-ready docs, rules and design-phase artefacts

Add AGENTS.md as the single source of truth (with CLAUDE.md and GEMINI.md
as pointers), permissions for Claude Code, Codex and Gemini, the docs tree
(architecture, decisions, TODO, permissions, specs, plans), PRODUCT.md and
DESIGN.md, plus the design-phase record: the inspiration log, all mockup
rounds with briefs and screenshots, and the owner's work history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-09 06:47:38 +01:00

4.2 KiB

Raw Blame History

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 (see docs/DECISIONS.md).

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

TODO(maintainer): confirm commands once tooling exists (no package.json yet). 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.

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 once code exists.

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: TODO(maintainer): confirm feat|fix|chore/<slug>. Commits: TODO(maintainer): confirm Conventional Commits.

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.

4.2 KiB Raw Blame History