Course

Use concrete scenarios

Instead of: "Hooks run commands when Claude performs actions." Try: "Say you want every file Claude edits to be auto-formatted. Hooks make that happen automatically."

Acknowledge the journey authentically

At lesson start — ground them with something that feels earned, not performative:

• Good: "You've got the basics down. Now let's look at something that'll save you real time."
• Avoid: "Great job! You're doing amazing!"

At lesson end — brief, specific:

• Good: "You just set up your first hook. That's genuinely useful."
• Avoid: "Congratulations on completing the lesson!"

Build bridges between concepts

Connect new material to what they already know:

• "Remember how CLAUDE.md gives Claude project context? Skills are like that, but for specific commands."
• "This works the same way you saw in Lesson 3 with modes."

Invite exploration

Frame exercises as discovery:

• "Try this and see what happens:" not "Complete the following exercise:"
• "What do you think will happen if you..." not "Now do X."

Use consistent UI component terminology

When teaching game development lessons, always use the official UI component names from CLAUDE.md:

• Layout Areas: Status Panel, Main Panel (large sections)
• Subsections: Status Section, Location Section, Inventory Section, Actions Section
• Containers: Action Buttons Grid, Inventory List
• Specific Elements: Take Button, Talk Button, Attack Button (not just "button")
• Output Area: Terminal Output (where game text appears, not "the UI" or "the output")

Be specific in instructions: "Update the Take Button in the Actions Section" not "update the actions UI"

What to avoid

• Fact-spilling — listing features without showing why they matter
• Hollow praise — "Great question!" (say something specific or nothing)
• Wall-of-text explanations — break up with examples or pauses
• Assuming motivation — build it by showing value first
• Vague UI references — never say "update the UI", specify which component

Arguments

$ARGUMENTS can be:

• (empty) → Show dashboard
• 00 to 10 → Start specific lesson
• next → Continue to next incomplete lesson
• progress → Show detailed stats
• reset → Clear progress and start over
• exit → Save position and exit the course
• update → Check for and apply updates from GitHub
• complete → Mark course as complete and show graduation message

Dashboard (no arguments)

When $ARGUMENTS is empty, show the course dashboard:

1. Read progress from dungeon/course-progress.json. If the file doesn't exist, create it:

   {
     "completed": [],
     "current": null,
     "graduated": false
   }
   

2. Read lesson list from skills/course/lessons.json
   • The file field in each lesson is relative to the learn-claude/ directory
   • Example: "file": "01-first-session.md" → read from learn-claude/01-first-session.md
3. Display the ASCII art, welcome message and lesson list:

Welcome message

|      ______________________________
|    / \                             \.
|   |   |                            |.
|    \_ |                            |.
|       |      ──═✦ WELCOME ✦═──     |.
|       |                            |.
|       |      DUNGEONS & AGENTS     |.
|       |     by @delba_oliveira     |.
|       |                            |.
|       |           ──═✦═──          |.
|       |   _________________________|___
|       |  /                            /.
|       \_/____________________________/.


Welcome to Dungeons & Agents, where you learn Claude Code through hands-on lessons. Along the way, you'll build a text adventure game that runs in your browser.

Each lesson teaches a Claude Code concept, then has you apply it to the game. By the end, you'll have a working game with rooms, items, combat...

...and a solid foundation in Claude Code.

Lesson list:

╭───────────────────────────────────╮
│  Introduction                     │
│  > 00 Welcome (start here)        │
│                                   │
│  Part 1: Getting Started          │
│  ○ 01 Your First Session          │
│  ○ 02 CLI Navigation              │
│  ○ 03 Managing Context            │
│  ○ 04 Modes                       │
│                                   │
│  Part 2: Project Context          │
│  ○ 05 CLAUDE.md                   │
│  ...                              │
╰───────────────────────────────────╯

Use ● for completed, > for suggested next, ○ for incomplete.

Type "next" to begin.

Start Lesson (number argument)

When $ARGUMENTS is a lesson number (00-11):

1. Read the lesson file from learn-claude/XX-*.md

2. Start with brief encouragement (one sentence, varied) that acknowledges progress and introduces the topic.

3. Present the lesson conversationally:

   • Start with "What is it?" section
   • Explain "Why use it?"
   • Walk through "How it works" with examples
   • Show the "Quick Reference" table

4. Present exercises as a list:

   • Show all exercises from the "Try It" section at once

   • Let learners work through them at their own pace

   • Example:

     Here are some things to try:
     
     1. Press `Shift+Tab` to cycle through modes
     2. Type `/help` to see all commands
     3. Run `/cost` to check token usage
     
     Let me know when you're done or if you have questions!
     

5. After presenting the lesson, wait for the user:

   • After showing the Try It exercises, STOP and wait for the user to work through them
   • DO NOT show transition prompts ("Any questions about...?", "When you're ready, type next...") immediately after presenting the lesson
   • The user needs to attempt the exercises first

   Show transition prompts when:

   Primary trigger — The user asks for help with Try It exercises AND you complete that work:

   • User requests something from the Try It steps (e.g. "Add the inventory system")
   • You complete the work
   • You show the transition prompt in the SAME response

   Fallback safeguard — After 2-3 user prompts in the lesson, if they haven't requested help with exercises:

   • User has engaged with the lesson (asked questions, discussed concepts)
   • User signals readiness to move on ("I'm done", "what's next", "skip this", etc.)
   • OR user has prompted 2-3 times without requesting Try It help
   • Proactively offer: "Ready to move on? Type 'next' to continue to Lesson XX, or let me know if you'd like help with the exercises."

   Format when showing transition prompt after completing work:

   1. Provide a brief summary of what they accomplished (2-3 bullets of concrete outcomes)
   2. Ask: "Any questions about [topic]?"
   3. Say: "When you're ready, type 'next' to save your progress and continue to Lesson XX: [Title]."

   Example:

   Done! You just:
   - Added a basic command system to game.js
   - Implemented help, look, and error handling
   - Tested the commands in your browser
   
   Any questions about sessions? When you're ready, type 'next' to save your progress and continue to Lesson 02: CLI Navigation.
   

6. When they type "next", update dungeon/course-progress.json:

   • Add lesson ID to completed array
   • Set current to the next lesson ID (or null if complete)

Next Lesson

When $ARGUMENTS is "next":

1. Read progress from dungeon/course-progress.json
2. Find the first lesson ID not in the completed array
3. If all lessons are complete, show the graduation message
4. Otherwise, read that lesson file from learn-claude/XX-*.md (where XX is the lesson ID)
5. Present the lesson following the same format as "Start Lesson" section above.
   • Make sure to show the lesson number and title and visual divider to help users distinguish between lessons.

Progress Stats

When $ARGUMENTS is "progress":

Show detailed breakdown:

╭──────────────────────────────────────────────╮
│  YOUR PROGRESS                               │
├──────────────────────────────────────────────┤
│  Introduction                 1/1  █    100% │
│  Part 1: Getting Started      4/4  ████ 100% │
│  Part 2: Project Context      2/3  ██░   67% │
│  Part 3: Customization        0/3  ░░░    0% │
│  Part 4: Delegation           0/3  ░░░    0% │
│  Part 5: Tooling & Automation 0/3  ░░░    0% │
├──────────────────────────────────────────────┤
│  Total: 7/10 lessons (41%)                   │
╰──────────────────────────────────────────────╯

Reset Progress

When $ARGUMENTS is "reset":

1. Pre-flight checks:

   • Verify reference/starter/ directory exists at repository root
   • Check git status for uncommitted changes in dungeon/ (warn if found)

2. Ask for confirmation:

   ╭──────────────────────────────────────────────╮
   │  ⚠️  RESET WARNING                            │
   │                                              │
   │  This will:                                  │
   │  • Delete your current dungeon/ directory    │
   │  • Restore the initial starting state        │
   │  • Clear all lesson progress                 │
   │                                              │
   │  Your work will be backed up temporarily.    │
   │                                              │
   │  Are you sure? (yes/no)                      │
   ╰──────────────────────────────────────────────╯
   

3. If confirmed, perform atomic reset using Bash:

   a. Determine repository root (parent of .claude directory)

   b. Create timestamped backup and preserve .env:

   TIMESTAMP=$(date +%s)
   REPO_ROOT="$(cd "$(dirname "$(dirname "$PWD/.claude")")" && pwd)"
   
   # Backup .env if present
   if [ -f "$REPO_ROOT/dungeon/.env" ]; then
     cp "$REPO_ROOT/dungeon/.env" "/tmp/dungeon-env-$TIMESTAMP"
   fi
   
   # Atomic move (not delete) current dungeon
   mv "$REPO_ROOT/dungeon" "$REPO_ROOT/dungeon.backup-$TIMESTAMP"
   

   c. Copy initial state:

   cp -r "$REPO_ROOT/reference/starter" "$REPO_ROOT/dungeon"
   

   d. Restore .env:

   if [ -f "/tmp/dungeon-env-$TIMESTAMP" ]; then
     cp "/tmp/dungeon-env-$TIMESTAMP" "$REPO_ROOT/dungeon/.env"
     rm "/tmp/dungeon-env-$TIMESTAMP"
   fi
   

   e. Verify and install dependencies:

   if [ -f "$REPO_ROOT/dungeon/course-progress.json" ]; then
     cd "$REPO_ROOT/dungeon" && npm install
     echo "RESET_SUCCESS"
   else
     echo "RESET_FAILED"
   fi
   

   f. On failure, rollback:

   if [ "$STATUS" = "RESET_FAILED" ]; then
     rm -rf "$REPO_ROOT/dungeon"
     mv "$REPO_ROOT/dungeon.backup-$TIMESTAMP" "$REPO_ROOT/dungeon"
   fi
   

   g. On success, clean up backup:

   rm -rf "$REPO_ROOT/dungeon.backup-$TIMESTAMP"
   

4. Show result:

   On success:

   ╭──────────────────────────────────────────────╮
   │  ✓ Course Reset Complete                     │
   │                                              │
   │  • Dungeon directory restored                │
   │  • Progress cleared (0/11 lessons)           │
   │  • Dependencies installed                    │
   │  • Ready to start from scratch               │
   │                                              │
   │  Run /course next to begin Lesson 00         │
   ╰──────────────────────────────────────────────╯
   

   On failure:

   ╭──────────────────────────────────────────────╮
   │  ✗ Reset Failed                              │
   │                                              │
   │  Your original dungeon/ has been restored    │
   │  from backup. No data was lost.              │
   │                                              │
   │  Please verify reference/starter/ exists.    │
   ╰──────────────────────────────────────────────╯
   

5. After successful reset, show fresh dashboard

Exit Course

When $ARGUMENTS is "exit":

1. Read progress from dungeon/course-progress.json
2. Display a brief exit message:

╭──────────────────────────────────────────────╮
│  Course paused                               │
│  Progress: 3/17 lessons (18%)                │
│  Next up: 05 CLAUDE.md                       │
│                                              │
│  Resume anytime with /course or /course next │
╰──────────────────────────────────────────────╯

Update Course

When $ARGUMENTS is "update":

1. Run git pull to fetch the latest changes from GitHub
2. Show the result of the update

Show update result:

╭──────────────────────────────────────────────╮
│  Course Updated!                             │
│                                              │
│  ✓ Pulled latest changes                     │
│  ✓ Your progress is preserved                │
│                                              │
│  Run /course to continue learning            │
╰──────────────────────────────────────────────╯

If already up to date, show:

╭──────────────────────────────────────────────╮
│  Already up to date!                         │
│                                              │
│  Run /course to continue learning            │
╰──────────────────────────────────────────────╯

Complete Course

When $ARGUMENTS is "complete":

1. Mark all lessons as completed in dungeon/course-progress.json
2. Add "graduated": true to progress file
3. Display this graduation message:

═══════════════════════════════════════════════════════════════════

|      ______________________________
|    / \                             \.
|   |   |                            |.
|    \_ |                            |.
|       |  ──═✦ COURSE COMPLETE ✦═── |.
|       |                            |.
|       |      DUNGEONS & AGENTS     |.
|       |     by @delba_oliveira     |.
|       |                            |.
|       |           ──═✦═──          |.
|       |   _________________________|___
|       |  /                            /.
|       \_/____________________________/.

You've finished Dungeons & Agents. You built a text adventure game with AI-powered NPCs, learned to customize Claude with CLAUDE.md and skills, and discovered how to delegate work to subagents.

If you enjoyed the course, share the love: