Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (68 loc) · 7.4 KB

AGENTS.md

File metadata and controls

90 lines (68 loc) · 7.4 KB
Raw

Agent Guidelines for al-folio (v1.x)

This file is the authoritative entry point for coding agents working in this repo. Read it before making any change. It is intentionally short and tool-neutral; it links to the one place each longer-form fact lives.

al-folio v1.x is a thin Jekyll starter, not a theme. This repo owns starter wiring, example content, docs, and cross-plugin tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems published under al-org-dev.

Route your change

Find your change on the left; edit only what is on the right.

Your change Goes in
Dependency pin, plugin activation, feature flag this repo: Gemfile and _config.yml (both — see below)
Example/demo content, bibliography, data files this repo: _pages, _posts, _projects, _news, _teachings, _books, _data
Documentation this repo: docs/ (long-form) or this file (agent rules)
Cross-plugin integration test, visual parity test this repo: test/integration_*.sh, test/visual/
Plugin catalog metadata this repo: _data/featured_plugins.yml
A layout, include, or Sass partial the owning gem — start with al_folio_core
A Liquid tag or filter, or what a tag renders the gem that registers it — see the delegation table
Feature behavior (search, math, charts, comments, cookies, icons, CV, distill, analytics, images, newsletter, citations) that feature's gem — see docs/BOUNDARIES.md
Component/unit test for gem-owned behavior the owning gem, not here
A feature with no existing owner open a plugin proposal issue first, then a standalone plugin repo

docs/BOUNDARIES.md is the authoritative area-to-gem table. docs/ARCHITECTURE.md explains how the pieces connect.

Stop sign

If your change would create any of these paths in this repo, it belongs in a gem instead:

_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/

npm run lint:style-contract fails CI when any of them exists here, and it also rejects build:css / build:tailwind npm scripts. Do not add a starter-local Tailwind or CSS build pipeline.

This restriction applies to this repo only. A user's own site created from this template may legally shadow gem-owned files — see local overrides: your site vs. this repo.

Three failures that produce no error message

Read docs/ARCHITECTURE.md for the full explanation. The short version:

  1. Features fail silently. A feature renders only when its gem is loaded and its flag is on and the page opts in. Otherwise the Liquid tag emits an empty string — no warning, no error.
  2. Gemfile and _config.yml are two lists that must agree. A plugin in only one of them is inert. Adding or removing a plugin means editing both. Repo dirs use hyphens (al-folio-core); gem/plugin ids use underscores (al_folio_core).
  3. This repo's effective baseurl is /al-folio. _config.yml already sets it, so a plain bundle exec jekyll build is correct — that is what deploy.yml, broken-links-site.yml and axe.yml run. Passing --baseurl /al-folio is redundant but harmless; blanking the baseurl out is what renders the site unstyled with broken links. Dev server is at http://localhost:4000/al-folio/.

Validated local command set

Run from the repo root, in this order:

bundle install
npm ci
npm run lint:prettier
npm run lint:style-contract
bundle exec jekyll build --baseurl /al-folio
bash test/integration_comments.sh
bash test/integration_plugin_toggles.sh
bash test/integration_distill.sh
bash test/integration_bootstrap_compat.sh
bash test/integration_upgrade_cli.sh
bash test/integration_css_minify.sh
npx playwright install chromium webkit
npm run test:visual
bundle exec al-folio upgrade audit
bundle exec al-folio upgrade overrides audit
bundle exec al-folio upgrade report
docker compose up -d
curl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null
docker compose logs --tail=80
docker compose down

All six test/integration_*.sh scripts are gated by unit-tests.yml; run the ones your change touches. Docker note: v1 uses /srv/jekyll/bin/entry_point.sh and serves from container-local /tmp/_site to avoid host bind-mount write deadlocks.

Before you open a PR

  • Keep starter work here; route runtime behavior to the owning plugin repo.
  • Run npm run lint:prettier (Prettier with @shopify/prettier-plugin-liquid, printWidth: 150). npx prettier . --write fixes formatting.
  • Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.
  • If you create or keep local overrides of plugin-owned files, run bundle exec al-folio upgrade overrides audit and commit .al-folio-overrides.yml after review.

Further reading

  • docs/ARCHITECTURE.md — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.
  • docs/BOUNDARIES.md — authoritative area-to-gem ownership table and PR triage playbook.
  • docs/CONTRIBUTING.md — contributor workflow and agent tooling.
  • docs/README.md — index of all user and maintainer guides.
  • .agents/skills/al-folio-bootstrap/SKILL.md — new-site setup workflow.
  • .agents/skills/al-folio-v1-migration/SKILL.md — customized-fork migration and override drift auditing.
  • .codex/skills and .claude/skills are symlinks to .agents/skills for agent-specific discovery.