FORMAT-CONCEPT-BOOK.md

AGENTS.md

AGENTS.md — Roadmap Curriculum Builder

This repo produces multi-concept learning roadmaps that bridge online courses to a build-from-scratch project (ZeroServe). Each roadmap is a single Markdown file converted to PDF.

Repo layout

roadmap/
├── FORMAT.md                 # Per-concept template (READ FIRST)
├── zeroserve-in-public.md    # LLM inference engine curriculum (101 concepts)
├── llm-lab.md                # PyTorch + TiP foundations (37 concepts)
├── scripts/
│   └── convert-to-pdf.sh     # Markdown + Mermaid → PDF pipeline
├── references/               # Source materials, config dumps
└── AGENTS.md                 # This file

Workflow: how to build a new roadmap

Follow these phases in order. Each phase has explicit steps.

Phase 1 — Research (gather before writing)

1. Read the target project. Read zeroserve-in-public.md to understand what the roadmap feeds into. Identify which concepts the learner needs BEFORE they can start ZeroServe.
2. Web-fetch the course page. Use webfetch on the course URL. Extract: module list, topics, hours, prerequisites, instructor.
3. Read FORMAT.md. This is the per-concept template. Every concept MUST follow it. No exceptions.
4. Explore the reference repo. If a local clone exists (e.g., ~/workspace/learning/deeplearning-ai-pytorch/), spawn an explore subagent to map its structure. Get: file inventory, naming conventions, notebook depth/style, data/model files.
5. Read 3–5 actual notebooks. Don't guess content. Read representative labs to understand what's actually taught, what APIs are used, and what exercises look like. This ensures the Write/Test sections reference REAL files.
6. Web-fetch supplementary courses. If blending multiple sources (e.g., PyTorch Certificate + Transformers in Practice), fetch each course page and map overlap vs unique content.

Phase 2 — Plan (structure before writing)

1. Map course modules to concepts. Break each module into 2–4 concepts. Aim for 30–40 total. Each concept should be learnable in 1–2 hours.
2. Organize into layers. Group concepts into sequential layers (Layer 0: foundations → Layer N: advanced). Each layer should take 1–2 weeks.
3. Identify bridge concepts. Mark which concepts unlock the target project (ZeroServe). These get a ★ KEY marker.
4. Create a todo list. Use todowrite with one entry per concept. Set priority: high for must-learn, medium for nice-to-have, low for optional.
5. Ask the user 2 questions before writing:
   • Depth per concept (full FORMAT ~80 lines vs compact stubs ~30 lines)
   • Reference model/dataset (e.g., Qwen3-0.6B vs course defaults)
6. Present the plan. Show the layer structure, concept count, and cross-reference to ZeroServe. Get confirmation before writing.

Phase 3 — Write (incremental, never all at once)

NEVER write all concepts in one pass. It is error-prone. Write incrementally:

1. Write the header first. Title, repos table, abbreviations, per-concept template reference, big-picture mermaid diagram. End with <!-- CONTINUE --> marker.
2. Write one layer (3–6 concepts) per turn. Use todowrite to mark the first concept in_progress, write the batch, mark all completed.
3. Append using the CONTINUE marker technique:
   • The file always ends with <!-- CONTINUE -->
   • Use edit tool: oldString = <!-- CONTINUE -->, newString = [new concepts] + <!-- CONTINUE -->
   • This guarantees reliable appending without reading the whole file
4. After the last batch, remove the <!-- CONTINUE --> marker (or replace with closing content).
5. Each concept follows FORMAT.md exactly:
   • Goal + Why (1 sentence each)
   • Read (real file paths from Phase 1 research)
   • Search (keywords, papers with arXiv IDs)
   • Write (runnable code, typed, with correct imports — NOT pseudocode)
   • Test (concrete bash command + expected output)
   • Commit (conventional commit format)
   • Think (3–5 bullets + mermaid diagram for anything structural)
   • Q&A (2–3 interview questions with specific numbers in answers)
   • Tips & Tricks (3–5 gotchas/shortcuts)
   • --- separator

Phase 4 — Blend (integrate supplementary courses)

When adding a second course (e.g., Transformers in Practice):

1. Map overlap vs unique content. Which TiP modules duplicate existing concepts? Which add new topics?
2. Enrich existing concepts. Add new course references to the Read section of overlapping concepts. Don't rewrite — just add references.
3. Add new concepts for unique content. Insert as a new batch between existing layers.
4. Create a two-track system. Mark skippable concepts with ⏭️ SKIP (fast track). Add a "Two tracks" table in the header showing fast vs full path.
5. Update the big-picture mermaid to show both tracks.
6. Update the cross-reference table at the end to include new bridge points.

Phase 5 — PDF generation

1. Fix mermaid syntax BEFORE running the script. Common bugs:
   • -> instead of --> (single dash fails silently)
   • Unicode arrows → ↔ in edge definitions (must be -->)
   • Emoji in node labels (⏭️, ★) — replace with ASCII ((skip), KEY)
   • En-dashes – in node labels — usually fine but replace with - to be safe
2. Check script dependencies: quarto, mmdc, pandoc, xelatex/pdflatex.
3. Install optional packages for quality:
   • fvextra (code line wrapping): tlmgr init-usertree && tlmgr --usermode option repository https://ftp.math.utah.edu/pub/tex/historic/systems/texlive/2025/tlnet-final/ && tlmgr --usermode install fvextra
   • DejaVu Nerd Font (Unicode): brew install --cask font-dejavu-sans-mono-nerd-font
4. Run: bash scripts/convert-to-pdf.sh <file>.md
5. If mermaid fails: The script reports which diagram number failed (e.g., FAILED: d007). Extract that diagram with:

   python3 -c "
   import re
   text = open('<file>.md').read()
   blocks = re.findall(r'\x60\x60\x60mermaid\n(.*?)\n\x60\x60\x60', text, re.DOTALL)
   print(blocks[N-1])  # N = failed diagram number
   "

   Fix the syntax, re-run.

Phase 6 — Commit

git add <file>.md <file>.pdf
git commit -m "docs: add <name> roadmap with N concepts

- N concepts across M batches
- <key features>
- Generated PDF with all K mermaid diagrams rendered"

Conventions

Concept numbering

• Sequential within a roadmap: C0, C1, ..., C36
• New concepts from blending get the next available numbers (e.g., C31–C36 for TiP)
• Batch headers: # BATCH N — LAYER X: NAME (Concepts A–B)

Mermaid rules

• Always --> for directed edges (NEVER -> or Unicode →)
• Node labels: ASCII only inside ["..."] (no emoji, no Unicode arrows)
• <br/> for line breaks inside labels — this is fine
• style NODE fill:#color,stroke:#color for coloring
• Test render before PDF: the convert script catches errors, but fixing pre-emptively saves iterations

Code rules

• All code in Write sections must be runnable Python (not pseudocode)
• Include import statements
• Include if __name__ or module path for direct execution
• Reference real APIs from the actual lab notebooks (verified in Phase 1)
• Use Qwen3-0.6B config numbers where relevant (verified from HF config.json)

Commit messages

• Conventional commits: feat(scope):, fix(scope):, docs(scope):
• For roadmap files: docs: add <name> roadmap with N concepts
• For fixes: fix(mermaid): correct edge syntax in diagram N

Current roadmaps

File	Concepts	Source courses	Feeds into
zeroserve-in-public.md	101 (C0–C100)	Practical LLMOps book + nanoGPT + nano-vllm	ZeroServe build repo
llm-lab.md	37 (C0–C36)	PyTorch Certificate (87h) + Transformers in Practice (11h)	zeroserve-in-public.md

FORMAT-CONCEPT-BOOK.md

FORMAT.md — Per-Concept Template

Every concept in this roadmap follows this exact structure. Aim for ~80 lines.

## Concept N — Title

**Goal:** One sentence. What you achieve by the end.
**Why:** One sentence. Why this matters in the bigger picture.

**Read:**
- `book` §X.Y "Section title" (lines ~NNNN–NNNN)
- `tutorial/CONCEPT.md` §section
- `reference/path/file.py` — what to look for
- Run: `cd ~/workspace/tutorials/llm && uv run python name.py`
- Visualize: open `tutorials/llm/name.html`

**Search:**
- Keywords: "search terms for Google/YouTube"
- Paper: Title (arXiv:XXXX.XXXXX)
- Docs: link or doc page name

**Write:**
- File: `zeroserve/path/to/file.py`
- Full code block (runnable, typed, documented)
- Or: edit instructions for an existing file

**Test:**
```bash
uv run pytest tests/path/to/test.py -v
# Expected: describe what a passing test proves

Commit:

git add src/zeroserve/... tests/...
git commit -m "feat(scope): description"

Think:

• Mental model in 3-5 bullet points
• What to ponder while working through it
• Mermaid diagram if the concept has structure/flow/architecture:

graph TD
    A["Step 1"] --> B["Step 2"]
    B --> C["Insight"]
    style A fill:#color,stroke:#color

Loading

Q&A:

• Q: Interview question phrased as someone would ask it? A: Model answer. 2-4 sentences. Specific numbers when relevant.
• (2-3 Q&A pairs per concept)

Tips & Tricks:

• Gotcha: Common mistake and how to avoid it
• Shortcut: Easier way to verify/test/debug
• Common bug: What goes wrong and how to fix it
• (3-5 tips per concept)

---

## Rules

1. **Every section is required.** No skipping. If a concept is "publish-only," still include Read/Think/Q&A.
2. **Code blocks are real code.** Not pseudocode. Runnable, typed, with correct imports.
3. **Numbers are verified.** Parameter counts, shapes, memory sizes — all from Qwen3-0.6B config.json or the book.
4. **Mermaid for anything structural.** Data flow, architecture, state machines, timelines.
5. **Q&A answers include specific numbers.** "Qwen3-0.6B has 600,651,776 params" not "about 600M."
6. **Commit messages use conventional commits.** `feat(scope):`, `fix(scope):`, `test(scope):`, `docs(scope):`, `refactor(scope):`.
7. **Target ~80 lines per concept.** Range 60–120 is acceptable. Under 40 is a stub that needs expansion.