Agent workshop documentation

instructor/guide.md

@@ -0,0 +1,99 @@
+# Epic Workshop Creation Guide for Agents
+
+This guide details how to create an Epic Workshop using the `epicshop` CLI and workshop format.
+
+## Workshop Philosophy
+Epic Workshops are:
+- **Iterative:** Students build on previous knowledge.
+- **Problem-based:** Students solve problems, they don't just read about them.
+- **Linear (usually):** There is a clear path from start to finish.
+- **Test-driven (often):** Tests verify the student's solution.
+
+## Workshop Structure
+A standard workshop has this directory structure:
+
+```
+workshop-name/
+├── epicshop/           # Workshop tools and configuration
+├── exercises/          # The core content
+│   ├── 01.module/      # Modules group related exercises
+│   │   ├── 01.problem.ex/ # Exercise: problem files
+│   │   │   ├── index.ts   # The code to fix
+│   │   │   ├── README.mdx # Instructions
+│   │   └── 01.solution.ex/# Exercise: solution files
+│   │       ├── index.ts   # The fixed code
+│   │       ├── README.mdx # Explanation of solution
+│   └── README.mdx      # Module introduction
+├── README.md           # Workshop introduction
+├── package.json        # Dependencies
+└── tsconfig.json       # TypeScript config
+```
+
+## Creating Content
+
+### 1. Modules and Exercises
+Exercises are organized into modules.
+- Format: `XX.module-name/` (e.g., `01.fundamentals/`)
+- Inside modules: `XX.problem.name/` and `XX.solution.name/` (e.g., `01.problem.hello/`, `01.solution.hello/`)
+
+### 2. The Exercise Flow
+For each concept `X`:
+1.  **Problem Directory (`problem`):**
+    -   Contains broken code or "TODO" comments.
+    -   `README.mdx`: Explains the concept, the task, and helpful resources. Uses the `<EpicVideo />` component if a video exists (agent can leave a placeholder).
+    -   Uses emojis like 🐨 (Koala) for helpful tips and 👨‍💼 (Product Manager) for requirements.
+
+2.  **Solution Directory (`solution`):**
+    -   Contains the working code.
+    -   `README.mdx`: Explains the solution.
+
+### 3. README.mdx format
+The `README.mdx` files use specific components:
+-   `<EpicVideo url="..." />`: Embeds a video lesson.
+-   `<callout-info>`, `<callout-success>`, `<callout-danger>`, `<callout-warning>`: For highlighted blocks.
+-   `<InlineFile file="..." />`: Links to a file in the editor.
+-   Code blocks with language tags.
+
+### 4. Tests
+Tests are crucial. They should be co-located with the exercise files or in a `test/` directory within the exercise.
+-   Tests run in the background to validate student progress.
+-   Filenames often match the code file (e.g., `index.test.ts`).
+
+## The `epicshop` Tool
+-   Used to scaffold and run the workshop.
+-   `npx epicshop add workshop-template`: Scaffolds a new workshop.
+-   Agents should simulate this structure or use the tool if available in the environment.
+
+## Step-by-Step Creation Process for Agents
+
+1.  **Scope & Research:**
+    -   Define the learning objectives.
+    -   Outline the modules and exercises.
+    -   Gather necessary code snippets and libraries.
+
+2.  **Scaffolding:**
+    -   Create the directory structure.
+    -   Set up `package.json` and dependencies.
+
+3.  **Drafting Exercises (Iterative):**
+    -   Start with the first concept.
+    -   Create the `solution` first (working code).
+    -   Create the `problem` by breaking the solution (remove code, add TODOs).
+    -   Write the `README.mdx` for the problem (instructions) and solution (explanation).
+    -   Write tests to verify the solution.
+
+4.  **Review:**
+    -   Ensure consistent naming.
+    -   Check that instructions are clear.
+    -   Verify that tests pass for the solution and fail for the problem.
+
+## Emoji Guide
+-   🐨 (Koala): Helpful tips, hints, "look here".
+-   👨‍💼 (Product Manager): Requirements, "we need this feature".
+-   💰 (Money Bag): Bonus content, "extra credit".
+-   🦉 (Owl): Deep dive, "learn more".
+
+## Validation
+-   Use `read_lints` to check for errors.
+-   Run tests to ensure validity.
+

instructor/plan_template.md

@@ -0,0 +1,28 @@
+# Workshop Plan
+
+**Topic:** {{TOPIC}}
+
+## Overview
+{{SUMMARY}}
+
+## Prerequisites
+- {{PREREQUISITE_1}}
+- {{PREREQUISITE_2}}
+
+## Modules
+
+### Module 1: {{MODULE_1_NAME}}
+- **Goal:** {{MODULE_1_GOAL}}
+- **Exercises:**
+  1.  **{{EXERCISE_1_NAME}}**:
+      -   **Concept:** {{CONCEPT}}
+      -   **Problem:** {{PROBLEM_DESCRIPTION}}
+      -   **Solution:** {{SOLUTION_DESCRIPTION}}
+  2.  ...
+
+### Module 2: ...
+
+## detailed Implementation Steps
+1.  Setup project structure.
+2.  Implement Module 1.
+3.  ...

instructor/system_prompt.md

@@ -0,0 +1,34 @@
+You are an expert technical instructor and workshop creator. Your goal is to build a high-quality, interactive coding workshop using the Epic Workshop format.
+
+## Instructions
+1.  **Analyze the Request:** Understand the topic and scope requested by the user.
+2.  **Plan the Workshop:**
+    -   Use the `instructor/plan_template.md` to outline the workshop.
+    -   Break the topic down into logical modules and linear exercises.
+    -   Ensure each exercise builds on the previous one.
+3.  **Scaffold the Workshop:**
+    -   Create the directory structure (following `instructor/guide.md`).
+    -   Initialize `package.json` and config files.
+4.  **Build Exercises (Iteratively):**
+    -   For each exercise:
+        -   **Write the Solution Code:** Implement the working version first.
+        -   **Write the Tests:** Create tests that pass with the solution code.
+        -   **Create the Problem:** Copy the solution, then remove key parts and add `// TODO` comments for the student.
+        -   **Write Documentation:**
+            -   `problem/README.mdx`: Clear instructions, requirements (👨‍💼), and hints (🐨).
+            -   `solution/README.mdx`: Explanation of the solution.
+5.  **Validation:**
+    -   Verify that the solution passes tests.
+    -   Verify that the problem fails tests (but compiles/runs enough to show the failure).
+
+## Resources
+-   `instructor/guide.md`: Detailed formatting and structural rules.
+-   `instructor/plan_template.md`: Template for planning.
+-   Reference Workshops: You can inspect the structure of `react-fundamentals` or `mcp-auth` if you need to see real examples.
+
+## Key Principles
+-   **"Going down to level up":** Teach the fundamentals (the "hard way") before introducing abstractions.
+-   **Real-world scenarios:** Frame exercises as requests from a Product Manager (👨‍💼).
+-   **Active learning:** The student must write code to solve the problem.
+
+Start by proposing a plan to the user (me) before writing code.