Skip to content

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Zer0-Mistakes is a Docker-first Jekyll theme published as the Ruby gem jekyll-theme-zer0, with Bootstrap 5.3.3, GitHub Pages remote-theme support, and automated semantic releases to RubyGems. Primary languages: Liquid/HTML (theme), SCSS, Bash (tooling), Ruby (gem + plugins).

Version source of truth: lib/jekyll-theme-zer0/version.rb. Don't bump it by hand. release-please is the canonical flow: it watches Conventional Commits on main, opens a "chore(main): release X.Y.Z" PR, and merging that PR tags the release and publishes the gem (.github/workflows/release.yml → reusable workflows in bamr87/.github). ./scripts/bin/release remains a manual fallback. Any version.rb bump MUST re-lock Gemfile.lock and package-lock.json in the same change — a stale lock breaks the frozen bundle install in the publish job (CI guards version.rb ↔ Gemfile.lock).

Layered Agent Guidance

This repo uses a layered guidance model — load only the layers matching the files you touch:

  • AGENTS.md — cross-tool entry point and operating rules.
  • .github/copilot-instructions.md — canonical detailed conventions (architecture, commit/release workflow).
  • .github/instructions/*.instructions.md — file-scoped rules; each file has an applyTo: glob in its front matter (layouts, includes, scripts, install, obsidian, sass, testing, documentation, version-control, backlog, content-review, ai-chat). Read the matching file before editing those paths.
  • .github/prompts/*.prompt.md — reusable multi-step workflows (commit-publish, repo-audit (repo audit + issue intake), backlog-implement, issue-implement (route one issue → loop-until-green → PR; human-dispatched), issue-plan (the planning committee), obsidian-add-syntax, frontmatter-maintainer, content-review, seed). Mirrored as Cursor commands in .cursor/commands/.
  • .github/skills/*/SKILL.md — operational checklists: change-workflow (branch → commit → PR for any change; read it before starting one), validate-build (pre-commit/PR validation), content-review, visual-evidence (regression test + before/after evidence for any UI/behavioural change; required for fixes to auto-merge — enforced by the evidence-gate check and visual-evidence.instructions.md), committee-plan (the /issue-plan fan-out + order-only synthesis).
  • Autonomous issue pipeline — extends the continuous-evolution loop to ingest GitHub issues. /repo-audit triages all open issues into _data/backlog.yml (source: issue, adopted via links.issue by scripts/sync-backlog.rb, no duplicates); /issue-plan plans them (order-only _data/roadmap_plan.yml + scripts/sync-plan.rb); /issue-implement routes via _data/routing.yml to a specialized .claude/agents/* lane. Issue text is untrusted (injection fence); agents never touch CODEOWNERS paths. See docs/systems/continuous-evolution.md.
  • AI content reviewer — reviews content PRs (Markdown under pages/**) for SEO, consistency, polish, accessibility, and accuracy. Two tiers: scripts/content-review.rb (deterministic, per-collection thresholds from .github/config/content_review.yml) and the .claude/agents/content-reviewer.md Claude Code agent, run on PRs by .github/workflows/ai-content-review.yml. Skill: .github/skills/content-review/.
  • AI chat assistant — opt-in Claude-powered chat widget grounded in the current page, with GitHub issue/PR tools and a dev-only local page-edit mode. Widget: _includes/components/ai-chat.html + assets/js/ai-chat.js; proxy: templates/deploy/chat-proxy/ (Cloudflare Worker + Node dev proxy), deployed by .github/workflows/deploy-chat-proxy.yml. Governed by ai-chat.instructions.md.
  • Site Builder — the Claude-guided setup wizard at /setup/ (and on the welcome layout): nine steps from prerequisites to a written, running site. Form + generators: _includes/setup/wizard.html + assets/js/setup-wizard.js (pure client-side, GitHub Pages-safe); Claude session: _includes/setup/claude-session.html + assets/js/site-builder.js, proxy-only via the dev proxy's /api/wizard/* routes, which exist only in templates/deploy/chat-proxy/dev-proxy.mjs and are bounded by wizard-store.mjs (fixed check table, read-only theme source, scaffold into a new folder under WIZARD_TARGET_ROOT, fixed docker compose actions). Catalogs and the framework brief live in _data/site_builder.yml; config under site_builder:. Governed by ai-chat.instructions.md §9; docs at pages/_docs/features/site-builder.md.
  • Page-feedback widget — the "Improve this page" capture flow: a runtime modal + global FAB turn a reader's report (request type + description + live page context + a captured console/error log buffer) into a well-formed, correctly-labeled GitHub issue. Base layer is a token-free issues/new prefill (GitHub Pages-safe); an optional AI layer sends the capture to Claude via the chat proxy's /api/feedback route (Claude Code OAuth) to clarify, vet, prioritize, and recommend before filing. Widget: _includes/components/page-feedback.html + assets/js/page-feedback.js + _includes/core/console-capture.html; request types in _data/feedback_types.yml; config under page_feedback: in _config.yml. Replaces the old build-time Copilot dropdown (which could not capture logs).
  • Multilingual translation pipeline — English (pages/**, _data/ui-text.yml en) is the only human-maintained language; alternates (fr/**, _data/i18n/**) are GENERATED by scripts/translate.rb (Claude Code OAuth) via .github/workflows/translate.yml (dispatch mode=full bulk job + incremental on content pushes; output lands as a chore/i18n-translations PR). Never hand-edit generated translations. Frontend: _includes/components/language-toggle.html, _includes/core/{i18n,hreflang}.html. Governed by translation.instructions.md; see docs/systems/multilingual-translation.md.
  • Giscus comment conversations — comments are GitHub Discussions (config: _config.yml giscus: block; include: _includes/content/giscus.html). scripts/bin/giscus-discussions (gh GraphQL) can list/read/draft/seed/post, driven by the giscus-conversation skill (.github/skills/giscus-conversation/). Read-only digest workflow: .github/workflows/giscus-digest.yml.
  • Theme propagation — how a release reaches the ~5 downstream sites built on this theme. _data/consumers.yml is the registry (consumer, consumption mode, every file holding a pin); scripts/propagate.rb reports pin drift or dispatches theme-release; .github/workflows/propagate-theme.yml fires it on release + weekly. Consumers copy their half from templates/consumer/ (bump-theme-pins.sh, theme-bump.yml, .theme-overrides.yml). This repo never pushes to a consumer — it dispatches, and each consumer opens a PR gated by its own CI. _data/theme-manifest.yml is the contract underneath it all: a release snapshot (regenerated by manifest-sync.yml in the release PR, gated in CI on version.rb ↔ manifest version), not a working-tree mirror — don't regenerate it in feature PRs. See docs/systems/theme-propagation.md.
  • _data/backlog.yml — tactical task backlog (source of truth; synced to GitHub Issues by .github/workflows/sync.yml). See docs/systems/continuous-evolution.md.

When a file-scoped instruction conflicts with a generic best practice, the file-scoped instruction wins.

Essential Commands

# Development (recommended; serves http://localhost:4000)
docker-compose up                          # Jekyll dev server with live reload
docker-compose exec jekyll bash            # Shell into the container
docker-compose down -v                     # Clean up
bundle exec jekyll serve                   # Local (non-Docker) alternative

# Validate a Jekyll build (required before declaring theme changes done)
docker-compose exec -T jekyll bundle exec jekyll build \
  --config '_config.yml,_config_dev.yml'

# Tests
./scripts/bin/test                         # All suites: lib + theme + integration
./scripts/bin/test lib                     # One tier: lib | theme | integration | install
./test/test_runner.sh                      # Theme test orchestrator (core suites)
./test/test_runner.sh --suites core        # Single suite: core, deployment, quality,
                                           #   installer, site_generation, i18n, obsidian,
                                           #   features, playwright, playwright_snapshots,
                                           #   audit  (the authoritative list is
                                           #   TEST_SUITE_KEYS in test/test_runner.sh;
                                           #   `installation` was retired — its scenarios
                                           #   live in test_install_legacy_flags.sh)
./test/test_runner.sh --suites full        # Everything incl. Playwright tiers
./test/test_core.sh                        # Run one test script directly
npm run test:smoke                         # Playwright smoke tier
npm run test:snapshots                     # Playwright pixel snapshots
npm run test:update-snapshots              # Refresh snapshot baselines

# Quality / preflight
./scripts/validate                         # Canonical preflight validation
./scripts/validate --quick                 # Host-only checks
markdownlint "**/*.md" --ignore node_modules
yamllint -c .github/config/.yamllint.yml .

# Build / release (semantic-version aware; full pipeline:
# changelog → version bump → test → build → tag → publish)
./scripts/bin/build                        # Build the gem only
./scripts/bin/release patch|minor|major    # Release (use --dry-run to preview)
./scripts/analyze-commits.sh HEAD~5..HEAD  # Preview version-bump analysis

# Assets
./scripts/vendor-install.sh                # Refresh committed Bootstrap/icon vendor files

Make targets (make test, make release-patch, …) and Rake tasks (rake test:all, rake dev:serve, rake preview:generate) wrap the same scripts. Wrappers at scripts/{build,release,test} forward to the canonical scripts/bin/ implementations.

Architecture

Dual configuration system — the core pattern to understand first:

  • _config.yml — production; uses remote_theme: "bamr87/zer0-mistakes" for GitHub Pages, analytics enabled.
  • _config_dev.yml — development overrides; remote_theme: false, loads the local theme files, analytics disabled. Docker runs Jekyll with both configs.

Layout hierarchy: _layouts/root.html (base) → default.html (main) → content layouts (article.html, home.html, …).

Modular includes (_includes/): core/ (head, header, footer), components/ (cookie consent, theme info), analytics/ (PostHog — production-only, consent-driven), navigation/ (navbar, breadcrumbs). Includes take parameters with safe defaults ({{ include.class | default: 'default-class' }}) and carry a documentation header block.

Content collections live under pages/: _posts/ (layout article), _docs/, _about/, _notebooks/, _notes/, _quickstart/. Front matter drives behavior — title, description, layout, categories, tags, date/lastmod, permalink.

Custom Jekyll plugins (_plugins/): obsidian_links.rb (Obsidian [[wiki-links]]/embeds/callouts — paired with assets/js/obsidian-*.js and assets/data/wiki-index.json; see .github/instructions/obsidian.instructions.md), search_and_sitemap_generator.rb (/search.json, /sitemap/), theme_version.rb, preview-image and content-statistics generators.

Vendored assets: Bootstrap 5.3.3 + Bootstrap Icons + Mermaid are committed under assets/vendor/ (GitHub Pages–safe, no CDN). Custom styles layer on via _sass/ → assets/css/main.css.

Automation scripts: canonical entry points in scripts/bin/ (build, release, test, validate, install) share modules from scripts/lib/*.sh. Scripts use set -euo pipefail, logging helpers, and support --dry-run. The self-healing installer is install.sh + scripts/lib/install/** + templates/.

Key Conventions

  1. Branch first; one concern per PR. Create a branch off main before editing — never commit to main directly (it's protected). Each branch/PR holds one logical change; stage by path so generated/lock files don't leak in. See the change-workflow skill and version-control.instructions.md.
  2. Make minimal, surgical changes. Match existing style; don't refactor unrelated code.
  3. Validate before declaring done. Run the relevant test suite; for any layout/include/sass change, run the Docker Jekyll build above.
  4. Update CHANGELOG.md for user-visible changes (Keep a Changelog format, newest entry at the top).
  5. Version bumps happen via release automation — release-please's release PR (canonical) or ./scripts/bin/release (manual fallback), never in unrelated PRs. A version.rb bump MUST re-lock Gemfile.lock and package-lock.json in the same change — a stale lock breaks the frozen bundle install in the publish workflow. Keep the generated _data/content_statistics.yml out of feature PRs (its own chore commit or CI).
  6. Conventional commits: types feat|fix|docs|style|refactor|perf|test|chore; scopes include search, navigation, layouts, includes, sass, config, ci, scripts, analytics. Commit analysis drives the automatic version-bump type.
  7. Prefer existing patterns: Bootstrap 5 components, Bootstrap Icons, and the modular _includes/ system cover most UI needs.
  8. Backlog: edit _data/backlog.yml, not the mirrored GitHub Issues.
  9. When asked to "commit", "release", or "publish", follow the structured workflow in .github/copilot-instructions.md (§ Commit and Release Workflow) or the /commit-publish prompt.

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. The AI step is not vendored at all: workflows call bamr87/bamr87/.github/actions/claude-run@main by reference (hub kit ai-runner), and this repo keeps only the consumer companions it probes for (_data/ai.yml, scripts/ai/usage.rb + usage_report.rb + api_call.rb, tools/unwrap-prose.py).

Standard deviations

  • UPS-REPO-02 — tests live under test/ (grandfathered, Ruby-gem convention).