How Learning Paths Are Defined and Tested in the AI Engineering From Scratch Curriculum

Learning paths in the rohitg00/ai-engineering-from-scratch repository are defined as JSON manifest files stored in the learning-paths/ directory and automatically validated by scripts/audit_lessons.py, which verifies lesson existence, prerequisite ordering, and schema conformance through the .github/workflows/curriculum.yml CI pipeline.

The curriculum structures its educational content into modular learning paths that guide users through specific skill tracks like "Using Coding Agents" or "Agentic AI Engineer." These paths are declared in machine-readable JSON files and enforced by a comprehensive auditing system that prevents broken or logically invalid curricula from merging into the main branch.

Defining Learning Paths via JSON Manifests

Core Schema and File Structure

Each learning path is defined by a JSON manifest file located in the repository root under learning-paths/. For example, the manifest at learning-paths/using-coding-agents.json follows a strict schema containing the following fields:

• title: The human-readable name of the learning track
• description: A brief overview of the path's objectives and target outcomes
• lessons: An ordered array of lesson slugs (e.g., "01-intro-to-coding-agents") that define the sequence of study
• prerequisites (optional): Global prerequisites that must be satisfied before starting the path
• metadata (optional): Additional attributes such as difficulty level, estimated completion time, or target role

The lesson slugs declared in the lessons array directly correspond to directories under the phases/ folder. This decouples the manifest from the physical folder layout, allowing the curriculum to evolve without breaking internal references.

Lesson Slug Resolution

The mapping between manifest entries and physical content relies on directory conventions. Each slug in the lessons array must resolve to an existing path under phases/ following the pattern phases/<phase-number>-<slug>/<lesson-slug>/. This convention ensures that the declarative JSON definitions remain tightly coupled to the actual lesson content while maintaining flexibility for structural reorganizations.

Below is a representative example from learning-paths/using-coding-agents.json:

{
  "title": "Using Coding Agents",
  "description": "Learn how to harness autonomous coding agents to build software faster.",
  "lessons": [
    "01-intro-to-coding-agents",
    "02-prompt-engineering",
    "03-agent-loop",
    "04-advanced-deployment"
  ]
}

Automated Testing of Learning Path Integrity

Existence Verification with audit_lessons.py

The primary validation logic resides in scripts/audit_lessons.py. This script performs an existence check by iterating through the lessons array of each manifest and confirming that the referenced directories actually exist within the phases/ structure. If a manifest references a slug that lacks a corresponding physical directory, the script immediately flags the error.

Prerequisite Ordering Validation

Beyond simple existence checks, the audit script validates logical consistency by examining prerequisite relationships. Each lesson directory contains a docs/en.md file with front-matter metadata defining that lesson's specific prerequisites. The script cross-references these declarations against the ordering in the learning path manifest to ensure that no lesson appears before its prerequisites are satisfied. If a lesson declares a dependency that appears later in the sequence, the validation fails.

Schema Conformance and Cross-Path Consistency

The validation enforces strict schema conformance by verifying that every manifest contains mandatory fields (title, description, lessons) and that the lessons field is a properly formatted array. Additionally, a global audit mechanism checks for cross-path consistency, ensuring that no two learning paths list the same lesson under incompatible prerequisite constraints, thereby preventing contradictory learning experiences across different tracks.

Here is a simplified excerpt from scripts/audit_lessons.py demonstrating the core validation logic:

import json, pathlib, sys

def load_path(path_file: pathlib.Path):
    data = json.loads(path_file.read_text())
    for slug in data["lessons"]:
        lesson_dir = pathlib.Path("phases").glob(f"*/*-{slug}")
        if not any(lesson_dir):
            sys.exit(f"❌ Lesson {slug} referenced in {path_file.name} does not exist.")
    print(f"✅ {path_file.name} passes validation")

CI/CD Pipeline Integration

The validation system is fully automated through the GitHub Actions workflow defined in .github/workflows/curriculum.yml. This workflow triggers scripts/audit_lessons.py on every push and pull request targeting the main branch. If the audit script detects any broken references, invalid prerequisite ordering, or schema violations, the CI job fails immediately, blocking the merge and ensuring that only well-formed learning paths reach production.

Summary

• Learning paths are defined as JSON manifests in the learning-paths/ directory, with each file specifying a title, description, and ordered list of lesson slugs
• Lesson slugs must resolve to physical directories under phases/ as validated by scripts/audit_lessons.py
• The audit script enforces prerequisite ordering by checking front-matter metadata in each lesson's docs/en.md file
• Schema conformance and cross-path consistency checks prevent malformed or contradictory curriculum definitions
• The .github/workflows/curriculum.yml CI workflow automatically runs these validations on every pull request, ensuring curriculum integrity

Frequently Asked Questions

What file format are learning paths stored in?

Learning paths are stored as JSON manifest files inside the learning-paths/ directory. Each file follows a structured schema containing the path title, description, and an ordered array of lesson slugs that define the curriculum sequence.

How does the audit script verify lesson prerequisites?

The audit script in scripts/audit_lessons.py validates prerequisites by parsing the front-matter metadata within each lesson's docs/en.md file. It ensures that prerequisite lessons appear earlier in the learning path sequence than the lessons that depend on them, preventing logical ordering errors.

Where is the continuous integration configured for curriculum validation?

The CI configuration resides in .github/workflows/curriculum.yml. This GitHub Actions workflow automatically executes the audit script on every push and pull request, failing the build if any learning path contains broken references or invalid prerequisite chains.

Can learning paths have overlapping lessons?

Yes, lessons can appear in multiple learning paths, but the global audit in scripts/audit_lessons.py performs cross-path consistency checks to ensure that shared lessons do not have conflicting prerequisite requirements across different paths, preventing contradictory learning experiences.

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