scaffold-exercises

Scaffold exercises

Create an exercise directory structure that passes pnpm ai-hero-cli internal lint checks, then commit using git commit .

Directory naming rules

• Sections: located under exercises/ in the XX-section-name/ format (e.g. 01-retrieval-skill-building）
• Exercises: located inside a section in the XX.YY-exercise-name/ format (e.g. 01.03-retrieval-with-bm25）
• Section number = XX, exercise number = XX.YY
• Names use kebab-case (lowercase letters, hyphens)

Exercise variants

Each exercise requires at least one of the following subfolders:

• problem/ — student workspace, contains TODO
• solution/ — reference implementation
• explainer/ — concept explanation material, does not contain TODO

When creating a template, use explainer/。

Required files

Each subfolder (problem/、solution/、explainer/) requires a readme.md, with the following requirements:

• Cannot be empty(must have actual content, even just a single heading is fine)
• Cannot have broken links

When creating a template, create a minimal readme containing a title and description:

# Exercise Title

Description here

If the subfolder contains code, a main.tsis also required (more than 1 line). But for templates, a readme-only exercise is also acceptable.

Workflow

1. Parse the plan — extract section names, exercise names, and variant types
2. Create directories — use mkdir -p to create each path
3. Create readme templates — one readme.mdper variant folder, containing a title
4. Run lint — run pnpm ai-hero-cli internal lint to verify
5. Fix errors — keep modifying until lint passes

Lint rules summary

linter（pnpm ai-hero-cli internal lint) checks the following:

• Each exercise has subfolders (problem/、solution/、explainer/）
• at least one of problem/、explainer/ or explainer.1/ exists
• The main subfolder contains readme.md and it is not empty
• No .gitkeep files
• No speaker-notes.md files
• No broken links in the readme
• No pnpm run exercise commands in the readme
• Each subfolder requires main.ts, unless it is readme-only

Move/rename exercises

When renumbering or moving exercises:

1. Use git mv(instead of mv) to rename directories — this preserves git history
2. Update numeric prefixes to maintain order
3. Re-run lint after moving

Example:

git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

Example: create templates from a plan

Given a plan such as:

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

Create:

mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer

Then create the readme templates:

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"