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`
`skills/`	Four portable skill directories: each `SKILL.md` and its `references/` render to `public/skills/<name>/index.html` (the raw files are also copied there verbatim)
`ideas.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`
`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, source-grouped shelves, each guide's use-when line, and the headings and descriptions the index pages open with
`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, the 19 ideas) 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.
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. build/handbook-workflow.example.yml provides an optional GitHub Actions check for stale committed output; it is not installed because the publishing token lacks GitHub workflow permission. Review changes to meaning and source claims in the editable Markdown.