How the AI Engineering from Scratch Repository Is Versioned and Updated

The AI Engineering from Scratch curriculum uses Git for source control with a strict one-commit-per-lesson policy, while embedding explicit semantic version strings in generated artifacts to enable precise dependency management for downstream agents and pipelines.

The rohitg00/ai-engineering-from-scratch repository manages a comprehensive AI engineering curriculum through a dual-layer versioning strategy. While Git tracks the evolution of lesson source code in phases/<NN>-<phase>/<NN>-<lesson>/ directories, individual learning artifacts carry semantic versions that allow reproducible consumption without cloning the entire repository. This architecture ensures automated website updates and protects downstream tooling from breaking changes through schema versioning.

Git-Based Source Control with Strict Commit Policies

The repository enforces a one-commit-per-lesson policy defined in AGENTS.md. Each lesson resides in its own directory under phases/, and contributors must isolate changes to single lessons per commit to maintain a bisectable history.

When adding new content, the workflow follows this pattern:

git add phases/14-agent-engineering/42-agent-workbench-capstone/
git add README.md ROADMAP.md
git commit -m "feat(phase-14/42): add agent-workbench-capstone lesson"
git push origin my-branch
gh pr create -t "feat(phase-14/42): add agent-workbench-capstone"

This convention ensures git log --oneline directly maps to curriculum progression, making it trivial to trace when specific artifacts were introduced.

Semantic Versioning for Lesson Artifacts

Every lesson produces reusable artifacts stored in outputs/ directories with explicit semantic version headers. For example, phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md begins with:

---
name: end-to-end-safety-gate
description: Safety-gate that refuses unsafe completions
version: 1.0.0
---

# Safety Gate Skill

...

The scripts/install_skills.py script (line 124) parses this version: field during installation, allowing downstream users to pin specific artifact versions (e.g., version: 1.2.3) without pulling the entire repository. This mirrors production package management patterns like pip install.

Schema Versioning for Data Compatibility

Internal JSON structures carry a top-level schema_version key to prevent breaking changes. The scripts/build_catalog.py script (line 15) emits catalog entries with "schema_version": 1, enabling loaders like scripts/link_check.py and scripts/install_skills.py to validate compatibility before processing.

When schema changes occur, the version is bumped and migration logic handles legacy files gracefully rather than failing silently.

Workbench Pack Versioning

Advanced lessons utilize optional agent workbench scaffolding tracked via .workbench-version. The scripts/scaffold_workbench.py script (lines 85-87) writes and reads this version, injecting it into generated README files and installation scripts.

$ cat .workbench-version
2.3.0

This ensures users know exactly which workbench pack version they are executing, and the scaffold script copies this version into generated artifacts for downstream reference.

Automated CI/CD Update Pipeline

The .github/workflows/curriculum.yml pipeline orchestrates updates through multiple validation stages:

• Validation: Runs audit_lessons.py to check file layout, tests, and schema versions, plus check_readme_counts.py to verify the lesson count badge matches actual content
• Build: Executes site/build.js to parse lesson markdown and regenerate site/data.js with updated lesson links
• Deployment: Automatically updates the website at aiengineeringfromscratch.com upon merge to main

When a lesson is edited, authors bump the artifact version string in the output file. CI then copies the new artifact to outputs/ and the web UI displays the updated version automatically.

Key Versioning Files

Path	Role
AGENTS.md	Defines the one-commit-per-lesson policy and hard conventions
scripts/build_catalog.py	Generates JSON catalogs with schema_version validation
scripts/install_skills.py	Reads artifact version fields and manages skill installation
site/build.js & site/data.js	Rebuilds website data from lesson markdown
.workbench-version	Tracks agent workbench pack revisions
.github/workflows/curriculum.yml	CI pipeline validating commits and rebuilding the site

Summary

• Git source control tracks lesson evolution through a strict one-commit-per-lesson policy enforced by AGENTS.md.
• Semantic versioning in artifact frontmatter (e.g., version: 1.0.0) allows downstream systems to pin specific releases without cloning the repository.
• Schema versioning via schema_version keys in JSON catalogs protects data compatibility across tooling updates.
• Automated CI/CD via .github/workflows/curriculum.yml validates lesson structure, rebuilds the website through site/build.js, and synchronizes README counts automatically.

Frequently Asked Questions

How does the repository enforce the one-commit-per-lesson policy?

The AGENTS.md file defines this hard convention, and the CI pipeline runs audit_lessons.py to validate commit structure and file layout before merging. Contributors must isolate changes to a single lesson directory per commit, ensuring git log --oneline remains readable and bisectable.

Where are artifact versions stored in lesson outputs?

Each artifact in phases/*/*/outputs/*.md contains a YAML frontmatter block with a version: field (e.g., version: 1.0.0). The scripts/install_skills.py script reads this field at line 124 during installation, enabling precise version pinning for downstream consumers.

How does the CI pipeline update the project website when content changes?

The .github/workflows/curriculum.yml triggers site/build.js on every merge to main, which parses lesson markdown and regenerates site/data.js to reflect new content. The website at aiengineeringfromscratch.com updates automatically without manual intervention.

What happens when the internal JSON schema changes?

The schema_version key in catalog files (set by scripts/build_catalog.py at line 15) allows loaders to detect mismatches and either migrate data or raise clear errors. This protects downstream tooling from breaking changes when the internal data format evolves.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}