ROADMAP.md in ai-engineering-from-scratch: Master Curriculum Tracker and Update Guide

ROADMAP.md serves as the central status tracker for the ai-engineering-from-scratch curriculum, where specific status glyphs feed the website generator and CI validation systems to keep the public roadmap synchronized with actual lesson progress.

The ROADMAP.md file in the rohitg00/ai-engineering-from-scratch repository functions as the single source of truth for curriculum completion status. Located in the repository root, this markdown file tracks every phase and lesson using standardized status indicators that automated parsers consume to generate the public website and enforce quality controls across the codebase.

What is ROADMAP.md?

ROADMAP.md is the master status tracker living at the repository root (/ROADMAP.md). It organizes the entire curriculum into phases, with each lesson assigned one of three status glyphs:

• ✅ – Complete
• 🚧 – In-Progress
• ⬚ – Planned

The file header explicitly warns contributors: "The status glyphs in this file feed the website (site/build.js parses them into site/data.js); do not change their shape."

According to the source code, the site/build.js script parses these markdown tables to produce site/data.js, which powers the public curriculum site without requiring manual edits. Additionally, the curriculum.yml CI linting job enforces consistency across the repository and blocks accidental changes to the glyph shapes.

How to Update ROADMAP.md

Adding a New Lesson

When inserting a new lesson into a phase table, maintain the exact column order: # | Lesson | Status | Est..

The Lesson column must contain a markdown link pointing to the lesson directory, formatted as [Lesson Title](phases/XX-phase/YY-lesson/). This enables the site/build.js linker to resolve URLs correctly.

## Phase 11: LLM Engineering — ✅ (~17 hours)

| # | Lesson | Status | Est. |

|---|--------|--------|------|
| 01 | [Prompt Engineering — Techniques & Patterns](phases/11-llm-engineering/01-prompt-engineering) | ✅ | ~45 min |
| 13 | [Prompt‑Injection Defense](phases/11-llm-engineering/13-prompt-injection-defence) | ⬚ | ~60 min |

Changing Status Glyphs

Update the status glyph to reflect current progress:

• Change ⬚ to 🚧 when beginning work
• Change 🚧 to ✅ upon completion

Never modify the glyph characters themselves—the parser in site/build.js and the curriculum.yml CI job are hard-coded to recognize only these three specific Unicode symbols.

Updating Time Estimates

Adjust the Est. column to reflect expected completion time (e.g., ~45 min). This data helps learners gauge effort and allows CI systems to recompute total curriculum hours automatically.

Validating Changes Locally

Before committing, run the local audit scripts to catch formatting errors:

python3 scripts/audit_lessons.py
python3 scripts/check_readme_counts.py --fix

The audit_lessons.py script validates ROADMAP.md structure, while check_readme_counts.py updates the README totals to match the current roadmap.

Commit changes atomically with any new lesson files (docs, code, tests, quiz) following the repository's one-commit-per-lesson rule. Use conventional commit titles such as feat(phase-NN/MM): add <lesson-slug>.

Critical Formatting Rules

Maintaining strict formatting ensures the automation pipeline functions correctly:

• Preserve table alignment – Keep pipe-separated columns aligned; the order must remain # | Lesson | Status | Est.

• Use markdown links exclusively – Plain text in the Lesson column causes broken links in the generated site

• Protect glyph integrity – Do not replace ✅, 🚧, or ⬚ with alternative symbols or text

Key Files in the Automation Pipeline

Several files interact with ROADMAP.md to maintain curriculum integrity:

• ROADMAP.md – The root-level source of truth for phase and lesson status
• site/build.js – Parses the markdown tables to generate site/data.js for the public website
• scripts/audit_lessons.py – Lints roadmap format and checks for structural consistency
• curriculum.yml – CI configuration that validates glyph usage and table structure
• README.md – Displays high-level lesson tables updated automatically from the roadmap

Summary

• ROADMAP.md is the root-level master tracker for all curriculum phases and lessons in rohitg00/ai-engineering-from-scratch
• Status glyphs (✅, 🚧, ⬚) must never be altered, as they are hard-coded in site/build.js and CI validators
• Always use markdown links in the Lesson column to ensure proper URL resolution on the public site
• Validate changes locally using scripts/audit_lessons.py before submitting PRs to prevent CI failures
• Commit changes atomically with associated lesson files using conventional commit format

Frequently Asked Questions

What happens if I change the status glyph characters in ROADMAP.md?

The site/build.js parser and curriculum.yml CI linting job rely on exact Unicode characters (✅, 🚧, ⬚) to calculate completion percentages and generate the website. Changing these glyphs will break the automated pipeline and cause CI failures, as the system cannot recognize alternative symbols or text descriptions.

Can I use plain text instead of markdown links for lesson names?

No. The Lesson column must contain markdown links formatted as [Lesson Title](path/) for the site/build.js generator to resolve URLs correctly. Plain text entries will cause the links to disappear in the generated site/data.js and result in broken navigation on the public curriculum site.

How do I update the README.md lesson counts?

Run python3 scripts/check_readme_counts.py --fix after updating ROADMAP.md. This script automatically synchronizes the README totals with the current roadmap status, ensuring the repository documentation stays accurate without requiring manual calculation of completed lessons or total hours.

Why does my PR fail CI even though the table looks correct?

The CI pipeline runs scripts/audit_lessons.py to validate table structure, column order, and glyph consistency. Common failures include misaligned pipe separators, missing markdown links in the Lesson column, or modified status glyphs. Always run the local audit script before pushing to catch formatting errors before they reach the CI environment.

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