Contributing · Agent Engineering Handbook

This handbook is Markdown-first: everything you read on the site is generated from editable sources in this repository, and public/ is committed output. To change content, edit the source and regenerate — never edit files under public/ by hand, since the next render overwrites them.

# 1. Edit the source you want to change:
#    guides/*.md, *.md at the root, skills/*/SKILL.md, evidence/*.md|json

# 2. Regenerate public/:
python3 -m pip install -r build/requirements.txt   # Markdown==3.10.3
python3 build/render.py

# 3. Check links, file counts, hashes and rendered output:
python3 build/check.py

# 3b. (optional) Rendered check — headless Chromium, scrollbars/overflow:
#    needs Node and puppeteer (`cd build && npm install`), then:
bash build/check.sh
#    `python3 build/check.py` alone is enough locally; the rendered check
#    (`build/check-render.js`) is optional and skipped when puppeteer is absent.

# 4. Preview before opening a pull request:
cd public && python3 -m http.server 8000    # http://localhost:8000

What lives where

Path	Role
`README.md`, `adoption.md`, `prompts.md`, `validation.md`	Reader entry points
`guides/`	The 13 implementation guides
`*-inspection.md`	The three repository investigation reports, also listed on `investigations.html`
`lessons/`	The ten lesson Markdown sources; `build/lessons.json` owns their order, chapters, source tips and legacy aliases
`skills/`	Seven portable skill directories: each `SKILL.md` and its `references/` render to `public/skills/<name>/index.html` (the raw files are also copied there verbatim)
`lessons.html`, `guides.html`, `skills.html`, `investigations.html`, `evidence.html`	Generated section pages; the skills and investigations indexes are built from the README's skills and investigations lists plus `build/home.json`. `public/ideas/*` are lightweight legacy aliases of the lesson pages; `vercel.json` permanently redirects the old routes
`evidence/`	Frame manifest, extracted ideas, verifier comparison
`screenshots/`	The 12 frames (do not replace without updating `evidence/frame-manifest.json`)
`examples/recurring-rule/`	Runnable lint demonstration (`npm ci --ignore-scripts && npm run demo`)
`build/`	Renderer, checker, pinned requirements
`build/assets/handbook.css`	The one stylesheet every page loads (tokens at the top)
`build/assets/handbook.js`	The one script: closes the header menu on Escape or an outside tap, and marks the current section in the reader's rail. Every control works without it
`build/home.json`	Landing-page data not already in `README.md`: title, lead, chapter directory, each guide's use-when line, and the headings and descriptions the index pages open with
`build/lesson_catalog.py`	The catalog seam: validates `build/lessons.json` against the ten approved lessons and the nineteen source tips, and syncs the README lesson table between its markers
`build/lessons.json`	The lesson manifest: order, chapters, source tip coverage, legacy alias routes
`DESIGN.md`, `INTERACTIONS.md`	Source-only design and behaviour guidance for contributors; never render or copy these into the website
`public/`	Generated site — committed, never edited by hand

Conventions

Keep source-derived facts (what the video says, what a repository contains) separate from recommendation, and keep honest caveats: a screen shown in a video is not a live demonstration, and an author-reported benchmark is not a local measurement.
Screenshots are quoted excerpts from the source video; see ATTRIBUTION.md. Do not add third-party code or longer excerpts.
New pages should be added to RENDER_MD in build/render.py and linked from README.md. The landing page is built from the README's own tables and lists (problem table, guide list, investigations, skills) plus build/home.json; a new guide needs a shelf entry and a use-when line there, and build/check.py fails until the counts on the map match. Edit lesson prose in lessons/ and its metadata in build/lessons.json. The catalog validates the approved lesson set. Only the generated README lesson table should not be edited by hand: regenerate it with python3 build/render.py --sync-readme. An ordinary render refuses table drift.
Visual changes go through build/assets/handbook.css (and the page structure in build/render.py) and are recorded in DESIGN.md; behaviour changes in INTERACTIONS.md.

Vercel regenerates and checks the site from these sources on every deployment. Edit the source, regenerate locally and commit both. GitHub Actions runs the same check on every pull request, from .github/workflows/checks.yml. A committed page that no longer matches its source fails that check and blocks the merge. Review changes to meaning and source claims in the editable Markdown.