AGENTS.md — Coworking Agreement

Binding working agreement for every contributor to this repository, human or AI. Any AI coding agent operating here must follow it. Humans use it to review AI work.

The project

This repository contains the source code for the personal website of Dr. Lennart de Vries (https://lennartdevries.de), built with Quarto.

  • The site type is website, configured in _quarto.yml.
  • Rendered static HTML files are output into _site/.
  • Pages are registered in _quarto.yml under project: render: (*.qmd with the !ai-coding/ exclusion), so reference folders and stray Quarto files are never rendered into the public site; register every new page there.
  • The homepage is index.qmd, featuring an about: hero-heading with template solana and listings for education and professional experience.
  • Education entries live in education.yaml, listed via the education listing ID in index.qmd.
  • Experience entries live in experience.yaml, listed via the experience listing ID in index.qmd.
  • Font Awesome icons are provided via the Quarto extension in _extensions/quarto-ext/fontawesome.
  • Custom CSS styles are placed in styles.css.
  • The custom domain is managed via CNAME (lennartdevries.de), included in resources in _quarto.yml.
  • Profile photos and static site images are stored in images/ (downloaded during build via make images from external storage).
  • The published site repository is deployed at https://github.com/lennart-devries/lennart-devries.github.io.

Formatting

Write Markdown and commit messages for diff readability.

  • Put one sentence per line in prose, in commit bodies, and in list items.
  • Never wrap a sentence across multiple lines.
  • Keep lists flat; do not indent list items or their continuation lines unless strictly necessary for structured markup (like YAML data blocks).
  • Maintain clean, minimal YAML syntax in education.yaml, experience.yaml, and _quarto.yml.

Roles

The human assigns the role per task. AI may serve as structural assistant, co-author, editor, or maintainer.

  • Structural assistant: scaffolding, styling fixes, configuration, Docker/CI updates.
  • Co-author: drafts profile copy, descriptions, or project entries for review.
  • Editor: proofreads, tightens copy, checks links and dates, ensures consistent formatting.
  • Maintainer: dependencies, toolchains, build scripts, agent sandboxes.

Unless stated otherwise, assume co-author or structural assistant mode. Draft freely and expect everything to be reviewed before it counts.

Workflow

  • Read and adhere to this file at the start of every task.
  • Work from one issue at a time; if a request has no issue yet, create or clarify the task scope first.
  • Every change should land cleanly via git branches or pull requests.
  • Never force-push or rewrite pushed history on shared branches.
  • Keep changes minimal, scoped, and focused on the immediate task.
  • When creating or editing content, verify that external links, images, and paths exist.

Sandbox and Containers

  • Sandbox images for agent sessions follow the pattern <project>-sandbox-<tool>, e.g. lennartdevries-sandbox-cline.
  • Dockerfile.cline serves as a custom template for Docker Sandboxes based on docker/sandbox-templates:shell, preinstalling Quarto, Git, Make, and the Cline CLI.
  • Build the template with make docker-build-cline and publish it to the registry with make docker-push-cline.
  • Run a sandboxed session from the template using make docker-run-cline, which invokes sbx run --template $(CLINE_IMAGE) shell.
  • Quarto preview inside containers listens on port 5555: quarto preview --no-browser --host 0.0.0.0 --port 5555

Commits

Use the format <TYPE> [Scope]: <Description> with a subject of at most 72 characters in English.

  • TYPE: one of the standard uppercase types listed below.
  • [Scope]: area of the change, first letter capitalized, e.g. [Agents], [Home], [Bio], [Docker], [Style].
  • <Description>: imperative mood, starting with a capital letter, e.g. Add …, Update …, never added … or updates ….
  • Every commit should carry a body, separated from the subject by a blank line.
  • Write the body one sentence per line; never wrap a sentence across lines.
  • The body clearly and concisely describes the change and focuses on why it is needed.
Type Meaning
ADD Added file(s) or new section(s)
RM Removed file(s) or section(s)
BF Bugfix
NF New feature or content
DOC Documentation added or changed
RF Refactoring or cleanups
ENH Enhancement or minor improvement

Example:

ADD [Agents]: Set up agentic coding infrastructure and coworking agreement

Establish binding ground rules for human-AI collaboration in this website repo.
Add AGENTS.md and a Cline sandbox template to support containerized agent workflows.

Definition of done

A change counts as done only when all of the following hold:

  • quarto render succeeds without errors for HTML output (or syntax validation passes if external images require network credentials).
  • The CI workflow (.github/workflows/ci.yml) passes on the pull request.
  • All modified YAML files (education.yaml, experience.yaml, _quarto.yml) are valid YAML.
  • Listing metadata maps correctly to existing fields (title, subtitle, period, description).
  • Internal references, links, and assets are intact.
  • Codespell checks pass without spelling errors.
  • Any new files adhere to the one-sentence-per-line Markdown convention.

If a check fails, say so plainly. A failing render or broken layout is never done.

Guardrails

  • Do not alter personal facts, education, or employment history without explicit direction.
  • Do not overwrite or delete CNAME or alter the custom domain configuration.
  • Do not commit downloaded images directly to git; images are fetched at build time.
  • Always check that .gitignore prevents generated artifacts (_site/, .quarto/, images/) from being committed.