diff --git a/instructor/guide.md b/instructor/guide.md new file mode 100644 index 0000000..947b565 --- /dev/null +++ b/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 `` 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: +- ``: Embeds a video lesson. +- ``, ``, ``, ``: For highlighted blocks. +- ``: 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. + diff --git a/instructor/plan_template.md b/instructor/plan_template.md new file mode 100644 index 0000000..c94304a --- /dev/null +++ b/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. ... diff --git a/instructor/system_prompt.md b/instructor/system_prompt.md new file mode 100644 index 0000000..37d05a9 --- /dev/null +++ b/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. diff --git a/reference_workshops/mcp-auth b/reference_workshops/mcp-auth new file mode 160000 index 0000000..749b6af --- /dev/null +++ b/reference_workshops/mcp-auth @@ -0,0 +1 @@ +Subproject commit 749b6af3d14536f198ded7d4f42ea628ceb118d4 diff --git a/reference_workshops/mcp-ui b/reference_workshops/mcp-ui new file mode 160000 index 0000000..f218caa --- /dev/null +++ b/reference_workshops/mcp-ui @@ -0,0 +1 @@ +Subproject commit f218caa21ddd33e40d82d780759faa8f60117eee diff --git a/reference_workshops/mocking-techniques b/reference_workshops/mocking-techniques new file mode 160000 index 0000000..06a02db --- /dev/null +++ b/reference_workshops/mocking-techniques @@ -0,0 +1 @@ +Subproject commit 06a02db9ede9c0d583ecab0c5b34944c034ac7e1 diff --git a/reference_workshops/react-fundamentals b/reference_workshops/react-fundamentals new file mode 160000 index 0000000..69b78fb --- /dev/null +++ b/reference_workshops/react-fundamentals @@ -0,0 +1 @@ +Subproject commit 69b78fb9c13621de0124a65c43a3cb8caf564ff3 diff --git a/reference_workshops/react-performance b/reference_workshops/react-performance new file mode 160000 index 0000000..0171913 --- /dev/null +++ b/reference_workshops/react-performance @@ -0,0 +1 @@ +Subproject commit 0171913da7693c05be26fdd4070ee4c7e59fd743 diff --git a/reference_workshops/react-server-components b/reference_workshops/react-server-components new file mode 160000 index 0000000..80035af --- /dev/null +++ b/reference_workshops/react-server-components @@ -0,0 +1 @@ +Subproject commit 80035afd8239ca1eee09ed505997a74c69a266bd diff --git a/reference_workshops/web-forms b/reference_workshops/web-forms new file mode 160000 index 0000000..e5b6143 --- /dev/null +++ b/reference_workshops/web-forms @@ -0,0 +1 @@ +Subproject commit e5b61431747ce803c4b205bff2ee92d2a4ffa506