scaffold-exercises

name	scaffold-exercises
description	Scaffold course exercise directories with numbered sections, exercise variants, required readmes, and repo-specific validation. Use when creating exercise stubs, adding a course section, or safely renaming exercises.

scaffold-exercises

Create course exercise directory structures that match the owning repository's documented conventions, then validate them with that repository's configured checks.

When to use

• User asks to scaffold exercises, exercise stubs, or a new course section.
• User provides a course plan with numbered sections and exercises.
• User wants to move, renumber, or rename exercise directories safely.

Before scaffolding

1. Read local repo guidance first: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, course docs, and any existing exercise README conventions.
2. If the work is tracked, inspect the bead with bd show <id> and add a concise worklog: comment before broad filesystem edits.
3. Inspect existing exercises/ structure and naming before creating new directories.
4. Confirm the owning repo's validation command. Use pnpm ai-hero-cli internal lint only when that repo documents it; otherwise use the local lint, test, or validation script.

Directory naming

• Sections live under exercises/ as XX-section-name/, for example 01-retrieval-skill-building/.
• Exercises live inside a section as XX.YY-exercise-name/, for example 01.03-retrieval-with-bm25/.
• Section number is XX; exercise number is XX.YY.
• Names are dash-case: lowercase words separated by hyphens.
• Preserve the numbering in the source plan unless the user explicitly asks to resequence.

Exercise variants

Each exercise needs at least one variant subfolder:

• problem/ - student workspace or prompt material.
• solution/ - reference implementation or answer.
• explainer/ - conceptual material with no student work required.

When the plan does not specify variants, default to explainer/. If the source course uses numbered explainer variants such as explainer.1/, follow the local pattern.

Required files

Each created variant folder needs a readme.md that:

• Is not empty.
• Has a meaningful title and short description.
• Avoids broken links.
• Avoids repo-level TODO-list artifacts such as TODO.md files or stray code TODO comments. Student-facing exercise prompts are fine when the course format expects them.

Minimal stub:

# Exercise Title

Description here.

If a variant contains code, add a main.ts only when the owning repo or exercise format requires it. For stub-only exercises, a readme-only variant is acceptable unless local validation says otherwise.

Scaffold workflow

1. Parse the plan for section names, exercise names, exercise numbers, and variant types.
2. Map names to dash-case paths without changing numeric prefixes.
3. Preview the paths before writing when the scaffold touches multiple exercises.
4. Create only the requested directories and variant folders.
5. Add one readme.md per variant with a title and description.
6. Add main.ts only for variants that need executable code.
7. Run the owning repo's documented validation command and fix reported issues.
8. Add a worklog: comment summarizing what was scaffolded when the work is tracked in Beads.

Validation checklist

Use the repo's own checks. Typical validation looks for:

• Each exercise has at least one expected variant folder such as problem/, solution/, explainer/, or a documented numbered explainer variant.
• Required readme.md files exist and are non-empty.
• README links resolve.
• Generated placeholder files such as .gitkeep are not present unless local docs explicitly require them.
• Undocumented files such as speaker-notes.md are not introduced.
• README commands match the owning repo's current scripts.
• main.ts exists only where required and contains more than a placeholder line when validation expects executable code.

Example conditional command selection:

# If documented by the owning repo:
pnpm ai-hero-cli internal lint

# Otherwise use local repo checks, for example:
bun run lint
bun run test
pnpm test

Moving or renaming exercises

When renumbering or moving exercises:

1. Use git mv for tracked directories so history follows the rename.
2. Update numeric prefixes to maintain the section and exercise order.
3. Update references, links, imports, indexes, manifests, and course navigation that mention the old path or title.
4. Run the owning repo's validation command after the move.
5. Record the rename in a Beads worklog: comment when the work is tracked.

Example:

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

Example: stubbing from a plan

Given:

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

Create:

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md

The 05.02-short-term-memory exercise gets all three requested variants; the others default to explainer/.