هاد المجلد هو مصدر الحقيقة الوحيد لحالة المشروع وخططه. أي agent أو شخص لازم يقرأ من هون قبل ما يلمس الكود، وأي خطوة كبيرة لازم تنوثّق هون بعدها.

الملفات

الملف	شو فيه	إمتى تقرأه
`PROJECT-STATE.md`	الوضع الحالي الفعلي للموقع — شو موجود وشو شغّال	أول شي دايماً لتعرف الحالة بدون قراءة الكود
`STACK.md`	الستاك الموصى به وأسبابه	عند اتخاذ قرار تقني أو إضافة مكتبة
`ARCHITECTURE.md`	المعمارية المستهدفة، مخطط الداتابيس، اتفاقيات المجلدات والمكونات	قبل ما تبني أي feature جديد
`CHECKLIST.md`	تشيك لست شاملة لكل شي لازم يتبنى	نظرة عامة على المتبقّي
`TODO.md`	المهام الحالية القابلة للتنفيذ مع حالاتها	عند السؤال "شو عنا شي نعملو؟"
`IDEAS.md`	أفكار مستقبلية لسا مو مجدولة	لما يخطر ببال أفكار جديدة

سير العمل للـ Agents (مهم)

اقرأ ../AGENTS.md بالتفصيل. الخلاصة:

قبل أي شغل → اقرأ PROJECT-STATE.md عشان تفهم الوضع، وافحص TODO.md عشان تعرف المهام المفتوحة.
عند اقتراح شغل → خد المهام يلي حالتها TODO من TODO.md واقترحها.
بعد إنجاز مهمة →
- انقل المهمة من قسم ## 🔵 قيد التنفيذ / مفتوحة لقسم ## ✅ منجزة (Ready) بملف TODO.md.
- حدّث PROJECT-STATE.md ليعكس الوضع الجديد.
- إذا كانت خطوة كبيرة، وثّقها بسطر بالـ changelog بآخر PROJECT-STATE.md.

القاعدة الذهبية: لا تخلّي الكود يسبق التوثيق. إذا الكود تغيّر والتوثيق لأ — هاد باگ.