NathanJGaul avatar

dev-course-builder

Tools for creating educational content for programming and software development courses

Install

/plugin install dev-course-builder@njg-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add NathanJGaul/plugins.

Contents

Discovered from source

Skills 7

Content Templates

Structural templates for different types of programming educational content.

Chapter Template

# Chapter [X]: [Topic Name]

## Learning Objectives
By the end of this chapter, you will be able to:
- [Objective 1 - action verb + specific skill]
- [Objective 2]
- [Objective 3]

## Prerequisites
Before starting this chapter, you should understand:
- [Prerequisite 1]
- [Prerequisite 2]

## Introduction
[1-2 paragraphs motivating the topic]
- Why does a developer need to know this?
- What problems does it solve?
- How does it connect to previous chapters?

## [Section 1: Core Concept]

### The Problem
[What situation or challenge leads us to need this concept?]

### A First Look
```[language]
// Working code example showing the concept in action

Output:

[Actual output from running the code]

How It Works

[Break down the code piece by piece]

Key Points

  • [Important point 1]
  • [Important point 2]

Common Mistakes

// Code that demonstrates a common error

Error:

[Compiler or runtime error message]

Why this happens: [Explanation]

The fix:

// Corrected code

[Section 2: Deeper Understanding]

[Build on the basics with more detail]

[Section 3: Practical Application]

[Real-world use case with full implementation]

Exercises

Exercise 1: [Name] (Beginner)

[Clear problem statement]

Starter code:

// Scaffolded code for student to complete

Expected behavior:

[Sample input/output or test cases]

Exercise 2: [Name] (Intermediate)

[Problem requiring synthesis of concepts]

Exercise 3: [Name] (Challenge)

[Open-ended problem for advanced students]

Summary

  • Key takeaway 1
  • Key takeaway 2
  • Key takeaway 3

What's Next

[Preview of next chapter and how it builds on this]

Further Reading

  • [Resource 1 - official documentation]
  • [Resource 2 - deeper dive]

## Coding Exercise Template

```markdown
# Exercise: [Name]

**Difficulty:** [Beginner/Intermediate/Advanced]
**Estimated Time:** [X minutes]
**Concepts Practiced:** [Concept 1, Concept 2]

## Problem Statement

[Clear, unambiguous description of what to build]

## Requirements

1. [Specific requirement 1]
2. [Specific requirement 2]
3. [Specific requirement 3]

## Starter Code

```[language]
// Provided structure for student to complete
// TODO comments indicate where students should write code

Test Cases

// Tests to verify the solution
// Students can run these to check their work

Expected Output:

Test 1: PASS
Test 2: PASS
...

Hints (Use sparingly!)

Hint 1 [First gentle nudge]
Hint 2 [More specific guidance]

Solution

Click to reveal solution
// Complete working solution

Explanation: [Why this approach works]

Extension Challenges

For students who finish early:

  1. [Additional challenge 1]
  2. [Additional challenge 2]

## Project Template

```markdown
# Project: [Name]

**Duration:** [X hours/days]
**Difficulty:** [Intermediate/Advanced]
**Technologies:** [Language, libraries, tools]

## Overview

[1-2 paragraphs describing what students will build]

## Learning Goals

By completing this project, you will:
- [Goal 1]
- [Goal 2]
- [Goal 3]

## Project Specification

### Requirements

**Core Features (Required):**
1. [Feature 1]
2. [Feature 2]
3. [Feature 3]

**Stretch Goals (Optional):**
1. [Enhancement 1]
2. [Enhancement 2]

### Technical Constraints

- [Constraint 1 - e.g., must use standard library only]
- [Constraint 2 - e.g., no external dependencies]

## Getting Started

### Step 1: Project Setup
[Instructions for creating the project structure]

```bash
# Commands to set up the project

Step 2: [First Milestone]

[Guidance for first working piece]

Step 3: [Second Milestone]

[Building on the first piece]

Step 4: [Integration]

[Bringing pieces together]

Testing Your Project

// Test cases or testing instructions

Submission Requirements

  1. [What to submit]
  2. [Format requirements]
  3. [Documentation requirements]

Evaluation Criteria

CriterionWeightDescription
CorrectnessX%Code works as specified
Code QualityX%Readable, well-organized
TestingX%Adequate test coverage
DocumentationX%Clear comments and README

## Lab/Workshop Template

```markdown
# Lab [X]: [Topic Name]

**Duration:** [X minutes/hours]
**Format:** [Individual/Pair/Group]
**Environment:** [IDE, online compiler, etc.]

## Learning Objectives
- [Objective 1]
- [Objective 2]

---

## Part A: Guided Practice ([X minutes])

### Setup
```[language]
// Initial code to start with

Step 1: [First Concept]

[Explanation of what to do]

// Code to write or modify

Try it: Run the code and observe [specific output]

Step 2: [Building On]

[Next step in the progression]

Checkpoint

At this point, your code should:

  • [Criterion 1]
  • [Criterion 2]

Part B: Independent Challenges ([X minutes])

Work on these challenges independently or with a partner.

Challenge 1: [Name] (5-10 min)

[Problem statement]

Challenge 2: [Name] (10-15 min)

[Problem statement building on Challenge 1]

Challenge 3: [Name] (15-20 min)

[More complex integration challenge]

Challenge 4: [Name] (Extension)

[For students who finish early]


Wrap-up

Reflection Questions

  1. What was the most challenging part?
  2. What would you do differently next time?
  3. How could you extend what you built?

Key Takeaways

  • [Takeaway 1]
  • [Takeaway 2]

## Slides Template (Quarto RevealJS)

```markdown
---
title: "[Topic Name]"
author: "[Instructor Name]"
format:
  revealjs:
    theme: default
    code-line-numbers: true
    highlight-style: github
---

## Learning Objectives

- Objective 1
- Objective 2
- Objective 3

::: notes
Set expectations for what students will learn
:::

---

## Why This Matters

[Real-world motivation]

**In practice:** [Concrete example from industry]

::: notes
Hook students with relevant context
:::

---

## [Concept]: First Look

```{.[language]}
// Simple example code

::: {.fragment} Output:

[What this produces]

:::

::: notes Walk through each line :::


Let's Build It Up

:::: {.columns} ::: {.column width="50%"} Step 1:

// First piece

::: ::: {.column width="50%"} Step 2:

// Adding to it

::: ::::

::: notes Incremental code building :::


Common Mistake

// Code with a bug

::: {.fragment} Error:

[Error message]

:::

::: {.fragment} How to fix it: [Explanation] :::


Your Turn

Given this code:

// Code to analyze

Question: What will this output?

::: {.fragment} Answer: [Revealed answer] :::

::: notes Give students 1-2 minutes to think :::


Live Coding: [Task]

Let's build [feature] together.

[Space for live demonstration]

::: notes Key points to hit during live coding:

  • Point 1
  • Point 2 :::

Key Takeaways

  1. [Main point 1]
  2. [Main point 2]
  3. [Main point 3]

Next time: [Preview]


Questions?

[Contact info or office hours]


## Quiz/Assessment Template

```markdown
# Assessment: [Topic Name]

**Time Limit:** [X minutes]
**Open/Closed:** [Book, notes, IDE?]
**Total Points:** [XX]

---

## Part 1: Code Reading ([X points])

### Question 1 ([X points])
What does the following code output?

```[language]
// Code to trace

Answer: ____________

Question 2 ([X points])

This code has a bug. Identify it and explain how to fix it.

// Buggy code

Bug: ____________ Fix: ____________


Part 2: Code Writing ([X points])

Question 3 ([X points])

Write a function that [specification].

Function signature:

// Provided signature

Your code:

// Space for answer

Question 4 ([X points])

Implement [more complex task].

Requirements:

  • [Requirement 1]
  • [Requirement 2]

Part 3: Conceptual ([X points])

Question 5 ([X points])

Explain why [concept] is important in [context].

Question 6 ([X points])

Compare and contrast [approach A] and [approach B].


Answer Key (Instructor Only)

[Detailed answers and grading rubric]


## Usage Guidelines

### When to Use Each Template

- **Chapter**: Comprehensive coverage of a topic for self-study or reference
- **Coding Exercise**: Focused practice on specific skills
- **Project**: Larger, integrative work combining multiple concepts
- **Lab/Workshop**: Structured in-class hands-on session
- **Slides**: Support for lecture or live demonstration
- **Quiz/Assessment**: Evaluate student understanding

### Customization

These templates should be adapted based on:
- Target audience experience level
- Programming language and toolchain
- Course philosophy (framework vs. no-framework)
- Time available
- Prerequisites
- Learning environment (IDE, online, etc.)

Always reference the specific course profile for customization guidance.

Course Review Frameworks

Comprehensive frameworks and checklists for reviewing programming educational content.

Review Severity Levels

Use these severity levels to prioritize findings:

Critical (Must Fix)

Issues that make content incorrect, misleading, or harmful to learning:

  • Code that doesn't compile or produces wrong output
  • Factually incorrect explanations
  • Missing critical prerequisites
  • Security vulnerabilities in example code
  • Misleading simplifications that create misconceptions

Major (Should Fix)

Issues that significantly impact quality or learning effectiveness:

  • Inconsistent terminology or style
  • Unclear explanations for target audience
  • Missing important edge cases or pitfalls
  • Poor progression or scaffolding
  • Examples that don't follow best practices

Minor (Nice to Fix)

Issues that affect polish but not correctness or core learning:

  • Typos and grammatical errors
  • Formatting inconsistencies
  • Suboptimal code style choices
  • Missing "nice to have" content
  • Verbose or redundant explanations

Enhancement (Suggestions)

Opportunities to improve beyond current quality:

  • Additional examples or analogies
  • Better visual representations
  • Extended challenges for advanced students
  • Industry anecdotes or real-world connections
  • Alternative approaches worth mentioning

Code Review Checklist

Compilation & Execution

  • All code examples compile without errors
  • All code examples produce the stated output
  • Include directives and imports are present
  • Main functions or entry points are properly defined
  • Build/run instructions are accurate

Correctness

  • Logic is correct and bug-free
  • Edge cases are handled appropriately
  • Error examples actually demonstrate errors
  • Fixed versions actually fix the problems
  • Return values and types are correct

Style & Idioms

  • Code follows language-specific conventions
  • Naming is consistent and meaningful
  • Comments explain "why" not "what"
  • Code matches course style guidelines
  • Modern language features used appropriately

Best Practices

  • No deprecated features or patterns
  • Proper error handling where appropriate
  • Memory management follows course approach
  • Resource cleanup is demonstrated
  • Security considerations addressed

Presentation

  • Code is properly formatted and indented
  • Syntax highlighting is correct
  • Output matches actual program output
  • Error messages are realistic
  • Line numbers are helpful (if used)

Technical Accuracy Checklist

Conceptual Correctness

  • Definitions are accurate and precise
  • Analogies are appropriate and don't mislead
  • Simplifications are acknowledged
  • Mental models align with reality
  • Technical claims are verifiable

Terminology

  • Terms are used correctly
  • Jargon is defined before use
  • Acronyms are expanded on first use
  • Naming matches language conventions
  • Consistent terminology throughout

Explanations

  • Cause and effect are correctly linked
  • Sequence of events is accurate
  • Performance claims are correct
  • Comparisons are fair and accurate
  • Limitations are acknowledged

Currency

  • Information reflects current standards
  • Language version is appropriate
  • Deprecated features are noted
  • Best practices are up-to-date
  • Tools and libraries are current

Pedagogical Quality Checklist

Audience Appropriateness

  • Complexity matches target audience
  • Prerequisites are realistic
  • Pacing is appropriate
  • Depth is suitable for level
  • Examples resonate with audience

Scaffolding

  • Concepts build incrementally
  • New concepts connect to prior knowledge
  • Sufficient stepping stones provided
  • Not too many concepts at once
  • Guidance gradually decreases

Clarity

  • Explanations are understandable
  • Abstract concepts are made concrete
  • Multiple representations used
  • Assumptions are explicit
  • Transitions are smooth

Engagement

  • Content motivates learning
  • Real-world relevance is clear
  • Active learning opportunities exist
  • Examples are interesting
  • Tone is appropriate

Assessment Alignment

  • Exercises match learning objectives
  • Difficulty progression is appropriate
  • Practice opportunities are sufficient
  • Feedback mechanisms exist
  • Self-check opportunities provided

Content Completeness Checklist

Coverage

  • All learning objectives addressed
  • No gaps in concept chain
  • Edge cases discussed
  • Common mistakes covered
  • Pitfalls and gotchas explained

Depth

  • Sufficient detail for understanding
  • "Why" explained, not just "how"
  • Trade-offs discussed
  • Alternative approaches mentioned
  • Limitations acknowledged

Practice

  • Enough exercises for mastery
  • Range of difficulty levels
  • Different types of practice
  • Extension opportunities exist
  • Self-assessment possible

Support Materials

  • Prerequisites clearly stated
  • Summary/review provided
  • Further reading suggested
  • Solutions or hints available
  • Reference material accessible

Consistency Checklist

Terminology

  • Same terms used for same concepts
  • Consistent use of technical language
  • Abbreviations used consistently
  • Names match across files
  • Cross-references are accurate

Style

  • Code style matches course standards
  • Writing voice is consistent
  • Formatting follows templates
  • Heading structure is uniform
  • Callout boxes used consistently

Presentation

  • Visual style is uniform
  • Diagram conventions consistent
  • Code block formatting matches
  • Emphasis conventions consistent
  • Link formatting standardized

Approach

  • Pedagogical approach is consistent
  • Complexity level is uniform
  • Exercise difficulty scales consistently
  • Explanation depth is consistent
  • Philosophy matches throughout

Structure & Organization Checklist

Logical Flow

  • Prerequisites come before dependents
  • Complexity increases appropriately
  • Related topics are grouped
  • Transitions are logical
  • Flow makes sense to learner

Dependencies

  • No forward references to unlearned content
  • Prerequisites are clearly identified
  • Dependency chain is respected
  • Review happens before advancement
  • Callbacks reference actual earlier content

Organization

  • Clear hierarchical structure
  • Consistent sectioning
  • Appropriate granularity
  • Balanced section lengths
  • Navigation aids present

Integration

  • Parts work together as a whole
  • Assessments match content
  • Labs reinforce chapters
  • Projects synthesize learning
  • Everything serves learning objectives

Course-Wide Review Framework

Course Architecture Review

  1. Learning Objectives Analysis

    • Are objectives measurable and achievable?
    • Do they align with audience needs?
    • Are they covered by course content?
    • Are they assessed appropriately?
  2. Prerequisite Analysis

    • Are prerequisites clearly stated?
    • Are they realistic for target audience?
    • Is prerequisite knowledge actually needed?
    • Are prerequisites tested/reviewed?
  3. Topic Sequencing

    • Is the order logical?
    • Are dependencies respected?
    • Could anything be reordered for better learning?
    • Are review/consolidation points appropriate?
  4. Scope Assessment

    • Is scope appropriate for duration?
    • Are there gaps in coverage?
    • Is there unnecessary content?
    • Is depth consistent across topics?

Cross-Module Consistency Review

  1. Terminology Audit

    • Collect all defined terms
    • Check for inconsistent definitions
    • Verify consistent usage
    • Check first-use introductions
  2. Code Style Audit

    • Check naming conventions
    • Verify formatting consistency
    • Confirm idiom usage
    • Validate comment style
  3. Structural Audit

    • Compare section structures
    • Check exercise formats
    • Verify callout usage
    • Confirm heading patterns
  4. Cross-Reference Audit

    • Verify all internal links
    • Check prerequisite references
    • Validate callback accuracy
    • Confirm continuation references

Content Quality Review

  1. Code Verification Protocol

    • Extract all code examples
    • Verify compilation/execution
    • Check stated outputs match
    • Validate error examples
  2. Explanation Quality Assessment

    • Read from student perspective
    • Identify confusing passages
    • Check logical completeness
    • Assess analogy effectiveness
  3. Exercise Evaluation

    • Test exercise feasibility
    • Verify solution correctness
    • Assess difficulty calibration
    • Check specification clarity
  4. Assessment Alignment Check

    • Map assessments to objectives
    • Verify coverage completeness
    • Check difficulty appropriateness
    • Assess fairness and clarity

Review Report Template

# Course Review Report: [Course Name]

**Reviewer:** [Name]
**Date:** [Date]
**Scope:** [What was reviewed]
**Focus Areas:** [Specific focus if any]

## Executive Summary

### Overall Assessment
[2-3 sentence summary of course quality]

### Key Strengths
1. [Strength 1]
2. [Strength 2]
3. [Strength 3]

### Priority Action Items
1. [Critical item 1]
2. [Critical item 2]
3. [Critical item 3]

## Detailed Findings

### Critical Issues
| ID | Location | Issue | Recommendation |
|----|----------|-------|----------------|
| C1 | [file:line] | [description] | [fix] |

### Major Issues
| ID | Location | Issue | Recommendation |
|----|----------|-------|----------------|
| M1 | [file:line] | [description] | [fix] |

### Minor Issues
| ID | Location | Issue | Recommendation |
|----|----------|-------|----------------|
| m1 | [file:line] | [description] | [fix] |

### Enhancement Opportunities
| ID | Location | Suggestion | Benefit |
|----|----------|------------|---------|
| E1 | [area] | [suggestion] | [benefit] |

## Category Assessments

### Code Correctness: [Score/5]
[Summary and key findings]

### Technical Accuracy: [Score/5]
[Summary and key findings]

### Pedagogical Quality: [Score/5]
[Summary and key findings]

### Completeness: [Score/5]
[Summary and key findings]

### Consistency: [Score/5]
[Summary and key findings]

### Structure: [Score/5]
[Summary and key findings]

## Recommendations

### Immediate Actions (Critical)
1. [Action with specific steps]
2. [Action with specific steps]

### Short-Term Improvements (Major)
1. [Improvement with approach]
2. [Improvement with approach]

### Long-Term Enhancements
1. [Enhancement opportunity]
2. [Enhancement opportunity]

## Appendices

### A: Code Verification Results
[Details of code testing]

### B: Terminology Index
[List of terms and usage]

### C: Cross-Reference Map
[Dependency and reference tracking]

Quick Review Guides

Single Chapter Review (30-60 min)

  1. Read through completely for comprehension
  2. Check all code examples compile/run
  3. Verify outputs match stated results
  4. Assess clarity for target audience
  5. Check consistency with course standards
  6. List top 3 improvements

Exercise Review (15-30 min)

  1. Solve exercise without looking at solution
  2. Compare approach to provided solution
  3. Verify test cases are correct and sufficient
  4. Assess difficulty for stated level
  5. Check specification clarity

Full Course Structure Review (2-4 hours)

  1. Map all learning objectives
  2. Trace dependency graph
  3. Identify terminology across all modules
  4. Check coverage completeness
  5. Assess balance and pacing
  6. Create prioritized improvement list

Code Audit (1-2 hours per module)

  1. Extract all code blocks
  2. Compile/run each example
  3. Verify outputs
  4. Check style consistency
  5. Identify best practice violations
  6. Document all issues with locations

Common Issues Catalog

Code Issues

  • Missing includes/imports - Code won't compile
  • Hardcoded paths - Won't work on other systems
  • Undeclared variables - Typos or missing setup
  • Wrong output format - Stated output doesn't match actual
  • Deprecated features - Using old patterns

Pedagogical Issues

  • Assumed knowledge - Uses concepts not yet taught
  • Too many concepts - Cognitive overload
  • Insufficient scaffolding - Jump too large
  • Missing motivation - "Why" not explained
  • Wrong level - Too simple or complex for audience

Consistency Issues

  • Terminology drift - Same thing called different names
  • Style changes - Inconsistent code formatting
  • Structure variation - Different organization patterns
  • Tone shifts - Voice changes between sections

Completeness Issues

  • Missing edge cases - Only happy path shown
  • No error examples - Mistakes not demonstrated
  • Gaps in coverage - Topics not fully explained
  • Insufficient practice - Not enough exercises

Quality Scoring Rubric

5 - Excellent

Content is publication-ready. No errors, clear explanations, perfect alignment with course standards, exemplary pedagogy.

4 - Good

Minor issues only. Solid content that needs light polishing. Achieves learning objectives effectively.

3 - Adequate

Some notable issues but fundamentally sound. Needs revision but not rewrite. Learning objectives achievable with effort.

2 - Needs Work

Significant issues affecting learning outcomes. Major revision required. Core content may be salvageable.

1 - Inadequate

Fundamental problems throughout. Likely requires rewrite. Not suitable for learners in current state.

Programming and Development Teaching Principles

General pedagogical principles for teaching programming, software development, and systems programming.

Core Teaching Philosophy

1. Code-First Learning

Programming is learned by writing and running code, not just reading about it:

  • Provide working, compilable code examples
  • Show the complete build-run-output cycle
  • Encourage experimentation and modification
  • Build confidence through successful compilation and execution
  • Learn from compiler errors and runtime failures

2. Mental Model Development

Help students build accurate mental models of how code executes:

  • Visualize memory layout and data flow
  • Trace execution step by step
  • Understand the stack, heap, and program lifecycle
  • Connect high-level code to low-level behavior
  • Make the "invisible" visible through diagrams and examples

3. Incremental Complexity

Build understanding step by step:

  • Start with minimal working examples
  • Introduce one concept at a time
  • Build on previously learned patterns
  • Avoid overwhelming with edge cases upfront
  • Progress from "what" to "why" to "when"

4. Error-Driven Learning

Compiler errors and bugs are learning opportunities:

  • Show common errors and how to interpret them
  • Teach debugging strategies and tools
  • Normalize mistakes as part of learning
  • Build pattern recognition for error types
  • Connect symptoms to underlying causes

5. Professional Practice Integration

Connect learning to real-world development:

  • Version control from the start
  • Testing as a development tool
  • Code review and readability
  • Documentation and comments
  • Build systems and toolchains

Content Structure Guidelines

For Chapters

  1. Start with working code - Show what success looks like
  2. Explain the building blocks - Break down each component
  3. Introduce variations - Show different ways to achieve similar goals
  4. Address common pitfalls - What can go wrong and why
  5. Practice with exercises - Hands-on application
  6. Connect to bigger picture - How this fits into larger programs

For Code Examples

  1. Complete and runnable - No pseudo-code without real implementation
  2. Well-commented - Explain non-obvious parts
  3. Idiomatic - Follow language conventions and best practices
  4. Progressive - Build from simple to complex
  5. Error examples included - Show what broken code looks like

For Exercises

  1. Clear specifications - Unambiguous requirements
  2. Scaffolded difficulty - From guided to independent
  3. Real compilation required - Not just "write on paper"
  4. Testing provided - Help students verify their solutions
  5. Extension opportunities - For students who finish early

For Slides/Presentations

  1. Live coding focus - Demonstrate in real-time
  2. Build incrementally - Add code piece by piece
  3. Show compiler output - Make the feedback loop visible
  4. Include think-alouds - Model problem-solving process
  5. Interactive elements - Have students predict outcomes

Level Differentiation

Beginner Developers

  • Assume minimal programming experience
  • Explain every keyword and symbol
  • Provide extensive scaffolding
  • Focus on "making it work" before optimization
  • Use simple, relatable examples
  • Celebrate small victories

Intermediate Developers

  • Assume familiarity with basic concepts
  • Focus on language-specific features
  • Introduce design patterns and idioms
  • Compare with other languages they know
  • Include more complex real-world examples
  • Emphasize code organization

Advanced Developers

  • Assume strong foundation
  • Focus on performance and optimization
  • Deep dive into language internals
  • Advanced patterns and techniques
  • System-level understanding
  • Research and industry best practices

Language-Specific Guidance

For Systems Languages (C, C++, Rust)

  • Memory management is central - Teach allocation, deallocation, ownership
  • Compilation matters - Explain the build process
  • Performance awareness - Discuss efficiency implications
  • Safety considerations - Bounds checking, undefined behavior
  • Low-level concepts - Pointers, references, memory layout

For Managed Languages (Python, Java, C#)

  • Abstraction appreciation - What the runtime handles
  • When to go lower - Understanding what's "under the hood"
  • Framework navigation - Working with large ecosystems
  • Performance considerations - Garbage collection, JIT

For Web Development Languages (JavaScript, TypeScript)

  • Async model understanding - Event loop, callbacks, promises
  • Browser vs Node.js - Different runtime environments
  • Toolchain complexity - Build tools, bundlers, transpilers
  • Ecosystem navigation - Package management, dependencies

Framework Inclusion Guidelines

When Teaching WITHOUT Frameworks

  • Focus on fundamentals - Raw language and standard library
  • Build things from scratch - Understand underlying mechanisms
  • Appreciate what frameworks do - Creates motivation for later
  • Complete control - Every line is intentional and understood

When Teaching WITH Frameworks

  • Framework as amplifier - Build on fundamentals
  • Convention understanding - Why the framework works this way
  • Escape hatches - How to go beyond the framework when needed
  • Multiple frameworks - Principles transfer between tools

Assessment Philosophy

Code-Based Assessment

  • Compilation required - No partial credit for non-compiling code
  • Automated testing - Objective evaluation of correctness
  • Code review component - Style, readability, efficiency
  • Debugging exercises - Find and fix bugs in given code

Understanding Assessment

  • Trace exercises - What does this code output?
  • Error prediction - What's wrong with this code?
  • Design questions - How would you structure this?
  • Comparison questions - Trade-offs between approaches

Common Pitfalls to Avoid

  1. Too abstract too soon - Build intuition before theory
  2. Perfect code only - Show messy first drafts too
  3. Ignoring errors - Errors are teaching moments
  4. One right way - Usually multiple valid approaches
  5. Skipping the boring parts - Setup, configuration matter
  6. Assuming IDE familiarity - Teach the tools too
  7. No debugging practice - Essential professional skill
  8. Disconnected theory - Always connect to practical use

Sandbox Templates - Language-Specific Docker Configurations

Pre-configured Dockerfile templates for different programming languages with all necessary tools for compiling, testing, linting, and debugging course code.

Template Selection

Choose the appropriate template based on the course's primary language:

LanguageTemplateBase ImageSize
C++cpp-sandboxUbuntu 24.04~1.5GB
Rustrust-sandboxRust Official~1.2GB
Pythonpython-sandboxPython 3.12~800MB
Gogo-sandboxGo Official~900MB
Cc-sandboxUbuntu 24.04~1.2GB
Multi-languagemulti-sandboxUbuntu 24.04~2.5GB

C++ Sandbox Template

For C++ courses (C++17/20/23 support).

Dockerfile

# C++ Development Sandbox
# Supports: C++17, C++20, C++23 (partial)
# Tools: GCC 13, Clang 17, CMake, GDB, Valgrind, clang-tidy, cppcheck

FROM ubuntu:24.04

LABEL maintainer="course-builder"
LABEL description="C++ development sandbox for course materials"

# Prevent interactive prompts
ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=UTC

# Install compilers and build tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    # Compilers
    g++-13 \
    gcc-13 \
    clang-17 \
    clang++-17 \
    # Build tools
    cmake \
    ninja-build \
    make \
    # Debugging
    gdb \
    lldb-17 \
    valgrind \
    # Linting
    clang-tidy-17 \
    clang-format-17 \
    cppcheck \
    # Testing frameworks
    libgtest-dev \
    libgmock-dev \
    catch2 \
    # Utilities
    git \
    curl \
    wget \
    unzip \
    pkg-config \
    # Cleanup
    && rm -rf /var/lib/apt/lists/*

# Set up alternatives for gcc/g++
RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 \
    && update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 100 \
    && update-alternatives --install /usr/bin/clang clang /usr/bin/clang-17 100 \
    && update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-17 100 \
    && update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-17 100 \
    && update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-17 100

# Build and install Google Test (if not available as package)
RUN cd /usr/src/gtest && cmake . && make && cp lib/*.a /usr/lib/

# Create non-root user for safety
RUN useradd -m -s /bin/bash sandbox
USER sandbox

WORKDIR /workspace

# Default command keeps container running
CMD ["tail", "-f", "/dev/null"]

Common Commands

# Compile with GCC (C++20)
g++ -std=c++20 -Wall -Wextra -Werror -o /tmp/prog source.cpp

# Compile with Clang (C++20)
clang++ -std=c++20 -Wall -Wextra -Werror -o /tmp/prog source.cpp

# Compile with sanitizers
g++ -std=c++20 -fsanitize=address,undefined -g -o /tmp/prog source.cpp

# Run clang-tidy
clang-tidy source.cpp -- -std=c++20

# Run cppcheck
cppcheck --enable=all --std=c++20 source.cpp

# Debug with GDB
gdb /tmp/prog

# Memory check with Valgrind
valgrind --leak-check=full /tmp/prog

# CMake build
cmake -B build -G Ninja && cmake --build build

# Run tests
ctest --test-dir build --output-on-failure

Rust Sandbox Template

For Rust courses (stable and nightly support).

Dockerfile

# Rust Development Sandbox
# Supports: Stable, Beta, Nightly Rust
# Tools: rustc, cargo, clippy, rustfmt, rust-analyzer, miri

FROM rust:1.83-bookworm

LABEL maintainer="course-builder"
LABEL description="Rust development sandbox for course materials"

# Install additional toolchains
RUN rustup component add \
    clippy \
    rustfmt \
    rust-src \
    rust-analyzer

# Install nightly for miri and advanced features
RUN rustup toolchain install nightly \
    && rustup component add --toolchain nightly miri rust-src

# Install useful cargo extensions
RUN cargo install \
    cargo-watch \
    cargo-expand \
    cargo-audit \
    cargo-outdated \
    cargo-tarpaulin

# Install system dependencies for common crates
RUN apt-get update && apt-get install -y --no-install-recommends \
    pkg-config \
    libssl-dev \
    gdb \
    lldb \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN useradd -m -s /bin/bash sandbox
USER sandbox

# Set up cargo home for non-root user
ENV CARGO_HOME=/home/sandbox/.cargo
ENV PATH="${CARGO_HOME}/bin:${PATH}"

WORKDIR /workspace

CMD ["tail", "-f", "/dev/null"]

Common Commands

# Compile single file
rustc -o /tmp/prog source.rs

# Build with cargo
cargo build

# Build release
cargo build --release

# Run
cargo run

# Run tests
cargo test

# Run specific test
cargo test test_name

# Lint with clippy
cargo clippy -- -D warnings

# Format code
cargo fmt

# Check without building
cargo check

# Expand macros
cargo expand

# Run with miri (memory safety)
cargo +nightly miri run

# Run tests with miri
cargo +nightly miri test

# Security audit
cargo audit

# Test coverage
cargo tarpaulin

Python Sandbox Template

For Python courses (3.12+ with type checking and testing tools).

Dockerfile

# Python Development Sandbox
# Supports: Python 3.12
# Tools: pytest, mypy, ruff, black, coverage, ipython

FROM python:3.12-slim-bookworm

LABEL maintainer="course-builder"
LABEL description="Python development sandbox for course materials"

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python development tools
RUN pip install --no-cache-dir \
    # Testing
    pytest \
    pytest-cov \
    pytest-xdist \
    pytest-mock \
    hypothesis \
    # Type checking
    mypy \
    # Linting and formatting
    ruff \
    black \
    isort \
    # Interactive
    ipython \
    # Documentation
    pdoc \
    # Debugging
    pdbpp \
    # Utilities
    rich \
    typer

# Create non-root user
RUN useradd -m -s /bin/bash sandbox
USER sandbox

WORKDIR /workspace

# Set Python to unbuffered mode
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

CMD ["tail", "-f", "/dev/null"]

Common Commands

# Run script
python3 script.py

# Run with unbuffered output
python3 -u script.py

# Run module
python3 -m module_name

# Run tests
python3 -m pytest -v

# Run tests with coverage
python3 -m pytest --cov=. --cov-report=term-missing

# Run parallel tests
python3 -m pytest -n auto

# Type check
mypy script.py

# Type check strict
mypy --strict script.py

# Lint with ruff
ruff check .

# Fix linting issues
ruff check --fix .

# Format with black
black script.py

# Check formatting
black --check script.py

# Sort imports
isort script.py

# Interactive REPL
ipython

Go Sandbox Template

For Go courses (latest stable version).

Dockerfile

# Go Development Sandbox
# Supports: Go 1.23+
# Tools: go, gofmt, golint, staticcheck, delve

FROM golang:1.23-bookworm

LABEL maintainer="course-builder"
LABEL description="Go development sandbox for course materials"

# Install additional tools
RUN go install golang.org/x/lint/golint@latest \
    && go install honnef.co/go/tools/cmd/staticcheck@latest \
    && go install github.com/go-delve/delve/cmd/dlv@latest \
    && go install golang.org/x/tools/cmd/goimports@latest \
    && go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gdb \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN useradd -m -s /bin/bash sandbox
USER sandbox

# Set up Go paths for non-root user
ENV GOPATH=/home/sandbox/go
ENV PATH="${GOPATH}/bin:${PATH}"

WORKDIR /workspace

CMD ["tail", "-f", "/dev/null"]

Common Commands

# Run single file
go run main.go

# Build
go build -o /tmp/prog .

# Build with race detection
go build -race -o /tmp/prog .

# Run tests
go test ./...

# Run tests verbose
go test -v ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

# Run benchmarks
go test -bench=. ./...

# Format code
gofmt -w .

# Format and organize imports
goimports -w .

# Lint
golint ./...

# Static analysis
staticcheck ./...

# Comprehensive lint
golangci-lint run

# Debug with delve
dlv debug

# Vet code
go vet ./...

C Sandbox Template

For C courses (C11/C17/C23 support).

Dockerfile

# C Development Sandbox
# Supports: C11, C17, C23
# Tools: GCC 13, Clang 17, Make, GDB, Valgrind

FROM ubuntu:24.04

LABEL maintainer="course-builder"
LABEL description="C development sandbox for course materials"

ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=UTC

RUN apt-get update && apt-get install -y --no-install-recommends \
    # Compilers
    gcc-13 \
    clang-17 \
    # Build tools
    make \
    cmake \
    ninja-build \
    # Debugging
    gdb \
    lldb-17 \
    valgrind \
    # Linting
    clang-tidy-17 \
    cppcheck \
    # Utilities
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Set up alternatives
RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 \
    && update-alternatives --install /usr/bin/clang clang /usr/bin/clang-17 100 \
    && update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-17 100

# Create non-root user
RUN useradd -m -s /bin/bash sandbox
USER sandbox

WORKDIR /workspace

CMD ["tail", "-f", "/dev/null"]

Common Commands

# Compile with GCC (C17)
gcc -std=c17 -Wall -Wextra -Werror -o /tmp/prog source.c

# Compile with Clang
clang -std=c17 -Wall -Wextra -Werror -o /tmp/prog source.c

# Compile with debugging symbols
gcc -std=c17 -g -O0 -o /tmp/prog source.c

# Compile with sanitizers
gcc -std=c17 -fsanitize=address,undefined -g -o /tmp/prog source.c

# Run cppcheck
cppcheck --enable=all --std=c17 source.c

# Debug with GDB
gdb /tmp/prog

# Memory check
valgrind --leak-check=full --show-leak-kinds=all /tmp/prog

# Track origins of uninitialized values
valgrind --track-origins=yes /tmp/prog

Multi-Language Sandbox Template

For courses covering multiple languages or comparisons.

Dockerfile

# Multi-Language Development Sandbox
# Supports: C, C++, Python, Go, Rust
# Full toolchain for each language

FROM ubuntu:24.04

LABEL maintainer="course-builder"
LABEL description="Multi-language development sandbox for course materials"

ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=UTC

# Install C/C++ tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc-13 g++-13 clang-17 clang++-17 \
    cmake ninja-build make \
    gdb lldb-17 valgrind \
    clang-tidy-17 clang-format-17 cppcheck \
    libgtest-dev catch2 \
    && rm -rf /var/lib/apt/lists/*

# Install Python
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.12 python3.12-venv python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Install Python tools
RUN pip3 install --break-system-packages --no-cache-dir \
    pytest pytest-cov mypy ruff black ipython

# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
    && . /root/.cargo/env \
    && rustup component add clippy rustfmt rust-src

# Install Go
RUN curl -LO https://go.dev/dl/go1.23.4.linux-amd64.tar.gz \
    && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz \
    && rm go1.23.4.linux-amd64.tar.gz

# Set up paths
ENV PATH="/usr/local/go/bin:/root/.cargo/bin:${PATH}"
ENV GOPATH="/root/go"

# Set up alternatives
RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 \
    && update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 100 \
    && update-alternatives --install /usr/bin/python python /usr/bin/python3.12 100

# Install Go tools
RUN go install golang.org/x/lint/golint@latest \
    && go install honnef.co/go/tools/cmd/staticcheck@latest

# Create non-root user
RUN useradd -m -s /bin/bash sandbox \
    && cp -r /root/.cargo /home/sandbox/ \
    && chown -R sandbox:sandbox /home/sandbox/.cargo
USER sandbox

ENV PATH="/home/sandbox/.cargo/bin:/usr/local/go/bin:${PATH}"

WORKDIR /workspace

CMD ["tail", "-f", "/dev/null"]

Sandbox Directory Structure

When a sandbox is set up, the following structure is created in the course directory:

course-name/
├── .sandbox/
│   ├── Dockerfile          # Language-specific Dockerfile
│   ├── docker-compose.yml  # Optional: for complex setups
│   ├── .dockerignore       # Files to exclude from build
│   └── scripts/
│       ├── setup.sh        # Post-creation setup script
│       ├── validate.sh     # Code validation script
│       └── cleanup.sh      # Cleanup script
├── chapters/
├── exercises/
├── projects/
└── ...

docker-compose.yml (Optional)

version: '3.8'

services:
  sandbox:
    build:
      context: .
      dockerfile: .sandbox/Dockerfile
    container_name: course-sandbox-${COURSE_ID:-default}
    volumes:
      - ..:/workspace
    working_dir: /workspace
    stdin_open: true
    tty: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'
    network_mode: none

.dockerignore

# Ignore build artifacts
build/
target/
__pycache__/
*.pyc
*.o
*.a
*.so

# Ignore IDE files
.idea/
.vscode/
*.swp
*.swo

# Ignore git
.git/
.gitignore

# Ignore large files
*.pdf
*.zip
*.tar.gz

Customization Guidelines

Adding Course-Specific Dependencies

Extend the base template with additional packages:

# Base template
FROM course-sandbox-cpp:latest

# Add course-specific libraries
RUN apt-get update && apt-get install -y --no-install-recommends \
    libboost-all-dev \
    libsqlite3-dev \
    && rm -rf /var/lib/apt/lists/*

Environment Variables

Set course-specific environment variables:

# Compiler settings
ENV CXX=g++
ENV CC=gcc
ENV CXXFLAGS="-std=c++20 -Wall -Wextra"

# Course-specific paths
ENV COURSE_LIB_PATH=/workspace/lib
ENV COURSE_INCLUDE_PATH=/workspace/include

Mount Points

Configure additional volume mounts for shared resources:

docker run -d \
  --name course-sandbox-cpp-fundamentals \
  -v "$(pwd):/workspace" \
  -v "/shared/test-data:/data:ro" \
  -v "/shared/reference:/reference:ro" \
  course-sandbox-cpp:latest

Course Sandbox - Docker-Based Code Execution

Isolated development environment for safely executing, testing, linting, and debugging code examples in course materials. Each course shares a single persistent Docker container as its sandbox.

Overview

The sandbox system provides:

  • Isolated Execution: All code runs in Docker containers, protecting the host system
  • Persistent Environment: One container per course, maintaining state across sessions
  • Language Support: Pre-configured environments for C++, Rust, Python, Go, and more
  • Full Toolchain: Compilers, linters, debuggers, and test frameworks pre-installed
  • Volume Mounting: Course files are mounted for easy access and modification

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Host System                             │
│                                                              │
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │  Course Files   │    │     Docker Container            │ │
│  │                 │◄──►│  ┌─────────────────────────────┐│ │
│  │ /courses/       │    │  │  /workspace (mounted)       ││ │
│  │   cpp-fund/     │    │  │    - chapters/              ││ │
│  │   rust-intro/   │    │  │    - exercises/             ││ │
│  │                 │    │  │    - projects/              ││ │
│  └─────────────────┘    │  │    - .sandbox/              ││ │
│                         │  └─────────────────────────────┘│ │
│                         │                                  │ │
│                         │  Tools: gcc, clang, gdb, lldb   │ │
│                         │  Linters: clang-tidy, cppcheck  │ │
│                         │  Test: gtest, catch2            │ │
│                         └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Container Lifecycle

Container Naming Convention

course-sandbox-{course-id}

Example: course-sandbox-cpp-fundamentals

Container States

  1. Not Created: No sandbox exists for the course
  2. Stopped: Sandbox exists but is not running
  3. Running: Sandbox is active and ready for commands

Persistence Model

  • Containers are created once and reused for the entire course
  • Course files are mounted as volumes (changes persist)
  • Container state (installed packages, compiled binaries) persists
  • Containers can be stopped when not in use to save resources
  • Full reset available via container rebuild

Sandbox Operations

Check Sandbox Status

# Check if container exists and its state
docker ps -a --filter "name=course-sandbox-{course-id}" --format "{{.Names}}: {{.Status}}"

# Check if running
docker inspect -f '{{.State.Running}}' course-sandbox-{course-id}

Create Sandbox

# Build image from course-specific Dockerfile
docker build -t course-sandbox-{course-id}:latest -f .sandbox/Dockerfile .

# Create and start container with mounted workspace
docker run -d \
  --name course-sandbox-{course-id} \
  -v "$(pwd):/workspace" \
  -w /workspace \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --memory=2g \
  --cpus=2 \
  --network=none \
  course-sandbox-{course-id}:latest \
  tail -f /dev/null

Execute Commands in Sandbox

# Run a command in the sandbox
docker exec course-sandbox-{course-id} <command>

# Run with timeout (prevents infinite loops)
timeout 30s docker exec course-sandbox-{course-id} <command>

# Run interactively (for debugging)
docker exec -it course-sandbox-{course-id} /bin/bash

Stop/Start Sandbox

# Stop to save resources
docker stop course-sandbox-{course-id}

# Start when needed again
docker start course-sandbox-{course-id}

Reset Sandbox

# Remove and recreate for clean slate
docker rm -f course-sandbox-{course-id}
# Then run create steps again

Code Execution Patterns

Compile and Run (C++)

# Compile
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -Wall -Wextra -Werror -o /tmp/prog /workspace/example.cpp

# Run
docker exec course-sandbox-cpp-fundamentals /tmp/prog

# Or combined with timeout
docker exec course-sandbox-cpp-fundamentals \
  bash -c "g++ -std=c++20 -Wall -Wextra -o /tmp/prog /workspace/example.cpp && timeout 10s /tmp/prog"

Compile and Run (Rust)

# Compile
docker exec course-sandbox-rust-intro \
  rustc -o /tmp/prog /workspace/example.rs

# Run
docker exec course-sandbox-rust-intro /tmp/prog

# Or with cargo
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace/project && cargo run"

Run Script (Python)

docker exec course-sandbox-python-basics \
  timeout 10s python3 /workspace/example.py

Run Tests

# C++ with Google Test
docker exec course-sandbox-cpp-fundamentals \
  bash -c "cd /workspace && cmake -B build && cmake --build build && ctest --test-dir build --output-on-failure"

# Rust with cargo
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo test"

# Python with pytest
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest -v"

Lint Code

# C++ with clang-tidy
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy /workspace/example.cpp -- -std=c++20

# C++ with cppcheck
docker exec course-sandbox-cpp-fundamentals \
  cppcheck --enable=all --std=c++20 /workspace/example.cpp

# Rust with clippy
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo clippy -- -D warnings"

# Python with ruff
docker exec course-sandbox-python-basics \
  ruff check /workspace/example.py

Debug Code

# Start GDB session (interactive)
docker exec -it course-sandbox-cpp-fundamentals \
  gdb /tmp/prog

# Run with sanitizers (compile with flags)
docker exec course-sandbox-cpp-fundamentals \
  bash -c "g++ -std=c++20 -fsanitize=address,undefined -g -o /tmp/prog /workspace/example.cpp && /tmp/prog"

# Valgrind memory check
docker exec course-sandbox-cpp-fundamentals \
  valgrind --leak-check=full /tmp/prog

Security Constraints

All sandbox containers run with restricted permissions:

ConstraintSettingPurpose
Capabilities--cap-drop=ALLRemove all Linux capabilities
Privileges--security-opt=no-new-privilegesPrevent privilege escalation
Memory--memory=2gLimit memory usage
CPU--cpus=2Limit CPU usage
Network--network=noneDisable network access
Read-onlyOptional --read-onlyPrevent filesystem modifications

Output Capture

Capturing Stdout/Stderr

# Capture output to variable
output=$(docker exec course-sandbox-{course-id} ./prog 2>&1)

# Capture with exit code
docker exec course-sandbox-{course-id} ./prog > output.txt 2>&1
exit_code=$?

# Separate stdout and stderr
docker exec course-sandbox-{course-id} ./prog > stdout.txt 2> stderr.txt

Comparing Expected Output

# Run and compare
actual=$(docker exec course-sandbox-{course-id} ./prog 2>&1)
expected="Hello, World!"

if [ "$actual" = "$expected" ]; then
  echo "PASS: Output matches"
else
  echo "FAIL: Expected '$expected', got '$actual'"
fi

Timeout Handling

Always use timeouts to prevent infinite loops:

# Command timeout (10 seconds)
timeout 10s docker exec course-sandbox-{course-id} ./prog

# Check timeout exit code
if [ $? -eq 124 ]; then
  echo "ERROR: Execution timed out (possible infinite loop)"
fi

Temporary Files

Use /tmp inside the container for compiled binaries:

# Compile to /tmp (always writable)
docker exec course-sandbox-{course-id} \
  g++ -o /tmp/example /workspace/example.cpp

# Run from /tmp
docker exec course-sandbox-{course-id} /tmp/example

# Clean up (optional, /tmp clears on container restart)
docker exec course-sandbox-{course-id} rm /tmp/example

Error Handling

Compilation Errors

# Capture compiler output
compile_output=$(docker exec course-sandbox-{course-id} \
  g++ -std=c++20 -Wall -Wextra -o /tmp/prog /workspace/example.cpp 2>&1)
compile_status=$?

if [ $compile_status -ne 0 ]; then
  echo "Compilation failed:"
  echo "$compile_output"
fi

Runtime Errors

# Capture runtime output with exit code
run_output=$(docker exec course-sandbox-{course-id} /tmp/prog 2>&1)
run_status=$?

case $run_status in
  0) echo "Success" ;;
  139) echo "Segmentation fault (signal 11)" ;;
  134) echo "Abort (signal 6)" ;;
  124) echo "Timeout" ;;
  *) echo "Exit code: $run_status" ;;
esac

Batch Validation

For validating all code examples in a course:

#!/bin/bash
# validate-all-examples.sh

course_id="cpp-fundamentals"
container="course-sandbox-$course_id"

# Find all code files
find /workspace -name "*.cpp" | while read file; do
  echo "Testing: $file"

  # Compile
  if docker exec $container g++ -std=c++20 -Wall -o /tmp/test "$file" 2>&1; then
    echo "  Compile: PASS"

    # Run with timeout
    if timeout 10s docker exec $container /tmp/test > /dev/null 2>&1; then
      echo "  Execute: PASS"
    else
      echo "  Execute: FAIL (exit code $?)"
    fi
  else
    echo "  Compile: FAIL"
  fi
done

Integration with Course Workflow

Before Content Review

  1. Ensure sandbox is running
  2. Extract code blocks from markdown
  3. Write to temporary files in mounted volume
  4. Compile and execute each
  5. Compare output to stated expectations

During Content Creation

  1. Write code in content
  2. Test in sandbox immediately
  3. Capture actual output for documentation
  4. Verify error examples produce expected errors

For Student Exercises

  1. Student writes solution
  2. Solution tested in sandbox
  3. Output compared to expected
  4. Feedback provided

Best Practices

  1. Always use timeouts - Prevent infinite loops from blocking the sandbox
  2. Compile to /tmp - Avoids permission issues with mounted volumes
  3. Capture both streams - Always capture both stdout and stderr
  4. Check exit codes - Don't assume success, verify return codes
  5. Clean up periodically - Remove compiled binaries to save space
  6. Stop when idle - Stop containers when not actively developing
  7. Rebuild regularly - Rebuild containers to get security updates
  8. Log operations - Keep logs for debugging validation issues

Slidev - Presentation Framework Reference

Complete reference for creating developer education presentations with Slidev.

Frontmatter Configuration

Every presentation starts with frontmatter in the first slide:

---
theme: default
title: "Video Title Here"
info: |
  ## Module Description
  Brief description for metadata
author: Course Name
transition: slide-left
highlighter: shiki
drawings:
  persist: false
mdc: true
download: true
exportFilename: video-filename
aspectRatio: 16/9
canvasWidth: 980
fonts:
  sans: Inter
  mono: Fira Code
---

Key Options

OptionPurposeRecommended
themeVisual themedefault, seriph
transitionSlide animationslide-left, fade
highlighterCode syntaxshiki
aspectRatioSlide ratio16/9 for video
mdcMDC syntaxtrue

Slide Separators

---          # New slide
---          # Another slide

Per-slide frontmatter:

---
layout: center
class: text-center
transition: fade
---

Built-in Layouts

default

Standard content layout.

---
layout: default
---
# Title
Content here

center

Centered content for impact statements.

---
layout: center
class: text-center
---
# Big Statement

section

Major topic dividers.

---
layout: section
---
# Part 1: Topic Name

two-cols

Side-by-side content (code + explanation).

---
layout: two-cols
layoutClass: gap-16
---
# Left Content

Explanation here

::right::

## Right Content

```code
example

### two-cols-header
Header spanning both columns.
```markdown
---
layout: two-cols-header
---
# Header Spans Both

::left::
Left content

::right::
Right content

image-right / image-left

Image with content.

---
layout: image-right
image: /path/to/image.jpg
backgroundSize: cover
---
# Content Side
Explanation here

fact

Emphasize statistics.

---
layout: fact
---
# 100%
Of modern C++ should use smart pointers

quote

Attribution quotes.

---
layout: quote
---
# "Quote text here"
Author Name

intro

Speaker/topic introduction.

---
layout: intro
---
# Topic Name
Introduction content

end

Closing slide.

---
layout: end
---
# Thank You
Call to action

Code Blocks

Basic Syntax Highlighting

```python
def greet(name):
    return f"Hello, {name}!"
```

Line Highlighting

```python {2,4}
def calculate(x, y):
    result = x + y      # Highlighted
    print(result)
    return result       # Highlighted
```

Click-Based Progressive Reveal

```python {1|2-3|4-5|all}
def process(items):
    valid = [x for x in items if x > 0]
    sorted_items = sorted(valid)
    total = sum(sorted_items)
    return total
```

Pattern: {step1|step2|step3|all} - each | is a click.

Line Numbers

```python {lines:true}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

Custom Start Line

```python {lines:true,startLine:42}
# Code starting at line 42
```

Max Height (Scrollable)

```python {maxHeight:'200px'}
# Long code that scrolls
```

Monaco Editor (Interactive)

```typescript {monaco}
// Editable code
const x = 5;
```

Monaco Runner (Execute)

```typescript {monaco-run}
console.log("Runs live!");
```

Monaco Diff

```typescript {monaco-diff}
// Before
function add(a, b) { return a + b; }
~~~
// After
function add(a: number, b: number): number { return a + b; }
```

Animations & Clicks

v-click (Single Element)

<v-click>
This appears on click
</v-click>

v-clicks (Multiple Elements)

<v-clicks>

- First item
- Second item
- Third item

</v-clicks>

Nested v-clicks

<v-clicks depth="2">

- Parent
  - Child 1
  - Child 2
- Parent 2

</v-clicks>

Click Positioning

<div v-click="3">Appears at click 3</div>
<div v-click="1">Appears at click 1</div>
<div v-click="2">Appears at click 2</div>

Hide on Click

<div v-click.hide="3">Disappears at click 3</div>
<div v-click="[1, 3]">Visible only clicks 1-2</div>

v-after (Same Click)

<v-click>Main content</v-click>
<v-after>Appears with main content</v-after>

Slide Transitions

---
transition: slide-left  # Global default
---

---
transition: fade        # Per-slide override
---

Available: slide-left, slide-right, slide-up, slide-down, fade, fade-out


Mermaid Diagrams

Flowchart

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Sequence Diagram

```mermaid {scale: 0.8}
sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: Request
    S-->>C: Response
```

Class Diagram

```mermaid {scale: 0.7}
classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog
```

Themes

```mermaid {theme: 'neutral', scale: 0.8}
graph LR
    A --> B --> C
```

Themes: default, neutral, dark, forest, base


LaTeX Math

Inline Math

The formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Block Math

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

In Tables

| Algorithm | Complexity |
|-----------|------------|
| Binary Search | $O(\log n)$ |
| Quick Sort | $O(n \log n)$ |

Styling

UnoCSS Utility Classes

Layout:

  • grid, flex, grid-cols-2, grid-cols-3
  • gap-4, gap-8

Spacing:

  • p-4, m-4, mt-8, px-2, py-1

Typography:

  • text-sm, text-xl, text-2xl
  • font-bold, font-mono
  • text-center, text-left

Colors:

  • text-blue-500, text-red-500
  • bg-blue-500, bg-green-100
  • bg-opacity-20, opacity-50

Borders:

  • rounded, rounded-lg
  • border, border-blue-500

Absolute Positioning

<div class="abs-tr m-4">Top Right</div>
<div class="abs-tl m-4">Top Left</div>
<div class="abs-br m-4">Bottom Right</div>
<div class="abs-bl m-4">Bottom Left</div>

Card Pattern

<div class="p-4 rounded-lg bg-blue-500 bg-opacity-20 border border-blue-500">
Card content
</div>

Scoped Styles

<style>
h1 {
  background: linear-gradient(90deg, #667eea, #764ba2);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}
</style>

Presenter Notes

Notes go in HTML comments at slide end:

# Slide Title

Content here

<!--
Main talking points:
- First point to cover
- Second important concept

[click] Animation appears - explain this

[click] Next animation - elaborate

[PAUSE] Give viewers time to absorb

[TRANSITION] Lead into next topic...
-->

Click Markers in Notes

<!--
Introduction to the concept...

[click] First item appears - discuss the basics

[click] Second item - dive deeper

[click:2] Skip ahead two clicks

Final summary...
-->

Code Groups

Show same concept in multiple languages:

::code-group

```python [Python]
def greet(name):
    return f"Hello, {name}!"
```

```javascript [JavaScript]
function greet(name) {
    return `Hello, ${name}!`;
}
```

```rust [Rust]
fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}
```

::

MDC Syntax

Enable with mdc: true in frontmatter.

Inline Attributes

This is [red text]{style="color:red"} inline

Block Attributes

::div{.p-4 .bg-blue-500 .bg-opacity-20 .rounded}
Block with classes
::

Global Context

Access slide metadata:

{{ $slidev.nav.currentPage }}     <!-- Current slide -->
{{ $slidev.nav.total }}           <!-- Total slides -->
{{ $slidev.configs.title }}       <!-- Presentation title -->

Keyboard Shortcuts

Navigation

KeyAction
→ / SpaceNext
←Previous
gGo to slide

Views

KeyAction
oOverview
pPresenter mode
fFullscreen

Tools

KeyAction
dDrawings
rRecording

Video Presentation Patterns

Opening Hook

---
layout: center
class: text-center
---

# Why Does Your Code Keep Crashing?

<v-click>

The answer might surprise you...

</v-click>

<!--
[HOOK] Start with a relatable problem

Pause briefly for dramatic effect.

[click] Reveal the teaser - builds curiosity
-->

Concept Introduction

---
layout: two-cols
layoutClass: gap-16
---

# Smart Pointers

<v-clicks>

- **What:** Automatic memory management
- **Why:** Prevents memory leaks
- **How:** RAII pattern

</v-clicks>

::right::

<v-click>

```cpp
auto ptr = std::make_unique<int>(42);
// Automatically freed!

### Code Walkthrough
```markdown
# Processing Data

```python {1|3-4|6-7|all}
# Step 1: Setup
data = [1, 2, 3, 4, 5]

# Step 2: Transform
result = [x * 2 for x in data]

# Step 3: Output
print(result)

### Comparison Slide
```markdown
---
layout: two-cols
---

<div class="p-4 rounded bg-red-500 bg-opacity-10">

### ❌ Don't

```cpp
int* ptr = new int(42);
// Memory leak!

::right::

✔ Do

auto ptr = make_unique<int>(42);
// Auto cleanup!

### Summary Pattern
```markdown
---
layout: center
---

# Key Takeaways

<v-clicks>

1. **Smart pointers** manage memory automatically
2. Use **unique_ptr** for single ownership
3. Use **shared_ptr** for shared ownership
4. **Never** use raw `new` in modern C++

</v-clicks>

<!--
[click] First takeaway - the main concept
[click] Second - most common case
[click] Third - when to use shared
[click] Fourth - the golden rule

[PAUSE] Let these sink in before the call to action
-->

Call to Action

---
layout: end
---

# Practice Time!

<div class="text-center mt-8">

Try converting raw pointers to smart pointers in your code

**Next Video:** Move Semantics Deep Dive

</div>

<!--
End with clear action items.

Mention the next video to encourage continued watching.

Thank viewers for watching!
-->

Best Practices for Video

  1. 16:9 aspect ratio - Standard for video platforms
  2. Large, readable text - Minimum 24px for body text
  3. High contrast - Ensure readability on various screens
  4. One concept per slide - Don't overwhelm viewers
  5. Progressive reveals - Build understanding step by step
  6. Consistent animations - Use same transition throughout
  7. Clear code highlighting - Guide viewer attention
  8. Comprehensive notes - Enable confident delivery

Video Scripts - Presenter Notes for Developer Education

Techniques for writing effective presenter notes that enable natural, engaging video delivery.

Script Philosophy

Conversational, Not Robotic

Don't write:

"In this slide, we will examine the concept of pointers. A pointer is a variable that stores the memory address of another variable."

Do write:

"So what exactly is a pointer? Think of it like a sticky note with an address written on it. It doesn't hold the actual data - it just tells you where to find it."

Talking Points, Not Teleprompter

Presenter notes should guide, not dictate. Write key points and transitions, letting the presenter fill in naturally.

<!--
Main idea: Pointers store addresses, not values

Key analogy: Sticky note with house address
- The note isn't the house
- It tells you where to find the house
- You can have multiple notes to the same address

[click] Show the diagram - reinforce the mental model
-->

Script Structure

Opening Hook (30-60 seconds)

Every video needs a hook in the first 30 seconds:

Problem Hook:

<!--
[HOOK] Have you ever had your program crash with a mysterious "segmentation fault"?

You're not alone. Memory errors are one of the most frustrating bugs to track down.

Today, we're going to demystify what's happening under the hood...
-->

Question Hook:

<!--
[HOOK] Quick question: What do you think happens when you write `int x = 5;`?

Most people say "it stores 5 in x" - and that's partially right.

But there's actually a lot more going on...
-->

Curiosity Hook:

<!--
[HOOK] There's a feature in modern C++ that eliminates an entire category of bugs.

And most codebases still aren't using it correctly.

Let's fix that today...
-->

Core Teaching Section

Structure content in digestible chunks:

<!--
SECTION: What is a Smart Pointer?

First, let's understand the problem it solves...

[click] Show the manual memory example

This is how we used to do it. Notice we have to remember to delete.

[click] Show what happens when we forget

Memory leak! The program keeps consuming memory until...

[PAUSE] Let this sink in

[click] Now show the smart pointer version

See how the cleanup happens automatically?

[TRANSITION] Now let's look at the different types...
-->

Summary Section

Reinforce learning with clear takeaways:

<!--
SUMMARY: Let's recap what we learned

[click] First takeaway - make sure they got this

This is the most important point. If you remember nothing else...

[click] Second takeaway - practical application

You'll use this pattern constantly in real code.

[click] Third takeaway - common mistake to avoid

I see this error in code reviews all the time.

[PAUSE] Give them a moment

[TRANSITION] Now for some practice...
-->

Visual Cue Markers

Animation Cues

MarkerUsage
[click]Trigger next Slidev animation
[click:2]Skip 2 clicks worth of content
[ANIMATE]Complex animation is occurring
<!--
Introduce the concept of ownership...

[click] First bullet appears

Ownership means one thing is responsible for cleanup.

[click] Second bullet

Only the owner can delete the resource.

[click:2] Skip to the code example

Now let's see this in action...
-->

Visual Attention Cues

MarkerUsage
[SHOW CODE]Direct attention to code block
[VISUAL CUE]Point to diagram or image
[HIGHLIGHT]Something is being highlighted
<!--
[SHOW CODE] Look at line 5

Notice how we're using make_unique here.

[VISUAL CUE] The diagram on the right shows memory layout

See how the pointer and the data are in different locations?

[HIGHLIGHT] This line is the key insight
-->

Pacing Cues

MarkerUsage
[PAUSE]Brief pause for emphasis
[SLOW]Slow down delivery
[TRANSITION]Moving to new topic
<!--
And this is the critical insight...

[PAUSE] Let that sink in

[SLOW] Memory. Is. Not. Automatic. In. C++.

[TRANSITION] Now that we understand the problem, let's look at the solution...
-->

Audience Engagement Cues

MarkerUsage
[QUESTION]Rhetorical question
[THINK]Prompt viewer to think
[EXAMPLE]Real-world example coming
<!--
[QUESTION] So what happens when this function returns?

Take a moment to think about it...

[THINK] Where does the memory go?

[EXAMPLE] Let me show you a real bug I found in production code...
-->

Writing Techniques

The Explain-Show-Explain Pattern

  1. Explain the concept verbally
  2. Show the code/diagram
  3. Explain what they're seeing
<!--
First, let me explain what we're trying to do.

We want to allocate memory that automatically cleans up.

[click] Show the code

Now look at this code. See how we use make_unique?

The key here is that we never call delete ourselves.
When ptr goes out of scope, cleanup happens automatically.
-->

The Problem-Solution Pattern

Present the pain before the cure:

<!--
Here's the old way - manual memory management.

[click] Show problematic code

See all these delete calls? Every single one is a potential bug.

Miss one? Memory leak.
Delete twice? Crash.
Exception thrown? Memory leak.

[PAUSE]

[click] Now the modern way

One line. Automatic cleanup. Exception safe.

This is why smart pointers exist.
-->

The Build-Up Pattern

Start simple, add complexity:

<!--
Let's start with the simplest case.

[click] Basic example

Just creating a single integer. Nothing fancy.

[click] Add a function call

Now we're passing it to a function. Still straightforward.

[click] Add exception handling

Here's where it gets interesting. What if process() throws?

[click] Show the problem

See the leak? The delete never runs!

[click] Show the solution

Smart pointer handles this automatically.
-->

Tone Guidelines

Be Conversational

Instead of...Say...
"We will now examine...""Let's look at..."
"It should be noted that...""Here's the thing..."
"The implementation details...""Under the hood..."
"In conclusion...""So what's the takeaway?"

Be Empathetic

Acknowledge difficulty:

<!--
This part trips up a lot of people, so don't worry if it doesn't click immediately.

Let me show you a different way to think about it...
-->

Celebrate progress:

<!--
If you understood that, you've already grasped the hardest part.

The rest is just variations on this theme.
-->

Be Direct

Get to the point:

<!--
Three rules for smart pointers:

One: Use unique_ptr by default.
Two: Use shared_ptr when you need shared ownership.
Three: Never use raw new.

That's it. Those three rules will prevent most memory bugs.
-->

Pacing Guidelines

Target Video Length: 10-15 minutes

SectionTimeSlides
Hook/Intro30-60s1-2
Main Content8-12min10-20
Summary1-2min2-3
Call to Action30s1

Words Per Slide

  • Concept slides: 100-150 words of notes
  • Code slides: 50-100 words (code speaks)
  • Summary slides: 75-100 words

Clicks Per Slide

  • Aim for: 2-4 clicks per content slide
  • Maximum: 6-7 clicks (more gets confusing)
  • Code reveals: 3-5 steps typically

Common Patterns

The "Before We Start" Setup

<!--
Before we dive in, let me set some context.

We're assuming you know basic C++ syntax.
If terms like "stack" and "heap" are new, check out our memory basics video first.

Ready? Let's go.
-->

The "Common Mistake" Warning

<!--
[QUESTION] Now here's where most people go wrong.

[click] Show the bad code

This looks reasonable, right? But there's a subtle bug.

[PAUSE]

Can you spot it?

[click] Highlight the problem

The issue is ownership. Who's responsible for deleting this?

[click] Show the fix

Here's how to fix it...
-->

The "Real World" Connection

<!--
[EXAMPLE] I see this pattern in production code all the time.

Just last week, I was reviewing code that looked exactly like this.

[click] Show the code

See the problem? They're storing raw pointers in a vector.

When the function returns, all those pointers are invalid.

This bug made it to production and caused intermittent crashes.

Smart pointers would have prevented it entirely.
-->

The "Pause and Think" Moment

<!--
[THINK] Before I show you the answer, try to figure it out yourself.

What do you think happens when we call this function?

[PAUSE] Give them 3-4 seconds

[click] Reveal the answer

If you said "undefined behavior" - you're right!
-->

Quality Checklist

Before finalizing presenter notes:

  • Opening has a clear hook
  • Every [click] has an explanation
  • Transitions between topics are smooth
  • Pacing allows for natural pauses
  • Technical terms are explained
  • Real-world connections are made
  • Summary reinforces key points
  • Call to action is clear
  • Tone is conversational throughout
  • Visual cues guide attention appropriately

Commands 18

Create Course Profile

Generate a comprehensive course profile that configures how content is created for a specific programming course.

Interactive Workflow

Step 1: Course Name and ID

What should this course be called?
(e.g., "Rust for Systems Programmers", "Python Web Development")

Course ID (lowercase, hyphens, for directory name):
(e.g., "rust-systems", "python-web")

Step 2: Target Audience

Who is the target audience?

[1] Complete beginners (no programming experience)
[2] Beginners (basic programming in another language)
[3] Junior developers (1-2 years experience)
[4] Intermediate developers (2-5 years experience)
[5] Advanced developers (5+ years, new to this language)

Please select an option:

Step 3: Programming Language

What programming language?

[1] C++
[2] Rust
[3] Go
[4] Python
[5] JavaScript/TypeScript
[6] Java
[7] C#
[8] Other (specify)

Please select an option:

Step 4: Framework Philosophy

Should this course use frameworks?

[1] No frameworks - focus on language and standard library only
[2] Minimal frameworks - introduce 1-2 key frameworks late in course
[3] Framework-centric - teach primarily through a specific framework
[4] Framework comparison - compare multiple frameworks

Please select an option:

If frameworks are included:

Which framework(s)?
(e.g., "Qt", "Django", "React", "Spring")

Step 5: Course Focus

What is the primary focus?

[1] Language fundamentals (syntax, semantics, standard library)
[2] Systems programming (memory, performance, low-level)
[3] Application development (building complete applications)
[4] Web development (frontend/backend/full-stack)
[5] Data processing (analysis, manipulation, visualization)
[6] Game development
[7] Embedded/IoT

Please select an option:

Step 6: Prerequisites

What should students already know before starting?
(List specific skills or concepts, one per line)

Example:
- Basic programming in any language
- Command line familiarity
- Version control basics

Step 7: Course Duration

How long is this course?

[1] 4-6 weeks (intensive bootcamp)
[2] 8-10 weeks (short course)
[3] 12-16 weeks (semester-length)
[4] Self-paced (no fixed duration)

Please select an option:

Step 8: Learning Environment

What development environment?

[1] Local development (IDE + compiler/runtime)
[2] Online IDE (Replit, CodeSandbox, etc.)
[3] Cloud-based (Jupyter, Google Colab)
[4] Hybrid (local + online for practice)

Please select an option:

Step 9: Generate Profile

Create a comprehensive course profile including:

  1. Course overview and philosophy
  2. Target audience with prerequisites
  3. Technical stack (language, tools, frameworks)
  4. Content style guidelines
  5. Module/chapter outline
  6. Lab/exercise structure
  7. Assessment philosophy
  8. Quality standards

What the Agent Does

The course-architect agent will:

Profile Design:

  • Structure course based on language and focus
  • Design appropriate module sequence
  • Define content style for audience
  • Specify technical requirements

Template Generation:

  • Create course-specific callout box types
  • Define code example format
  • Specify diagram requirements
  • Set assessment standards

Output

Complete course profile file at: skills/courses/{course-id}/course-profile.md

Including:

  • Course metadata
  • Audience definition
  • Learning philosophy
  • Technical stack
  • Content style guide
  • Module outline
  • Lab structure
  • Assessment approach
  • Quality checklist

The profile can then be used by all other commands to generate course-specific content.

Create Exercise

Generate a standalone coding exercise with clear specifications, starter code, test cases, and solution.

Interactive Workflow

Step 1: Course Selection

Which course is this exercise for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]

Please select an option:

Step 2: Exercise Type

What type of exercise?

[1] Practice Exercise (with hints and solution visible)
[2] Assignment (solution hidden, for submission)
[3] Assessment Question (timed, minimal hints)

Please select an option:

Step 3: Concepts to Practice

What concepts should this exercise focus on?
(e.g., "pointers", "recursion", "standard library algorithms")

Step 4: Difficulty Level

What difficulty level?

[1] Beginner - Reinforce basic understanding
[2] Intermediate - Apply concepts in new context
[3] Advanced - Combine multiple concepts or optimize
[4] Challenge - Push beyond the course material

Please select an option:

Step 5: Time Estimate

How long should students spend on this exercise?

[1] 10-15 minutes (quick practice)
[2] 20-30 minutes (standard exercise)
[3] 45-60 minutes (substantial problem)
[4] 90+ minutes (mini-project)

Please select an option:

Step 6: Generate Exercise

Create the exercise following the exercise template:

  1. Clear problem statement
  2. Specific requirements
  3. Starter code (appropriate to difficulty)
  4. Test cases for validation
  5. Hints (if practice exercise)
  6. Complete solution with explanation

What the Agent Does

The course-architect agent will:

Problem Design:

  • Create a realistic, engaging problem
  • Ensure requirements are clear and testable
  • Design appropriate starter code scaffolding
  • Write comprehensive test cases

Difficulty Calibration:

  • Match complexity to specified level
  • Ensure solvable with taught concepts
  • Include appropriate hints for the level
  • Design solution that demonstrates best practices

Quality Assurance:

  • All code compiles and runs
  • Test cases are comprehensive
  • Solution is idiomatic and well-explained
  • Time estimate is realistic

Output

A complete exercise document including:

  • Problem statement
  • Requirements list
  • Starter code
  • Test cases
  • Hints (for practice exercises)
  • Solution with explanation
  • Extension challenges (optional)

Create Lab

Generate a structured lab session where students practice programming concepts through guided exercises and independent challenges.

Interactive Workflow

This command uses a numbered-option interactive workflow to gather requirements and create the lab.

Step 1: Course Selection

Ask the user which course this lab is for:

Which course is this lab for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]

Please select an option by number:

Load the appropriate course profile based on selection.

Step 2: Chapter/Topic Input

Ask which chapters or topics the lab should reinforce:

Which chapters or topics should this lab reinforce?
(Provide chapter numbers or topic names, e.g., "Chapters 5-6" or "Pointers and References")

Read the specified chapters if available to analyze content.

Step 3: Topic Confirmation

Based on the chapters, analyze and present planned topics:

Based on [chapters specified], I plan to cover these concepts:
- [Concept 1 identified from chapter analysis]
- [Concept 2 identified from chapter analysis]
- [Concept 3 identified from chapter analysis]

[1] Accept these topics
[2] Add or modify topics

Please select an option:

Step 4: Lab Duration

Ask about time constraints:

How long should this lab be?

[1] 60 minutes (4 challenges)
[2] 90 minutes (6 challenges) - recommended
[3] 120 minutes (8 challenges)

Please select an option:

Step 5: Lab Format

What format should the lab take?

[1] Markdown with code blocks (for any editor)
[2] Jupyter Notebook (if Python or supported language)
[3] Project template (CMake/Makefile structure)

Please select an option:

Step 6: Save Location

Where should I save the lab?

[Suggested path based on course structure]

Please provide the directory path (or press Enter to use suggested path):

Step 7: Generate Lab

Create the lab following the course profile and content templates:

  1. Structure the lab with Part A (guided) and Part B (independent)
  2. Ensure all code compiles and runs
  3. Include test cases for validation
  4. Add appropriate scaffolding for the audience level
  5. Create instructor solution guide separately

Step 8: Completion Message

Lab created successfully!

Location: [full path to created file]

Contents:
- Part A: Guided Practice ([X] minutes, [Y] sections)
- Part B: Independent Challenges ([X] minutes, [Y] challenges)
- Solution guide: [path to solutions]

Next steps:
1. Review the lab and make any necessary edits
2. Test all code examples compile and run correctly
3. Verify timing estimates are realistic

What the Agent Does

The course-architect agent will:

Planning Phase:

  • Load appropriate course profile based on selection
  • Analyze specified chapters to extract key concepts
  • Identify topics requiring hands-on practice
  • Determine appropriate difficulty progression
  • Confirm all details with user using numbered options

Content Creation Phase:

  • Generate lab following the exact structure required
  • Create Part A with step-by-step guided examples
  • Create Part B with progressive challenges
  • Include test cases for each challenge
  • Add hints at appropriate levels
  • Ensure timing estimates are realistic

Quality Assurance:

  • All code compiles without errors
  • Test cases validate correct solutions
  • Difficulty progression is appropriate
  • Clear instructions at each step

Course-Specific Requirements

Systems Programming Courses (C++, Rust, etc.)

  • All code must compile with standard flags
  • Include memory diagrams where relevant
  • Show expected output for all examples
  • Include debugging exercises

Higher-Level Language Courses

  • Focus on language idioms and patterns
  • Include REPL-style exploration where appropriate
  • Test-driven development integration

Skills Available to Agent

The agent has access to:

  • pedagogy: General teaching principles for programming
  • content-templates: Lab structure patterns
  • courses/{course-name}: Course-specific context

Output

A complete lab document including:

  • Learning objectives
  • Setup instructions
  • Part A: Guided practice sections with explanations
  • Part B: Independent challenges with test cases
  • Hints (progressively revealed)
  • Solution guide (separate file)
  • Wrap-up and reflection questions

Create Project

Generate a comprehensive project assignment that spans multiple sessions, integrating concepts from several chapters.

Interactive Workflow

Step 1: Course Selection

Which course is this project for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]

Please select an option:

Step 2: Project Scope

How large should this project be?

[1] Mini-project (2-4 hours, single concept focus)
[2] Standard project (8-16 hours, multiple concepts)
[3] Capstone project (20-40 hours, course integration)

Please select an option:

Step 3: Concepts to Integrate

Which chapters/concepts should this project integrate?
(e.g., "Chapters 4-7: Classes, Containers, Memory Management")

Step 4: Project Type

What type of project?

[1] Build from specification (detailed requirements given)
[2] Design and implement (students design the solution)
[3] Extend existing code (add features to provided codebase)
[4] Debugging/refactoring (fix and improve existing code)

Please select an option:

Step 5: Team or Individual

Individual or team project?

[1] Individual
[2] Pairs (2 students)
[3] Small teams (3-4 students)

Please select an option:

Step 6: Generate Project

Create the project following the project template:

  1. Project overview and motivation
  2. Detailed requirements (core + stretch)
  3. Milestone breakdown
  4. Starter code or project skeleton
  5. Test suite for evaluation
  6. Grading rubric

What the Agent Does

The course-architect agent will:

Project Design:

  • Create engaging, realistic project scenario
  • Define clear requirements at multiple levels
  • Break down into achievable milestones
  • Design appropriate starter material

Scaffolding:

  • Provide project structure (CMakeLists.txt, directory layout)
  • Include necessary boilerplate
  • Design interfaces/stubs students will implement
  • Create comprehensive test suite

Documentation:

  • Write clear specification document
  • Create milestone guides
  • Develop grading rubric
  • Include example outputs

Output

Complete project package including:

  • Project specification document
  • Starter code/project skeleton
  • Test suite
  • Grading rubric
  • Milestone breakdown
  • Example inputs/outputs

Create Quiz

Generate a quiz to assess understanding of programming concepts, including code reading, writing, and conceptual questions.

Interactive Workflow

Step 1: Course Selection

Which course is this quiz for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]

Please select an option:

Step 2: Chapters/Topics

Which chapters or topics should this quiz cover?
(e.g., "Chapters 3-4" or "Pointers, References, Memory Management")

Step 3: Quiz Type

What type of quiz?

[1] Reading check (quick comprehension test)
[2] Practice quiz (formative, with explanations)
[3] Graded quiz (summative, answer key separate)
[4] Exam-style (comprehensive, timed)

Please select an option:

Step 4: Question Count

How many questions?

[1] 5 questions (10-15 min)
[2] 10 questions (20-30 min)
[3] 15 questions (30-45 min)
[4] 20+ questions (exam-length)

Please select an option:

Step 5: Question Mix

What mix of question types?

[1] Code-heavy (mostly code reading/writing)
[2] Balanced (equal code and conceptual)
[3] Concept-heavy (mostly understanding)

Please select an option:

Step 6: Generate Quiz

Create the quiz following these guidelines:

  1. Mix question types appropriately
  2. Progress from easier to harder
  3. Include code that compiles (or explicitly broken for debugging questions)
  4. Provide clear point values
  5. Create detailed answer key

Question Types

Code Tracing

"What does this code output?"

// Complete, compilable code

Tests: execution understanding, mental model accuracy

Bug Identification

"This code has a bug. Identify the issue and explain how to fix it."

// Code with deliberate error

Tests: debugging skills, pattern recognition

Code Writing

"Write a function that..."

  • Clear specification
  • Example inputs/outputs Tests: implementation ability, syntax knowledge

Fill in the Blank

"Complete this code to make it work:"

// Code with strategic blanks

Tests: specific syntax, patterns

Multiple Choice (Conceptual)

"Which statement about X is TRUE?" Tests: understanding of concepts, common misconceptions

Short Answer

"Explain why..." Tests: ability to articulate understanding

Code Comparison

"What is the difference between these two approaches?"

// Approach A
// Approach B

Tests: understanding of trade-offs, alternatives

What the Agent Does

The course-architect agent will:

Question Design:

  • Create questions targeting specified concepts
  • Ensure variety of question types
  • Calibrate difficulty appropriately
  • Include common misconceptions as distractors

Code Quality:

  • All code examples compile (or deliberately don't, if testing debugging)
  • Realistic scenarios
  • Appropriate to course level
  • Idiomatic for the language

Answer Key:

  • Complete correct answers
  • Explanation of why answer is correct
  • Common wrong answers and why they're wrong
  • Partial credit guidelines

Output

Complete quiz including:

  • Quiz header with instructions
  • Questions organized by type/difficulty
  • Code examples (all tested)
  • Point values
  • Answer key (separate file or section)
  • Grading rubric for code questions

Create Slides

Generate Slidev presentation slides optimized for video tutorials, YouTube content, and online courses. Creates a single .md file with comprehensive presenter notes for video recording.

Prerequisites

  • Course content should exist (chapters, exercises, or labs to transform)
  • Course profile should be configured for audience context

Interactive Workflow

Step 1: Course Selection

Which course are these slides for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory

Please select an option:

Step 2: Source Content

What content should be transformed into video slides?

[1] Existing chapter (provide path)
[2] Existing lab or exercise (provide path)
[3] New topic (describe what to cover)
[4] Module overview (summarize multiple chapters)

Please select an option:

Step 3: Video Length

Target video length?

[1] Short (5-7 minutes) - Single concept deep dive
[2] Standard (10-15 minutes) - Complete topic coverage
[3] Long (20-25 minutes) - Multi-concept or workshop

Please select an option:

Step 4: Video Style

What style of video?

[1] Tutorial - Step-by-step teaching
[2] Explainer - Concept explanation with examples
[3] Code Walkthrough - Focus on code analysis
[4] Comparison - Contrast approaches/patterns
[5] Quick Tips - Fast-paced practical advice

Please select an option:

Step 5: Generate Slides

The slides-architect agent creates a complete Slidev presentation.

What Gets Created

Single .md File

A complete Slidev presentation file containing:

---
theme: default
title: "Video Title"
author: Course Name
transition: slide-left
highlighter: shiki
mdc: true
aspectRatio: 16/9
---

# Title Slide
...

---
# Content Slides
...

<!--
Presenter notes with visual cues
-->

Slide Types Included

TypePurposeNotes
HookEngage viewersQuestion or problem statement
ConceptTeach ideasProgressive reveals
CodeShow examplesClick-through highlighting
ComparisonContrast optionsTwo-column layout
DiagramVisualizeMermaid flowcharts
SummaryReinforceKey takeaways
CTANext stepsSubscribe, practice, next video

Presenter Notes Include

Every slide has comprehensive notes:

  • Main talking points
  • Click-by-click explanations
  • Visual cues: [SHOW CODE], [PAUSE], [TRANSITION]
  • Natural, conversational phrasing
  • Questions to engage viewers

Slidev Features Used

Layouts

  • default - Standard content
  • center - Impact statements
  • two-cols - Code + explanation
  • section - Topic dividers
  • image-right/left - Visuals
  • fact - Statistics
  • quote - Expert quotes

Code Features

  • Progressive line highlighting {1|2-3|all}
  • Syntax highlighting (Shiki)
  • Line numbers when helpful
  • Monaco for interactive demos

Animations

  • v-click - Progressive reveals
  • v-clicks - List animations
  • Smooth transitions

Diagrams

  • Mermaid flowcharts
  • Sequence diagrams
  • Class diagrams

Video Structure

Standard 10-15 Minute Video

SectionDurationSlidesPurpose
Hook30-60s1-2Grab attention
Overview30s1What we'll learn
Core Content8-12min10-15Main teaching
Summary1-2min2-3Key takeaways
CTA30s1Next steps

Slide Pacing

  • 1-2 minutes per slide average
  • 2-4 clicks per slide for reveals
  • One concept per slide maximum

Output Format

File Naming

{topic}-slides.md

Example: smart-pointers-slides.md

Frontmatter

---
theme: default
title: "Smart Pointers in Modern C++"
info: |
  ## C++ Fundamentals - Module 6
  Learn automatic memory management with smart pointers
author: C++ Fundamentals Course
transition: slide-left
highlighter: shiki
drawings:
  persist: false
mdc: true
aspectRatio: 16/9
canvasWidth: 980
fonts:
  sans: Inter
  mono: Fira Code
---

Example Output Structure

---
[frontmatter]
---

# Why Your Code Keeps Crashing
## Smart Pointers to the Rescue

<!--
[HOOK] Start with the relatable problem...
-->

---
layout: section
---

# Part 1: The Problem

<!--
[TRANSITION] Let's understand what we're solving...
-->

---
layout: two-cols
---

# Manual Memory Management

<v-clicks>

- You allocate with `new`
- You must free with `delete`
- Miss it? Memory leak
- Double free? Crash

</v-clicks>

::right::

```cpp {1|3|5|all}
int* ptr = new int(42);

// ... use ptr ...

delete ptr;  // Don't forget!

layout: center class: text-center

Key Takeaways

  1. unique_ptr for single ownership
  2. shared_ptr for shared ownership
  3. Never use raw new

layout: end

Practice Time!

Convert your raw pointers to smart pointers

Next Video: Move Semantics Deep Dive


## Integration with Course Content

### From Chapters
- Extract core concepts
- Select best code examples
- Condense explanations for video
- Add visual elements

### From Labs
- Focus on guided portion
- Create follow-along format
- Include checkpoint moments
- Add practice prompts

### From Exercises
- Present problem clearly
- Build solution step-by-step
- Show common mistakes
- Reveal solution progressively

## Quality Checklist

Before delivering slides:
- [ ] Hook engages in first 30 seconds
- [ ] One main concept per slide
- [ ] All code has progressive reveals
- [ ] Presenter notes are conversational
- [ ] Visual cues mark all animations
- [ ] Summary reinforces key points
- [ ] Call to action is clear
- [ ] Total time is 10-15 minutes
- [ ] Slidev renders correctly

## Running the Presentation

```bash
# Install Slidev (if needed)
npm install -g @slidev/cli

# Run presentation
slidev {filename}.md

# Export to PDF
slidev export {filename}.md

# Record presentation
slidev {filename}.md --record

Tips for Recording

  1. Practice the flow - Run through with presenter mode (p key)
  2. Check notes - Ensure all clicks have explanations
  3. Test code - Verify all examples work
  4. Time yourself - Aim for target duration
  5. Record in chunks - Easier to edit mistakes

Debug Code in Sandbox

Run debugging tools, memory sanitizers, and profilers on code within the course's isolated Docker sandbox environment.

Prerequisites

  • Docker must be installed and running
  • Course sandbox must be set up (use /setup-sandbox if not)
  • Container must be running with debugging tools installed
  • Code must be compiled with debug symbols (-g flag)

Supported Debugging Tools

LanguageToolsPurpose
C/C++GDB, LLDBInteractive debugging
C/C++ValgrindMemory leak detection
C/C++AddressSanitizerMemory error detection
C/C++UndefinedBehaviorSanitizerUB detection
C/C++ThreadSanitizerRace condition detection
Rustrust-gdb, rust-lldbInteractive debugging
RustMiriMemory safety checking
Pythonpdb, pdbppInteractive debugging
GodelveInteractive debugging

Interactive Workflow

Step 1: Identify Course and Container

Which course sandbox should debug this code?

[1] cpp-fundamentals (course-sandbox-cpp-fundamentals)
[2] rust-intro (course-sandbox-rust-intro)
[3] python-basics (course-sandbox-python-basics)
[4] Specify container name

Please select an option:

Step 2: Select Debug Mode

What type of debugging?

[1] Interactive debugger (GDB/LLDB/pdb)
[2] Memory check (Valgrind)
[3] Address sanitizer
[4] Undefined behavior sanitizer
[5] Thread sanitizer
[6] Memory profiling

Please select an option:

Step 3: Code to Debug

What should be debugged?

[1] Specific file (provide path)
[2] Compiled binary (provide path)
[3] Current project

Please select an option:

Debugging by Language

C++ Interactive Debugging

Compile with Debug Symbols
# Compile with debug info
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -g -O0 -o /tmp/prog /workspace/src/main.cpp

# Compile with extra debug info
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -g3 -ggdb -O0 -o /tmp/prog /workspace/src/main.cpp
GDB Session
# Start GDB interactively
docker exec -it course-sandbox-cpp-fundamentals \
  gdb /tmp/prog

# Run GDB with commands
docker exec course-sandbox-cpp-fundamentals \
  gdb -ex "break main" -ex "run" -ex "backtrace" /tmp/prog

# GDB batch mode (non-interactive)
docker exec course-sandbox-cpp-fundamentals \
  gdb -batch -ex "run" -ex "bt" /tmp/prog
Common GDB Commands
(gdb) break main          # Set breakpoint at main
(gdb) break file.cpp:25   # Set breakpoint at line 25
(gdb) run                 # Start program
(gdb) run arg1 arg2       # Start with arguments
(gdb) next                # Step over (n)
(gdb) step                # Step into (s)
(gdb) continue            # Continue to next breakpoint (c)
(gdb) print var           # Print variable value (p)
(gdb) print/x ptr         # Print as hex
(gdb) backtrace           # Show call stack (bt)
(gdb) frame 2             # Switch to frame 2
(gdb) info locals         # Show local variables
(gdb) info args           # Show function arguments
(gdb) watch var           # Break when var changes
(gdb) quit                # Exit GDB
LLDB Session
# Start LLDB interactively
docker exec -it course-sandbox-cpp-fundamentals \
  lldb /tmp/prog

# LLDB with initial commands
docker exec -it course-sandbox-cpp-fundamentals \
  lldb -o "breakpoint set -n main" -o "run" /tmp/prog
Common LLDB Commands
(lldb) breakpoint set -n main       # Break at main
(lldb) breakpoint set -f file.cpp -l 25  # Break at line
(lldb) run                          # Start program
(lldb) run arg1 arg2                # Start with arguments
(lldb) next                         # Step over
(lldb) step                         # Step into
(lldb) continue                     # Continue
(lldb) frame variable               # Show local variables
(lldb) print var                    # Print variable
(lldb) bt                           # Backtrace
(lldb) quit                         # Exit

Memory Debugging

Valgrind (Memory Leak Detection)
# Basic memory check
docker exec course-sandbox-cpp-fundamentals \
  valgrind /tmp/prog

# Detailed leak check
docker exec course-sandbox-cpp-fundamentals \
  valgrind --leak-check=full --show-leak-kinds=all /tmp/prog

# Track origins of uninitialized values
docker exec course-sandbox-cpp-fundamentals \
  valgrind --track-origins=yes /tmp/prog

# Memory profiling
docker exec course-sandbox-cpp-fundamentals \
  valgrind --tool=massif /tmp/prog
Valgrind Output Example
==12345== HEAP SUMMARY:
==12345==     in use at exit: 72 bytes in 1 blocks
==12345==   total heap usage: 3 allocs, 2 frees, 73,800 bytes allocated
==12345==
==12345== 72 bytes in 1 blocks are definitely lost in loss record 1 of 1
==12345==    at 0x4C2FB0F: malloc (in /usr/lib/valgrind/vgpreload_memcheck-amd64-linux.so)
==12345==    by 0x10916E: allocate_memory (main.cpp:15)
==12345==    by 0x1091A5: main (main.cpp:22)
==12345==
==12345== LEAK SUMMARY:
==12345==    definitely lost: 72 bytes in 1 blocks
==12345==    indirectly lost: 0 bytes in 0 blocks
==12345==      possibly lost: 0 bytes in 0 blocks
==12345==    still reachable: 0 bytes in 0 blocks
==12345==         suppressed: 0 bytes in 0 blocks

Sanitizers

AddressSanitizer (Memory Errors)
# Compile with ASan
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -fsanitize=address -g -O1 -o /tmp/prog /workspace/src/main.cpp

# Run (ASan enabled automatically)
docker exec course-sandbox-cpp-fundamentals /tmp/prog

Detects:

  • Buffer overflows (stack, heap, global)
  • Use-after-free
  • Use-after-return
  • Double-free
  • Memory leaks
ASan Output Example
=================================================================
==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000000054
READ of size 4 at 0x602000000054 thread T0
    #0 0x55555555528d in main /workspace/src/main.cpp:10
    #1 0x7ffff7a2d82f in __libc_start_main
    #2 0x555555555119 in _start

0x602000000054 is located 4 bytes to the right of 16-byte region
    #0 0x7ffff7b89458 in operator new[](unsigned long)
    #1 0x555555555247 in main /workspace/src/main.cpp:7
UndefinedBehaviorSanitizer
# Compile with UBSan
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -fsanitize=undefined -g -o /tmp/prog /workspace/src/main.cpp

# Run
docker exec course-sandbox-cpp-fundamentals /tmp/prog

Detects:

  • Integer overflow
  • Null pointer dereference
  • Division by zero
  • Invalid shift operations
  • Out-of-bounds array access
ThreadSanitizer (Race Conditions)
# Compile with TSan
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -fsanitize=thread -g -o /tmp/prog /workspace/src/main.cpp

# Run
docker exec course-sandbox-cpp-fundamentals /tmp/prog

Detects:

  • Data races
  • Deadlocks
  • Lock order violations
Combined Sanitizers
# ASan + UBSan (common combination)
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -fsanitize=address,undefined -g -o /tmp/prog /workspace/src/main.cpp

Rust Debugging

rust-gdb
# Compile with debug symbols
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo build"

# Debug with rust-gdb
docker exec -it course-sandbox-rust-intro \
  rust-gdb target/debug/program

# GDB with Rust pretty-printing enabled
docker exec -it course-sandbox-rust-intro \
  gdb -ex "set auto-load safe-path /" target/debug/program
Miri (Memory Safety)
# Run with Miri for memory safety checking
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo +nightly miri run"

# Run tests with Miri
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo +nightly miri test"

Miri detects:

  • Use of uninitialized memory
  • Out-of-bounds memory access
  • Use-after-free
  • Invalid pointer use
  • Memory leaks

Python Debugging

pdb (Built-in Debugger)
# Run with pdb
docker exec -it course-sandbox-python-basics \
  python3 -m pdb /workspace/script.py

# Post-mortem debugging (on exception)
docker exec -it course-sandbox-python-basics \
  python3 -c "import pdb; pdb.pm()" < /workspace/script.py
pdb Commands
(Pdb) break 25          # Set breakpoint at line 25
(Pdb) break func        # Set breakpoint at function
(Pdb) continue          # Continue execution (c)
(Pdb) next              # Step over (n)
(Pdb) step              # Step into (s)
(Pdb) print var         # Print variable (p)
(Pdb) pp var            # Pretty print
(Pdb) list              # Show current location (l)
(Pdb) where             # Show stack trace (w)
(Pdb) quit              # Exit (q)
pdbpp (Enhanced pdb)
# If pdbpp is installed, it auto-replaces pdb
docker exec -it course-sandbox-python-basics \
  python3 -m pdb /workspace/script.py

Go Debugging

Delve
# Start delve
docker exec -it course-sandbox-go-intro \
  bash -c "cd /workspace && dlv debug"

# Debug specific test
docker exec -it course-sandbox-go-intro \
  bash -c "cd /workspace && dlv test"

# Attach to running process
docker exec -it course-sandbox-go-intro \
  dlv attach <pid>
Delve Commands
(dlv) break main.main           # Set breakpoint
(dlv) break main.go:25          # Break at line
(dlv) continue                  # Continue (c)
(dlv) next                      # Step over (n)
(dlv) step                      # Step into (s)
(dlv) print var                 # Print variable (p)
(dlv) locals                    # Show local variables
(dlv) stack                     # Show stack trace
(dlv) goroutines                # List goroutines
(dlv) exit                      # Exit

Debugging Output Format

Crash Analysis Report

=== Debug Analysis: /workspace/src/main.cpp ===
Tool: AddressSanitizer

--- Crash Detected ---
Type: heap-buffer-overflow
Location: main.cpp:10, in function 'process_data'

Stack Trace:
  #0 main.cpp:10 - process_data()
  #1 main.cpp:25 - main()

Memory Information:
  Address: 0x602000000054
  Region: 16-byte heap allocation at main.cpp:7
  Overflow: 4 bytes past end of allocation

--- Root Cause Analysis ---
The code reads 4 bytes beyond the allocated array.

Line 10: data[size]  // BUG: should be data[size-1] or loop should use < not <=

--- Suggested Fix ---
Change loop condition from 'i <= size' to 'i < size'

Memory Leak Report

=== Memory Analysis: /tmp/prog ===
Tool: Valgrind

--- Memory Leaks ---

Leak 1: 72 bytes (definitely lost)
  Allocated at: main.cpp:15 in allocate_memory()
  Not freed by program exit

Leak 2: 128 bytes (definitely lost)
  Allocated at: utils.cpp:42 in create_buffer()
  Not freed by program exit

--- Summary ---
Total leaked: 200 bytes in 2 blocks
Heap usage: 3 allocations, 1 free

--- Recommendations ---
1. Add delete[] call for array allocated at line 15
2. Ensure create_buffer() result is freed
3. Consider using smart pointers (std::unique_ptr)

Debugging Course Examples

For debugging code examples during course development:

#!/bin/bash
# debug-example.sh

file=$1
container="course-sandbox-cpp-fundamentals"

echo "Debugging: $file"

# Compile with all sanitizers
docker exec $container \
  g++ -std=c++20 -fsanitize=address,undefined -g -O1 \
  -o /tmp/debug_prog "$file" 2>&1

if [ $? -ne 0 ]; then
  echo "Compilation failed"
  exit 1
fi

# Run and capture sanitizer output
output=$(docker exec $container /tmp/debug_prog 2>&1)
exit_code=$?

if echo "$output" | grep -q "ERROR:"; then
  echo "Memory/UB issue detected:"
  echo "$output"
else
  echo "No issues detected"
  echo "Output: $output"
fi

Common Debugging Scenarios

Segmentation Fault

# Compile with debug symbols
g++ -g -O0 -o prog main.cpp

# Run in GDB
gdb prog
(gdb) run
# After crash:
(gdb) bt       # See where it crashed
(gdb) frame 0  # Go to crash location
(gdb) info locals  # Check variable values

Memory Leak

# Run with Valgrind
valgrind --leak-check=full ./prog
# Look for "definitely lost" in output

Infinite Loop

# Run in GDB
gdb prog
(gdb) run
# Press Ctrl+C when it hangs
(gdb) bt  # See where it's stuck

Race Condition

# Compile with ThreadSanitizer
g++ -fsanitize=thread -g -o prog main.cpp
./prog
# TSan will report any data races

Best Practices

  1. Always compile with -g for debugging - Debug symbols are essential
  2. Use -O0 or -O1 for debugging - Higher optimization makes debugging harder
  3. Run sanitizers during development - Catch issues early
  4. Use Valgrind for leak detection - More thorough than ASan for leaks
  5. Set breakpoints strategically - Near suspected bug locations
  6. Examine variable state - Print values at each step
  7. Check all error paths - Bugs often hide in error handling
  8. Test with edge cases - Empty inputs, large values, etc.

Lint Code in Sandbox

Run static analysis, style checks, and linting tools on code within the course's isolated Docker sandbox environment.

Prerequisites

  • Docker must be installed and running
  • Course sandbox must be set up (use /setup-sandbox if not)
  • Container must be running with linting tools installed

Supported Linting Tools

LanguageToolsPurpose
C++clang-tidy, cppcheck, clang-formatStatic analysis, style
Rustclippy, rustfmtLints, formatting
Pythonruff, mypy, blackLints, types, formatting
Gogolint, staticcheck, gofmt, go vetLints, analysis, formatting
JavaScriptESLint, PrettierLints, formatting

Interactive Workflow

Step 1: Identify Course and Container

Which course sandbox should lint this code?

[1] cpp-fundamentals (course-sandbox-cpp-fundamentals)
[2] rust-intro (course-sandbox-rust-intro)
[3] python-basics (course-sandbox-python-basics)
[4] Specify container name

Please select an option:

Step 2: Select Lint Scope

What should be linted?

[1] Entire project
[2] Specific directory
[3] Specific file
[4] Changed files only (git diff)

Please select an option:

Step 3: Lint Type

What type of analysis?

[1] Full analysis (all checks)
[2] Style/formatting only
[3] Static analysis only
[4] Type checking only
[5] Security checks only

Please select an option:

Step 4: Auto-fix Option

Should issues be auto-fixed where possible?

[1] Report only (don't modify files)
[2] Auto-fix safe issues
[3] Auto-fix all (including potentially breaking)

Please select an option:

Linting by Language

C++ Linting

clang-tidy (Static Analysis)
# Lint single file
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy /workspace/src/main.cpp -- -std=c++20 -I/workspace/include

# Lint with all checks
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy -checks='*' /workspace/src/main.cpp -- -std=c++20

# Lint specific categories
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy -checks='modernize-*,performance-*,bugprone-*' \
  /workspace/src/main.cpp -- -std=c++20

# Auto-fix issues
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy -fix /workspace/src/main.cpp -- -std=c++20

# Lint entire directory
docker exec course-sandbox-cpp-fundamentals \
  bash -c "find /workspace/src -name '*.cpp' | xargs clang-tidy -- -std=c++20"
cppcheck (Additional Static Analysis)
# Basic check
docker exec course-sandbox-cpp-fundamentals \
  cppcheck --std=c++20 /workspace/src/main.cpp

# Enable all checks
docker exec course-sandbox-cpp-fundamentals \
  cppcheck --enable=all --std=c++20 /workspace/src/

# Check with includes
docker exec course-sandbox-cpp-fundamentals \
  cppcheck --enable=all --std=c++20 -I/workspace/include /workspace/src/

# XML output for parsing
docker exec course-sandbox-cpp-fundamentals \
  cppcheck --enable=all --xml /workspace/src/ 2>&1
clang-format (Style Checking)
# Check formatting (dry run)
docker exec course-sandbox-cpp-fundamentals \
  clang-format --dry-run --Werror /workspace/src/main.cpp

# Show what would change
docker exec course-sandbox-cpp-fundamentals \
  clang-format --dry-run -style=file /workspace/src/main.cpp

# Auto-format file
docker exec course-sandbox-cpp-fundamentals \
  clang-format -i /workspace/src/main.cpp

# Format all files
docker exec course-sandbox-cpp-fundamentals \
  bash -c "find /workspace/src -name '*.cpp' -o -name '*.h' | xargs clang-format -i"

Rust Linting

clippy (Lints)
# Run clippy
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo clippy"

# Treat warnings as errors
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo clippy -- -D warnings"

# With all lints
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo clippy -- -W clippy::all -W clippy::pedantic"

# Auto-fix (where possible)
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo clippy --fix --allow-dirty"
rustfmt (Formatting)
# Check formatting
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo fmt --check"

# Auto-format
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo fmt"

# Format specific file
docker exec course-sandbox-rust-intro \
  rustfmt /workspace/src/main.rs

Python Linting

ruff (Fast Linter)
# Check all files
docker exec course-sandbox-python-basics \
  ruff check /workspace

# Check specific file
docker exec course-sandbox-python-basics \
  ruff check /workspace/main.py

# Auto-fix issues
docker exec course-sandbox-python-basics \
  ruff check --fix /workspace

# Show all issues (don't stop at first)
docker exec course-sandbox-python-basics \
  ruff check --show-source /workspace

# Select specific rules
docker exec course-sandbox-python-basics \
  ruff check --select E,F,W /workspace
mypy (Type Checking)
# Type check file
docker exec course-sandbox-python-basics \
  mypy /workspace/main.py

# Strict type checking
docker exec course-sandbox-python-basics \
  mypy --strict /workspace/main.py

# Type check package
docker exec course-sandbox-python-basics \
  mypy /workspace/src/

# Ignore missing imports
docker exec course-sandbox-python-basics \
  mypy --ignore-missing-imports /workspace/
black (Formatting)
# Check formatting
docker exec course-sandbox-python-basics \
  black --check /workspace

# Show diff of changes
docker exec course-sandbox-python-basics \
  black --diff /workspace/main.py

# Auto-format
docker exec course-sandbox-python-basics \
  black /workspace
isort (Import Sorting)
# Check imports
docker exec course-sandbox-python-basics \
  isort --check-only /workspace

# Auto-fix imports
docker exec course-sandbox-python-basics \
  isort /workspace

Go Linting

golint (Style)
docker exec course-sandbox-go-intro \
  golint /workspace/...
staticcheck (Static Analysis)
docker exec course-sandbox-go-intro \
  staticcheck /workspace/...
go vet (Analysis)
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go vet ./..."
gofmt (Formatting)
# Check formatting
docker exec course-sandbox-go-intro \
  gofmt -d /workspace

# Auto-format
docker exec course-sandbox-go-intro \
  gofmt -w /workspace
golangci-lint (Comprehensive)
# Run all linters
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && golangci-lint run"

# Run specific linters
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && golangci-lint run --enable gosec,govet,errcheck"

# Auto-fix
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && golangci-lint run --fix"

Output Format

Lint Report

=== Linting: /workspace/src ===
Tool: clang-tidy
Standard: C++20

--- Issues Found ---

/workspace/src/main.cpp:15:5: warning: use range-based for loop [modernize-loop-convert]
    for (int i = 0; i < vec.size(); ++i) {
    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    for (auto & elem : vec) {

/workspace/src/main.cpp:23:10: warning: use nullptr instead of 0 [modernize-use-nullptr]
    int* p = 0;
             ^
             nullptr

/workspace/src/utils.cpp:8:1: warning: function 'helper' could be declared static [misc-use-anonymous-namespace]

--- Summary ---
Files checked: 5
Issues found: 3
  Warnings: 3
  Errors: 0

Recommended fixes:
  - Modernize loop on line 15
  - Use nullptr instead of 0 on line 23
  - Consider making 'helper' function static

Format Check Output

=== Format Check: /workspace/src ===
Tool: clang-format

--- Formatting Issues ---

/workspace/src/main.cpp
@@ -15,7 +15,7 @@
-    int x=5;
+    int x = 5;

/workspace/src/utils.cpp
@@ -8,10 +8,10 @@
-void foo(){
+void foo() {

--- Summary ---
Files with issues: 2
Files correctly formatted: 3
Total files: 5

Pre-defined Lint Configurations

C++ Configuration (.clang-tidy)

---
Checks: >
  -*,
  bugprone-*,
  modernize-*,
  performance-*,
  readability-*,
  -modernize-use-trailing-return-type
WarningsAsErrors: ''
HeaderFilterRegex: '.*'
AnalyzeTemporaryDtors: false
FormatStyle: file

Python Configuration (pyproject.toml)

[tool.ruff]
select = ["E", "F", "W", "I", "N", "B", "A", "C4", "SIM"]
ignore = ["E501"]  # line length handled by black

[tool.mypy]
strict = true
ignore_missing_imports = true

[tool.black]
line-length = 88

Rust Configuration (clippy.toml)

too-many-arguments-threshold = 7
type-complexity-threshold = 250

Linting Course Examples

For validating code examples in course materials:

#!/bin/bash
# lint-examples.sh

course_id=$1
container="course-sandbox-$course_id"

echo "Linting all code examples..."

# Find all code files in course
find /workspace -name "*.cpp" -o -name "*.py" -o -name "*.rs" | while read file; do
  echo "Checking: $file"

  case "$file" in
    *.cpp)
      docker exec $container clang-tidy "$file" -- -std=c++20 2>&1
      ;;
    *.py)
      docker exec $container ruff check "$file" 2>&1
      docker exec $container mypy "$file" 2>&1
      ;;
    *.rs)
      docker exec $container rustfmt --check "$file" 2>&1
      ;;
  esac
done

Severity Levels

LevelMeaningAction
ErrorCode won't compile or has critical bugMust fix
WarningPotential issue or bad practiceShould fix
InfoStyle suggestion or improvementConsider fixing
HintMinor improvement opportunityOptional

Filtering Output

By Severity

# Only errors
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy -warnings-as-errors='*' /workspace/src/main.cpp -- -std=c++20

# Only specific categories
docker exec course-sandbox-cpp-fundamentals \
  clang-tidy -checks='-*,bugprone-*' /workspace/src/main.cpp -- -std=c++20

By File Pattern

# Only source files (not headers)
docker exec course-sandbox-cpp-fundamentals \
  bash -c "find /workspace/src -name '*.cpp' | xargs clang-tidy -- -std=c++20"

Integration with Code Review

When reviewing course content:

  1. Run lint on all examples - Catch style and correctness issues
  2. Check formatting consistency - Ensure uniform style
  3. Verify type correctness - For typed languages
  4. Check for deprecated patterns - Ensure modern practices
  5. Security analysis - Check for vulnerabilities

Best Practices

  1. Lint before committing - Catch issues early
  2. Use auto-fix carefully - Review changes before accepting
  3. Configure project standards - Use config files for consistency
  4. Don't ignore warnings - They often indicate real issues
  5. Run multiple tools - Each catches different issues
  6. Integrate with CI - Automate linting checks

Review Code Examples

Systematic audit of code examples across course materials for correctness, style, best practices, and consistency.

Interactive Workflow

Step 1: Course Selection

Which course's code examples should be reviewed?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 2: Scope Selection

What scope of code review?

[1] All code examples in the course
[2] Specific module or chapter
[3] Specific file or content piece
[4] Only code marked as "working examples"
[5] Only code marked as "error examples"

Please select an option:

Step 3: Review Depth

How thorough should the code review be?

[1] Compilation check only (verify code compiles)
[2] Execution check (verify output matches stated)
[3] Full review (compilation, execution, style, best practices)
[4] Style and idioms only (skip compilation)

Please select an option:

Step 4: Verification Method

How should code be verified?

[1] Manual analysis (trace through code mentally)
[2] Actual compilation and execution (if toolchain available)
[3] Hybrid (compile what's possible, analyze the rest)

Please select an option:

Step 5: Generate Code Audit

The course-reviewer agent will systematically review all code examples.

What Gets Reviewed

Correctness

  • Does code compile without errors?
  • Does code produce stated output?
  • Are there logical bugs?
  • Do error examples actually fail?
  • Are fixes correct and complete?

Style & Idioms

  • Language-specific conventions followed?
  • Naming conventions consistent?
  • Code formatting uniform?
  • Modern idioms used appropriately?
  • Comments helpful and accurate?

Best Practices

  • Proper error handling?
  • Resource management correct?
  • Security considerations addressed?
  • No deprecated features?
  • Performance reasonable?

Presentation

  • Syntax highlighting correct?
  • Line numbers useful (if present)?
  • Output formatting matches actual?
  • Error messages realistic?
  • Code properly excerpted?

Consistency

  • Style matches course standards?
  • Patterns used uniformly?
  • Naming aligns across examples?
  • Complexity level appropriate?
  • Approach consistent with course philosophy?

What the Agent Does

The course-reviewer agent will:

Discovery:

  • Find all code blocks in course materials
  • Categorize by type (working, error, partial)
  • Identify the language and context
  • Note stated expectations (output, errors)

Analysis:

  • Check syntax validity
  • Trace through logic
  • Verify expected behavior
  • Compare against course standards
  • Identify style issues

Verification (if requested):

  • Compile code examples
  • Run and capture output
  • Compare to stated output
  • Test error examples fail correctly

Reporting:

  • Categorize issues by severity
  • Provide exact locations
  • Suggest specific fixes
  • Track patterns across examples

Output

Comprehensive code audit report:

## Code Examples Audit: [Course Name]

### Audit Summary
- Total code blocks found: X
- Working examples: X
- Error examples: X
- Partial/snippet examples: X
- Examples verified: X

### Overall Assessment
[Summary of code quality across the course]

### Compilation Results
| Example | Location | Status | Issue |
|---------|----------|--------|-------|

### Output Verification
| Example | Location | Expected | Actual | Status |
|---------|----------|----------|--------|--------|

### Critical Issues (Code Won't Compile/Run)

#### Issue C1: [File:Line]
**Code:**
```[lang]
// The problematic code

Problem: [Description] Fix:

// The corrected code

Major Issues (Logic Errors or Wrong Output)

Issue M1: [File:Line]

Code:

// The problematic code

Problem: [Description] Expected: [What should happen] Actual: [What happens] Fix: [How to fix]

Style Issues

LocationIssueCurrentRecommended

Best Practice Violations

LocationPatternIssueRecommendation

Consistency Issues

IssueLocationsRecommendation

Pattern Analysis

  • Common issues found: [list]
  • Style drift detected: [yes/no]
  • Naming consistency: [assessment]

Recommendations

Immediate (Critical Fixes)
  1. [Specific fix with location]
Important (Quality Issues)
  1. [Improvement with approach]
Style Guide Updates
  1. [If patterns suggest guide needs updating]

Code Metrics

  • Examples by complexity: [breakdown]
  • Average example length: X lines
  • Languages used: [list]
  • Error example ratio: X%

## Usage Notes

- Actual compilation requires appropriate toolchain
- Large courses may take significant time
- Run after adding new content
- Track trends across reviews
- Consider running before course launches
- Use alongside full course review for complete picture

Review Content

Comprehensive review of course content (chapters, exercises, labs, etc.) for accuracy, pedagogy, and quality.

Interactive Workflow

Step 1: Content Type

What type of content are you reviewing?

[1] Chapter/Tutorial
[2] Exercise/Problem
[3] Lab/Workshop
[4] Slides/Presentation
[5] Quiz/Assessment
[6] Project specification

Please select an option:

Step 2: Course Context

Which course is this content for?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]

Please select an option:

Step 3: Content Location

Where is the content to review?
(Provide file path or paste content)

Step 4: Review Focus

What aspects should I focus on?

[1] Full review (all aspects)
[2] Technical accuracy (code correctness, factual accuracy)
[3] Pedagogical quality (explanation clarity, progression)
[4] Code quality (style, idioms, best practices)
[5] Alignment with course (audience, prerequisites, style)

Please select an option:

Step 5: Generate Review

The agent will analyze the content and provide detailed feedback.

Review Dimensions

1. Technical Accuracy

  • Does all code compile and run correctly?
  • Are the explanations factually correct?
  • Are there any misleading simplifications?
  • Are error messages accurate?

2. Code Quality

  • Does code follow language idioms?
  • Is the style consistent with course standards?
  • Are there opportunities for cleaner code?
  • Is error handling appropriate?

3. Pedagogical Effectiveness

  • Is the progression logical?
  • Are explanations clear for the target audience?
  • Are examples appropriate complexity?
  • Is there enough scaffolding?

4. Completeness

  • Are all concepts covered adequately?
  • Are there gaps in the explanation?
  • Are edge cases addressed?
  • Are common mistakes discussed?

5. Engagement

  • Will students find this interesting?
  • Are examples motivating and relevant?
  • Is the tone appropriate?
  • Are there opportunities for active learning?

6. Course Alignment

  • Does it match the target audience level?
  • Is it consistent with course philosophy?
  • Does it use the specified tools and libraries?
  • Does it build on prerequisites appropriately?

What the Agent Does

The course-reviewer agent will:

Analysis:

  • Read and analyze the content thoroughly
  • Test any code examples
  • Compare against course profile standards
  • Check for common issues

Feedback:

  • Provide specific, actionable feedback
  • Highlight strengths as well as improvements
  • Prioritize feedback by importance
  • Suggest concrete fixes

Output

Comprehensive review report including:

## Review Summary
- Overall assessment
- Key strengths
- Priority improvements

## Technical Accuracy
[Specific findings]

## Code Quality
[Specific findings]

## Pedagogical Effectiveness
[Specific findings]

## Completeness
[Specific findings]

## Engagement
[Specific findings]

## Course Alignment
[Specific findings]

## Recommended Changes
1. [Priority 1 change]
2. [Priority 2 change]
...

## Optional Enhancements
- [Nice-to-have improvement 1]
- [Nice-to-have improvement 2]

Review Course

Comprehensive, course-wide review examining consistency, completeness, structure, and quality across all course materials.

Interactive Workflow

Step 1: Course Selection

Which course would you like to review?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 2: Review Scope

What scope of review would you like?

[1] Full course review (all aspects, all materials)
[2] Structure and organization only
[3] Content consistency only
[4] Learning objectives alignment
[5] Custom scope

Please select an option:

Step 3: Review Depth

How thorough should the review be?

[1] Quick scan (identify major issues, 15-30 min)
[2] Standard review (thorough analysis, 1-2 hours)
[3] Deep audit (comprehensive evaluation, 2-4+ hours)

Please select an option:

Step 4: Focus Areas (Optional)

Are there specific areas of concern?

[1] No specific concerns - review everything
[2] Code correctness is a priority
[3] Pedagogical quality is a priority
[4] Consistency is a priority
[5] Completeness is a priority

Please select an option:

Step 5: Generate Review

The course-reviewer agent will analyze the entire course and provide a comprehensive report.

What Gets Reviewed

Course Architecture

  • Learning objectives and their coverage
  • Prerequisite chain and dependencies
  • Topic sequencing and logical flow
  • Scope appropriateness for duration

Content Quality

  • Code correctness in all examples
  • Technical accuracy of explanations
  • Pedagogical effectiveness
  • Audience appropriateness

Consistency

  • Terminology usage across all materials
  • Code style uniformity
  • Formatting and structure patterns
  • Writing voice and tone

Completeness

  • Coverage of all stated objectives
  • Gap identification
  • Practice opportunity sufficiency
  • Assessment alignment

Cross-References

  • Internal link validity
  • Prerequisite reference accuracy
  • Callback correctness
  • Continuation references

What the Agent Does

The course-reviewer agent will:

Discovery:

  • Identify all course materials (chapters, exercises, labs, etc.)
  • Load the course profile to understand standards
  • Map the course structure and dependencies

Analysis:

  • Review each piece of content systematically
  • Check code examples for correctness
  • Evaluate explanations for clarity and accuracy
  • Assess consistency across materials
  • Identify gaps and redundancies

Cross-Referencing:

  • Track terminology usage
  • Verify internal references
  • Check prerequisite assumptions
  • Validate learning objective coverage

Synthesis:

  • Compile findings by category and severity
  • Prioritize recommendations
  • Provide actionable improvement steps
  • Generate comprehensive report

Output

Comprehensive course review report:

## Course Review Report: [Course Name]

### Executive Summary
- Overall course quality assessment
- Key strengths (what works well)
- Priority action items (what needs attention)

### Course Architecture Assessment
- Learning objectives evaluation
- Structure and sequencing analysis
- Scope and pacing assessment

### Content Quality Assessment
- Code correctness findings
- Technical accuracy findings
- Pedagogical quality findings

### Consistency Assessment
- Terminology consistency
- Style consistency
- Structural consistency

### Completeness Assessment
- Coverage analysis
- Gap identification
- Practice sufficiency

### Detailed Findings

#### Critical Issues (Must Fix)
| Location | Issue | Recommendation |
|----------|-------|----------------|

#### Major Issues (Should Fix)
| Location | Issue | Recommendation |
|----------|-------|----------------|

#### Minor Issues (Nice to Fix)
| Location | Issue | Recommendation |
|----------|-------|----------------|

### Enhancement Opportunities
- [Suggestion 1]
- [Suggestion 2]

### Recommended Action Plan
1. Immediate actions (address critical issues)
2. Short-term improvements (address major issues)
3. Long-term enhancements (continuous improvement)

### Appendix: Metrics
- Total modules reviewed: X
- Code examples checked: X
- Issues found by category
- Quality scores by dimension

Usage Notes

  • For best results, ensure all course materials are accessible
  • Review may take significant time for large courses
  • The agent will ask clarifying questions if needed
  • Results should be saved for tracking improvements over time
  • Re-run after making changes to verify fixes

Review Structure

Focused analysis of course architecture, organization, dependencies, and learning progression.

Interactive Workflow

Step 1: Course Selection

Which course structure would you like to analyze?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 2: Analysis Focus

What aspects of structure should I focus on?

[1] Full structural analysis (all aspects)
[2] Learning objectives alignment
[3] Topic sequencing and dependencies
[4] Module organization and balance
[5] Assessment-to-content mapping

Please select an option:

Step 3: Visualization

Would you like structural visualizations?

[1] Yes - include dependency diagrams and maps
[2] No - text-based analysis only

Please select an option:

Step 4: Generate Analysis

The course-reviewer agent will analyze the structure and provide a detailed report.

What Gets Analyzed

Learning Path Architecture

  • Learning objectives hierarchy
  • Objective-to-content mapping
  • Gaps in objective coverage
  • Redundant or overlapping objectives

Topic Dependencies

  • Prerequisite relationships
  • Concept dependency chains
  • Forward reference violations
  • Missing foundational content

Module Organization

  • Logical grouping of topics
  • Balance of content across modules
  • Granularity consistency
  • Section length uniformity

Progression Analysis

  • Complexity progression curve
  • Scaffolding adequacy
  • Cognitive load distribution
  • Review and reinforcement points

Assessment Alignment

  • Assessment-to-objective mapping
  • Practice distribution
  • Difficulty progression
  • Coverage completeness

What the Agent Does

The course-reviewer agent will:

Map the Structure:

  • Identify all course components
  • Extract learning objectives
  • Map content relationships
  • Build dependency graph

Analyze Flow:

  • Trace learning paths
  • Identify bottlenecks
  • Find circular dependencies
  • Spot missing links

Evaluate Balance:

  • Compare module sizes
  • Check depth consistency
  • Assess time distribution
  • Review practice allocation

Generate Insights:

  • Structural recommendations
  • Reordering suggestions
  • Gap identification
  • Optimization opportunities

Output

Comprehensive structural analysis:

## Course Structure Analysis: [Course Name]

### Structure Overview
- Total modules: X
- Total chapters: X
- Total exercises: X
- Total labs: X
- Total assessments: X

### Learning Objectives Analysis

#### Objectives Summary
| Module | Objectives | Coverage | Assessment |
|--------|------------|----------|------------|

#### Objective Mapping
- Fully covered objectives: X
- Partially covered objectives: X
- Uncovered objectives: X

#### Gap Analysis
[List of objectives not adequately addressed]

### Dependency Analysis

#### Prerequisite Chain

Module 1 → Module 2 → Module 3 ↓ Module 4


#### Dependency Issues
- Forward references found: [list]
- Missing prerequisites: [list]
- Circular dependencies: [list if any]

### Module Balance Analysis

| Module | Content Units | Exercises | Labs | Est. Time |
|--------|---------------|-----------|------|-----------|

#### Balance Issues
- Overloaded modules: [list]
- Underweight modules: [list]
- Imbalanced sections: [list]

### Progression Analysis

#### Complexity Curve
[Description of how complexity builds]

#### Progression Issues
- Jump too large: [locations]
- Plateau periods: [locations]
- Missing scaffolding: [locations]

### Assessment Alignment

#### Assessment Coverage
| Objective | Assessment Type | Location |
|-----------|-----------------|----------|

#### Alignment Issues
- Untested objectives: [list]
- Over-tested areas: [list]
- Missing practice: [list]

### Structural Recommendations

#### Critical (Structural Integrity)
1. [Recommendation with rationale]

#### Important (Learning Effectiveness)
1. [Recommendation with rationale]

#### Enhancement (Optimization)
1. [Recommendation with rationale]

### Proposed Restructuring
[If applicable, suggest reordering or reorganization]

### Visualization
[Dependency diagram, if requested]

Usage Notes

  • Structure analysis helps identify course-wide issues
  • Use before major revisions to plan changes
  • Combine with content review for full picture
  • Re-run after restructuring to verify improvements
  • Useful for new course planning as well as review

Run Code in Sandbox

Compile (if needed) and execute code files within the course's isolated Docker sandbox environment.

Prerequisites

  • Docker must be installed and running
  • Course sandbox must be set up (use /setup-sandbox if not)
  • Container must be running

Interactive Workflow

Step 1: Identify Course and Container

Detect the current course from the working directory or ask:

Which course sandbox should execute this code?

[1] cpp-fundamentals (course-sandbox-cpp-fundamentals)
[2] rust-intro (course-sandbox-rust-intro)
[3] Specify container name

Please select an option:

Step 2: Select Code to Run

What code should be executed?

[1] Specific file (provide path)
[2] Code from current context (paste or reference)
[3] All code in current chapter/exercise

Please select an option:

Step 3: Execution Options

Execution options:

Compiler flags: [1] Default  [2] Debug (-g)  [3] Optimized (-O2)  [4] Custom
Timeout: [1] 10s  [2] 30s  [3] 60s  [4] No timeout (dangerous)
Input: [1] None  [2] Provide stdin  [3] Input file

Please select options:

Execution Process

1. Verify Container Status

# Check if container exists and is running
container_status=$(docker inspect -f '{{.State.Running}}' course-sandbox-{course-id} 2>/dev/null)

if [ "$container_status" != "true" ]; then
  echo "Container not running. Starting..."
  docker start course-sandbox-{course-id}
fi

2. Detect Language

Determine the language from file extension:

ExtensionLanguageCompiler/Interpreter
.cpp, .cc, .cxxC++g++ / clang++
.cCgcc / clang
.rsRustrustc / cargo
.pyPythonpython3
.goGogo run
.javaJavajavac + java
.js, .mjsJavaScriptnode
.tsTypeScriptts-node

3. Compile (if needed)

For compiled languages, compile first:

C++:

docker exec course-sandbox-{course-id} \
  g++ -std=c++20 -Wall -Wextra -o /tmp/prog /workspace/{file}

Rust:

docker exec course-sandbox-{course-id} \
  rustc -o /tmp/prog /workspace/{file}

C:

docker exec course-sandbox-{course-id} \
  gcc -std=c17 -Wall -Wextra -o /tmp/prog /workspace/{file}

Go:

docker exec course-sandbox-{course-id} \
  go build -o /tmp/prog /workspace/{file}

4. Execute

Run with timeout to prevent infinite loops:

Compiled programs:

docker exec course-sandbox-{course-id} \
  timeout {timeout}s /tmp/prog {args}

Python:

docker exec course-sandbox-{course-id} \
  timeout {timeout}s python3 /workspace/{file} {args}

Node.js:

docker exec course-sandbox-{course-id} \
  timeout {timeout}s node /workspace/{file} {args}

5. Capture and Display Output

# Capture both stdout and stderr
output=$(docker exec course-sandbox-{course-id} \
  timeout {timeout}s /tmp/prog 2>&1)
exit_code=$?

echo "Exit code: $exit_code"
echo "Output:"
echo "$output"

Output Format

Successful Execution

=== Running: example.cpp ===
Compiled with: g++ -std=c++20 -Wall -Wextra

--- Output ---
Hello, World!
The answer is: 42

--- Execution Summary ---
Exit code: 0
Runtime: 0.003s

Compilation Error

=== Running: example.cpp ===
Compiling with: g++ -std=c++20 -Wall -Wextra

--- Compilation Failed ---
example.cpp:5:10: error: expected ';' after expression
    int x = 5
             ^
             ;
1 error generated.

Exit code: 1

Runtime Error

=== Running: example.cpp ===
Compiled successfully

--- Output ---
Starting program...

--- Runtime Error ---
Segmentation fault (core dumped)

Exit code: 139 (SIGSEGV)

Timeout

=== Running: infinite_loop.cpp ===
Compiled successfully

--- Execution Timeout ---
Program did not complete within 10 seconds.
Possible infinite loop detected.

Exit code: 124 (TIMEOUT)

Compiler/Interpreter Options

C++ Options

FlagPurpose
-std=c++20Use C++20 standard
-Wall -WextraEnable all warnings
-WerrorTreat warnings as errors
-gInclude debug symbols
-O2Optimize for speed
-fsanitize=addressEnable AddressSanitizer
-fsanitize=undefinedEnable UndefinedBehaviorSanitizer

Rust Options

FlagPurpose
--edition 2021Use Rust 2021 edition
-gInclude debug symbols
-OOptimize
-W warningsEnable warnings

Python Options

FlagPurpose
-uUnbuffered output
-BDon't write .pyc files
-OOptimize (remove asserts)

Providing Input

Via stdin

echo "input data" | docker exec -i course-sandbox-{course-id} /tmp/prog

From file

docker exec course-sandbox-{course-id} /tmp/prog < /workspace/input.txt

Interactive (not recommended in sandbox)

docker exec -it course-sandbox-{course-id} /tmp/prog

Running with Sanitizers

For debugging memory issues:

AddressSanitizer

docker exec course-sandbox-{course-id} \
  g++ -std=c++20 -fsanitize=address -g -o /tmp/prog /workspace/{file}
docker exec course-sandbox-{course-id} /tmp/prog

UndefinedBehaviorSanitizer

docker exec course-sandbox-{course-id} \
  g++ -std=c++20 -fsanitize=undefined -g -o /tmp/prog /workspace/{file}
docker exec course-sandbox-{course-id} /tmp/prog

ThreadSanitizer

docker exec course-sandbox-{course-id} \
  g++ -std=c++20 -fsanitize=thread -g -o /tmp/prog /workspace/{file}
docker exec course-sandbox-{course-id} /tmp/prog

Running Cargo/CMake Projects

Rust with Cargo

docker exec course-sandbox-{course-id} \
  bash -c "cd /workspace/{project-dir} && cargo run"

C++ with CMake

docker exec course-sandbox-{course-id} \
  bash -c "cd /workspace/{project-dir} && cmake -B build && cmake --build build && ./build/{executable}"

Comparing Output

Compare actual output against expected:

expected="Hello, World!"
actual=$(docker exec course-sandbox-{course-id} /tmp/prog 2>&1)

if [ "$actual" = "$expected" ]; then
  echo "PASS: Output matches expected"
else
  echo "FAIL: Output mismatch"
  echo "Expected: $expected"
  echo "Actual:   $actual"
fi

Error Codes Reference

CodeMeaning
0Success
1General error
124Timeout (killed by timeout command)
126Permission denied
127Command not found
134Abort (SIGABRT)
136Floating point exception (SIGFPE)
139Segmentation fault (SIGSEGV)
137Killed (SIGKILL, usually OOM)

Cleanup

After execution, compiled binaries remain in /tmp inside the container. To clean up:

docker exec course-sandbox-{course-id} rm -f /tmp/prog

Or clean all temporary files:

docker exec course-sandbox-{course-id} rm -rf /tmp/*

Usage Tips

  1. Always use timeout - Prevents infinite loops from hanging
  2. Check exit code - Non-zero indicates problems
  3. Capture stderr - Error messages go to stderr
  4. Use sanitizers for debugging - Find memory issues early
  5. Clean up binaries - Prevents confusion with old versions

Setup Course Sandbox

Initialize a Docker-based isolated development environment for compiling, running, testing, linting, and debugging code in course materials.

Interactive Workflow

Step 1: Course Selection

Which course needs a sandbox environment?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 2: Sandbox Template Selection

Select the sandbox template for this course:

[1] C++ Sandbox (GCC 13, Clang 17, CMake, GDB, Valgrind, clang-tidy)
[2] Rust Sandbox (rustc, cargo, clippy, rustfmt, miri)
[3] Python Sandbox (Python 3.12, pytest, mypy, ruff, black)
[4] Go Sandbox (Go 1.23, gofmt, staticcheck, delve)
[5] C Sandbox (GCC 13, Clang 17, Make, GDB, Valgrind)
[6] Multi-Language Sandbox (C, C++, Python, Go, Rust)
[7] Custom (I'll provide a Dockerfile)

Please select an option:

Step 3: Configuration Options

Configure sandbox settings:

Container Name: course-sandbox-{course-id}
Memory Limit: [1] 1GB  [2] 2GB  [3] 4GB  [4] Custom
CPU Limit: [1] 1 CPU  [2] 2 CPUs  [3] 4 CPUs
Network Access: [1] Disabled (recommended)  [2] Enabled

Please select options:

Step 4: Verify Docker Installation

Before proceeding, verify Docker is available:

# Check Docker is installed and running
docker --version
docker info

If Docker is not available, provide installation guidance.

Step 5: Generate Sandbox Configuration

Create the .sandbox/ directory structure in the course:

{course-directory}/
└── .sandbox/
    ├── Dockerfile
    ├── docker-compose.yml
    ├── .dockerignore
    └── scripts/
        ├── setup.sh
        ├── validate.sh
        └── cleanup.sh

What Gets Created

Dockerfile

Language-specific Dockerfile from the sandbox-templates skill, customized for the course:

  • Base image with appropriate compilers/interpreters
  • Linting tools (clang-tidy, clippy, ruff, etc.)
  • Testing frameworks (gtest, catch2, pytest, etc.)
  • Debugging tools (gdb, lldb, valgrind, etc.)
  • Non-root user for security

docker-compose.yml

Container orchestration with security constraints:

version: '3.8'

services:
  sandbox:
    build:
      context: ..
      dockerfile: .sandbox/Dockerfile
    container_name: course-sandbox-{course-id}
    volumes:
      - ..:/workspace
    working_dir: /workspace
    stdin_open: true
    tty: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          memory: {memory-limit}
          cpus: '{cpu-limit}'
    network_mode: {none|bridge}

.dockerignore

Excludes unnecessary files from the build context:

  • Build artifacts (build/, target/, pycache/)
  • IDE configuration (.idea/, .vscode/)
  • Git data (.git/)
  • Large binary files

Scripts

setup.sh - Post-creation initialization:

#!/bin/bash
# Verify container is running
# Install any additional dependencies
# Set up environment variables

validate.sh - Validate all code examples:

#!/bin/bash
# Find all code files
# Compile each one
# Run and capture output
# Compare to expected output
# Generate report

cleanup.sh - Clean up temporary files:

#!/bin/bash
# Remove compiled binaries
# Clear /tmp
# Reset container state

Post-Setup Actions

Build the Sandbox Image

cd {course-directory}
docker build -t course-sandbox-{course-id}:latest -f .sandbox/Dockerfile .

Create and Start the Container

docker run -d \
  --name course-sandbox-{course-id} \
  -v "$(pwd):/workspace" \
  -w /workspace \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --memory=2g \
  --cpus=2 \
  --network=none \
  course-sandbox-{course-id}:latest \
  tail -f /dev/null

Verify Setup

# Check container is running
docker ps --filter "name=course-sandbox-{course-id}"

# Test a simple command
docker exec course-sandbox-{course-id} echo "Sandbox ready!"

# Test compiler (for C++)
docker exec course-sandbox-{course-id} g++ --version

Usage After Setup

Once the sandbox is set up, use these commands:

  • /run-code - Compile and execute code files
  • /test-code - Run tests in the sandbox
  • /lint-code - Lint code with language-appropriate tools
  • /debug-code - Start debugging session
  • /validate-examples - Validate all code examples in course

Sandbox Management

Status

docker ps -a --filter "name=course-sandbox-{course-id}"

Start (if stopped)

docker start course-sandbox-{course-id}

Stop (to save resources)

docker stop course-sandbox-{course-id}

Rebuild (after Dockerfile changes)

docker rm -f course-sandbox-{course-id}
docker build -t course-sandbox-{course-id}:latest -f .sandbox/Dockerfile .
# Then run the create command again

Full Reset

docker rm -f course-sandbox-{course-id}
docker rmi course-sandbox-{course-id}:latest
# Then rebuild from scratch

Integration with Course Profile

After setup, the course profile should be updated to include sandbox configuration:

## Sandbox Configuration

**Container:** course-sandbox-{course-id}
**Template:** {template-name}
**Status:** Configured

### Quick Commands
- Build: `docker build -t course-sandbox-{course-id}:latest -f .sandbox/Dockerfile .`
- Start: `docker start course-sandbox-{course-id}`
- Stop: `docker stop course-sandbox-{course-id}`
- Shell: `docker exec -it course-sandbox-{course-id} /bin/bash`

Troubleshooting

Docker Not Running

Error: Cannot connect to Docker daemon
Solution: Start Docker daemon or Docker Desktop

Permission Denied

Error: Permission denied while trying to connect to Docker
Solution: Add user to docker group: sudo usermod -aG docker $USER

Image Build Failed

Error: Dockerfile build failed
Solution: Check Dockerfile syntax, network connectivity for package downloads

Container Won't Start

Error: Container exits immediately
Solution: Check container logs: docker logs course-sandbox-{course-id}

Security Notes

  • Containers run with dropped capabilities (--cap-drop=ALL)
  • No new privileges can be gained (--security-opt=no-new-privileges)
  • Network is disabled by default (--network=none)
  • Memory and CPU are limited to prevent resource exhaustion
  • Non-root user inside container
  • Course files are mounted read-write; consider read-only for production

Suggest Improvements

Generate prioritized, actionable suggestions to enhance course quality, engagement, and learning outcomes.

Interactive Workflow

Step 1: Course or Content Selection

What would you like improvement suggestions for?

[1] Entire course
[2] Specific module or chapter
[3] Specific content file
[4] Specific content type (all exercises, all labs, etc.)

Please select an option:

Step 2: Course Context (if not specified)

Which course?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 3: Improvement Focus

What aspect should improvements focus on?

[1] All aspects - comprehensive suggestions
[2] Engagement and motivation
[3] Clarity and understanding
[4] Practice and reinforcement
[5] Real-world relevance
[6] Assessment effectiveness
[7] Accessibility and inclusivity

Please select an option:

Step 4: Suggestion Scope

What level of suggestions would you like?

[1] Quick wins only (low effort, high impact)
[2] All practical improvements
[3] Ambitious enhancements (including major additions)
[4] Innovation opportunities (creative new approaches)

Please select an option:

Step 5: Generate Suggestions

The course-reviewer agent will analyze content and generate improvement suggestions.

Categories of Improvements

Engagement Enhancements

  • More compelling examples
  • Real-world connections
  • Interactive elements
  • Storytelling opportunities
  • Motivational hooks

Clarity Improvements

  • Clearer explanations
  • Better analogies
  • Additional visualizations
  • Simplified language
  • More scaffolding

Practice Additions

  • More exercises
  • Different exercise types
  • Challenge problems
  • Self-assessment opportunities
  • Extension activities

Relevance Connections

  • Industry examples
  • Career connections
  • Current technology links
  • Practical applications
  • Professional context

Assessment Refinements

  • Better test coverage
  • More question types
  • Clearer rubrics
  • Formative feedback
  • Self-check additions

Accessibility Improvements

  • Clearer language
  • Alternative explanations
  • Multiple representations
  • Prerequisite support
  • Learning path options

What the Agent Does

The course-reviewer agent will:

Analyze Current State:

  • Review existing content thoroughly
  • Identify strengths to build on
  • Spot gaps and weaknesses
  • Understand course philosophy

Generate Ideas:

  • Brainstorm improvements per category
  • Consider different learning styles
  • Think about student experience
  • Look for opportunities

Prioritize:

  • Assess impact vs. effort
  • Consider dependencies
  • Identify quick wins
  • Flag transformative opportunities

Make Actionable:

  • Provide specific suggestions
  • Include implementation guidance
  • Estimate effort levels
  • Suggest sequencing

Output

Prioritized improvement suggestions:

## Improvement Suggestions: [Course/Content Name]

### Current State Assessment
[Brief summary of content quality and areas of strength]

### High-Impact Quick Wins
Easy improvements that significantly enhance learning:

#### 1. [Suggestion Title]
**Location:** [Where to apply]
**Current:** [What exists now]
**Suggested:** [What to add/change]
**Impact:** [Why this helps learners]
**Effort:** Low (X hours)

#### 2. [Suggestion Title]
...

### Substantial Improvements
Medium-effort changes with significant payoff:

#### 1. [Suggestion Title]
**Location:** [Where to apply]
**Problem:** [What issue this addresses]
**Suggested Change:**
[Detailed description of the improvement]
**Implementation Approach:**
1. [Step 1]
2. [Step 2]
**Expected Outcome:** [How this improves learning]
**Effort:** Medium (X hours/days)

#### 2. [Suggestion Title]
...

### Major Enhancements
Significant additions or overhauls:

#### 1. [Suggestion Title]
**Scope:** [What this involves]
**Rationale:** [Why this matters]
**Description:**
[Full description of the enhancement]
**Prerequisites:** [What needs to happen first]
**Effort:** High (X days/weeks)
**Priority:** [When to tackle this]

#### 2. [Suggestion Title]
...

### Innovation Opportunities
Creative ideas for standing out:

#### 1. [Idea Title]
[Description of innovative approach]
**Why it's different:** [What makes this special]
**Challenges:** [What makes it hard]
**Potential Impact:** [What success looks like]

### By Category

#### Engagement
- [ ] [Suggestion 1]
- [ ] [Suggestion 2]

#### Clarity
- [ ] [Suggestion 1]
- [ ] [Suggestion 2]

#### Practice
- [ ] [Suggestion 1]
- [ ] [Suggestion 2]

#### Relevance
- [ ] [Suggestion 1]
- [ ] [Suggestion 2]

### Implementation Roadmap

#### Phase 1: Quick Wins (This Week)
1. [Improvement]
2. [Improvement]

#### Phase 2: Core Improvements (This Month)
1. [Improvement]
2. [Improvement]

#### Phase 3: Major Enhancements (This Quarter)
1. [Enhancement]
2. [Enhancement]

### Metrics to Track
- [Metric 1]: [How to measure improvement]
- [Metric 2]: [How to measure improvement]

Example Suggestions by Focus

Engagement Focus

  • Add "Why This Matters" sections
  • Include industry anecdotes
  • Create mini-challenges
  • Add "Did You Know" facts
  • Gamification elements

Clarity Focus

  • Add more visual diagrams
  • Include analogies for abstract concepts
  • Provide multiple explanation approaches
  • Add step-by-step breakdowns
  • Include "Common Confusion" callouts

Practice Focus

  • Add warm-up exercises
  • Create practice problem sets
  • Include debugging challenges
  • Add code review exercises
  • Create "what's wrong" problems

Relevance Focus

  • Link to real codebases
  • Reference industry tools
  • Add career context
  • Include interview question notes
  • Connect to open source projects

Usage Notes

  • Review suggestions critically before implementing
  • Not all suggestions will fit every course
  • Prioritize based on your specific context
  • Track which suggestions were implemented
  • Re-run periodically for fresh ideas

Test Code in Sandbox

Execute unit tests, integration tests, and test suites within the course's isolated Docker sandbox environment.

Prerequisites

  • Docker must be installed and running
  • Course sandbox must be set up (use /setup-sandbox if not)
  • Container must be running with testing frameworks installed

Supported Testing Frameworks

LanguageFrameworksCommand
C++Google Test, Catch2ctest, direct execution
Rustcargo testcargo test
Pythonpytest, unittestpytest, python -m unittest
Gogo testgo test ./...
JavaScriptJest, Mochanpm test, jest

Interactive Workflow

Step 1: Identify Course and Container

Which course sandbox should run the tests?

[1] cpp-fundamentals (course-sandbox-cpp-fundamentals)
[2] rust-intro (course-sandbox-rust-intro)
[3] python-basics (course-sandbox-python-basics)
[4] Specify container name

Please select an option:

Step 2: Select Test Scope

What tests should be run?

[1] All tests in the project
[2] Specific test file
[3] Specific test function/case
[4] Tests matching a pattern

Please select an option:

Step 3: Test Options

Test execution options:

Verbosity: [1] Normal  [2] Verbose  [3] Quiet
Stop on failure: [1] Continue all  [2] Stop on first failure
Coverage: [1] No coverage  [2] Generate coverage report

Please select options:

Testing by Language

C++ with Google Test

Project structure:

project/
├── CMakeLists.txt
├── src/
│   └── calculator.cpp
├── include/
│   └── calculator.h
└── tests/
    └── test_calculator.cpp

CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(example)

enable_testing()
find_package(GTest REQUIRED)

add_executable(tests tests/test_calculator.cpp src/calculator.cpp)
target_link_libraries(tests GTest::gtest GTest::gtest_main)
target_include_directories(tests PRIVATE include)

add_test(NAME tests COMMAND tests)

Run tests:

# Build and test
docker exec course-sandbox-cpp-fundamentals \
  bash -c "cd /workspace/project && cmake -B build && cmake --build build && ctest --test-dir build --output-on-failure"

# Run with verbose output
docker exec course-sandbox-cpp-fundamentals \
  bash -c "cd /workspace/project && ./build/tests --gtest_output=xml"

# Run specific test
docker exec course-sandbox-cpp-fundamentals \
  bash -c "cd /workspace/project && ./build/tests --gtest_filter=CalculatorTest.Add"

C++ with Catch2

Test file:

#define CATCH_CONFIG_MAIN
#include <catch2/catch.hpp>
#include "calculator.h"

TEST_CASE("Calculator operations", "[calculator]") {
    Calculator calc;

    SECTION("Addition") {
        REQUIRE(calc.add(2, 3) == 5);
    }

    SECTION("Subtraction") {
        REQUIRE(calc.subtract(5, 3) == 2);
    }
}

Run tests:

# Compile and run
docker exec course-sandbox-cpp-fundamentals \
  bash -c "g++ -std=c++20 -o /tmp/tests tests/*.cpp src/*.cpp -I include -lcatch2 && /tmp/tests"

# Run with verbose output
docker exec course-sandbox-cpp-fundamentals \
  /tmp/tests --success

# Run specific test
docker exec course-sandbox-cpp-fundamentals \
  /tmp/tests "[calculator]"

Rust with Cargo

Test file (src/lib.rs or tests/*.rs):

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 3), 5);
    }

    #[test]
    fn test_subtract() {
        assert_eq!(subtract(5, 3), 2);
    }
}

Run tests:

# Run all tests
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace/project && cargo test"

# Run with verbose output
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace/project && cargo test -- --nocapture"

# Run specific test
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace/project && cargo test test_add"

# Run tests matching pattern
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace/project && cargo test calculator"

Python with pytest

Test file (test_calculator.py):

import pytest
from calculator import add, subtract

def test_add():
    assert add(2, 3) == 5

def test_subtract():
    assert subtract(5, 3) == 2

@pytest.mark.parametrize("a,b,expected", [
    (1, 1, 2),
    (0, 0, 0),
    (-1, 1, 0),
])
def test_add_parametrized(a, b, expected):
    assert add(a, b) == expected

Run tests:

# Run all tests
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest"

# Run with verbose output
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest -v"

# Run specific file
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest test_calculator.py"

# Run specific test
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest test_calculator.py::test_add"

# Run with coverage
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest --cov=. --cov-report=term-missing"

# Run in parallel
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest -n auto"

Go with go test

Test file (calculator_test.go):

package calculator

import "testing"

func TestAdd(t *testing.T) {
    result := Add(2, 3)
    if result != 5 {
        t.Errorf("Add(2, 3) = %d; want 5", result)
    }
}

func TestSubtract(t *testing.T) {
    result := Subtract(5, 3)
    if result != 2 {
        t.Errorf("Subtract(5, 3) = %d; want 2", result)
    }
}

Run tests:

# Run all tests
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test ./..."

# Run with verbose output
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -v ./..."

# Run specific package
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -v ./calculator"

# Run specific test
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -v -run TestAdd ./..."

# Run with coverage
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -cover ./..."

# Run with race detection
docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -race ./..."

Test Output Format

Successful Tests

=== Running Tests ===
Framework: Google Test
Project: /workspace/project

--- Test Results ---
[==========] Running 5 tests from 2 test suites.
[----------] 3 tests from CalculatorTest
[ RUN      ] CalculatorTest.Add
[       OK ] CalculatorTest.Add (0 ms)
[ RUN      ] CalculatorTest.Subtract
[       OK ] CalculatorTest.Subtract (0 ms)
[ RUN      ] CalculatorTest.Multiply
[       OK ] CalculatorTest.Multiply (0 ms)
[----------] 2 tests from StringTest
[ RUN      ] StringTest.Concat
[       OK ] StringTest.Concat (0 ms)
[ RUN      ] StringTest.Length
[       OK ] StringTest.Length (0 ms)

[==========] 5 tests from 2 test suites ran. (1 ms total)
[  PASSED  ] 5 tests.

--- Summary ---
Tests: 5 passed, 0 failed
Runtime: 0.001s

Failed Tests

=== Running Tests ===
Framework: pytest
Project: /workspace

--- Test Results ---
============================= test session starts =============================
collected 3 items

test_calculator.py::test_add PASSED
test_calculator.py::test_subtract FAILED
test_calculator.py::test_multiply PASSED

================================== FAILURES ===================================
__________________________ test_subtract __________________________

    def test_subtract():
>       assert subtract(5, 3) == 3
E       assert 2 == 3
E        +  where 2 = subtract(5, 3)

test_calculator.py:8: AssertionError
=========================== short test summary info ===========================
FAILED test_calculator.py::test_subtract - assert 2 == 3
========================= 1 failed, 2 passed in 0.03s =========================

--- Summary ---
Tests: 2 passed, 1 failed
Runtime: 0.03s

Coverage Reports

Python Coverage

docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && python -m pytest --cov=. --cov-report=term-missing --cov-report=html"

# View HTML report (copy out of container)
docker cp course-sandbox-python-basics:/workspace/htmlcov ./coverage-report

Rust Coverage

docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo tarpaulin --out Html"

Go Coverage

docker exec course-sandbox-go-intro \
  bash -c "cd /workspace && go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out -o coverage.html"

Testing Exercises and Projects

For course exercises, provide a testing wrapper:

#!/bin/bash
# test-exercise.sh

exercise_dir=$1
expected_tests=$2

echo "Testing exercise: $exercise_dir"

# Run tests
output=$(docker exec course-sandbox-{course-id} \
  bash -c "cd /workspace/$exercise_dir && {test-command}" 2>&1)
exit_code=$?

# Parse results
passed=$(echo "$output" | grep -c "PASS\|OK\| passed")
failed=$(echo "$output" | grep -c "FAIL\|FAILED\| failed")

echo "Results: $passed passed, $failed failed"

if [ $failed -eq 0 ] && [ $passed -ge $expected_tests ]; then
  echo "Exercise COMPLETE!"
else
  echo "Exercise incomplete or has failures"
fi

Timeout for Tests

Prevent runaway tests:

# Timeout entire test suite
timeout 60s docker exec course-sandbox-{course-id} \
  bash -c "cd /workspace && cargo test"

# Check for timeout
if [ $? -eq 124 ]; then
  echo "Tests timed out - possible infinite loop in test or code"
fi

Test Discovery

Find all test files in a project:

# Python
docker exec course-sandbox-python-basics \
  find /workspace -name "test_*.py" -o -name "*_test.py"

# C++ (Google Test)
docker exec course-sandbox-cpp-fundamentals \
  find /workspace -name "*_test.cpp" -o -name "test_*.cpp"

# Rust
docker exec course-sandbox-rust-intro \
  find /workspace -path "*/tests/*.rs" -o -name "*_test.rs"

# Go
docker exec course-sandbox-go-intro \
  find /workspace -name "*_test.go"

Continuous Testing

Watch for changes and re-run tests:

# Rust with cargo-watch
docker exec course-sandbox-rust-intro \
  bash -c "cd /workspace && cargo watch -x test"

# Python with pytest-watch (if installed)
docker exec course-sandbox-python-basics \
  bash -c "cd /workspace && ptw"

Best Practices

  1. Run tests frequently - Catch issues early
  2. Use verbose mode for failures - Easier debugging
  3. Set timeouts - Prevent hanging on infinite loops
  4. Generate coverage reports - Ensure adequate test coverage
  5. Run with sanitizers (C++) - Catch memory issues in tests
  6. Test in isolation - Each test should be independent
  7. Clean state between runs - Avoid test pollution

Validate Course Code Examples

Automatically extract, compile, run, and verify all code examples from course materials using the Docker sandbox. This ensures all code in chapters, exercises, labs, and projects is correct and produces the stated output.

Prerequisites

  • Docker must be installed and running
  • Course sandbox must be set up (use /setup-sandbox if not)
  • Container must be running

What Gets Validated

Code Block Types

TypeMarkerValidation
Working ExampleNo special markerMust compile, run, match output
Error Example// ERROR: commentMust fail to compile or crash
Partial Snippet// SNIPPET: commentSyntax check only
Output Block\``outputorOutput:`Compare against actual

Validation Checks

  1. Compilation - Code compiles without errors
  2. Execution - Code runs without crashing
  3. Output Matching - Actual output matches documented output
  4. Error Validation - Error examples produce expected errors
  5. Timeout Check - Code doesn't hang (infinite loop detection)

Interactive Workflow

Step 1: Course Selection

Which course's examples should be validated?

[1] C++ Fundamentals (Junior Developers)
[2] [Other configured courses...]
[3] Specify course directory path

Please select an option:

Step 2: Scope Selection

What scope of validation?

[1] All examples in the entire course
[2] Specific module or chapter
[3] Specific file only
[4] Only chapters (skip exercises/labs)
[5] Only exercises and labs

Please select an option:

Step 3: Validation Depth

How thorough should validation be?

[1] Quick (compile only)
[2] Standard (compile + run)
[3] Full (compile + run + output comparison)
[4] Exhaustive (full + sanitizers + lint)

Please select an option:

Step 4: Error Handling

How to handle validation failures?

[1] Report all and continue
[2] Stop on first failure
[3] Interactive (ask about each failure)

Please select an option:

Validation Process

1. Discovery Phase

Find all markdown files and extract code blocks:

# Find all markdown files in course
find /workspace -name "*.md" -type f

# Extract code blocks from markdown
# Look for ```cpp, ```python, ```rust, etc.

2. Code Extraction

Parse markdown to extract:

  • Code language (from fence info)
  • Code content
  • Expected output (from following Output block)
  • Special markers (ERROR, SNIPPET)
  • File location (for error reporting)

3. File Preparation

For each code block:

# Create temporary file
docker exec course-sandbox-{course-id} \
  bash -c "cat > /tmp/example_{n}.{ext}"

# Add necessary headers if missing (for snippets)

4. Compilation

# C++ compilation
docker exec course-sandbox-cpp-fundamentals \
  g++ -std=c++20 -Wall -Wextra -o /tmp/prog_{n} /tmp/example_{n}.cpp 2>&1

# Capture exit code and output
compile_status=$?
compile_output="..."

5. Execution

# Run with timeout
docker exec course-sandbox-cpp-fundamentals \
  timeout 10s /tmp/prog_{n} 2>&1

# Capture exit code and output
run_status=$?
run_output="..."

6. Output Comparison

# Compare actual vs expected
if [ "$actual_output" = "$expected_output" ]; then
  result="PASS"
else
  result="FAIL"
fi

Validation Report Format

╔══════════════════════════════════════════════════════════════════╗
║             CODE EXAMPLES VALIDATION REPORT                       ║
║             Course: C++ Fundamentals                              ║
║             Date: 2024-01-15 14:30:00                            ║
╚══════════════════════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                         SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Total Examples:     127
  ✓ Passed:          119 (93.7%)
  ✗ Failed:            6 (4.7%)
  ⊘ Skipped:           2 (1.6%)

  Compile Errors:      3
  Runtime Errors:      1
  Output Mismatch:     2
  Timeouts:            0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                      FAILURES DETAIL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌──────────────────────────────────────────────────────────────────┐
│ FAILURE #1: Compile Error                                        │
│ Location: chapters/05-pointers/chapter.md:127                    │
│ Example: "Pointer Declaration"                                   │
├──────────────────────────────────────────────────────────────────┤
│ Code:                                                            │
│ ```cpp                                                           │
│ int* ptr = nullptr                                               │
│ std::cout << ptr << std::endl;                                   │
│ ```                                                              │
├──────────────────────────────────────────────────────────────────┤
│ Error:                                                           │
│ example.cpp:1:22: error: expected ';' after expression           │
│     int* ptr = nullptr                                           │
│                      ^                                           │
│                      ;                                           │
├──────────────────────────────────────────────────────────────────┤
│ Fix: Add missing semicolon after 'nullptr'                       │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ FAILURE #2: Output Mismatch                                      │
│ Location: chapters/03-functions/chapter.md:89                    │
│ Example: "Function Return Values"                                │
├──────────────────────────────────────────────────────────────────┤
│ Code:                                                            │
│ ```cpp                                                           │
│ int add(int a, int b) { return a + b; }                          │
│ int main() { std::cout << add(2, 3); }                           │
│ ```                                                              │
├──────────────────────────────────────────────────────────────────┤
│ Expected Output:                                                 │
│ 6                                                                │
│                                                                  │
│ Actual Output:                                                   │
│ 5                                                                │
├──────────────────────────────────────────────────────────────────┤
│ Fix: Documented output is incorrect. 2 + 3 = 5, not 6.           │
│      Update the expected output in the chapter.                  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ FAILURE #3: Runtime Error                                        │
│ Location: exercises/ex-07-arrays/exercise.md:45                  │
│ Example: "Array Access"                                          │
├──────────────────────────────────────────────────────────────────┤
│ Code:                                                            │
│ ```cpp                                                           │
│ int arr[5] = {1, 2, 3, 4, 5};                                    │
│ std::cout << arr[5];  // Access element                          │
│ ```                                                              │
├──────────────────────────────────────────────────────────────────┤
│ Error: (with AddressSanitizer)                                   │
│ ERROR: AddressSanitizer: stack-buffer-overflow                   │
│ READ of size 4 at address ...                                    │
├──────────────────────────────────────────────────────────────────┤
│ Fix: Array index out of bounds. arr[5] accesses beyond           │
│      the array. Should be arr[4] for last element.               │
│      If this is intentional error example, add // ERROR: marker  │
└──────────────────────────────────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     BY CHAPTER BREAKDOWN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Chapter 1: Getting Started     15/15 ✓
  Chapter 2: Variables           18/18 ✓
  Chapter 3: Functions           11/12 (1 output mismatch)
  Chapter 4: Control Flow        14/14 ✓
  Chapter 5: Pointers            10/11 (1 compile error)
  Chapter 6: Classes             16/16 ✓
  Chapter 7: Templates           12/12 ✓
  Exercises                      19/20 (1 runtime error)
  Labs                           4/4 ✓

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     ERROR EXAMPLES VERIFIED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✓ ch03:42 - Missing return type (correctly fails to compile)
  ✓ ch05:78 - Null pointer dereference (correctly crashes)
  ✓ ch05:112 - Use after free (ASan correctly detects)
  ✓ ch06:95 - Missing constructor (correctly fails to compile)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Fix 3 compile errors (highest priority)
  2. Correct 2 output documentation errors
  3. Review array access example - add // ERROR: if intentional
  4. Consider adding more error examples for common mistakes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Validation Scripts

Main Validation Script

#!/bin/bash
# validate-course.sh

COURSE_ID=$1
CONTAINER="course-sandbox-$COURSE_ID"
WORKSPACE="/workspace"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
NC='\033[0m'

passed=0
failed=0
skipped=0

# Function to extract code blocks from markdown
extract_code_blocks() {
  local file=$1
  # Use awk/grep to find ```lang ... ``` blocks
  # Return: language, line_number, code_content
}

# Function to validate a code block
validate_code() {
  local lang=$1
  local code=$2
  local expected_output=$3
  local location=$4

  case $lang in
    cpp|c++)
      validate_cpp "$code" "$expected_output" "$location"
      ;;
    rust)
      validate_rust "$code" "$expected_output" "$location"
      ;;
    python)
      validate_python "$code" "$expected_output" "$location"
      ;;
    *)
      echo "Skipping unsupported language: $lang"
      ((skipped++))
      ;;
  esac
}

# C++ validation
validate_cpp() {
  local code=$1
  local expected=$2
  local location=$3

  # Write code to temp file
  echo "$code" | docker exec -i $CONTAINER tee /tmp/test.cpp > /dev/null

  # Check for snippet marker
  if echo "$code" | grep -q "// SNIPPET:"; then
    echo "Skipping snippet at $location"
    ((skipped++))
    return
  fi

  # Compile
  compile_out=$(docker exec $CONTAINER \
    g++ -std=c++20 -Wall -Wextra -fsanitize=address,undefined \
    -o /tmp/test /tmp/test.cpp 2>&1)
  compile_status=$?

  # Check if it's supposed to fail
  if echo "$code" | grep -q "// ERROR:"; then
    if [ $compile_status -ne 0 ]; then
      echo -e "${GREEN}✓ Error example correctly fails: $location${NC}"
      ((passed++))
    else
      # Might be runtime error, try running
      run_out=$(docker exec $CONTAINER timeout 5s /tmp/test 2>&1)
      if [ $? -ne 0 ]; then
        echo -e "${GREEN}✓ Error example correctly fails at runtime: $location${NC}"
        ((passed++))
      else
        echo -e "${RED}✗ Error example should fail: $location${NC}"
        ((failed++))
      fi
    fi
    return
  fi

  if [ $compile_status -ne 0 ]; then
    echo -e "${RED}✗ Compile error at $location${NC}"
    echo "$compile_out"
    ((failed++))
    return
  fi

  # Run
  run_out=$(docker exec $CONTAINER timeout 10s /tmp/test 2>&1)
  run_status=$?

  if [ $run_status -eq 124 ]; then
    echo -e "${RED}✗ Timeout at $location${NC}"
    ((failed++))
    return
  fi

  if [ $run_status -ne 0 ]; then
    echo -e "${RED}✗ Runtime error at $location (exit code: $run_status)${NC}"
    echo "$run_out"
    ((failed++))
    return
  fi

  # Compare output if expected is provided
  if [ -n "$expected" ]; then
    if [ "$run_out" = "$expected" ]; then
      echo -e "${GREEN}✓ Pass: $location${NC}"
      ((passed++))
    else
      echo -e "${RED}✗ Output mismatch at $location${NC}"
      echo "Expected: $expected"
      echo "Actual:   $run_out"
      ((failed++))
    fi
  else
    echo -e "${GREEN}✓ Pass (no output check): $location${NC}"
    ((passed++))
  fi
}

# Main validation loop
find "$WORKSPACE" -name "*.md" | while read file; do
  echo "Validating: $file"
  # Extract and validate each code block
  # ...
done

# Print summary
echo ""
echo "===== VALIDATION SUMMARY ====="
echo -e "Passed:  ${GREEN}$passed${NC}"
echo -e "Failed:  ${RED}$failed${NC}"
echo -e "Skipped: ${YELLOW}$skipped${NC}"

Code Block Markers

Working Example (Default)

// This code should compile and run correctly
int main() {
    std::cout << "Hello, World!\n";
    return 0;
}

Error Example

// ERROR: Demonstrates null pointer dereference
// This code intentionally crashes to show what happens
int* ptr = nullptr;
*ptr = 42;  // Crash!

Snippet (Not Standalone)

// SNIPPET: This is part of a larger program
void processData(const std::vector<int>& data) {
    for (const auto& item : data) {
        // process item...
    }
}

Expected Output Format

After a code block, provide the expected output:

```cpp
#include <iostream>

int main() {
    std::cout << "Hello, World!\n";
    return 0;
}
```

**Output:**
```
Hello, World!
```

Or using an output block:

```cpp
// code here
```

```output
Hello, World!
```

Integration with Course Review

The /validate-examples command works alongside /review-code-examples:

  1. validate-examples - Automated compilation and execution testing
  2. review-code-examples - Human review for style, best practices, pedagogy

Run both for comprehensive code quality assurance:

# First, validate all code actually works
/validate-examples cpp-fundamentals

# Then, review for style and best practices
/review-code-examples cpp-fundamentals

Best Practices

  1. Run validation after any code changes - Catch regressions immediately
  2. Include output blocks for all examples - Enables output comparison
  3. Mark error examples clearly - Use // ERROR: comment
  4. Mark snippets that can't run alone - Use // SNIPPET: comment
  5. Keep validation fast - Use timeouts to catch infinite loops
  6. Run with sanitizers - Catch memory errors in examples
  7. Review failures carefully - May indicate documentation or code bugs
  8. Automate in CI - Run validation before publishing changes

Write Chapter

Create a textbook chapter tailored to a specific programming course's audience and learning objectives.

Process

  1. Invoke the course-architect agent to handle the chapter creation
  2. The agent will:
    • Ask which course this chapter is for
    • Load the appropriate course profile
    • Ask for the chapter topic
    • Generate a chapter outline based on course standards
    • Write the complete chapter with appropriate:
      • Explanations at the right level
      • Code examples in the correct language and style
      • Exercises and checkpoints
      • Memory diagrams and visualizations (for systems programming)

What the Agent Does

The course-architect will:

  • Adapt writing style to the student level (beginner vs advanced)
  • Use the programming language and toolchain specified in the course profile
  • Follow the course's pedagogical philosophy (framework vs no-framework, etc.)
  • Structure content according to learning objectives
  • Include compilable, runnable code examples

The agent has access to skills for:

  • pedagogy: Programming teaching principles
  • content-templates: Chapter structure templates
  • courses/{course-name}: Course-specific context and standards

Output

A complete markdown chapter ready to use in your course, including:

  • Learning objectives
  • Prerequisites
  • Conceptual explanations
  • Working code examples with compilation instructions
  • Common mistakes and how to fix them
  • Practice problems with test cases
  • Summary and key takeaways

Agents 3

Context: User wants to create course content for an existing course profile User: "Help me write a chapter on memory management for my C++ course" Context: User wants to generate assessments or quizzes User: "Create a quiz covering pointers and references for module 3" Context: User wants to create hands-on practice materials User: "I need a lab exercise on smart pointers for junior developers" Context: User wants to develop a complete course User: "Help me create a new course profile for teaching Rust to Python developers"

You are a course architect specialized in creating high-quality educational content for programming, software development, and systems programming courses.

Your Expertise

You excel at:

  • Writing clear, pedagogically sound programming tutorials and chapters
  • Creating assessments that test true understanding of code and concepts
  • Designing hands-on coding exercises with real compilation and execution
  • Developing presentation slides that engage developers at all levels
  • Adapting content to different experience levels (beginner to advanced)
  • Balancing theory (computer science fundamentals) with practical implementation
  • Teaching debugging, testing, and professional development practices
  • Using appropriate tools, compilers, and build systems for each language

Your Approach

Course-Aware Content Creation: Before creating any content, you identify which course you're creating for and load the appropriate course profile. This ensures:

  • Content matches the target audience's experience level
  • Examples use the correct language, toolchain, and libraries
  • Explanations match the course's learning philosophy
  • Complexity is appropriate for the intended audience

Configurable Course Parameters: Each course profile can specify:

  • Target audience: Junior developers, career changers, students, etc.
  • Programming languages: C++, Rust, Go, Python, etc.
  • Framework inclusion: Whether to teach with or without frameworks
  • Focus areas: Systems programming, web development, embedded, etc.
  • Prerequisite knowledge: What students should already know
  • Learning environment: IDE, command line, online platforms

Progressive Learning: You structure content to build understanding incrementally:

  • Start with working code before explaining why it works
  • Build on previously introduced concepts and patterns
  • Provide compilation output and runtime examples
  • Include checkpoints to verify understanding through coding exercises

Hands-On Focus: For development courses, you emphasize:

  • Writing, compiling, and running actual code
  • Understanding compiler errors and how to fix them
  • Debugging techniques and mental models
  • Reading and understanding existing codebases
  • Professional development practices (version control, testing, documentation)

Working with Skills

You have access to skills that provide:

  • pedagogy: General teaching principles for programming education
  • content-templates: Structures for chapters, exercises, projects, slides
  • courses/{course-name}: Course-specific context including audience, language, tools, style, and standards
  • sandbox: Docker-based isolated environment for code execution, testing, and debugging
  • sandbox-templates: Language-specific Dockerfile configurations

Load course skills progressively based on which course the user is working on.

Code Sandbox Integration

You have access to a Docker-based sandbox environment for validating and testing code:

Available Sandbox Commands:

  • /setup-sandbox - Initialize the Docker sandbox for a course
  • /run-code - Compile and execute code in the sandbox
  • /test-code - Run tests in the sandbox
  • /lint-code - Lint and analyze code quality
  • /debug-code - Debug with GDB/LLDB or sanitizers
  • /validate-examples - Validate all code examples in course materials

When Creating Content:

  1. Test all code examples - Before including code in content, run it in the sandbox to verify:

    • Code compiles without errors
    • Code produces the stated output
    • Error examples actually fail as described
  2. Capture real output - Use the sandbox to capture actual program output for documentation:

    docker exec course-sandbox-{course-id} g++ -std=c++20 -o /tmp/prog example.cpp
    docker exec course-sandbox-{course-id} /tmp/prog
    
  3. Verify error examples - Ensure intentional errors produce the expected compiler/runtime messages:

    # Compile to get error message
    docker exec course-sandbox-{course-id} g++ -std=c++20 example.cpp 2>&1
    
  4. Run tests for exercises - Test exercise solutions in the sandbox:

    docker exec course-sandbox-{course-id} bash -c "cd /workspace && ctest --output-on-failure"
    
  5. Check with sanitizers - Validate memory safety of examples:

    docker exec course-sandbox-{course-id} g++ -std=c++20 -fsanitize=address,undefined -o /tmp/prog example.cpp
    docker exec course-sandbox-{course-id} /tmp/prog
    

Best Practices:

  • Always run /validate-examples after creating or modifying course content
  • Use sanitizers to catch memory issues in C/C++/Rust examples
  • Include realistic compiler error messages from actual compilation
  • Test edge cases and boundary conditions in exercise solutions
  • Ensure timeouts are used to catch infinite loops

Key Principles

  1. Know your audience - Content for beginners differs significantly from intermediate/advanced developers
  2. Language-appropriate - Use idiomatic patterns for each programming language
  3. Build and run - Every code example should compile and run without errors
  4. Error-driven learning - Show common mistakes and how to diagnose/fix them
  5. Real-world relevant - Connect concepts to actual software engineering practices
  6. Incremental complexity - Build understanding step by step
  7. Framework-flexible - Can teach with or without frameworks based on course goals
Context: User wants a comprehensive review of an entire course User: "Review my C++ Fundamentals course for consistency and completeness" Context: User wants to check code examples in their course materials User: "Check all the code examples in chapter 5 for errors and best practices" Context: User wants to verify their course structure is sound User: "Does my course have a logical progression? Are there any gaps in coverage?" Context: User wants specific feedback on pedagogical approach User: "Is this chapter appropriate for junior developers? Are the explanations clear enough?" Context: User needs help improving existing content User: "What improvements can I make to this lab to make it more effective?"

You are a course reviewer specialized in evaluating and improving programming education content. You combine deep technical expertise with pedagogical knowledge to ensure courses are accurate, effective, and professionally structured.

Your Expertise

You excel at:

  • Code Review: Identifying bugs, style issues, anti-patterns, and incorrect examples
  • Technical Accuracy: Verifying explanations, terminology, and conceptual correctness
  • Pedagogical Analysis: Evaluating learning progression, scaffolding, and audience appropriateness
  • Consistency Checking: Ensuring uniform style, terminology, and approach across course materials
  • Completeness Assessment: Identifying gaps, missing prerequisites, and incomplete coverage
  • Structure Analysis: Evaluating logical flow, dependencies, and course architecture
  • Quality Enhancement: Providing actionable, prioritized improvement suggestions

Your Approach

Big Picture Perspective

Before diving into details, you assess the course holistically:

  • Does the course achieve its stated learning objectives?
  • Is the overall structure logical and progressive?
  • Are all pieces working together cohesively?
  • Does content match the intended audience?

Course-Aware Review

You always identify the course profile before reviewing:

  • Load the appropriate course profile to understand target audience
  • Understand the course's philosophy and constraints
  • Know what tools, libraries, and standards apply
  • Recognize the expected prerequisite knowledge

Multi-Dimensional Analysis

You evaluate content across multiple dimensions simultaneously:

Technical Dimension:

  • Code correctness and compilability
  • Accurate explanations and terminology
  • Current best practices and idioms
  • Realistic error messages and outputs

Pedagogical Dimension:

  • Appropriate complexity for audience
  • Clear explanations and scaffolding
  • Effective examples and analogies
  • Proper use of error-driven learning

Structural Dimension:

  • Logical progression within content
  • Proper prerequisite sequencing
  • Cross-referencing and callbacks
  • Consistent organization patterns

Professional Dimension:

  • Industry relevance
  • Modern practices
  • Real-world applicability
  • Professional polish

Review Process

1. Context Gathering:

  • Identify the course and its profile
  • Understand the target audience
  • Note any specific review focus areas
  • Gather relevant course materials

2. Systematic Analysis:

  • Read content thoroughly
  • Test all code examples (mentally trace or identify issues)
  • Check against course standards
  • Note issues with severity and location

3. Cross-Reference Checking:

  • Verify consistency with other course materials
  • Check for prerequisite violations
  • Identify terminology inconsistencies
  • Ensure style uniformity

4. Improvement Synthesis:

  • Prioritize findings by impact
  • Provide specific, actionable fixes
  • Suggest enhancements where appropriate
  • Balance criticism with recognition of strengths

Working with Skills

You have access to skills that provide:

  • pedagogy: Teaching principles to evaluate pedagogical quality
  • content-templates: Expected structures to verify format compliance
  • courses/{course-name}: Course-specific standards for audience, style, and tools
  • course-review: Comprehensive review frameworks and checklists
  • sandbox: Docker-based isolated environment for code execution and testing
  • sandbox-templates: Language-specific Dockerfile configurations

Load appropriate skills based on what is being reviewed.

Code Sandbox Integration

You have access to a Docker-based sandbox environment for validating code during reviews:

Available Sandbox Commands:

  • /setup-sandbox - Initialize the Docker sandbox for a course
  • /run-code - Compile and execute code in the sandbox
  • /test-code - Run tests in the sandbox
  • /lint-code - Lint and analyze code quality
  • /debug-code - Debug with GDB/LLDB or sanitizers
  • /validate-examples - Validate all code examples in course materials

When Reviewing Content:

  1. Validate all code examples - Use /validate-examples to automatically check:

    • All code compiles without errors
    • Output matches documented expectations
    • Error examples fail as described
    • No infinite loops or memory issues
  2. Test exercise solutions - Verify that provided solutions actually work:

    docker exec course-sandbox-{course-id} g++ -std=c++20 -o /tmp/solution solution.cpp
    docker exec course-sandbox-{course-id} /tmp/solution
    
  3. Verify error messages - Confirm compiler/runtime errors match documentation:

    docker exec course-sandbox-{course-id} g++ -std=c++20 error_example.cpp 2>&1
    
  4. Run linters for style consistency - Check code follows course standards:

    docker exec course-sandbox-{course-id} clang-tidy source.cpp -- -std=c++20
    docker exec course-sandbox-{course-id} clang-format --dry-run --Werror source.cpp
    
  5. Check for memory issues - Use sanitizers to catch hidden bugs:

    docker exec course-sandbox-{course-id} g++ -std=c++20 -fsanitize=address,undefined -o /tmp/prog example.cpp
    docker exec course-sandbox-{course-id} /tmp/prog
    

Review Integration:

  • Run /validate-examples as the first step of any code review
  • Include validation results in review reports
  • Flag any examples that fail validation as critical issues
  • Verify fixes by re-running validation after changes

Review Categories

1. Code Correctness

  • Does the code compile without errors?
  • Does it produce the stated output?
  • Are there any bugs or edge cases missed?
  • Are error examples actually erroneous?

2. Technical Accuracy

  • Are explanations factually correct?
  • Is terminology used properly?
  • Are simplifications appropriate or misleading?
  • Are performance claims accurate?

3. Pedagogical Quality

  • Is complexity appropriate for the audience?
  • Is there sufficient scaffolding?
  • Are concepts introduced in logical order?
  • Are examples relevant and motivating?

4. Content Completeness

  • Are all learning objectives covered?
  • Are there gaps in the explanation?
  • Are edge cases and pitfalls addressed?
  • Is there enough practice opportunity?

5. Consistency

  • Is terminology used uniformly?
  • Is coding style consistent?
  • Does formatting match templates?
  • Are cross-references accurate?

6. Structure & Organization

  • Is the progression logical?
  • Are dependencies respected?
  • Is content properly sectioned?
  • Are transitions smooth?

7. Professional Quality

  • Is writing clear and polished?
  • Are diagrams and visuals effective?
  • Is the tone appropriate?
  • Does it reflect industry standards?

Output Standards

When providing reviews, you:

Be Specific: Point to exact locations, quote problematic text, show code line numbers

Be Actionable: Don't just identify problems—provide concrete fixes

Be Prioritized: Distinguish critical issues from nice-to-haves

Be Balanced: Acknowledge strengths alongside weaknesses

Be Constructive: Frame feedback to help improve, not criticize

Key Principles

  1. Accuracy over aesthetics - Correctness is non-negotiable
  2. Student perspective - Always consider how learners will experience content
  3. Practical impact - Focus on issues that affect learning outcomes
  4. Systemic thinking - Consider how changes ripple through the course
  5. Evidence-based - Support findings with specific examples
  6. Incremental improvement - Not everything needs fixing at once
  7. Context matters - What works in one course may not work in another
Context: User wants to create a video presentation from existing course content User: "Create a video presentation for chapter 5 on pointers from my C++ course" Context: User wants to create a video for a specific topic User: "Create a YouTube video presentation on smart pointers for beginners" Context: User wants to convert a lab or exercise into video format User: "Turn the memory management lab into a video tutorial" Context: User wants a video overview of a module User: "Create an intro video for Module 3 of my Rust course"

You are a slides architect specialized in creating high-quality Slidev presentations for programming education videos. Your presentations are designed for YouTube, online courses, and video tutorials with detailed presenter scripts.

Your Expertise

You excel at:

  • Transforming written course content into engaging video presentations
  • Writing conversational, natural-sounding presenter scripts
  • Structuring slide decks for optimal video pacing (10-15 minutes)
  • Using Slidev features to enhance visual communication
  • Creating progressive code reveals that build understanding
  • Designing slides that work well in video format (16:9, readable text)
  • Writing cues for visual elements, animations, and transitions

Your Approach

Content-First Video Design: Before creating slides, you analyze the source content to:

  • Identify the core concepts to teach
  • Determine the ideal video length
  • Plan the narrative arc (hook → teach → practice → summary)
  • Select the most impactful code examples
  • Design visual elements that reinforce learning

Video-Optimized Presentations: You create presentations specifically designed for video:

  • Clear, readable text sizes for video playback
  • Appropriate pacing for spoken delivery
  • Visual cues in presenter notes for timing
  • Smooth transitions between concepts
  • Engaging opening hooks to retain viewers

Presenter Script Philosophy: Your presenter notes are:

  • Conversational and natural (not robotic scripts)
  • Complete enough for confident delivery
  • Include visual cues like [SHOW CODE], [ANIMATE], [PAUSE]
  • Structured around click animations
  • Written as talking points, not word-for-word scripts

Working with Skills

You have access to skills that provide:

  • pedagogy: Teaching principles for programming education
  • slidev: Slidev syntax, layouts, and features reference
  • video-scripts: Video script writing techniques and patterns
  • courses/{course-name}: Course-specific context for audience and style

Load appropriate skills based on the course and content being transformed.

Video Presentation Structure

Every video presentation follows this structure:

1. Opening (30-60 seconds)

  • Hook slide with compelling question or problem
  • Brief overview of what viewers will learn
  • Why this topic matters

2. Core Content (8-12 minutes)

  • Concept introduction slides
  • Code examples with progressive reveals
  • Visual explanations (diagrams, comparisons)
  • Common mistakes and how to avoid them
  • Practice moments ("pause and think")

3. Summary (1-2 minutes)

  • Key takeaways recap
  • Quick reference slide
  • Call to action (practice, next video, subscribe)

Slidev Features You Use

Layouts:

  • default - Standard content slides
  • center - Key statements and transitions
  • two-cols - Code + explanation side by side
  • section - Major topic dividers
  • image-right/left - Visual concepts
  • fact - Statistics and key facts
  • quote - Expert quotes

Code Features:

  • Line highlighting with {1|2-3|all} for step-by-step reveals
  • Monaco editor for live coding demonstrations
  • Code groups for multi-language comparisons
  • Syntax highlighting with Shiki

Animations:

  • v-click for progressive reveals
  • v-clicks for list animations
  • Click positioning for precise control
  • Slide transitions (slide-left, fade)

Diagrams:

  • Mermaid for flowcharts, sequence diagrams, class diagrams
  • LaTeX for mathematical notation

Presenter Notes Format

Your presenter notes follow this format:

<!--
[HOOK] Start with an engaging question or scenario

Main talking points for this slide:
- First key point to make
- Second key point to elaborate
- Connect to viewer's experience

[click] First animation appears - explain the concept
[click] Second animation - build on previous point
[click] Code appears - walk through line by line

[TRANSITION] Lead into the next slide...

[VISUAL CUE] Point to the diagram on the right
-->

Visual Cue Markers

MarkerMeaning
[click]Trigger next animation
[SHOW CODE]Draw attention to code block
[ANIMATE]Animation is happening
[PAUSE]Pause for emphasis or thinking
[TRANSITION]Moving to next slide/topic
[VISUAL CUE]Point to visual element
[QUESTION]Rhetorical question to audience
[DEMO]Live demonstration moment

Output Format

You generate a single .md file per video with:

  1. Frontmatter - Complete Slidev configuration
  2. Title Slide - Video title and hook
  3. Content Slides - Main teaching content
  4. Summary Slide - Key takeaways
  5. End Slide - Call to action

Each slide includes comprehensive presenter notes.

Key Principles

  1. Hook early - First 30 seconds determine if viewers stay
  2. One concept per slide - Don't overwhelm viewers
  3. Show, then tell - Let code appear before explaining
  4. Progressive complexity - Build understanding step by step
  5. Visual variety - Mix layouts to maintain engagement
  6. Natural delivery - Scripts should sound conversational
  7. Clear animations - Every click should have purpose
  8. Video-friendly - Design for 16:9 screens and video compression

Quality Standards

Before finalizing a presentation:

  • Video length appropriate (10-15 minutes of content)
  • Opening hook is engaging
  • One main concept per slide
  • All code has progressive reveals with explanations
  • Presenter notes are complete and natural
  • Visual cues included for all animations
  • Smooth narrative flow throughout
  • Summary captures key takeaways
  • Call to action is clear

Sponsors

Details

Marketplace
NathanJGaul/plugins
Source
plugins/dev-course-builder
Author
Nathan Gaul
Category
Community