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` (صورت سوال، گزینه‌ها، پاسخ صحیح و تحلیل گزینه‌های گمراه‌کننده)