What Is the Role of ROADMAP.md in Tracking Phase and Lesson Completion Status?

ROADMAP.md serves as the single source of truth for curriculum progress, using visual status glyphs to track completion states while powering automated website generation and CI validation workflows.

In the rohitg00/ai-engineering-from-scratch repository, the ROADMAP.md file functions as the central ledger for tracking phase and lesson completion status, coordinating lesson development, learner navigation, and automated tooling. This centrally maintained markdown file records the implementation state of every phase and lesson, enabling both human contributors and automated systems to assess curriculum completeness at a glance.

Core Responsibilities of ROADMAP.md

The roadmap fulfills four critical functions that keep the curriculum coherent and discoverable.

Visual Status Tracking

At its foundation, ROADMAP.md implements a status tracking system using Unicode glyphs to indicate lesson states. According to AGENTS.md (lines 19-22), each lesson row contains one of three status indicators: ✅ for completed, 🚧 for in-progress, or ⬚ for not-started. These visual markers provide immediate scannable context for maintainers and learners regarding which curriculum components are production-ready versus under development.

Time Estimation and Curriculum Metrics

Beyond status tracking, the file stores estimated completion times for each lesson. The skills/find-your-level/SKILL.md module (lines 198-203) reads these duration estimates to calculate aggregate learning-hour totals, allowing automated tools to recommend appropriate starting phases based on available study time. This transforms the roadmap from a simple checklist into a data source for personalized learning path generation.

Website Generation Pipeline

The roadmap directly drives the public-facing curriculum site. In site/build.js (lines 4-17 and 97-103), the build script parses ROADMAP.md alongside README.md and glossary/terms.md to generate site/data.js. This parsed data structure powers phase-level progress bars and lesson listings on the website, ensuring that the published curriculum always reflects the current implementation status recorded in the repository.

Continuous Integration Validation

The file acts as a quality gate in the continuous integration pipeline. The .github/workflows/curriculum.yml workflow (lines 24-26) specifically monitors ROADMAP.md for changes, triggering an audit job that verifies lesson rows are present and correctly linked. This prevents curriculum drift by ensuring that code changes remain synchronized with documentation updates.

Integration with Development Workflows

ROADMAP.md is deeply embedded in the contribution lifecycle, enforcing consistency through automated checks and manual checkpoints.

Automated Parsing in site/build.js

The website build process relies on regex-based extraction of roadmap data. The build script reads the entire file contents and matches phase headers against status glyphs to construct the navigation hierarchy. This automated parsing ensures that any status update in the roadmap immediately reflects on the public site upon the next deployment.

CI Enforcement via curriculum.yml

The curriculum validation workflow treats roadmap modifications as significant events requiring verification. When contributors submit pull requests that alter ROADMAP.md, the CI system validates that all referenced lesson directories exist and that the markdown-link syntax follows the established convention of [Lesson Title](phases/NN-phase-slug/MM-lesson/).

Contribution Requirements in PULL_REQUEST_TEMPLATE.md

Human validation complements automated checks through mandatory contributor acknowledgments. The .github/PULL_REQUEST_TEMPLATE.md (lines 21-22) includes a checklist item requiring authors to add a markdown-link row to ROADMAP.md under the appropriate phase when submitting new lessons. This institutionalizes the update process within the ritual of contribution.

Scaffolding Reminders in scaffold-lesson.sh

The repository tooling actively prevents omissions during lesson creation. The scripts/scaffold-lesson.sh script (lines 135-137) outputs explicit reminders to edit ROADMAP.md after generating lesson scaffolding, reducing the likelihood that contributors forget to register new content in the central ledger.

Practical Code Examples

When adding a new lesson, contributors must follow a specific pattern to maintain roadmap integrity:

# Adding a new lesson (Phase 03, Lesson 04)

echo "  4. add a markdown‑link row to ROADMAP.md under Phase 03:"
echo "  | 04 | [My New Lesson](phases/03-deep-learning-core/04-my-new-lesson/) | ✅ | Python |"
git add phases/03-deep-learning-core/04-my-new-lesson ROADMAP.md
git commit -m "feat(phase-03/04): add My New Lesson"

The website generation logic extracts status information using pattern matching against the roadmap contents:

// site/build.js – extracting status glyphs from ROADMAP.md
const roadmap = fs.readFileSync(ROADMAP_PATH, 'utf8');
const phaseStatus = roadmap.match(/^## Phase (\d+).*?([✅🚧⬚])$/gm);

// …the parsed data becomes part of site/data.js for the UI

Summary

• ROADMAP.md acts as the central ledger for the ai-engineering-from-scratch curriculum, maintaining the authoritative record of lesson completion states.
• Status glyphs (✅, 🚧, ⬚) provide at-a-glance visual indicators of implementation progress, as documented in AGENTS.md.
• Time estimates embedded in the file enable automated tools like find-your-level to calculate learning path durations.
• Website generation depends on parsing ROADMAP.md in site/build.js to create dynamic progress indicators and navigation.
• CI validation through .github/workflows/curriculum.yml ensures roadmap entries remain synchronized with actual lesson content.
• Contribution workflows mandate roadmap updates via pull request templates and scaffolding scripts, preventing curriculum drift.

Frequently Asked Questions

What do the status glyphs in ROADMAP.md represent?

The ROADMAP.md file uses three Unicode symbols to indicate lesson states: ✅ denotes a completed lesson with all content finalized, 🚧 marks lessons currently under active development, and ⬚ identifies not-started lessons awaiting implementation. These glyphs appear in both the phase headers and individual lesson rows to provide immediate visual scanning capability.

How does ROADMAP.md drive the public curriculum website?

The site/build.js script parses ROADMAP.md during the build process to generate site/data.js, which serves as the data layer for the public curriculum site. This parsing extracts phase numbers, lesson titles, and status glyphs to render dynamic progress bars and lesson listings. Any status change in the roadmap automatically propagates to the website upon the next deployment.

Why does the CI workflow monitor ROADMAP.md changes?

The .github/workflows/curriculum.yml configuration specifically watches for modifications to ROADMAP.md to trigger validation jobs. The audit process verifies that lesson rows are correctly formatted and that linked directories exist, ensuring that the documented curriculum structure accurately reflects the repository's actual state and preventing broken links or orphaned lessons.

Can ROADMAP.md be used to calculate total learning time?

Yes, the file stores estimated minutes for each lesson, which the skills/find-your-level/SKILL.md tool reads to calculate aggregate learning-hour totals. This enables automated recommendations for phase selection based on available study time, transforming the roadmap into a functional data source for personalized learning path generation.

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