CLAUDE.md

Guidance for AI coding agents (Claude Code, Copilot, Cursor) working in lifehacker.dev.

lifehacker.dev is a satirical-but-actually-working Jekyll site (“Surviving life, one byte at a time”) on the bamr87/zer0-mistakes remote theme — ~200 posts across four news sections (Hacks / Tools / Field Notes / The Wire under pages/_posts/<section>/) plus pages/_docs/, published by an autonomous Claude Code fleet and merged by a human. The repo is the CMS: brand, backlog, ledgers, and health all live in-tree as data files. The Wire is the news desk: model-beat journalism under the press charter in identity.yml (press_charter) — satire in the framing, never the facts; every dispatch pins front-matter sources:. Its sister sites are it-journey.dev (the game — same theme, opposite temperament) and bash-365.com (BASH Consulting). “Done” here means: the test harness is green, the content is on-voice per _data/brand/, and a human merges the PR — agents never merge.

Read-by-task

Stack & commands

bundle install              # deps (github-pages + remote theme; lockfile is committed on purpose)
scripts/preview.sh          # local preview: overlay onto a theme clone + docker compose up → http://localhost:4000
scripts/ci/run-all.sh       # full test harness (Pages safe-mode build + frontmatter/brand/drift/link lints → test-results/findings.jsonl)
scripts/ci/build.sh         # just the Pages-parity build (safe mode, _plugins stripped)
python3 tools/unwrap-prose.py --write   # FIX one-paragraph-per-line (the harness checks it; this repairs it)
node scripts/preview/generate.mjs -f <article.md>   # cover art (Trace Bloom; offline, zero-dep)
ruby scripts/content/weekly_digest.rb --days 7      # the prior week's publications, as JSON (feeds the weekly epic + its figures)
node scripts/media/figures.mjs <type> …             # weekly-epic in-body figures (constellation/timeline/gauge; offline, deterministic)

The harness scripts are the same ones CI runs (pipeline.yml, required check = verify); run them before opening a PR — run-all.sh covers every gate CI enforces, including the one-paragraph-per-line rule, so a green harness means a green verify. A new check is only real once it is BOTH run by run-all.sh and listed in aggregate.rb’s CHECK_FILES; miss the second and it silently gates nothing (scripts/devops/audit.rb fails the build if you do). Frontmatter required keys: title description date author excerpt tags (preview: is warn-only; wire dispatches also require a non-empty sources: URL list). Posts pin explicit permalinks (/hacks/:slug/, /tools/:slug/, /wire/:slug/) — the old collections were folded into posts in issue #337, so never “fix” a permalink to match the collection default.

The theme pin is deliberately floating

_config.yml sets remote_theme: "bamr87/zer0-mistakes" with no tag or ref — this site tracks the theme’s default branch on purpose, so theme fixes land here without a bump PR. scripts/ci/build.sh matches production: it clones the theme with git clone --depth 1 of the default branch, no ref. Write that down as a posture, not a bug — but know what it costs:

• The nightly is the only guaranteed-fresh build. .github/workflows/nightly.yml runs build-overlay with fresh-theme: 'true', which bypasses the cache and re-clones the theme specifically so upstream drift surfaces; on failure it files one coarse issue. Nothing else in CI re-clones.
• PR-time builds use a CACHED theme clone. .github/actions/build-overlay defaults to fresh-theme: 'false' and restores /tmp/zer0-theme from actions/cache. The key is date-stamped (zer0-theme-<YYYY-MM-DD>) but restore-keys: zer0-theme- prefix-matches an older entry, and lh_ensure_theme() skips the clone whenever _layouts/ is already there — so a PR can be reviewed, pass verify, and merge against a theme snapshot that predates an upstream break. A green PR is not evidence the current theme still builds this site. When a change is theme-sensitive, re-run nightly by hand (workflow_dispatch) before merging.
• The precedent is documented, not hypothetical. scripts/ci/build.sh (in lh_overlay(), at the rm -rf "$dest/_data" step) records it: zer0-mistakes 1.28.0 began shipping _data/navigation/docs.yml for its own docs site, and the overlay’s old merge-keep behavior gave every /docs/ page a 47-link sidebar of theme-repo paths — 1,987 phantom broken-link errors the live site would never have served. The fix was to make our _data/ replace the theme’s wholesale, exactly like production. That is the class of break a floating pin buys, and the class the nightly exists to catch.
• Theme problems are still fixed upstream (see the rule below) and picked up on the next clone — never patched around locally, and never by pinning our way out of a bug.

Conventions

• Conventional Commits: type(scope): description. The types actually in this history are feat, content, fix, chore, docs, build, ci, style — plus the standard refactor/test/perf, which are allowed but so far unused. content(<section>): … is the content lanes’ type and by volume the second most common (content(doc|post|hack|field-note)); build(deps): … is Dependabot’s.
• The bot lanes commit under a lane prefix instead of a CC type, hard-coded in their workflow: scout: (content-scout.yml), triage: (triage.yml), wire: (wire-scout.yml), explore: (explore.yml), ai-usage: (ai-usage.yml). scout: and triage: alone are ~15% of all commits. Nothing lints commit messages — there is no commitlint — so this list describes practice rather than gating it; keep it true when you add a lane.
• Default branch is main — branch from it and open a PR; never push to it directly.
• README-First, README-Last: read the nearest README.md before changing a directory, and update it after.
• Don’t suppress type errors (as any, @ts-ignore, # type: ignore) or leave empty exception handlers.
• Brand voice is enforced in tiers: deterministic scripts/ci/lint_brand.rb (only avoid_phrases hard-fail), then the brand-reviewer agent judges satire-vs-sincere; adjudicated uses go in _data/brand/accepted.yml — don’t rewrite prose just to silence a satire_suspected warning.
• Theme bugs go upstream to bamr87/zer0-mistakes, never patched around locally.

Fleet context

This repo is one of ~40 managed by the bamr87/bamr87 dash (registry: _data/projects.yml; tiered baseline: docs/STANDARDS.md). It is vendored there as a git submodule: commit and push changes here first — the hub only bumps its pointer afterwards. Shared CI, release, schema, and agent kits are seeded from the hub’s templates/; prefer adopting those over hand-rolling equivalents.