initial commit

.agents/rules/quera-styleguide.md

@@ -0,0 +1,37 @@
+# شیوه‌نامهٔ نگارش فنی و استانداردهای کوئرا کالج
+## دورهٔ وایب کدینگ (Vibe Coding)
+
+این شیوه‌نامه استانداردهای زبانی، ساختاری و بصری درس‌نامه‌های متنی و تمرین‌های دوره را مشخص می‌کند.
+
+---
+
+## ۱. لحن و زبان نگارش (Tone & Voice)
+
+* **مخاطب دوره:** افراد بدون پیش‌زمینهٔ کدنویسی (طراحان، مدیران محصول، کارآفرینان، بازاریاب‌ها و علاقه‌مندان).
+* **لحن:** صمیمی، حرفه‌ای، تشویق‌کننده، شفاف و بدون اصطلاحات پیچیدهٔ غیرضروری.
+* **رعایت نیم‌فاصله‌ها:** در تمام متون فارسی، نیم‌فاصله برای پیشوندها و پسوندها (مانند «می‌شود»، «درس‌نامه»، «ایجنت‌ها»، «راه‌اندازی») الزامی است.
+* **اصطلاحات فنی:** اصطلاحات کلیدی (مثل Token, Context Window, Prompt, Agent, Git, Repository, PRD, MVP, Mock Data, Supabase) در اولین اشاره به همراه معادل انگلیسی درون پرانتز یا پاورقی آورده شوند.
+
+---
+
+## ۲. ساختار استاندارد درس‌نامه‌های کوئرا (Lesson Anatomy)
+
+هر درس‌نامه متنی باید ساختار زیر را رعایت کند:
+
+1. **مقدمه و قلاب (Hook):** یک موقعیت واقعی، مسئله یا چالش روزمره که ضرورت این موضوع را نشان می‌دهد.
+2. **شرح مفهوم به زبان ساده (Core Concept):** توضیح اصل موضوع بدون پرداختن به جزییات زائد. استفاده از استعاره‌ها و نمودارهای بصری (Mermaid).
+3. **جعبه‌های راهنما و هشدار (Admonitions):**
+   - `> [!NOTE]` برای نکات تکمیلی و پس‌زمینه
+   - `> [!TIP]` برای ترفندها و پرامپت‌های طلایی
+   - `> [!IMPORTANT]` برای ملزومات کلیدی
+   - `> [!WARNING]` برای اشتباهات رایج و توهم‌های هوش مصنوعی (AI Hallucinations)
+4. **جعبه پرامپت نمونه (Ready-to-Use Prompt):** پرامپت‌های کپی-پیست آماده برای ادیتورهایی مثل Cursor/Claude Code.
+5. **جمع‌بندی و گام بعدی (Summary & Action Item):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش درس بعدی.
+
+---
+
+## ۳. استاندارد تمرین‌های داوری خودکار (Judge Problems)
+
+* **داستان‌پردازی بومی (Iranian Startup Scenarios):** تمرین‌ها حول مسائل واقعی استارتاپ‌ها (اسنپ‌فود، دیوار، طاقچه، دیجی‌کالا، فیلیمو، علی‌بابا، تپسی، شیپور، پونیشا، والکس، بازار، ویرگول، آپارات، جابینجا) طراحی می‌شوند.
+* **وضوح خروجی:** دانشجو باید دقیقاً بداند چه فایل‌هایی با چه ساختاری و چه فرمتی از او خواسته شده است.
+* **پیام‌های خطای آموزشی:** تست‌های داور خودکار باید خطاهای شفاف تولید کنند تا دانشجو با ارائهٔ همان خطا به هوش مصنوعی بتواند کد را دیباگ کند.

.agents/rules/sdd-workflow.md

@@ -0,0 +1,43 @@
+# راهنمای گردش‌کار توسعهٔ مبتنی بر مشخصات (Spec-Driven Development — SDD)
+## دورهٔ وایب کدینگ — کوئرا کالج
+
+در این مخزن، تمام محتواها، درس‌نامه‌ها، تمرین‌های داوری خودکار و آزمون‌های تستی **باید** بر اساس متدولوژی **Spec-Driven Development (SDD)** تولید شوند.
+
+---
+
+## اصول کلیدی SDD در این مخزن
+
+1. **قانون طلایی (No Spec, No Content):**
+   هیچ درس‌نامه (`lesson.md`)، هیچ کد مسئله‌ای (`problem.md`, `solution/`, `tests/`) و هیچ سوال تستی بدون داشتن یک فایل مشخصات (`spec.md`) تایید شده، نباید نوشته شود.
+
+2. **سلسله‌مراتب توسعه:**
+   ```
+   [Syllabus / Spreadsheet]
+           │
+           ▼
+   [Phase 1: Lesson / Exercise Spec (spec.md)]
+           │
+           ▼  (User Review & Approval)
+   [Phase 2: Reference Implementation / Content Draft]
+           │
+           ▼
+   [Phase 3: Automated Test Matrix & Verification]
+           │
+           ▼
+   [Phase 4: Final Publish-Ready Review]
+   ```
+
+3. **تفکیک مسئولیت پوشه‌ها:**
+   هر درس‌نامه یا تمرین در پوشهٔ اختصاصی خود در ساختار زیر قرار می‌گیرد:
+   - **درس‌نامه:** `chapters/ch<XX>-<name>/<YY>-<lesson-slug>/`
+     - `spec.md` (مشخصات و اهداف یادگیری)
+     - `lesson.md` (متن نهایی درس‌نامه کوئرا)
+   - **تمرین داوری:** `chapters/ch<XX>-<name>/<YY>-<exercise-slug>/`
+     - `spec.md` (مشخصات ورودی/خروجی، سناریو، سنجه‌های داوری)
+     - `problem.md` (صورت مسئله برای دانشجو)
+     - `initial/` (کد و اسکلت اولیه)
+     - `solution/` (پاسخ مرجع و بهینه)
+     - `tests/` (مجموعه تست‌های داوری خودکار)
+   - **تمرین تستی:** `chapters/ch<XX>-<name>/<YY>-<quiz-slug>/`
+     - `spec.md` (مشخصات مفهومی و توزیع گزینه‌ها)
+     - `questions.json` یا `questions.md` (صورت سوال، گزینه‌ها، پاسخ صحیح و تحلیل گزینه‌های گمراه‌کننده)

.agents/skills/course-sdd-planner/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: course-sdd-planner
+description: >-
+  Use this skill when planning, structuring, or generating specification documents (spec.md)
+  for chapters and lessons in the Vibe Coding course for Quera College.
+---
+
+# Course SDD Planner (طراحی و تدوین مشخصات درس‌نامه‌ها)
+
+این مهارت راهنمای تدوین سند مشخصات (`spec.md`) برای هر درس‌نامه در متدولوژی Spec-Driven Development است. قبل از نوشتن هرگونه محتوای متنی، باید این سند ایجاد و تایید شود.
+
+---
+
+## ساختار فایل `spec.md` برای درس‌نامه‌ها
+
+هر درس‌نامه باید در مسیر `chapters/ch<XX>-<name>/<YY>-<slug>/spec.md` دارای این قالب باشد:
+
+```markdown
+# مشخصات درس‌نامه: [عنوان درس‌نامه]
+- **شناسه در سیلابس:** L<X>.<Y>
+- **فصل:** [شماره و نام فصل]
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** [مثلاً ۱۰ دقیقه]
+- **پیش‌نیازهای مستقیم:** [شناسه درس‌های قبلی یا "ندارد"]
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس باید بتواند:
+- [ ] **درک کند (Understand):** [مفهوم کلیدی ۱]
+- [ ] **به‌کار ببندد (Apply):** [مهارت یا پرامپت عملی ۱]
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** [تشخیص خروجی صحیح از خطای هوش مصنوعی]
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+- **آنچه باید پوشش داده شود (In-Scope):**
+  - نکته الف
+  - نکته ب
+- **آنچه نباید وارد آن شویم (Out-of-Scope - جلوگیری از سردرگمی):**
+  - مباحث پیچیده و نامرتبط که جلوتر تدریس می‌شوند.
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| Prompt | پرامپت (درخواست/دستور) | پیامی که به هوش مصنوعی می‌دهیم تا خروجی تولید کند |
+
+---
+
+## ۴. استعاره‌ها، سناریوهای ملموس و دیاگرام‌ها (Pedagogy & Visuals)
+- **داستان/استعاره ملموس:** [تشبیه موضوع به یک کار روزمره برای درک بدون پیش‌نیاز فنی]
+- **دیاگرام پیشنهادی (Mermaid):** [شرح فلوچارت یا نمودار مورد نیاز]
+
+---
+
+## ۵. پرامپت‌ها و ابزارهای مورد استفاده در درس
+- **ابزار هدف:** (Cursor / Claude Code / Lovable / Supabase / ...)
+- **پرامپت طلایی نمونه:** [متن پرامپت پیشنهادی که در درس آموزش داده می‌شود]
+
+---
+
+## ۶. معیارهای پذیرش درس‌نامه (Acceptance Criteria)
+- [ ] آیا لحن صمیمی و ساده برای غیربرنامه‌نویسان رعایت شده است؟
+- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی آورده شده‌اند؟
+- [ ] آیا حداقل یک باکس هشدار توهم هوش مصنوعی یا نکته طلایی وجود دارد؟
+- [ ] آیا پرامپت نمونه تست‌شده و بدون خطا کار می‌کند؟
+```

.agents/skills/quera-judge-problem-spec/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: quera-judge-problem-spec
+description: >-
+  Use this skill when defining specifications, starter code, test suites, and judge rubrics
+  for automated judge exercises (coding, configuration, or LLM-judged problems) for Quera College.
+---
+
+# Quera Judge Problem Specifier (طراحی تمرین‌های داوری خودکار)
+

.agents/skills/quera-lesson-author/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: quera-lesson-author
+description: >-
+  Use this skill when drafting or refining full document-based lessons (lesson.md)
+  from an approved spec.md file, following Quera College pedagogical and formatting rules.
+---
+
+# Quera Lesson Author (نگارش درس‌نامه‌های متنی کوئرا کالج)
+
+این مهارت راهنمای تبدیل یک سند مشخصات تایید شده (`spec.md`) به متن نهایی و جذاب درس‌نامه (`lesson.md`) است.
+
+---
+
+## چک‌لیست قبل از نگارش
+1. آیا فایل `spec.md` در پوشهٔ درس وجود دارد و اهداف آن مشخص است؟
+2. آیا شیوه‌نامه نگارش فارسی کوئرا (`.agents/rules/quera-styleguide.md`) بررسی شده است؟
+
+---
+
+## ساختار نگارشی درس‌نامه (`lesson.md`)
+
+```markdown
+# [عنوان درس‌نامه]
+
+[مقدمه جذاب و قلاب داستانی: چرا این موضوع برای کسی که می‌خواهد با هوش مصنوعی محصول بسازد حیاتی است؟]
+
+---
+
+## [عنوان بخش اول: مفهوم اصلی به زبان ساده]
+
+[توضیح شفاف همراه با استعاره‌های روزمره و مقایسه‌های ملموس]
+
+```mermaid
+flowchart LR
+    A[ایده اولیه] --> B[پرامپت ساختاریافته]
+    B --> C[کد تولید شده با AI]
+    C --> D[بررسی و تست خروجی]
+```
+
+> [!NOTE]
+> [نکته تکمیلی درباره عملکرد هوش مصنوعی یا پیش‌زمینه مورد نیاز]
+
+---
+
+## [عنوان بخش دوم: پیاده‌سازی عملی و کار با ابزار]
+
+[گام‌های عملی استفاده از ادیتور/ابزار به همراه تصویرسازی ذهنی]
+
+> [!TIP]
+> **پرامپت پیشنهادی برای ادیتور:**
+> ```text
+> [متن دقیق و تمیز پرامپت آماده استفاده]
+> ```
+
+---
+
+## [عنوان بخش سوم: خطرات و توهم‌های رایج هوش مصنوعی]
+
+> [!WARNING]
+> **مراقب این تله باشید:**
+> [توضیح خطایی که ایجنت‌ها ممکن است در این مرحله مرتکب شوند و نحوه هدایت مجدد آن‌ها]
+
+---
+
+## جمع‌بندی و گام بعدی
+
+در این درس یاد گرفتیم که:
+- **نکته ۱:** [خلاصه نکته کلیدی]
+- **نکته ۲:** [خلاصه نکته کلیدی]
+- **نکته ۳:** [خلاصه نکته کلیدی]
+
+> در درس بعدی به سراغ **[عنوان درس بعد]** می‌رویم تا یاد بگیریم چگونه ...
+```

.agents/skills/quera-quiz-spec/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: quera-quiz-spec
+description: >-
+  Use this skill when designing theoretical, conceptual, and multiple-choice quiz questions
+  for the Vibe Coding course on Quera College.
+---
+
+# Quera Quiz Specifier (طراحی آزمون‌های تستی و مفهومی)
+