repo/
  README.md
  .gitignore
  .env.example

  docs/
    rules/
      index.md
      workflow.md
      testing.md
      security.md
      coding.md

  prompts/
    launch.md
    onboard.md
    think.md
    spike.md
    implement.md
    test.md
    review.md
    retrospect.md

  tasks/
    current.md
    20251228-example-task.md

  experiments/
    README.md
    20251228-example_spike.md

  test-data/
    README.md
    golden/
      README.md
      case01_input.json
      case01_expected.json

  src/
    core/
    adapters/
    app/

  tests/
    unit/
    integration/

# الأسرار
.env

# السجلات والبيانات المؤقتة
*.log
*.tmp
*.bak
*.swp

# نظام التشغيل
.DS_Store
Thumbs.db

# لغة / وقت التشغيل (تعديل حسب الحاجة)
__pycache__/
.pytest_cache/
node_modules/
dist/
build/
coverage/

# انسخ إلى .env (لا تلتزم بـ .env)
# مثال:
# API_BASE_URL=https://example.com
# API_TOKEN=replace_me

# تطوير مدفوع بالذكاء الاصطناعي (تطوير مدفوع بالتحفيز) قالب

تحسين الأعمال، الأتمتة، والمشاريع الصغيرة للمستهلكين، يتم تطويرها بسرعة مع AI،
لضمان "قابلية التكرار"، "تحويل المعرفة إلى أصول"، و"منع الاندفاع" بأقل تكلفة.

---

## الهدف
- صنع بسرعة (استخدام AI)
- جعلها أقل عرضة للكسر (أقل وسائل الأمان)
- القدرة على الإصلاح لاحقًا (تحويل التحفيز / البحث / التوقعات إلى أصول)
- عدم الاعتماد على الأدوات (يمكن استخدام واجهة ويب / IDE / CLI)

---

## المبادئ الأساسية (الأقصر)
- **التوقعات (المدخلات → المخرجات المتوقعة) يتم تأكيدها من قبل البشر** (لمنع المرجع الدائري لـ AI)
- **يجب الالتزام بالتحفيز، تخطيط المهام، وكود التحقق** (شرط لقابلية التكرار)
- النقاط غير الواضحة يجب **أن يتم تحقيقها قبل التنفيذ باستخدام `experiments/`**
- القواعد يجب أن تكون **مدخلاً + مقسمة** (يجب الحفاظ على `docs/rules/index.md` قصيرة)
- يجب أن تتضمن Done **تحديث الأصول** (إضافة حالات ذهبية / إضافة تجارب / تحديث القواعد / إضافة إلى README)

---

## الملفات التي يجب تمريرها إلى AI (غير معتمدة على الأدوات)
عند البدء / إعادة البدء، مرر إلى AI:
1) docs/rules/index.md
2) tasks/current.md

※ لا تعتمد على التحميل التلقائي. إذا كنت تستخدم واجهة ويب، يمكنك اللصق، وإذا كنت تستخدم IDE/CLI، يمكنك إعطاء تعليمات الإشارة.

---

## سير العمل (مع وسائل الأمان)
1) التخطيط والموافقة
- يقوم AI بإنشاء / تحديث tasks/current.md (مسودة)
- يقوم البشر بتأكيد القبول (التوقعات) ويضعون الموافقة على APPROVED
- ممنوع التنفيذ حتى تصبح APPROVED

2) Spike (اختياري)
- إذا كانت النقاط غير واضحة، ضع كود إعادة الإنتاج / البحث في experiments/
- سجل النتائج في experiments/README.md (سطر واحد يكفي)

3) التنفيذ والاختبار
- يجب أن تكون التغييرات صغيرة (3-5 ملفات، فرق معقول)
- أضف / تحديث الاختبارات و / أو test-data

4) المراجعة والالتزام
- يقوم البشر بمراجعة git diff
- الالتزام بالتقنيات التقليدية

5) التفكير في الماضي والتحديث (شرط الإنجاز)
- أضف على الأقل واحدة من:
  - حالة بيانات ذهبية جديدة، أو
  - تجربة جديدة / إعادة إنتاج، أو
  - تحديث القواعد في docs/rules/ أو README
- أرشفة tasks/current.md إلى tasks/YYYYMMDD-*.md

# اتفاقية العمل مع AI (الفهرس)

## ترتيب القراءة (بدء / استئناف)
1) tasks/current.md
2) docs/rules/workflow.md
3) docs/rules/testing.md
4) docs/rules/security.md (إذا كانت تتعلق بالمصادقة / البيانات / الأسرار)
5) docs/rules/coding.md

## القواعد الصارمة (يجب الالتزام بها)
- لا تقم بالبرمجة حتى يظهر في tasks/current.md `Approval: APPROVED`.
- يمتلك البشر المخرجات المتوقعة (بيانات ذهبية). لا تخترع التوقعات.
- إذا كان السلوك غير واضح، قم بإنشاء Spike تحت experiments/ قبل التنفيذ.
- لا تلتزم بالأسرار (.env ممنوع). استخدم فقط .env.example.
- المس فقط الملفات المتعلقة بالمهمة الحالية.
- استخدم الالتزامات التقليدية. يجب أن يكون كل التزام له معنى.

# قواعد سير العمل (مشروع صغير)

## المراحل
1) التخطيط والموافقة
- إنشاء / تحديث tasks/current.md
- الانتظار لموافقة البشر (APPROVED)

2) Spike (اختياري)
- إضافة كود إعادة الإنتاج أو البحث في experiments/
- سجل النتيجة في experiments/README.md (سطر واحد يكفي)

3) التنفيذ والاختبار
- تغييرات صغيرة في كل خطوة (3-5 ملفات، فرق معقول)
- أضف / تحديث الاختبارات و / أو test-data

4) المراجعة والالتزام
- يقوم البشر بمراجعة git diff
- الالتزام بالتقنيات التقليدية

5) التفكير في الماضي والتحديث (شرط الإنجاز)
- أضف على الأقل واحدة من:
  - حالة بيانات ذهبية جديدة، أو
  - تجربة جديدة / إعادة إنتاج، أو
  - تحديث القواعد في docs/rules/ أو README
- أرشفة tasks/current.md إلى tasks/YYYYMMDD-*.md

# قواعد الاختبار

## مصدر الحقيقة
- الحقيقة = tests/ + test-data/
- المخرجات المتوقعة (الذهبية) مملوكة للبشر.

## العناصر المملوكة للبشر
- test-data/golden/*_expected.*  (أو لقطات)
- قسم القبول في tasks/current.md

## مسؤوليات AI
- إنشاء إطار اختبار وبيانات مقارنة بين الفعلي والمتوقع المقدم من البشر.
- لا تعدل المخرجات المتوقعة ما لم يُطلب ذلك صراحة من قبل البشر.

## عند إضافة ميزة / إصلاح
- أضف / تحديث على الأقل حالة بيانات ذهبية واحدة.
- تغطية الحدود وحالات الخطأ (فارغ، null، غير صحيح، إدخال كبير).

## قواعد مكافحة الغش
- تجنب كتابة اختبارات تعكس التنفيذ الحالي فقط.
- تفضل الاختبارات ذات الصندوق الأسود باستخدام المدخلات / المخرجات الذهبية.

# قواعد الأمان والخصوصية (الحد الأدنى للمشاريع الصغيرة)

## الأسرار
- لا تلتزم بـ .env. فقط التزم بـ .env.example.
- لا أسرار في الكود، التعليقات، الاختبارات، أو السجلات.
- إذا تم العثور على سر، توقف وحذر المستخدم.

## معالجة البيانات
- لا تضف بيانات حقيقية للعملاء / المستخدمين إلى المستودع.
- استخدم مجموعات بيانات مشفرة أو صناعية في test-data/ إذا لزم الأمر.

## استخدام الرموز (أدوات اختيارية)
- إذا كنت تستخدم gh CLI، فإن المصادقة مطلوبة:
  - محلي: `gh auth login`
  - CI / حاوية: قم بتعيين `GH_TOKEN` وتحقق من `gh auth status`
- احتفظ بالنطاقات في الحد الأدنى. تفضل النطاقات للقراءة فقط ما لم يكن ذلك ضروريًا.

## الأدوات / التكاملات الخارجية
- تجنب إدخال وكلاء / أدوات خارجية جديدة دون الإشارة إلى المخاطر في tasks/current.md.

# قواعد البرمجة

## الهيكل
- src/core: المنطق النقي (بدون إدخال / إخراج)
- src/adapters: الإدخال / الإخراج الخارجي (API / DB / ملفات)
- src/app: نقاط الدخول (CLI / HTTP / وظيفة)

## نطاق التغيير
- عدل فقط الملفات اللازمة للمهمة الحالية.
- إذا كان هناك حاجة إلى إعادة هيكلة أوسع، اقترح ذلك في tasks/current.md وانتظر الموافقة.

## الأسلوب
- حافظ على الوظائف صغيرة وذات مسؤولية واحدة.
- تفضل معالجة الأخطاء بشكل صريح للمكالمات الخارجية.

## رسائل الالتزام (التزامات تقليدية)
- feat: ...
- fix: ...
- refactor: ...
- test: ...
- docs: ...
- chore: ...

أنت مساعد في إنشاء خطة تطوير.
يرجى قراءة ما يلي وإنشاء أو تحديث tasks/current.md.

ترتيب القراءة:
1) docs/rules/index.md
2) README.md
3) tasks/current.md الحالية (إذا كانت موجودة)

متطلبات الإخراج:
- يجب أن يكون tasks/current.md "وثيقة خطة يتم الموافقة عليها من قبل البشر".
- ضع Goal / Non-goals / Acceptance (مملوكة للبشر) في البداية.
- يجب تقسيم الخطة إلى "حجم يمكن لـ AI التعامل معه في سياق واحد":
  - 3-5 ملفات مستهدفة للتغيير
  - إذا كانت الفروقات كبيرة، يجب تقسيمها
- إذا كانت هناك نقاط غير واضحة، يجب إدخال Spike في الخطة، مع افتراض وضعها في experiments/ لاحقًا.
- يجب أن تكون الموافقة دائمًا `WAITING` (ممنوع التنفيذ حتى يغيرها البشر إلى APPROVED).
- التوقعات (expected) يتم تأكيدها من قبل البشر، لذا لا تقم بإنشائها بشكل عشوائي، اترك "مساحة لتعبئة البشر".

سنستأنف العمل. يرجى تنفيذ ما يلي.

1) اقرأ docs/rules/index.md و tasks/current.md، وقدم ملخصًا عن الوضع الحالي
2) اختر عنصر تحقق واحد من tasks/current.md (يجب أن تكون الموافقة APPROVED)
3) قدم باختصار "ملفات التأثير المحتملة"، "استراتيجية التنفيذ"، و"طرق التحقق" لذلك العنصر
4) لا تكتب أي كود بعد (فقط خطط هنا)

يرجى تلخيص السياسة قبل التنفيذ حول المهمة الفرعية التالية.

- المسؤولية التي سيتم تغييرها (في core/adapters/app)
- الاستثناءات / شروط الحدود
- إذا كانت الاعتمادات غير واضحة، هل هناك حاجة إلى Spike؟
- ماذا يجب أن تضيفه في بيانات الاختبار (الذهبية) (التوقعات يتم كتابتها من قبل البشر)

سنقوم بإجراء Spike (بحث).

- قم بتنظيم خطوات البحث والنتائج المتوقعة مع افتراض إنشاء experiments/YYYYMMDD-<topic>.*.
- اكتب ما الذي يجب أن نعرفه للانتقال إلى التنفيذ الفعلي (شروط Go/No-Go).
- قدم مسودة لتدوين النتائج في experiments/README.md.

سنبدأ التنفيذ. القواعد:

- نفذ فقط النطاق المعتمد في tasks/current.md
- يجب أن تكون الملفات المتغيرة في الحد الأدنى (3-5 ملفات كحد أقصى)
- لا تقم بتغيير التوقعات (expected) حتى يتم تأكيدها من قبل البشر
- يجب احتواء الإدخال / الإخراج الخارجي في adapters
- بعد التنفيذ، قدم "كيف سيتم التحقق من ذلك (الأمر / نقاط المراقبة)"

سنقوم بإعداد الاختبارات.

- قم بإنشاء كود الاختبار في tests/ (إطار المقارنة)
- اجعل test-data/golden تعتمد على المدخلات / المخرجات
- يجب أن يتم إعداد محتوى expected من قبل البشر، لذا اعتبره كعنصر نائب
- اقترح إضافة حالات الحدود / الحالات الشاذة (لكن لا تنشئ التوقعات)

سنقوم بإعداد المراجعة.

- قدم قائمة الملفات التي تم تغييرها
- تحقق ذاتيًا من عدم وجود تغييرات غير متوقعة
- قدم جدولًا يوضح ما إذا كانت تلبي المواصفات (القبول) أم لا
- اقترح رسائل الالتزام باستخدام Commits التقليدية

قم بالتفكير في الماضي وحول ذلك إلى أصول.

- ما الذي نجح / لم ينجح
- القواعد التي يجب اتباعها في المهام المماثلة القادمة (أين يجب أن تضيف إلى docs/rules)
- حالات بيانات ذهبية إضافية يجب إضافتها، أو اقتراحات لإعادة إنتاج الأكواد في التجارب
- اقتراح إعادة تسمية tasks/current.md إلى tasks/YYYYMMDD-<short>.md

# الهدف
(يجب أن يكتبها البشر) ما الذي يجب تحقيقه في هذه المهمة في 1-3 أسطر.

# غير الأهداف
(يجب أن يكتبها البشر) ما الذي لن يتم القيام به هذه المرة. لمنع الانحراف عن النطاق.

# القبول (مملوك للبشر)
※ التوقعات يتم تأكيدها من قبل البشر. AI لا ينشئها.
- الحالة 01: المدخلات = test-data/golden/case01_input.json -> المتوقعة = test-data/golden/case01_expected.json
- الحالة 02: المدخلات = ... -> المتوقعة = ...

# الخطة (مسودات AI، يوافق عليها البشر)
- [ ] Spike: (إذا لزم الأمر) إضافة تحقق من الاعتمادات / سلوك الكود الموجود إلى experiments/
- [ ] التنفيذ: تعديل src/... (الملفات المستهدفة:)
- [ ] الاختبار: إضافة tests/... (مقارنة ذهبية)
- [ ] المراجعة: إعداد ملخص التغييرات واقتراح رسائل الالتزام
- [ ] التفكير في الماضي: إضافة حالة ذهبية أو تحديث القواعد أو إضافة تجربة (شرط الإنجاز)

# الملاحظات
- القيود، الفخاخ، الملاحظات

# الموافقة
الحالة: WAITING
الموافقة من:
الموافقة في:

# التجارب/

سنضع هنا تحقق من سلوك المكتبات المعتمدة، إعادة إنتاج الأخطاء، والتحقق من شروط الحدود.
هذا هو "مستند متحرك". لا نستخدمه لمرة واحدة (يجب الالتزام به).

## الفهرس
- 20251228-example_spike.md: مثال

# Spike: مثال

الهدف:
- التحقق من تنسيق الإدخال للمكتبة X

Go/No-Go:
- لا توجد استثناءات مع الإدخال A
- الناتج بهذا التنسيق مع الإدخال B (المراقبة)

النتائج:
- (سيتم إضافته بعد التنفيذ)

# test-data/

سنضع "التوقعات" التي يتم تأكيدها من قبل البشر هنا.
لمنع المرجع الدائري لـ AI، يجب أن يتم مراجعة expected من قبل البشر وتأكيدها.

- الذهبية/: أزواج الإدخال / المخرجات المتوقعة ذات الصندوق الأسود

# بيانات الاختبار الذهبية

التسمية:
- caseNN_input.*
- caseNN_expected.*

التشغيل:
- يجب أن يتم تأكيد expected من قبل البشر (لا ينشئها AI بشكل عشوائي)
- إضافة حالات الحدود / الحالات الشاذة

{
  "example": "input"
}

{
  "example": "expected"
}