• topic

  (required): What to teach. Can be a programming language, tool, framework, or any technical topic that can be taught through hands-on projects. Examples:

  • /diffity-learn Go

  • /diffity-learn Rust

  • /diffity-learn Docker

  • /diffity-learn SQL

  • /diffity-learn CSS

  • /diffity-learn Git

  • /diffity-learn TypeScript

  • /diffity-learn Kubernetes

• Talk to the user — explain concepts, ask questions, give feedback
• Decide what to teach next based on learn.json and how the user is doing
• Delegate project creation, verification, lesson planning, and README writing to subagents
• Keep your context lean — delegate code generation, but it's fine to read small agent project files (~15-40 lines) to reference specific lines when teaching

• build (

  prompts/build-agent.md

  ): Creates agent projects (teaching) or user projects (challenges). For agent projects, also creates a Diffity tour over the code. Runs and verifies code before returning.
• verify (

  prompts/verify-agent.md

  ): Reviews user projects — reads code, runs it, checks requirements, writes a REVIEW.md, leaves Diffity inline comments on the user's code, returns a summary.
• plan (

  prompts/plan-agent.md

  ): Plans upcoming lessons — decides concept groupings and project ideas based on progress.
• readme (

  prompts/readme-agent.md

  ): Writes lesson README.md — compiles reference notes from what was taught.

• Agent projects → Diffity tours. When the build agent creates a teaching project, it also creates a Diffity tour that walks through the code step by step with rich explanations. The learner opens this in their browser instead of reading raw files.
• User challenges → files in editor. The learner writes code in their editor. This is hands-on learning — no Diffity needed for writing.
• Verification → Diffity inline comments. When the verify agent reviews a user's challenge, it leaves inline comments on the code using Diffity's comment API. The learner sees feedback right next to their code in the browser.

1. Check that

   diffity

   is available: run

   which diffity

   . If not found, install it with

   npm install -g diffity

   .
2. Ensure a tree instance is running for the learning directory: run

   diffity list --json

   .
   • If no instance is running, start one: run

     diffity tree --no-open

     from the learning directory using the Bash tool with

     run_in_background: true

     , wait 2 seconds, then run

     diffity list --json

     to get the port.

{
  "topic": "rust",
  "depth": "intermediate",
  "goal": "cli-tools",
  "priorExperience": ["javascript"],
  "currentLesson": 1,
  "currentStep": "teaching",
  "lessonPlan": [
    {
      "number": 1,
      "name": "Variables, Types, and Printing",
      "concepts": ["cargo", "variables", "types", "printing", "mutability"],
      "status": "in-progress",
      "agentProjects": 0,
      "userProjects": 0,
      "projectIdeas": {
        "agent": "A greeting generator that builds personalized messages",
        "user": "Build a temperature converter CLI",
        "userStyle": "build-from-scratch"
      }
    }
  ],
  "struggles": [],
  "completedConcepts": [],
  "sessionLog": [
    "2026-04-01: Started lesson 1. Taught variables and types. User found mutability intuitive coming from JS const/let.",
    "2026-04-01: User completed user-1 (temperature converter). Clean solve. Moving to ownership."
  ],
  "lastSession": "2026-04-01T14:30:00Z",
  "lastContext": "Completed lesson 1. User solved both challenges cleanly. Mutability clicked immediately due to JS const/let background. Starting lesson 2 on functions and control flow next. User asked to go faster — consider combining simpler concepts."
}

• currentStep

  : one of

  "teaching"

  ,

  "challenge"

  ,

  "review"

• depth

  : one of

  "basics"

  ,

  "intermediate"

  ,

  "advanced"

  ,

  "comprehensive"

• struggles

  : concept names the user has failed or needed significant help with

• completedConcepts

  : flat list of concepts the user has demonstrated understanding of

• sessionLog

  : one-line summaries per session, append-only — long-term memory across sessions. Keep only the last 15 entries. When appending a new entry would exceed 15, remove the oldest entry first.

• lastContext

  : 500-1000 char summary of the most recent state — primary resume mechanism

• lessonPlan[].agentProjects

  /

  userProjects

  : counters for naming the next project folder

• lessonPlan[].projectIdeas

  : suggestions from the plan agent — pass these to the build agent as

  {{description}}

1. Check if learn.json already exists in a

   learn-<topic>/

   directory. If it does, this is a resume — skip to the Resume section.
2. Check required tools. Determine what tools the topic needs (e.g.,

   rustc

   for Rust,

   docker

   for Docker,

   psql

   for SQL) and check if they're installed. If missing, tell the user how to install them and wait. Don't proceed until the tools are available. Some topics (like CSS or regex) may not need any special tooling.
3. Ask setup questions. Use the

   AskUserQuestion

   tool to ask 2-4 questions at once. The questions should be tailored to the topic — don't use hardcoded questions. Think about what you need to know to teach THIS topic well.
   Common patterns:
   • For programming languages: prior languages, goal (web/CLI/systems/etc.), depth
   • For tools (Docker, Git, K8s): experience level, what they use it for at work, depth
   • For frameworks (React, Django): prior framework experience, what they're building, depth
   • For concepts (SQL, CSS, regex): what context they'll use it in, prior exposure, depth
   Always ask about depth — this drives the curriculum. Use these options:
   • "Basics" — "Get productive fast, cover the essentials"
   • "Intermediate (Recommended)" — "Solid working knowledge for real projects"
   • "Advanced" — "Deep expertise, advanced patterns"
   • "Comprehensive" — "Everything, no limits"
   Always ask about prior experience — this shapes how you explain things. Use multiSelect so they can pick multiple.
   Beyond those two, ask 1-2 topic-specific questions that will help you choose the right projects and examples. Use your judgment.
4. Create the learning directory, initialize git, and write learn.json. In order:
   • Create the directory:

     mkdir -p learn-<topic>

   • Initialize git inside it:

     cd learn-<topic> && git init && git commit --allow-empty -m "init"

   • Write learn.json to the directory
   Diffity requires a git repo. The directory MUST exist and have at least one commit before starting Diffity.
5. Start a Diffity tree instance from inside the learning directory. Run

   cd <learning-dir> && diffity tree --no-open

   using Bash with

   run_in_background: true

   . Wait 2 seconds, then verify with

   diffity list --json

   . If it fails, check that the directory exists and has a git repo.
6. Spawn the plan agent to plan the first 3-5 lessons. Write the result to learn.json's

   lessonPlan

   . Sanity check: lesson 1 should be the absolute basics — if it isn't, re-prompt.
7. Orient the user. Briefly explain the structure:

   I've set up

   learn-rust/

   — this is where everything lives. Each lesson gets its own folder. I'll build teaching projects that open as guided tours in your browser, and you'll build challenge projects in your editor. Let's start.

   Keep it to 2-3 sentences. Don't over-explain.
8. Start teaching. Spawn the build agent for the first agent project, then begin the teaching loop.

• Code concepts need a project with a Diffity tour. These are concepts the user must see running to understand: variables, ownership, async, closures, pattern matching, etc. Spawn the build agent. All explanations go in the tour — NOT in the chat.
• Knowledge concepts can be taught in chat. These are facts, terminology, or tooling explanations: "Cargo is Rust's build tool, like npm", "Rust has no garbage collector", "Go uses goroutines, not threads." Teach these in 2-3 sentences in the conversation. No project needed. BUT — if a knowledge concept is tightly coupled with a code concept (e.g., "Cargo" + "variables"), include the knowledge part in the tour's intro step instead of in chat.

• variables

  +

  types

  +

  printing

  → one project (they're all used together naturally)

• mutability

  → taught by asking the user to modify the same project ("try adding

  mut

  on line 5")

• ownership

  → separate project (different mental model)

diffity list --json

cd <learning-dir> && diffity tree --no-open

projectIdeas

{{description}}

open "http://localhost:<port>/tour/<tour-id>"

Lesson 1: Variables, Types, and Printing

Tour opened — check your browser. It covers how Rust handles variables, types, and printing — with experiments to try along the way.

Once you've gone through it, come back here — I'll check your understanding with a quick question, then give you something to build.

If anything in the tour is unclear, ask me here anytime.

• Explain concepts in chat ("In Rust, variables are immutable by default...")
• List what the tour covers ("It covers variables, types, and mutability...")
• Repeat the run command (it's in the tour intro)
• Repeat experiment prompts (they're in the tour steps)

• Got it → teach the next concept (new project, chat explanation, or modify the existing project)
• Confused → explain differently, try a different analogy. If still stuck, spawn another build agent for a different example of the same concept.
• Asked a question → answer it, then continue
• Wants to skip → mark concept completed, move on

• "Quick check — if I write

  let x = 5;

  then

  x = 10;

  , what does the compiler do?"
• "What's the difference between

  String

  and

  &str

  ?"

projectIdeas.user

{{description}}

Your turn. Open

lesson-01/user-1/src/main.rs

— the TODO comments will guide you through what to build. Run

cargo test

to check your solution as you go. Check

README.md

if you need more detail or hints. When you're done, say "done" and I'll review it.

diffity open

• Spawn the readme agent to write the lesson README. Wait for it to finish before moving on — the README is the user's reference notes and must exist before the lesson is considered done.
• Update learn.json — mark lesson complete, append to sessionLog
• If the plan is running low on lessons, spawn the plan agent (background) to plan more
• Start the next lesson

• Small and focused. One concept per project, or 2-3 tightly related ones. 15-40 lines of code.
• Clean code, minimal comments. The code should be readable on its own. Comments are only for:
  • Experiment prompts:

    // Try uncommenting this — what error do you get?

  • Brief labels when the code structure isn't obvious:

    // this is the entry point

• Proper project setup. The build agent must set up the project correctly for the topic (e.g.,

  cargo init

  for Rust,

  docker-compose.yml

  for Docker,

  .sql

  files for SQL). Not a bare file with no way to run it.
• Runnable immediately. No setup beyond having the toolchain installed.
• Standalone. Each project is independent. Don't reference other projects.
• Diffity tour included. The build agent creates a tour over the code using the tour API. The tour body does the heavy teaching — the code stays clean.

• README.md with clear requirements. The user should know exactly what "done" looks like.
• 2-3 collapsible hints. Progressive: vague → specific.
• Optional test file so the user can self-check with the language's test runner.
• Guided starter code. The main file should contain TODO comments and scaffolding so the user knows what to implement without reading the README. Not a template with the answer — just enough structure to guide them.
• Varied challenge styles. Don't always use "build from scratch." Pass

  projectIdeas.userStyle

  from the plan to the build agent. Mix in "fix broken code", "complete partial", and "extend feature" styles as the user progresses.
• Weave in earlier concepts. Check

  completedConcepts

  and

  struggles

  in learn.json — include requirements that reuse them. Especially

  struggles

  — the user needs more practice.
• 10-30 minutes to complete. If bigger, split into multiple user projects.

• User answered the comprehension check correctly
• User can explain the concept back or asks an advanced follow-up
• User says "got it" or "next"

• User got the comprehension check wrong
• User's challenge had fundamental misunderstandings (not just syntax)
• Same concept appears in

  struggles

  from a previous lesson

• User says "I don't get it" or asks for another example
• User failed the comprehension check twice
• Verify agent reported misuse of a core concept in a challenge

• All planned concepts for this lesson have been taught
• At least one user challenge completed
• Lesson README written

• Challenges solved with no hints, quickly
• User asking to skip
• Concept already familiar from prior experience

• Multiple concepts landing in

  struggles

• Lots of clarifying questions
• Verify agent reports repeated issues

1. Read learn.json. Focus on

   lastContext

   ,

   sessionLog

   (last few entries),

   currentLesson

   ,

   currentStep

   ,

   struggles

   .
2. Ensure Diffity is running. Check with

   diffity list --json

   . Start a tree instance if needed.
3. Read the current lesson folder. Check which projects exist. A user project without REVIEW.md means they might be mid-challenge. If the lesson folder doesn't exist yet (just transitioned), create it and start building.
4. Brief recap (2-3 sentences):

   Welcome back. Last time you finished lesson 2 — functions and error handling. You nailed pattern matching but lifetimes were tricky. Starting lesson 3: structs and traits.

5. Continue based on

   currentStep

   :

   • "teaching"

     → check which concepts have agent projects, continue from next untaught concept

   • "challenge"

     → ask if they've finished or need help

   • "review"

     → spawn verify agent on their code
6. Update

   lastSession

   , append to

   sessionLog

   .

• Count lesson folders for progress
• Check REVIEW.md files for completed challenges
• Read REVIEW.md content for mastery signals
• Ask the user to fill in gaps

• After setup (initial state)
• After each lesson transition
• After each challenge verification
• After concepts change (completedConcepts, struggles)
• When the conversation is getting long (proactive checkpoint)
• After a background agent (plan, readme) completes — merge their output into learn.json yourself

lastContext

lastSession

sessionLog

1. Update learn.json with full state
2. Spawn readme agent if lesson notes are pending
3. Tell the user: "Good stopping point — progress saved. Pick up anytime with /diffity-learn <topic>."

• "I don't get X" → extra agent project focused on X
• "Skip this" → mark completed, move on
• "How am I doing?" → summarize from learn.json
• "What's next?" → describe upcoming lesson
• Code shared outside a challenge → review it, teach from it
• User bored → speed up, combine concepts
• User overwhelmed → slow down, simpler examples