# What Is the Specific Structure of Agent Workbench Lessons? Inside the ai-engineering-from-scratch Curriculum

> Explore the specific structure of Agent Workbench lessons within the ai-engineering-from-scratch curriculum. Discover documented tutorials, executable code, unit tests, and quizzes.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: getting-started
- Published: 2026-06-05

---

**Every Agent Workbench lesson in the `rohitg00/ai-engineering-from-scratch` repository is a self-contained directory under `phases/14-agent-engineering/` that packages a documented tutorial, a mission statement, executable stdlib Python code, at least five unit tests, a six-question quiz, and optional reusable artifacts.**

The `rohitg00/ai-engineering-from-scratch` repository teaches agent engineering through a strict, reproducible lesson format. The **Agent Workbench lessons**—located in Phase 14 · Agent Engineering—follow a standardized directory and file contract that supports the curriculum’s seven workbench surfaces: Instructions, State, Scope, Feedback, Verification, Review, and Handoff. This layout guarantees that each lesson can be built, tested, and shipped independently.

## Standard Directory Layout for Every Agent Workbench Lesson

Each lesson lives in its own folder under `phases/14-agent-engineering/<lesson-slug>/` and contains the same core set of files. For example, the lesson *Agent Workbench: Why Capable Models Still Fail* resides in `phases/14-agent-engineering/31-agent-workbench-why-models-fail/`.

The complete tree looks like this:

```text
phases/14-agent-engineering/<lesson-slug>/
├─ docs/
│   └─ en.md                 # tutorial + front-matter

├─ mission.md                # one-sentence mission

├─ code/
│   ├─ main.py               # implementation (Python stdlib)

│   └─ tests/
│       └─ test_main.py      # ≥5 unit tests

├─ quiz.json                 # 6-question knowledge check

└─ outputs/                  # optional reusable artifacts

```

## Core Components of the Agent Workbench Lesson Structure

### Lesson Documentation ([`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md))

The file [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) is the human-readable tutorial. It includes front-matter that satisfies the curriculum contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), ensuring the lesson metadata aligns with the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) table and the [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status row. The metadata specifies the **title**, **type**, **languages**, **prerequisites**, **time**, and **learning objectives**.

For example, [`phases/14-agent-engineering/31-agent-workbench-why-models-fail/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/31-agent-workbench-why-models-fail/docs/en.md) opens with:

```markdown

# Agent Workbench Engineering: Why Capable Models Still Fail

> A capable model is not enough. Reliable agents need a workbench…

**Type:** Learn + Build  
**Languages:** Python (stdlib)  
**Prerequisites:** Phase 14 · 01 (Agent Loop), Phase 14 · 26 (Failure Modes)  
**Time:** ~45 minutes

```

### Mission Statement ([`mission.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/mission.md))

The [`mission.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/mission.md) file sits at the lesson root and provides a concise, one-sentence mission description. This string appears in the UI and helps learners orient themselves before they start the tutorial.

### Executable Code ([`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py))

Every lesson includes a **pure stdlib** Python script at [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py). The script demonstrates the workbench surface in action and can be executed directly without external dependencies. In [`31-agent-workbench-why-models-fail/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/31-agent-workbench-why-models-fail/code/main.py), the implementation runs a minimal repo-task twice—once as a prompt-only run and once with the full workbench surfaces wired in—and writes a [`failure_modes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/failure_modes.json) report.

### Unit Tests ([`code/tests/test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/tests/test_main.py))

Lessons validate correctness with a language-native test suite located at [`code/tests/test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/tests/test_main.py). The repository requires **at least five unit tests** per lesson. You can execute them with the stdlib runner:

```bash
cd phases/14-agent-engineering/31-agent-workbench-why-models-fail/code
python3 -m unittest discover tests -v

```

### Knowledge Quiz ([`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json))

At the root of each lesson, [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) encodes a six-question assessment. The format follows a strict split: **one pre-question**, **three checkpoint questions**, and **two post-questions**. This enforces the learning outcomes after the student has read the documentation and run the code.

### Reusable Outputs (`outputs/`)

The `outputs/` directory is optional, but when present it holds reusable artifacts that downstream lessons can import. For instance, [`phases/14-agent-engineering/31-agent-workbench-why-models-fail/outputs/skill-workbench-audit.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/31-agent-workbench-why-models-fail/outputs/skill-workbench-audit.md) is a skill file generated for later reuse. The capstone lesson at [`phases/14-agent-engineering/42-agent-workbench-capstone/outputs/agent-workbench-pack/README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/42-agent-workbench-capstone/outputs/agent-workbench-pack/README.md) even ships a full pack description.

## How the Seven Surfaces Map to the Lesson Code

The Agent Workbench curriculum is built around seven surfaces: **Instructions**, **State**, **Scope**, **Feedback**, **Verification**, **Review**, and **Handoff**. The [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) script in each lesson is the concrete implementation of these surfaces.

In the *Why Capable Models Still Fail* lesson, the script contrasts a naive prompt-only execution against a run that uses the full workbench. It then persists its findings to [`failure_modes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/failure_modes.json), turning the abstract surface concepts into observable behavior that the unit tests assert against.

## Running an Agent Workbench Lesson Locally

Because every lesson relies only on the Python standard library, you can run them without installing extra packages. Navigate to the lesson’s `code/` directory and execute the script:

```bash
cd phases/14-agent-engineering/31-agent-workbench-why-models-fail/code
python3 main.py

```

Then validate your changes with the bundled test suite:

```bash
python3 -m unittest discover tests -v

```

This "one commit per lesson" workflow guarantees that each Agent Workbench lesson remains **self-contained, reproducible, and independently shippable**.

## Summary

- Every Agent Workbench lesson lives under `phases/14-agent-engineering/<lesson-slug>/` in the `rohitg00/ai-engineering-from-scratch` repository.
- The standardized structure includes [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), [`mission.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/mission.md), [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py), [`code/tests/test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/tests/test_main.py), [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and an optional `outputs/` folder.
- [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) carries curriculum-compliant front-matter that links the lesson to the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) table and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status row.
- [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) demonstrates the seven workbench surfaces with pure stdlib Python and emits artifacts such as [`failure_modes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/failure_modes.json).
- Each lesson ships with **at least five unit tests** and a **six-question quiz** to enforce learning outcomes.
- The capstone lesson produces a reusable `agent-workbench-pack` that includes its own [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md).

## Frequently Asked Questions

### Where are the Agent Workbench lessons located in the repository?

The Agent Workbench lessons are part of **Phase 14 · Agent Engineering** and are stored under the `phases/14-agent-engineering/` directory. Each lesson has its own subfolder, such as `phases/14-agent-engineering/31-agent-workbench-why-models-fail/`.

### What is the purpose of the [`mission.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/mission.md) file?

The [`mission.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/mission.md) file contains a concise, one-sentence mission statement that surfaces in the UI. It orients the learner by summarizing the lesson’s goal before they open the tutorial or the code.

### How many questions are in an Agent Workbench lesson quiz?

Every [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) contains exactly **six questions**: one pre-assessment question, three checkpoint questions, and two post-assessment questions. This structure validates knowledge before, during, and after the lesson.

### Do Agent Workbench lessons require third-party Python libraries?

No. According to the source code, each lesson’s [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) is written using the **Python standard library only**. Learners can run the scripts directly with `python3 main.py` and execute tests with `python3 -m unittest discover tests -v` without installing external dependencies.