# How the AI Engineering from Scratch Repository Is Versioned and Updated

> Learn how the ai engineering from scratch curriculum uses Git for versioning and explicit semantic version strings for precise dependency management.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-06-19

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md) begins with:

```markdown
---
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py) script (line 15) emits catalog entries with `"schema_version": 1`, enabling loaders like [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py) and [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py) script (lines 85-87) writes and reads this version, injecting it into generated README files and installation scripts.

```bash
$ 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) pipeline orchestrates updates through multiple validation stages:

- **Validation**: Runs [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) to check file layout, tests, and schema versions, plus [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py) to verify the lesson count badge matches actual content
- **Build**: Executes [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to parse lesson markdown and regenerate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) | Defines the one-commit-per-lesson policy and hard conventions |
| [`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py) | Generates JSON catalogs with `schema_version` validation |
| [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) | Reads artifact version fields and manages skill installation |
| [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) & [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) | Rebuilds website data from lesson markdown |
| `.workbench-version` | Tracks agent workbench pack revisions |
| [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) validates lesson structure, rebuilds the website through [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file defines this hard convention, and the CI pipeline runs [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) triggers [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) on every merge to `main`, which parses lesson markdown and regenerates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.