Folder Structure for Contributing New Lessons to ai-engineering-from-scratch

TLDR: Every new lesson lives under phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/ and must contain three sub-folders—docs/ for the narrative, code/ for implementations and tests, and outputs/ for artifacts—plus mandatory quiz.json and registration entries in README.md and ROADMAP.md.

The rohitg00/ai-engineering-from-scratch repository enforces a strict folder structure for contributing new lessons to maintain consistency across its 20-phase curriculum. As defined in AGENTS.md and the "The shape of a lesson" section of the README, this convention ensures that every lesson follows the same organizational pattern, making the codebase navigable for both human contributors and automated agents.

The Standard Three-Folder Layout

Each lesson directory requires three top-level sub-folders that separate content from executable code and generated artifacts.

docs/

The docs/ folder holds the lesson narrative in en.md, which must include YAML front-matter specifying the title, type, supported languages, prerequisites, estimated time, and learning objectives. This file serves as the canonical source for lesson metadata and instructional content.

code/

The code/ folder contains the implementation logic and test suite. You must provide a main.<lang> entry point (supporting Python, TypeScript, Rust, or Julia) with a header comment citing the lesson's documentation path. A tests/ subdirectory must contain at least five unit tests validating the implementation.

outputs/

The outputs/ folder stores reusable artifacts generated during the lesson, such as skill definitions, prompt templates, agent configurations, or MCP server manifests. While optional during initial development, this folder must exist to accommodate generated files that extend the lesson's utility.

Naming Conventions and Path Structure

The repository uses zero-padded two-digit indices to preserve lexical ordering. The full path follows this pattern:

phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/

For example, the second lesson in the first phase resides at phases/01-math-foundations/02-vectors-matrices-operations/. The <NN> prefix ensures that file explorers and shell commands list lessons in chronological order, while the hyphenated slugs provide human-readable context.

Mandatory Files for Contribution

Beyond the directory structure, four specific files must exist before a lesson is considered complete according to the New-Lesson Onboarding guide in AGENTS.md.

Documentation with Front-Matter

Create docs/en.md with standard front-matter that includes the title, type (e.g., "Build"), languages, prerequisites, time estimate, and bullet-list learning objectives.

# Vectors, Matrices & Operations

> Learn the algebra that powers every neural net.

**Type:** Build  
**Languages:** Python, Julia  
**Prerequisites:** 01-linear-algebra-intuition  
**Time:** ~30 minutes

## Learning Objectives

- Compute dot products and matrix multiplications
- Derive broadcasting rules
- Implement basic linear-algebra utilities from scratch

Implementation and Test Code

Place your primary implementation in code/main.<ext> with a header comment referencing the documentation path. Include a comprehensive test suite in code/tests/ with a minimum of five unit tests.

# =============================================================================

# Lesson: Vectors, Matrices & Operations

# Path: phases/01-math-foundations/02-vectors-matrices-operations/docs/en.md

# =============================================================================

import unittest
from ..main import dot, matmul

class TestLinearAlgebra(unittest.TestCase):
    def test_dot(self):
        self.assertEqual(dot([1, 2, 3], [4, 5, 6]), 32)

    def test_matmul(self):
        a = [[1, 2], [3, 4]]
        b = [[5, 6], [7, 8]]
        self.assertEqual(matmul(a, b), [[19, 22], [43, 50]])

if __name__ == "__main__":
    unittest.main()

Assessment Configuration

Include a quiz.json file in the lesson root following the six-question schema to validate learning outcomes. This file drives the automated assessment system and ensures students have mastered the material before proceeding.

Central Index Registration

After creating the folder structure and content, you must register the lesson in two central index files to make it discoverable.

Update README.md by adding a row to the appropriate phase's lesson table that links to your new directory:

| 02 | [Vectors, Matrices & Operations](phases/01-math-foundations/02-vectors-matrices-operations/) | Build | Python, Julia |

Update ROADMAP.md to track the lesson's development status, typically marking it as WIP (Work In Progress) initially and updating to ✅ upon completion.

Step-by-Step Creation Workflow

To scaffold a new lesson programmatically, use this bash command structure, replacing the placeholders with your specific phase and lesson identifiers:

mkdir -p phases/01-math-foundations/02-vectors-matrices-operations/{docs,code,outputs}
touch phases/01-math-foundations/02-vectors-matrices-operations/quiz.json
mkdir phases/01-math-foundations/02-vectors-matrices-operations/code/tests

This command creates the required directory hierarchy in a single operation, establishing the docs/, code/, and outputs/ folders while preparing the quiz.json file and test directory for immediate population.

Summary

• The canonical path is phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/ with zero-padded indices.
• Every lesson requires three sub-folders: docs/ for narratives, code/ for implementations, and outputs/ for artifacts.
• Mandatory files include docs/en.md with front-matter, code/main.<lang>, code/tests/ with five+ unit tests, and quiz.json.
• Registration in README.md (lesson table) and ROADMAP.md (status tracking) is required for visibility.
• The complete specification lives in AGENTS.md under the New-Lesson Onboarding section.

Frequently Asked Questions

What are the exact sub-folders required for a new lesson?

Every lesson must contain three sub-folders: docs/ for the markdown narrative (specifically en.md), code/ for runnable implementations and tests, and outputs/ for generated artifacts like skills, prompts, or agent configurations. This structure is enforced across all 20 phases of the curriculum.

How do I name the lesson directory correctly?

Use the pattern phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/ where <NN> is a zero-padded two-digit number (e.g., 01, 02). The slugs should be short, hyphenated descriptors like math-foundations or vectors-matrices-operations that preserve lexical order when sorted alphabetically.

What content must the docs/en.md file contain?

The docs/en.md file must include YAML front-matter with the title, type (e.g., "Build"), supported languages, prerequisite lessons, estimated time, and learning objectives. It also contains the narrative explanation of the lesson concepts and serves as the primary documentation source.

How do I register a new lesson so it appears in the curriculum?

You must edit two files: add a row to the lesson table in README.md linking to your lesson path, and add a status line in ROADMAP.md to track whether the lesson is WIP or complete. Without these entries, the lesson remains invisible to the curriculum index.

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