ROADMAP.md Status Tracking System for Lesson Completion in AI Engineering From Scratch

The ROADMAP.md status tracking system uses a machine-readable, emoji-based markup scheme where contributors update markdown tables with completion glyphs (✅, 🚧, ⬚) that a Node.js parser converts into structured JSON to power the project's website.

The AI Engineering From Scratch curriculum maintains lesson progress through an elegant single-file tracking approach. Instead of relying on external project management tools, the repository uses a standardized markdown table format in ROADMAP.md that serves as the single source of truth for curriculum completion. This approach allows both humans and automation to read progress status directly from version-controlled markdown.

How the ROADMAP.md Table Structure Works

Each phase of the curriculum is represented by a markdown table containing lesson metadata and a dedicated Status column. The table follows a strict schema with five columns: lesson number, title (with link), status glyph, and time estimate.

In ROADMAP.md, a typical entry looks like this:

| # | Lesson | **Status** | Est. |

|---|--------|------------|------|
| 01 | Dev Environment | ✅ | ~75 min |
| 02 | Git & Collaboration | ✅ | ~45 min |
| 13 | [Attention Mechanism — The Breakthrough](phases/05-nlp-foundations-to-advanced/10-attention-mechanism) | ⬚ | ~45 min |

The status column is the only field that changes during development. When work begins on a lesson, the author updates the glyph from ⬚ to 🚧, and upon completion, replaces it with ✅.

Status Glyph Legend

The top of ROADMAP.md defines a three-state emoji legend that standardizes progress communication across the curriculum:

• ✅ — Complete: The lesson content is finalized and published
• 🚧 — In Progress: Active development is underway
• ⬚ — Planned: Scheduled for future development but not yet started

This glyph system creates a human-readable and machine-parsable interface. Contributors can scan the markdown visually to understand progress, while automated tooling extracts these Unicode characters to generate statistics and UI components.

To mark a lesson as complete, you simply edit the table cell:

| 13 | [Attention Mechanism — The Breakthrough](phases/05-nlp-foundations-to-advanced/10-attention-mechanism) | ✅ | ~45 min |

Build Pipeline Automation

The repository automates website updates by parsing ROADMAP.md on every commit. The build pipeline consists of three interconnected components that keep documentation synchronized without manual intervention.

1. Parsing with site/build.js

The Node.js script site/build.js contains the parseRoadmap function (lines 31-37) that scans the markdown file, detects phase headers, and extracts table rows into structured objects:

function parseRoadmap(content) {
  const lines = content.split('\n');
  const roadmap = {};
  // ...detect phase headers, then table rows
  // each row yields: { phase, lessonNumber, title, statusGlyph, est }
  return roadmap;
}

This function treats the emoji glyphs as discrete state tokens, converting the visual markdown representation into programmatic data.

2. Data Generation for the Website

The parsed output is written to site/data.js, which powers the lesson catalog and progress widgets. The conversion produces JSON objects like:

{
  "phase": "Phase 5: NLP",
  "lesson": "10",
  "title": "Attention Mechanism — The Breakthrough",
  "status": "✅",
  "estimate": "~45 min"
}

3. CI/CD Integration

The curriculum.yml CI job runs site/build.js on every push to the repository. This automation updates the README lesson counts and regenerates site assets immediately after ROADMAP.md changes, ensuring the live website reflects the current curriculum state without requiring additional build steps from contributors.

Summary

• ROADMAP.md acts as the central progress tracker using markdown tables with emoji status glyphs
• Three-state system: ✅ (Complete), 🚧 (In Progress), ⬚ (Planned) provides unambiguous lesson states
• site/build.js parses the roadmap and converts markdown tables into JSON data structures
• Continuous integration automatically synchronizes the website whenever status changes are pushed

Frequently Asked Questions

What do the emoji symbols in ROADMAP.md mean?

The emoji symbols represent discrete lesson states: ✅ indicates a complete lesson, 🚧 marks lessons currently in development, and ⬚ designates planned content that has not yet started. These glyphs appear in the Status column of the markdown tables and are defined in the legend at the top of ROADMAP.md.

How does the website stay synchronized with ROADMAP.md changes?

The synchronization happens automatically through the curriculum.yml CI pipeline. When you push changes to ROADMAP.md, the CI job executes site/build.js, which parses the updated tables and writes fresh data to site/data.js. This triggers a site rebuild that displays the current lesson completion status without requiring manual website updates.

Can I manually edit lesson status without running the build script locally?

Yes. Since ROADMAP.md is plain markdown, you can edit the status glyphs directly in any text editor or through GitHub's web interface. The CI pipeline handles the build process automatically after you commit changes, so local builds are only necessary for development or testing the parser logic.

What happens if I use an incorrect status emoji in the table?

The parseRoadmap function in site/build.js extracts whatever glyph appears in the status column, so using an undefined emoji will not break the build but may cause the website to display incorrect status indicators. Stick to the three defined glyphs (✅, 🚧, ⬚) to ensure consistent rendering in the lesson catalog and progress widgets.

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