Skip to content

agents.md

Latest commit

 

History

History
106 lines (79 loc) · 3.63 KB

agents.md

File metadata and controls

106 lines (79 loc) · 3.63 KB
Raw

Agents — APH Slides

AI agent entry point. Human readers: start with README.md and docs/.

Project in One Paragraph

Static slide generator for APHGames (NI-APH) courses. Pug templates + Reveal.js runtime, built with Parcel v1 and Node preprocessors for code snippets (Prism) and equations (MathJax). Output is static HTML in build/. No backend, no database, no test suite.

Read Order

  1. This file (quick context)
  2. docs/ai-onboarding.md (agent workflow)
  3. docs/architecture.md (system design)
  4. docs/project-structure.md (where files live)
  5. docs/development-workflow.md (commands)

Commands

npm install
npm run generate-index   # after deck add/rename — NOT in dev script
npm run dev              # http://localhost:1112/index.html
npm run build            # production output → build/

Key Boundaries

Layer Path Rule
Decks slides/view/*.pug Indexable entry points only
Chapters slides/view/chapters/ Included fragments — not indexed
Mixins slides/view/mixins/ Reuse before inventing layout
Assets slides/assets/<topic>/ Co-locate media with topic
Generated *_generated/ Never edit — regenerate via copydata
Build scripts/ Node CommonJS (except reveal-setup.js)
Output build/ Gitignored — do not commit

Safe Changes

  • Edit chapter Pug content and assets
  • Add snippets to snippets/, equations to equations/
  • Add decks with metadata + matching icon SVG
  • Extend mixins and themes following existing patterns

Dangerous — Ask First

  • remove-unused-pics.js (deletes unreferenced images)
  • Upgrading Parcel / changing bundler
  • Bulk asset deletion or reorganization
  • Editing generated *_generated/ folders

Deck Metadata Template

// GROUP=Lectures
// COURSE=APH
// NAME=Games
// LOCALE=en
// ORDER=1.1

Icon required: slides/icons/<deck_basename>.svg

Extension Points

Goal Location
New deck slides/view/<name>.pug + icon
New chapter slides/view/chapters/<topic>.pug
New layout slides/view/mixins/
New theme slides/themes/
Snippet language scripts/process-snippets.js
Reveal plugin slides/plugins/ + reveal-setup.js

Doc Sync (Required)

Update docs when changing:

  • docs/architecture.md — structure, data flow, scripts
  • docs/project-structure.md — folders, naming
  • docs/development-workflow.md — commands, workflows
  • docs/prd.md — scope/capabilities
  • This file — if agent entry points or boundaries change

Known Problems (Do Not Hide)

Problem Location
No automated tests Entire repo
README port wrong (1234 vs 1112) README.md (fixed)
License mismatch MIT vs BSD package.json vs LICENSE
Missing backgrounds tree.png, marioworld.jpg, minecraft_blocks.png
Async race in equations scripts/process-equations.js
Fragile snippet processor scripts/process-snippets.js (TODO in source)
Parcel v1 unmaintained package.json
generate-index not in dev package.json scripts
Unknown CATEGORY attribute lecture_org_cs.pug logs warning — likely typo for GROUP

Verification

Always run npm run build before marking work complete. If decks changed, run npm run generate-index first.

Assumptions

  • GitHub Release zip is the CI deliverable; aphgames.io deployment is external
  • Slide assets (images) are license-restricted separately from code (see README)