speccrew 0.5.10 → 0.5.12

package/docs/GETTING-STARTED.ar.md

@@ -1,4 +1,4 @@
-<div dir="rtl">
+# دليل البدء السريع لـ SpecCrew
 
 <p align="center">
   <a href="./GETTING-STARTED.md">简体中文</a> |
@@ -14,13 +14,11 @@
   <a href="./GETTING-STARTED.ar.md">العربية</a>
 </p>
 
-# دليل البدء السريع لـ SpecCrew
-
-يساعدك هذا المستند على فهم كيفية استخدام فريق وكلاء SpecCrew لإكمال دورة التطوير الكاملة من المتطلبات إلى التسليم باتباع عمليات الهندسة القياسية.
+تساعدك هذه الوثيقة على الفهم السريع لكيفية استخدام فريق Agent الخاص بـ SpecCrew لإكمال التطوير الكامل من المتطلبات إلى التسليم وفق عمليات الهندسة القياسية.
 
 ---
 
-## 1. المتطلبات الأساسية
+## 1. المتطلبات المسبقة
 
 ### تثبيت SpecCrew
 
@@ -34,49 +32,124 @@ npm install -g speccrew
 speccrew init --ide qoder
 ```
 
-بيئات التطوير المدعومة: `qoder`، `cursor`، `claude`، `codex`
+بيئات التطوير المدعومة: `qoder`, `cursor`, `claude`, `codex`
 
-### هيكل الدليل بعد التهيئة
+### بنية الدليل بعد التهيئة
 
 ```
 .
 ├── .qoder/
-│   ├── agents/          # ملفات تعريف الوكلاء
-│   └── skills/          # ملفات تعريف المهارات
+│   ├── agents/          # ملفات تعريف Agent
+│   └── skills/          # ملفات تعريف Skill
 ├── speccrew-workspace/  # مساحة العمل
-│   ├── docs/            # التكوينات والقواعد والقوالب والحلول
+│   ├── docs/            # التكوينات، القواعد، القوالب، الحلول
 │   ├── iterations/      # التكرارات الجارية حالياً
 │   ├── iteration-archives/  # التكرارات المؤرشفة
 │   └── knowledges/      # قاعدة المعرفة
-│       ├── base/        # المعلومات الأساسية (تقارير التشخيص والديون التقنية)
-│       ├── bizs/        # قاعدة المعرفة التجارية
+│       ├── base/        # المعلومات الأساسية (تقارير التشخيص، الديون التقنية)
+│       ├── bizs/        # قاعدة معرفة الأعمال
 │       └── techs/       # قاعدة المعرفة التقنية
 ```
 
 ### مرجع سريع لأوامر CLI
 
 | الأمر | الوصف |
-|-------|--------|
-| `speccrew list` | عرض جميع الوكلاء والمهارات المتاحة |
+|------|------|
+| `speccrew list` | سرد جميع Agents و Skills المتاحة |
 | `speccrew doctor` | التحقق من سلامة التثبيت |
 | `speccrew update` | تحديث تكوين المشروع إلى أحدث إصدار |
 | `speccrew uninstall` | إلغاء تثبيت SpecCrew |
 
 ---
 
-## 2. نظرة عامة على سير العمل
+## 2. البدء السريع في 5 دقائق بعد التثبيت
+
+بعد تشغيل `speccrew init`، اتبع هذه الخطوات للدخول بسرعة في حالة العمل:
+
+### الخطوة 1: اختر بيئة التطوير الخاصة بك
+
+| بيئة التطوير | أمر التهيئة | سيناريو التطبيق |
+|-----|-----------|----------|
+| **Qoder** (موصى به) | `speccrew init --ide qoder` | أوركسترا كامل للوكلاء، عمال متوازيون |
+| **Cursor** | `speccrew init --ide cursor` | سير العمل القائم على Composer |
+| **Claude Code** | `speccrew init --ide claude` | تطوير CLI أولاً |
+| **Codex** | `speccrew init --ide codex` | تكامل نظام OpenAI البيئي |
+
+### الخطوة 2: تهيئة قاعدة المعرفة (موصى به)
+
+بالنسبة للمشاريع ذات الكود المصدري الموجود، يوصى بتهيئة قاعدة المعرفة أولاً حتى يفهم الوكلاء قاعدة الكود الخاصة بك:
+
+```
+@speccrew-team-leader تهيئة قاعدة المعرفة التقنية
+```
+
+ثم:
+
+```
+@speccrew-team-leader تهيئة قاعدة معرفة الأعمال
+```
+
+### الخطوة 3: ابدأ مهمتك الأولى
+
+```
+@speccrew-product-manager لدي متطلب جديد: [صف متطلبك الوظيفي]
+```
+
+> **نصيحة**: إذا لم تكن متأكداً مما يجب فعله، فقط قل `@speccrew-team-leader ساعدني على البدء` — سيكتشف Team Leader حالة مشروعك تلقائياً ويرشدك.
+
+---
+
+## 3. شجرة القرار السريع
+
+غير متأكد مما يجب فعله؟ ابحث عن السيناريو الخاص بك أدناه:
+
+- **لدي متطلب وظيفي جديد**
+  → `@speccrew-product-manager لدي متطلب جديد: [صف متطلبك الوظيفي]`
+
+- **أريد مسح معرفة المشروع الموجود**
+  → `@speccrew-team-leader تهيئة قاعدة المعرفة التقنية`
+  → ثم: `@speccrew-team-leader تهيئة قاعدة معرفة الأعمال`
+
+- **أريد متابعة العمل السابق**
+  → `@speccrew-team-leader ما هو التقدم الحالي؟`
+
+- **أريد التحقق من حالة صحة النظام**
+  → تشغيل في الطرفية: `speccrew doctor`
+
+- **لست متأكداً مما يجب فعله**
+  → `@speccrew-team-leader ساعدني على البدء`
+  → سيكتشف Team Leader حالة مشروعك تلقائياً ويرشدك
+
+---
+
+## 4. مرجع سريع للوكلاء
+
+| الدور | Agent | المسؤوليات | مثال على الأمر |
+|------|-------|-----------------|-----------------|
+| قائد الفريق | `@speccrew-team-leader` | تنقل المشروع، تهيئة قاعدة المعرفة، التحقق من الحالة | "ساعدني على البدء" |
+| مدير المنتج | `@speccrew-product-manager` | تحليل المتطلبات، إنشاء PRD | "لدي متطلب جديد: ..." |
+| مصمم الوظائف | `@speccrew-feature-designer` | تحليل الوظائف، تصميم المواصفات، عقود API | "ابدأ تصميم الوظائف للتكرار X" |
+| مصمم النظام | `@speccrew-system-designer` | تصميم الهندسة المعمارية، التصميم التفصيلي للمنصة | "ابدأ تصميم النظام للتكرار X" |
+| مطور النظام | `@speccrew-system-developer` | تنسيق التطوير، إنشاء الكود | "ابدأ التطوير للتكرار X" |
+| مدير الاختبار | `@speccrew-test-manager` | تخطيط الاختبار، تصميم الحالات، التنفيذ | "ابدأ الاختبار للتكرار X" |
+
+> **ملاحظة**: لا تحتاج إلى تذكر جميع الوكلاء. فقط تحدث مع `@speccrew-team-leader` وسيقوم بتوجيه طلبك إلى الوكيل المناسب.
+
+---
+
+## 5. نظرة عامة على سير العمل
 
 ### مخطط التدفق الكامل
 
 ```mermaid
 flowchart LR
-    PRD[المرحلة 1<br/>تحليل المتطلبات<br/>Product Manager] --> FD[المرحلة 2<br/>تصميم الميزات<br/>Feature Designer]
+    PRD[المرحلة 1<br/>تحليل المتطلبات<br/>Product Manager] --> FD[المرحلة 2<br/>تصميم الوظائف<br/>Feature Designer]
     FD --> SD[المرحلة 3<br/>تصميم النظام<br/>System Designer]
     SD --> DEV[المرحلة 4<br/>التطوير<br/>System Developer]
     DEV --> TEST[المرحلة 5<br/>اختبار النظام<br/>Test Manager]
     TEST --> ARCHIVE[المرحلة 6<br/>الأرشفة]
     
-    KB[(قاعدة المعرفة<br/>على مدار العملية)] -.-> PRD
+    KB[(قاعدة المعرفة<br/>طوال العملية)] -.-> PRD
     KB -.-> FD
     KB -.-> SD
     KB -.-> DEV
@@ -85,17 +158,17 @@ flowchart LR
 
 ### المبادئ الأساسية
 
-1. **تبعيات المراحل**: مخرجات كل مرحلة هي مدخلات للمرحلة التالية
-2. **تأكيد نقطة التحقق**: تحتوي كل مرحلة على نقطة تأكيد تتطلب موافقة المستخدم قبل المتابعة إلى المرحلة التالية
-3. **الاعتماد على قاعدة المعرفة**: تعمل قاعدة المعرفة طوال العملية بأكملها، مما يوفر السياق لجميع المراحل
+1. **تبعية المراحل**: مخرجات كل مرحلة هي مدخلات المرحلة التالية
+2. **تأكيد نقطة التفتيش**: كل مرحلة لها نقطة تأكيد تتطلب موافقة المستخدم قبل المتابعة إلى المرحلة التالية
+3. **مدعوم بقاعدة المعرفة**: قاعدة المعرفة تعمل طوال العملية بأكملها، وتوفر السياق لجميع المراحل
 
 ---
 
-## 3. تهيئة قاعدة المعرفة
+## 6. الخطوة صفر: تهيئة قاعدة المعرفة
 
 قبل بدء عملية الهندسة الرسمية، تحتاج إلى تهيئة قاعدة معرفة المشروع.
 
-### 3.1 تهيئة قاعدة المعرفة التقنية
+### 6.1 تهيئة قاعدة المعرفة التقنية
 
 **مثال على المحادثة**:
 ```
@@ -104,33 +177,33 @@ flowchart LR
 
 **عملية من ثلاث مراحل**:
 1. اكتشاف المنصة — تحديد المنصات التقنية في المشروع
-2. إنشاء الوثائق التقنية — إنشاء مستندات المواصفات التقنية لكل منصة
+2. إنشاء الوثائق التقنية — إنشاء وثائق المواصفات التقنية لكل منصة
 3. إنشاء الفهرس — إنشاء فهرس قاعدة المعرفة
 
-**المخرجات**:
+**المخرج**:
 ```
 speccrew-workspace/knowledges/techs/{platform-id}/
-├── tech-stack.md          # تعريف المكدس التقني
+├── tech-stack.md          # تعريف مكدس التقنية
 ├── architecture.md        # اتفاقيات الهندسة المعمارية
 ├── dev-spec.md            # مواصفات التطوير
 ├── test-spec.md           # مواصفات الاختبار
 └── INDEX.md               # ملف الفهرس
 ```
 
-### 3.2 تهيئة قاعدة المعرفة التجارية
+### 6.2 تهيئة قاعدة معرفة الأعمال
 
 **مثال على المحادثة**:
 ```
-@speccrew-team-leader تهيئة قاعدة المعرفة التجارية
+@speccrew-team-leader تهيئة قاعدة معرفة الأعمال
 ```
 
 **عملية من أربع مراحل**:
-1. جرد الميزات — مسح الكود لتحديد جميع الميزات الوظيفية
-2. تحليل الميزات — تحليل المنطق التجاري لكل ميزة
-3. تلخيص الوحدة — تلخيص الميزات حسب الوحدة
-4. تلخيص النظام — إنشاء نظرة عامة على الأعمال على مستوى النظام
+1. جرد الوظائف — مسح الكود لتحديد جميع الوظائف
+2. تحليل الوظائف — تحليل منطق الأعمال لكل وظيفة
+3. ملخص الوحدة — تلخيص الوظائف حسب الوحدة
+4. ملخص النظام — إنشاء نظرة عامة على الأعمال على مستوى النظام
 
-**المخرجات**:
+**المخرج**:
 ```
 speccrew-workspace/knowledges/bizs/
 ├── {platform-type}/
@@ -141,55 +214,55 @@ speccrew-workspace/knowledges/bizs/
 
 ---
 
-## 4. دليل المحادثة المرحلي
+## 7. دليل المحادثة مرحلة بمرحلة
 
-### 4.1 المرحلة 1: تحليل المتطلبات (Product Manager)
+### 7.1 المرحلة 1: تحليل المتطلبات (Product Manager)
 
 **كيفية البدء**:
 ```
 @speccrew-product-manager لدي متطلب جديد: [صف متطلبك]
 ```
 
-**سير عمل الوكيل**:
-1. قراءة نظرة عامة على النظام لفهم الوحدات الموجودة
-2. تحليل متطلبات المستخدم
-3. إنشاء مستند PRD منظم
+**سير عمل Agent**:
+1. اقرأ نظرة عامة على النظام لفهم الوحدات الموجودة
+2. حلل متطلبات المستخدم
+3. أنشئ وثيقة PRD منظمة
 
-**المخرجات**:
+**المخرج**:
 ```
 iterations/{رقم}-{نوع}-{اسم}/01.product-requirement/
-├── [feature-name]-prd.md           # مستند متطلبات المنتج
-└── [feature-name]-bizs-modeling.md # النمذجة التجارية (للمتطلبات المعقدة)
+├── [feature-name]-prd.md           # وثيقة متطلبات المنتج
+└── [feature-name]-bizs-modeling.md # نمذجة الأعمال (للمتطلبات المعقدة)
 ```
 
-**قائمة التحقق للتأكيد**:
-- [ ] هل يعكس وصف المتطلب نية المستخدم بدقة؟
-- [ ] هل القواعد التجارية كاملة؟
+**قائمة مراجعة التأكيد**:
+- [ ] هل وصف المتطلب يعكس بدقة نية المستخدم؟
+- [ ] هل قواعد الأعمال كاملة؟
 - [ ] هل نقاط التكامل مع الأنظمة الموجودة واضحة؟
-- [ ] هل معايير القبول قابلة للقياس؟
+- [ ] هل معايير الق acceptance قابلة للقياس؟
 
 ---
 
-### 4.2 المرحلة 2: تصميم الميزات (Feature Designer)
+### 7.2 المرحلة 2: تصميم الوظائف (Feature Designer)
 
 **كيفية البدء**:
 ```
-@speccrew-feature-designer بدء تصميم الميزات
+@speccrew-feature-designer ابدأ تصميم الوظائف
 ```
 
-**سير عمل الوكيل**:
-1. تحديد موقع مستند PRD المؤكد تلقائياً
-2. تحميل قاعدة المعرفة التجارية
-3. إنشاء تصميم الميزات (بما في ذلك مخططات wireframe للواجهة، وتدفقات التفاعل، وتعريفات البيانات، وعقود API)
-4. لـ PRDs متعددة، استخدام Task Worker للتصميم المتوازي
+**سير عمل Agent**:
+1. تحديد موقع وثيقة PRD المؤكدة تلقائياً
+2. تحميل قاعدة معرفة الأعمال
+3. إنشاء تصميم الوظيفة (بما في ذلك wireframes UI، تدفقات التفاعل، تعريفات البيانات، عقود API)
+4. لعدة PRDs، استخدم Task Worker للتصميم المتوازي
 
-**المخرجات**:
+**المخرج**:
 ```
 iterations/{iter}/02.feature-design/
-└── [feature-name]-feature-spec.md  # مستند تصميم الميزات
+└── [feature-name]-feature-spec.md  # وثيقة تصميم الوظيفة
 ```
 
-**قائمة التحقق للتأكيد**:
+**قائمة مراجعة التأكيد**:
 - [ ] هل جميع سيناريوهات المستخدم مغطاة؟
 - [ ] هل تدفقات التفاعل واضحة؟
 - [ ] هل تعريفات حقول البيانات كاملة؟
@@ -197,88 +270,88 @@ iterations/{iter}/02.feature-design/
 
 ---
 
-### 4.3 المرحلة 3: تصميم النظام (System Designer)
+### 7.3 المرحلة 3: تصميم النظام (System Designer)
 
 **كيفية البدء**:
 ```
-@speccrew-system-designer بدء تصميم النظام
+@speccrew-system-designer ابدأ تصميم النظام
 ```
 
-**سير عمل الوكيل**:
+**سير عمل Agent**:
 1. تحديد موقع Feature Spec و API Contract
-2. تحميل قاعدة المعرفة التقنية (المكدس التقني، والهندسة المعمارية، والمواصفات لكل منصة)
-3. **نقطة التحقق أ**: تقييم الإطار — تحليل الفجوات التقنية، وتوصية أطر عمل جديدة (إذا لزم الأمر)، والانتظار لتأكيد المستخدم
+2. تحميل قاعدة المعرفة التقنية (مكدس التقنية، الهندسة المعمارية، المواصفات لكل منصة)
+3. **Checkpoint A**: تقييم الإطار — تحليل الفجوات التقنية، توصية أطر جديدة (إذا لزم الأمر)، انتظار تأكيد المستخدم
 4. إنشاء DESIGN-OVERVIEW.md
-5. استخدام Task Worker للتوزيع المتوازي للتصميم لكل منصة (الواجهة الأمامية/الخلفية/الجوال/سطح المكتب)
-6. **نقطة التحقق ب**: التأكيد المشترك — عرض ملخص جميع تصاميم المنصات، والانتظار لتأكيد المستخدم
+5. استخدام Task Worker للتوزيع المتوازي للتصميم لكل منصة (frontend/backend/mobile/desktop)
+6. **Checkpoint B**: تأكيد مشترك — عرض ملخص جميع تصاميم المنصات، انتظار تأكيد المستخدم
 
-**المخرجات**:
+**المخرج**:
 ```
 iterations/{iter}/03.system-design/
 ├── DESIGN-OVERVIEW.md              # نظرة عامة على التصميم
 ├── {platform-id}/
 │   ├── INDEX.md                    # فهرس تصميم المنصة
-│   └── {module}-design.md          # تصميم الوحدة على مستوى الشيفرة الوهمية
+│   └── {module}-design.md          # تصميم الوحدة على مستوى pseudocode
 ```
 
-**قائمة التحقق للتأكيد**:
-- [ ] هل تستخدم الشيفرة الوهمية بناء جملة إطار العمل الفعلي؟
-- [ ] هل عقود API متعددة المنصات متسقة؟
+**قائمة مراجعة التأكيد**:
+- [ ] هل يستخدم pseudocode بناء الإطار الفعلي؟
+- [ ] هل عقود API عبر المنصات متسقة؟
 - [ ] هل استراتيجية معالجة الأخطاء موحدة؟
 
 ---
 
-### 4.4 المرحلة 4: تنفيذ التطوير (System Developer)
+### 7.4 المرحلة 4: التطوير (System Developer)
 
 **كيفية البدء**:
 ```
-@speccrew-system-developer بدء التطوير
+@speccrew-system-developer ابدأ التطوير
 ```
 
-**سير عمل الوكيل**:
-1. قراءة مستندات تصميم النظام
+**سير عمل Agent**:
+1. اقرأ وثائق تصميم النظام
 2. تحميل المعرفة التقنية لكل منصة
-3. **نقطة التحقق أ**: الفحص المسبق للبيئة — التحقق من إصدارات وقت التشغيل والتبعيات وتوفر الخدمات؛ الانتظار لحل المستخدم في حالة الفشل
+3. **Checkpoint A**: الفحص المسبق للبيئة — التحقق من إصدارات runtime، التبعيات، توفر الخدمات؛ انتظار حل المستخدم إذا فشل
 4. استخدام Task Worker للتوزيع المتوازي للتطوير لكل منصة
-5. التحقق من التكامل: محاذاة عقود API، واتساق البيانات
+5. فحص التكامل: محاذاة عقد API، اتساق البيانات
 6. إخراج تقرير التسليم
 
-**المخرجات**:
+**المخرج**:
 ```
-# كتابة الكود المصدري في دليل الكود المصدري الفعلي للمشروع
+# يتم كتابة الكود المصدري في دليل المصدر الفعلي للمشروع
 iterations/{iter}/04.development/
 ├── {platform-id}/
-│   └── tasks/                      # سجلات مهام التطوير
+│   └── tasks/                      # سجلات مهمة التطوير
 └── delivery-report.md
 ```
 
-**قائمة التحقق للتأكيد**:
+**قائمة مراجعة التأكيد**:
 - [ ] هل البيئة جاهزة؟
 - [ ] هل مشاكل التكامل ضمن النطاق المقبول؟
 - [ ] هل الكود يتوافق مع مواصفات التطوير؟
 
 ---
 
-### 4.5 المرحلة 5: اختبار النظام (Test Manager)
+### 7.5 المرحلة 5: اختبار النظام (Test Manager)
 
 **كيفية البدء**:
 ```
-@speccrew-test-manager بدء الاختبار
+@speccrew-test-manager ابدأ الاختبار
 ```
 
 **عملية الاختبار من ثلاث مراحل**:
 
-| المرحلة | الوصف | نقطة التحقق |
-|---------|--------|-------------|
-| تصميم حالات الاختبار | إنشاء حالات اختبار بناءً على PRD و Feature Spec | أ: عرض إحصائيات تغطية الحالات ومصفوفة التتبع، والانتظار لتأكيد المستخدم على التغطية الكافية |
-| إنشاء كود الاختبار | إنشاء كود اختبار قابل للتنفيذ | ب: عرض ملفات الاختبار المنشأة وتعيين الحالات، والانتظار لتأكيد المستخدم |
-| تنفيذ الاختبار وتقرير الأخطاء | تنفيذ الاختبارات تلقائياً وإنشاء التقارير | لا شيء (تنفيذ تلقائي) |
+| المرحلة | الوصف | Checkpoint |
+|-------|-------------|------------|
+| تصميم حالات الاختبار | إنشاء حالات اختبار بناءً على PRD و Feature Spec | A: عرض إحصائيات تغطية الحالات ومصفوفة التتبع، انتظار تأكيد المستخدم على التغطية الكافية |
+| إنشاء كود الاختبار | إنشاء كود اختبار قابل للتنفيذ | B: عرض ملفات الاختبار التي تم إنشاؤها وتخطيط الحالات، انتظار تأكيد المستخدم |
+| تنفيذ الاختبار وإعداد تقارير الأخطاء | تنفيذ الاختبارات تلقائياً وإنشاء التقارير | لا شيء (تنفيذ تلقائي) |
 
-**المخرجات**:
+**المخرج**:
 ```
 iterations/{iter}/05.system-test/
 ├── cases/
-│   └── {platform-id}/              # مستندات حالات الاختبار
+│   └── {platform-id}/              # وثائق حالات الاختبار
 ├── code/
 │   └── {platform-id}/              # خطة كود الاختبار
 ├── reports/
@@ -287,16 +360,16 @@ iterations/{iter}/05.system-test/
     └── BUG-{id}-{title}.md         # تقارير الأخطاء (ملف واحد لكل خطأ)
 ```
 
-**قائمة التحقق للتأكيد**:
+**قائمة مراجعة التأكيد**:
 - [ ] هل تغطية الحالات كاملة؟
 - [ ] هل كود الاختبار قابل للتشغيل؟
-- [ ] هل تقييم خطورة الأخطاء دقيق؟
+- [ ] هل تقييم شدة الخطأ دقيق؟
 
 ---
 
-### 4.6 المرحلة 6: الأرشفة
+### 7.6 المرحلة 6: الأرشفة
 
-يتم أرشفة التكرارات تلقائياً عند اكتمالها:
+يتم أرشفة التكرارات تلقائياً بعد الاكتمال:
 
 ```
 speccrew-workspace/iteration-archives/
@@ -310,13 +383,13 @@ speccrew-workspace/iteration-archives/
 
 ---
 
-## 5. نظرة عامة على قاعدة المعرفة
+## 8. نظرة عامة على قاعدة المعرفة
 
-### 5.1 قاعدة المعرفة التجارية (bizs)
+### 8.1 قاعدة معرفة الأعمال (bizs)
 
-**الغرض**: تخزين أوصاف الوظائف التجارية للمشروع، وتقسيم الوحدات، وخصائص API
+**الغرض**: تخزين أوصاف وظائف أعمال المشروع، تقسيمات الوحدات، خصائص API
 
-**هيكل الدليل**:
+**بنية الدليل**:
 ```
 knowledges/bizs/
 ├── {platform-type}/
@@ -325,13 +398,13 @@ knowledges/bizs/
 └── system-overview.md
 ```
 
-**سيناريوهات الاستخدام**: Product Manager، Feature Designer
+**سيناريوهات الاستخدام**: Product Manager, Feature Designer
 
-### 5.2 قاعدة المعرفة التقنية (techs)
+### 8.2 قاعدة المعرفة التقنية (techs)
 
-**الغرض**: تخزين المكدس التقني للمشروع، واتفاقيات الهندسة المعمارية، ومواصفات التطوير، ومواصفات الاختبار
+**الغرض**: تخزين مكدس تقنية المشروع، اتفاقيات الهندسة المعمارية، مواصفات التطوير، مواصفات الاختبار
 
-**هيكل الدليل**:
+**بنية الدليل**:
 ```
 knowledges/techs/{platform-id}/
 ├── tech-stack.md
@@ -341,25 +414,25 @@ knowledges/techs/{platform-id}/
 └── INDEX.md
 ```
 
-**سيناريوهات الاستخدام**: System Designer، System Developer، Test Manager
+**سيناريوهات الاستخدام**: System Designer, System Developer, Test Manager
 
 ---
 
-## 6. إدارة تقدم سير العمل
+## 9. إدارة تقدم سير العمل
 
-يتبع الفريق الافتراضي SpecCrew آلية بوابة مرحلية صارمة حيث يجب تأكيد كل مرحلة من قبل المستخدم قبل المتابعة إلى المرحلة التالية. كما يدعم التنفيذ القابل للاستئناف — عند إعادة التشغيل بعد الانقطاع، يستمر تلقائياً من حيث توقف.
+يتبع فريق SpecCrew الافتراضي آلية بوابة مرحلة صارمة حيث يجب تأكيد كل مرحلة من قبل المستخدم قبل الانتقال إلى المرحلة التالية. كما يدعم التنفيذ القابل للاستئناف — عند إعادة التشغيل بعد الانقطاع، يستمر تلقائياً من حيث توقف.
 
-### 6.1 ملفات التقدم ثلاثية الطبقات
+### 9.1 ملفات التقدم ذات الطبقات الثلاث
 
-يحافظ سير العمل تلقائياً على ثلاثة أنواع من ملفات تقدم JSON، موجودة في دليل التكرار:
+يحافظ سير العمل تلقائياً على ثلاثة أنواع من ملفات تقدم JSON، الموجودة في دليل التكرار:
 
 | الملف | الموقع | الغرض |
-|-------|--------|--------|
-| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | يسجل حالة كل مرحلة من مراحل خط الأنابيب |
-| `.checkpoints.json` | تحت كل دليل مرحلة | يسجل حالة تأكيد نقطة التحقق من المستخدم |
-| `DISPATCH-PROGRESS.json` | تحت كل دليل مرحلة | يسجل التقدم بند لكل بند للمهام المتوازية (متعددة المنصات/الوحدات) |
+|------|----------|---------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | يسجل حالة كل مرحلة من pipeline |
+| `.checkpoints.json` | تحت كل دليل مرحلة | يسجل حالة تأكيد checkpoint للمستخدم |
+| `DISPATCH-PROGRESS.json` | تحت كل دليل مرحلة | يسجل التقدم بنداً بنداً للمهام المتوازية (متعدد المنصات/متعدد الوحدات) |
 
-### 6.2 تدفق حالة المرحلة
+### 9.2 تدفق حالة المرحلة
 
 تتبع كل مرحلة تدفق الحالة هذا:
 
@@ -368,27 +441,27 @@ pending → in_progress → completed → confirmed
 ```
 
 - **pending**: لم يبدأ بعد
-- **in_progress**: قيد التنفيذ حالياً
-- **completed**: اكتمل تنفيذ الوكيل، في انتظار تأكيد المستخدم
-- **confirmed**: أكد المستخدم عبر نقطة التحقق النهائية، يمكن بدء المرحلة التالية
+- **in_progress**: قيد التنفيذ
+- **completed**: اكتمل تنفيذ Agent، في انتظار تأكيد المستخدم
+- **confirmed**: أكد المستخدم عبر checkpoint النهائي، يمكن بدء المرحلة التالية
 
-### 6.3 التنفيذ القابل للاستئناف
+### 9.3 التنفيذ القابل للاستئناف
 
-عند إعادة تشغيل وكيل لمرحلة:
+عند إعادة تشغيل Agent لمرحلة:
 
-1. **التحقق التلقائي من المنبع**: يتحقق مما إذا كانت المرحلة السابقة مؤكدة، ويحظر ويطالب إذا لم تكن كذلك
-2. **استعادة نقطة التحقق**: يقرأ `.checkpoints.json`، يتخطى نقاط التحقق المتجاوزة، يستمر من نقطة الانقطاع الأخيرة
-3. **استعادة المهمة المتوازية**: يقرأ `DISPATCH-PROGRESS.json`، يعيد تنفيذ المهام ذات الحالة `pending` أو `failed` فقط، يتخطى المهام `completed`
+1. **فحص upstream تلقائي**: التحقق مما إذا كانت المرحلة السابقة مؤكدة، يمنع ويطلب إذا لم تكن كذلك
+2. **استعادة Checkpoint**: يقرأ `.checkpoints.json`، يتخطى checkpoints التي تم اجتيازها، يستمر من آخر نقطة انقطاع
+3. **استعادة المهام المتوازية**: يقرأ `DISPATCH-PROGRESS.json`، يعيد تنفيذ المهام ذات الحالة `pending` أو `failed` فقط، يتخطى المهام `completed`
 
-### 6.4 عرض التقدم الحالي
+### 9.4 عرض التقدم الحالي
 
-عرض حالة بانوراما خط الأنابيب عبر وكيل قائد الفريق:
+عرض حالة panorama للـ pipeline عبر Agent Team Leader:
 
 ```
 @speccrew-team-leader عرض تقدم التكرار الحالي
 ```
 
-سيقرأ قائد الفريق ملفات التقدم ويعرض نظرة عامة على الحالة مشابهة لـ:
+سيقرأ Team Leader ملفات التقدم ويعرض نظرة عامة على الحالة مشابهة لـ:
 
 ```
 Pipeline Status: i001-user-management
@@ -399,27 +472,27 @@ Pipeline Status: i001-user-management
   05 System Test:    ⏳ Pending
 ```
 
-### 6.5 التوافق العكسي
+### 9.5 التوافق مع الإصدارات السابقة
 
-آلية ملفات التقدم متوافقة تماماً مع الإصدارات السابقة — إذا لم تكن ملفات التقدم موجودة (مثلاً في المشاريع القديمة أو التكرارات الجديدة)، سيقوم جميع الوكلاء بالتنفيذ بشكل طبيعي وفقاً للمنطق الأصلي.
+آلية ملف التقدم متوافقة تماماً مع الإصدارات السابقة — إذا لم تكن ملفات التقدم موجودة (مثل المشاريع القديمة أو التكرارات الجديدة)، فسينفذ جميع Agents بشكل طبيعي وفقاً للمنطق الأصلي.
 
 ---
 
-## 7. الأسئلة الشائعة (FAQ)
+## 10. الأسئلة الشائعة (FAQ)
 
-### س1: ماذا أفعل إذا لم يعمل الوكيل كما هو متوقع؟
+### س1: ماذا أفعل إذا لم يعمل Agent كما هو متوقع؟
 
-1. قم بتشغيل `speccrew doctor` للتحقق من سلامة التثبيت
-2. تأكد من تهيئة قاعدة المعرفة
-3. تأكد من وجود مخرجات المرحلة السابقة في دليل التكرار الحالي
+1. تشغيل `speccrew doctor` للتحقق من سلامة التثبيت
+2. تأكيد تهيئة قاعدة المعرفة
+3. تأكيد وجود مخرجات المرحلة السابقة في دليل التكرار الحالي
 
-### س2: كيف يمكنني تخطي مرحلة معينة؟
+### س2: كيف أتخطى مرحلة؟
 
-**غير موصى به** — مخرجات كل مرحلة هي مدخلات للمرحلة التالية.
+**غير مستحسن** — مخرجات كل مرحلة هي مدخلات المرحلة التالية.
 
-إذا كان يجب عليك التخطي، قم بإعداد مستند الإدخال للمرحلة المقابلة يدوياً وتأكد من أنه يتبع مواصفات التنسيق.
+إذا كنت يجب أن تتخطى، قم يدوياً بإعداد مستند الإدخال للمرحلة المقابلة وتأكد من أنه يتوافق مع مواصفات التنسيق.
 
-### س3: كيفية التعامل مع متطلبات متعددة بالتوازي؟
+### س3: كيف أتعامل مع متطلبات متعددة متوازية؟
 
 أنشئ أدلة تكرار مستقلة لكل متطلب:
 ```
@@ -431,94 +504,94 @@ iterations/
 
 كل تكرار معزول تماماً ولا يؤثر على الآخرين.
 
-### س4: كيفية تحديث إصدار SpecCrew؟
+### س4: كيف أحدث إصدار SpecCrew؟
 
-يتم التحديث على خطوتين:
+يتطلب التحديث خطوتين:
 
 ```bash
-# الخطوة 1: تحديث أداة CLI العامة
+# الخطوة 1: تحديث أداة CLI العالمية
 npm install -g speccrew@latest
 
-# الخطوة 2: مزامنة Agents و Skills في دليل المشروع
+# الخطوة 2: مزامنة Agents و Skills في دليل مشروعك
 cd /path/to/your-project
 speccrew update
 ```
 
-- `npm install -g speccrew@latest`: تحديث أداة CLI نفسها (قد تحتوي النسخة الجديدة على تعريفات Agent/Skill جديدة، إصلاحات أخطاء، إلخ)
-- `speccrew update`: مزامنة ملفات تعريف Agent و Skill في المشروع إلى أحدث إصدار
-- `speccrew update --ide cursor`: تحديث تكوين IDE المحدد فقط
+- `npm install -g speccrew@latest`: يحدث أداة CLI نفسها (قد تتضمن الإصدارات الجديدة تعريفات Agent/Skill جديدة، إصلاحات الأخطاء، إلخ)
+- `speccrew update`: يزامن ملفات تعريف Agent و Skill في مشروعك إلى أحدث إصدار
+- `speccrew update --ide cursor`: يحدث التكوين لبيئة تطوير محددة فقط
 
-> **ملاحظة**: يجب تنفيذ الخطوتين. تنفيذ `speccrew update` فقط لن يحدث أداة CLI نفسها؛ وتنفيذ `npm install` فقط لن يحدث الملفات في المشروع.
+> **ملاحظة**: كلتا الخطوتين مطلوبتان. تشغيل `speccrew update` فقط لن يحدث أداة CLI نفسها؛ تشغيل `npm install` فقط لن يحدث ملفات المشروع.
 
-### س5: يظهر `speccrew update` إصدارًا جديدًا لكن بعد التثبيت لا يزال الإصدار القديم؟
+### س5: `speccrew update` يظهر إصدار جديد متاح لكن `npm install -g speccrew@latest` لا يزال يثبت الإصدار القديم؟
 
-عادةً ما يكون بسبب ذاكرة التخزين المؤقت npm. الحل:
+هذا عادة ما يكون بسبب ذاكرة التخزين المؤقت لـ npm. الحل:
 
 ```bash
+# مسح ذاكرة التخزين المؤقت لـ npm وإعادة التثبيت
 npm cache clean --force
 npm install -g speccrew@latest
+
+# التحقق من الإصدار
 npm list -g speccrew
 ```
 
-إذا لم يعمل، حدد رقم الإصدار:
+إذا لم ينجح ذلك بعد، حاول التثبيت برقم إصدار محدد:
 ```bash
 npm install -g speccrew@0.5.6
 ```
 
-### س6: كيفية عرض التكرارات التاريخية؟
+### س6: كيف أعرض التكرارات التاريخية؟
 
-بعد الأرشفة، عرض في `speccrew-workspace/iteration-archives/`، منظم بتنسيق `{رقم}-{نوع}-{اسم}-{تاريخ}/`.
+بعد الأرشفة، اعرض في `speccrew-workspace/iteration-archives/`، منظمة بتنسيق `{رقم}-{نوع}-{اسم}-{تاريخ}/`.
 
-### س7: هل تحتاج قاعدة المعرفة إلى تحديثات دورية؟
+### س7: هل تحتاج قاعدة المعرفة إلى تحديثات منتظمة؟
 
-مطلوب إعادة التهيئة في الحالات التالية:
-- تغييرات كبيرة في هيكل المشروع
-- ترقية أو استبدال المكدس التقني
-- إضافة/حذف وحدات تجارية
+إعادة التهيئة مطلوبة في الحالات التالية:
+- تغييرات كبيرة في بنية المشروع
+- ترقية أو استبدال مكدس التقنية
+- إضافة/إزالة وحدات الأعمال
 
 ---
 
-## 8. مرجع سريع
+## 11. مرجع سريع
 
-### مرجع سريع لبدء الوكلاء
-
-| المرحلة | الوكيل | محادثة البدء |
-|---------|--------|--------------|
+### مرجع سريع لبدء Agent
 
+| المرحلة | Agent | محادثة البدء |
+|-------|-------|-------------------|
 | التهيئة | Team Leader | `@speccrew-team-leader تهيئة قاعدة المعرفة التقنية` |
-| تحليل المتطلبات | Product Manager | `@speccrew-product-manager لدي متطلب جديد: [الوصف]` |
-| تصميم الميزات | Feature Designer | `@speccrew-feature-designer بدء تصميم الميزات` |
-| تصميم النظام | System Designer | `@speccrew-system-designer بدء تصميم النظام` |
-| التطوير | System Developer | `@speccrew-system-developer بدء التطوير` |
-| اختبار النظام | Test Manager | `@speccrew-test-manager بدء الاختبار` |
-
-### قائمة التحقق لنقاط التحقق
-
-| المرحلة | عدد نقاط التحقق | عناصر التحقق الرئيسية |
-|---------|-----------------|----------------------|
-| تحليل المتطلبات | 1 | دقة المتطلبات، اكتمال القواعد التجارية، قابلية قياس معايير القبول |
-| تصميم الميزات | 1 | تغطية السيناريوهات، وضوح التفاعل، اكتمال البيانات، معالجة الاستثناءات |
-| تصميم النظام | 2 | أ: تقييم الإطار؛ ب: بناء جملة الشيفرة الوهمية، الاتساق عبر المنصات، معالجة الأخطاء |
+| تحليل المتطلبات | Product Manager | `@speccrew-product-manager لدي متطلب جديد: [وصف]` |
+| تصميم الوظائف | Feature Designer | `@speccrew-feature-designer ابدأ تصميم الوظائف` |
+| تصميم النظام | System Designer | `@speccrew-system-designer ابدأ تصميم النظام` |
+| التطوير | System Developer | `@speccrew-system-developer ابدأ التطوير` |
+| اختبار النظام | Test Manager | `@speccrew-test-manager ابدأ الاختبار` |
+
+### قائمة مراجعة Checkpoint
+
+| المرحلة | عدد Checkpoints | عناصر التحقق الرئيسية |
+|-------|----------------------|-----------------|
+| تحليل المتطلبات | 1 | دقة المتطلب، اكتمال قاعدة الأعمال، قابلية قياس معايير القبول |
+| تصميم الوظائف | 1 | تغطية السيناريو، وضوح التفاعل، اكتمال البيانات، معالجة الاستثناءات |
+| تصميم النظام | 2 | أ: تقييم الإطار؛ ب: بناء pseudocode، اتساق عبر المنصات، معالجة الأخطاء |
 | التطوير | 1 | أ: جاهزية البيئة، مشاكل التكامل، مواصفات الكود |
 | اختبار النظام | 2 | أ: تغطية الحالات؛ ب: قابلية تشغيل كود الاختبار |
 
 ### مرجع سريع لمسارات المخرجات
 
 | المرحلة | دليل الإخراج | تنسيق الملف |
-|---------|-------------|-------------|
-| تحليل المتطلبات | `iterations/{iter}/01.product-requirement/` | `[name]-prd.md`، `[name]-bizs-modeling.md` |
-| تصميم الميزات | `iterations/{iter}/02.feature-design/` | `[name]-feature-spec.md` |
-| تصميم النظام | `iterations/{iter}/03.system-design/` | `DESIGN-OVERVIEW.md`، `{platform}/INDEX.md`، `{platform}/{module}-design.md` |
+|-------|-----------------|-------------|
+| تحليل المتطلبات | `iterations/{iter}/01.product-requirement/` | `[name]-prd.md`, `[name]-bizs-modeling.md` |
+| تصميم الوظائف | `iterations/{iter}/02.feature-design/` | `[name]-feature-spec.md` |
+| تصميم النظام | `iterations/{iter}/03.system-design/` | `DESIGN-OVERVIEW.md`, `{platform}/INDEX.md`, `{platform}/{module}-design.md` |
 | التطوير | `iterations/{iter}/04.development/` | الكود المصدري + `delivery-report.md` |
-| اختبار النظام | `iterations/{iter}/05.system-test/` | `cases/`، `code/`، `reports/`، `bugs/` |
-| الأرشفة | `iteration-archives/{iter}-{تاريخ}/` | نسخة كاملة من التكرار |
+| اختبار النظام | `iterations/{iter}/05.system-test/` | `cases/`, `code/`, `reports/`, `bugs/` |
+| الأرشفة | `iteration-archives/{iter}-{date}/` | نسخة تكرار كاملة |
 
 ---
 
 ## الخطوات التالية
 
 1. قم بتشغيل `speccrew init --ide qoder` لتهيئة مشروعك
-2. نفذ تهيئة قاعدة المعرفة
-3. تقدم عبر كل مرحلة باتباع سير العمل، واستمتع بتجربة التطوير المستندة إلى المواصفات!
-
-</div>
+2. نفذ الخطوة صفر: تهيئة قاعدة المعرفة
+3. تقدم مرحلة بمرحلة وفقاً لسير العمل، استمتع بتجربة التطوير المدعومة بالمواصفات!