Engineering Baseline

Single source of truth for how I build software. This repository closes the gap between an LLM's training data and the current state of the art. AI agents working on any of my projects MUST consult this baseline before making stack, version, or pattern decisions — do not rely on training data for anything covered here.

The bar: production grade, simplicity first, performant and secure out of the box. Boring technology, one static Go binary, hypermedia over JavaScript, security as layered defaults rather than a checklist. Every rule exists to make the default path the correct one — an agent that follows the documents verbatim ships a correct, hardened application without inventing anything.

• Last verified: 2026-08-12
• Format: Markdown only, plus the MIT LICENSE. No code, no CI, no build steps. Documents are the product. The one piece of tooling is the root Makefile, which installs the baseline into Claude Code (see below) — it builds nothing.

How to use this repository (AI agents)

Follow this protocol top-down. Never skip to a leaf document without reading its parent.

1. Identify the project type you are building (e.g. "web application").
2. Open the matching document in project-types/. It defines the mandated stack and links to everything that applies.
3. Read the linked stack/ documents for language/tool conventions and the linked patterns/ documents for concrete implementation patterns.
4. Check VERSIONS.md and adopt exactly those versions, the way its version policy prescribes (e.g. go 1.26 in go.mod, never a pinned toolchain patch). If a version in your training data is newer than what is listed here, the baseline wins — flag the discrepancy to the user instead of silently upgrading.
5. Before declaring work done, walk the matching document in checklists/.

Rules in these documents use RFC-2119 style keywords: MUST, MUST NOT, SHOULD, MAY.

Install into Claude Code

make install    # symlinks this repo to ~/.claude/skills/engineering-baseline
make uninstall  # removes the symlink

Claude Code then loads the baseline as a skill (SKILL.md) whenever a stack, version, or pattern decision comes up. The symlink keeps the repository the single copy — git pull is the update mechanism. This Makefile is repo tooling, not the project Makefile that stack/makefile.md prescribes. That document's rules (including the install-target ban) govern projects built from the baseline, not the baseline itself.

Repository structure

baseline/
├── checklists/                     ← definition of done per project type
│   ├── cli-tool.md
│   ├── library.md
│   └── web-application.md
├── LICENSE                         ← MIT
├── Makefile                        ← make install / make uninstall (Claude Code)
├── operations/                     ← how projects run in production
│   ├── ci.md
│   ├── cli-release.md
│   └── web-application.md
├── patterns/                       ← concrete, copyable implementation patterns
│   ├── css-layout.md
│   ├── css-motion.md
│   ├── css-tokens.md
│   ├── go-auth-sessions.md
│   ├── go-cli.md
│   ├── go-errors-logging.md
│   ├── go-forms-validation.md
│   ├── go-http-server.md
│   ├── go-library.md
│   ├── go-performance.md
│   ├── go-project-layout.md
│   ├── go-sqlite.md
│   ├── go-testing.md
│   └── htmx-server-rendering.md
├── project-types/                  ← entry point per kind of project
│   ├── cli-tool.md
│   ├── library.md
│   └── web-application.md
├── README.md                       ← you are here: navigation protocol
├── SKILL.md                        ← makes the repo a Claude Code skill
├── stack/                          ← per-technology conventions
│   ├── css.md
│   ├── go.md
│   ├── html.md
│   ├── htmx.md
│   └── makefile.md
├── STYLE.md                        ← how everything for humans is written
└── VERSIONS.md                     ← pinned versions, dated, with sources

Core engineering values

These apply to every project regardless of type:

1. Boring technology. Standard library first. Every dependency must justify itself.
2. No JavaScript. Interactivity comes from htmx and modern CSS. If a feature seems to require custom JS, redesign the feature (see stack/html.md).
3. Server is the source of truth. State lives on the server; the client renders hypermedia.
4. Simplicity over cleverness. Code is read far more often than written.
5. Current, not bleeding edge. Latest stable versions, never betas/RCs in production.
6. Write for humans. Every doc, comment, and prompt passes the 10-year-old test in STYLE.md: point first, short sentences, plain words.

Quality bar & verification

• Adversarial review covers every tagged release: independent reviewers hunt cross-document contradictions, trace every canonical snippet's mechanics end to end, and verify factual claims against upstream sources (Go, htmx, scs, SQLite, systemd, Caddy) — repeated until two consecutive passes find zero defects. Last run: 2026-08-12 over the v1.8.0 additions (11 rounds, 26 defects fixed, converged at two consecutive zero-defect rounds); last full-corpus sweep: 2026-08-11.
• The reference implementation is the executable check. baseline-reference implements these rules end to end and MUST be synced to every tagged release — when a rule is ambiguous, the reference resolves it.

Maintenance protocol (humans)

• Every document carries a Last verified: date. Re-verify at least every 3 months, and always after a major release of Go (Feb/Aug) or htmx.
• When updating a version: update VERSIONS.md first, then any stack document that references behavior of that version, then bump the Last verified: dates.
• New recurring decision in a project? Extract it into a pattern document here — the whole point is to never solve the same problem twice.