scaffold-exercises

name	scaffold-exercises
description	Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

Scaffold Exercises

Create exercise directory structures that pass pnpm ai-hero-cli internal lint, then commit with git commit.

Directory naming

• Sections: XX-section-name/ inside exercises/ (e.g., 01-retrieval-skill-building)
• Exercises: XX.YY-exercise-name/ inside a section (e.g., 01.03-retrieval-with-bm25)
• Section number = XX, exercise number = XX.YY
• Names are dash-case (lowercase, hyphens)

Exercise variants

Each exercise needs at least one of these subfolders:

• problem/ - student workspace with TODOs
• solution/ - reference implementation
• explainer/ - conceptual material, no TODOs

When stubbing, default to explainer/ unless the plan specifies otherwise.

Required files

Each subfolder needs a readme.md that:

• Is not empty (must have real content, even a single title line works)
• Has no broken links

When stubbing, create a minimal readme with a title and a description:

# Exercise Title

Description here

Workflow

1. Parse the plan - extract section names, exercise names, and variant types
2. Create directories - mkdir -p for each path
3. Create stub readmes - one readme.md per variant folder with a title
4. Run lint - pnpm ai-hero-cli internal lint to validate
5. Fix any errors - iterate until lint passes

Lint rules summary

The linter checks:

• Each exercise has subfolders (problem/, solution/, explainer/)
• At least one of problem/, explainer/, or explainer.1/ exists
• readme.md exists and is non-empty in the primary subfolder
• No .gitkeep files
• No broken links in readmes
• main.ts required per subfolder unless it's readme-only

Moving/renaming exercises

When renumbering or moving exercises:

1. Use git mv (not mv) to rename directories - preserves git history
2. Update the numeric prefix to maintain order
3. Re-run lint after moves