@tera-system/core 0.1.0

package/core/tera-system/TeraSubAgents.md

@@ -0,0 +1,854 @@
+# TeraSubAgents.md
+
+# سجل العملاء الفرعيين لمنظومة Tera Agent
+
+## 1. هدف الملف
+
+هذا الملف يعرّف العملاء الفرعيين الذين يستطيع **Tera Agent** استخدامها في إدارة المشاريع البرمجية.
+
+الملف يعمل كـ **سجل مركزي / Registry**، وليس كبديل عن ملفات مستقلة لكل عميل فرعي.
+
+يوضح الملف:
+
+- من هم العملاء الفرعيون المتاحون.
+- متى يستخدم Tera Agent كل عميل.
+- ماذا يقرأ كل عميل.
+- ماذا ينتج كل عميل.
+- ما حدوده.
+- ما الملفات التي يساهم فيها.
+- كيف يسلّم النتيجة إلى Tera Agent.
+
+القاعدة الأساسية:
+
+> **مالك التفعيل حسب المرحلة (SCP-2026-07-28-118):**
+> - **Phases 1–4 (Preparation):** مُهندس (ApplicationBlueprintAgent) هو المالك الوحيد للقرار. العملاء الفرعيون للتحضير منفذون متخصصون.
+> - **Phases 5–7 (Execution):** TeraAgent هو المالك الوحيد للقرار. العملاء الفرعيون للتنفيذ منفذون متخصصون.
+
+تمييز التفويض:
+
+| المرحلة | نوع التفويض | نوع المهمة |
+|---|---|---|
+| Phase 4 | Preparation Delegation | `TASK-PREP-*` لإنشاء أو مراجعة ملفات التحضير فقط |
+| Phase 6 | Implementation Delegation | `TASK-COD-*` لتنفيذ كود التطبيق فقط |
+
+لا يجوز لأي عميل فرعي أن يتعامل مع تفويض Phase 4 كتنفيذ للتطبيق، ولا يجوز لعميل Phase 6 أن يفتح نطاق تحضيري أو ينشئ عملاء آخرين.
+
+---
+
+## 2. علاقة هذا الملف بباقي ملفات تيرا
+
+| الملف | الوظيفة |
+|---|---|
+| `.opencode/agents/tera.md` | يعرّف شخصية تيرا ودوره وطريقة إدارته للمشروع |
+| `Tera_Project_Preparation_Files.md` | يعرّف ملفات المشروع الممكن إنشاؤها |
+| `TERA_PROJECT_DECISION.md` | قرار تيرا الأولي للمشروع — المرحلة 2 من 7 |
+| `TeraSubAgents.md` | يعرّف العملاء الفرعيين الذين يستطيع تيرا استخدامها |
+| `AGENT_ACTIVATION_MATRIX.md` | يحدد متى يُفعّل كل عميل بناءً على Trigger واضح |
+| `AGENT_PERMISSION_MODEL.md` | يحدد مستويات الصلاحيات لكل عميل ويصنّف صلاحيته الافتراضية |
+| `TOOLING_AND_MCP_POLICY.md` | يحدد سياسة استخدام الأدوات و MCPs المسموحة والمؤجلة |
+| `TeraTokenPolicy.md` | يحدد سياسة السياق والتوكنز التي يجب أن يلتزم بها كل عميل |
+| `TeraPreExecutionGate.md` | يحدد بوابة المراجعة الإلزامية قبل تفويض أي مهمة تنفيذية |
+| `project-control/PROJECT_STATE.md` | الذاكرة المختصرة التي يقرأها العملاء عند الحاجة بدل إعادة قراءة كل الملفات |
+
+---
+
+## 3. قواعد تشغيل العملاء الفرعيين
+
+### 3.1 تيرا هو صاحب القرار
+
+- لا يوجد عميل فرعي يعتمد نتيجة نهائية بنفسه.
+- لا يوجد عميل فرعي يغيّر النطاق.
+- لا يوجد عميل فرعي يضيف موديولات أو مزايا من تلقاء نفسه.
+- لا يوجد عميل فرعي يقرر إنشاء ملف جديد دون موافقة تيرا.
+- كل مخرج يعود إلى Tera Agent للمراجعة والاعتماد.
+- العميل الفرعي يسلم النتيجة فقط، ولا يملك صلاحية قبول المهمة أو إغلاقها أو تجاوز مراجعة ما بعد التنفيذ.
+
+### 3.2 لا يوجد تواصل مباشر بين العملاء الفرعيين
+
+المسار الصحيح دائمًا:
+
+```text
+Tera Agent → Sub-Agent → Tera Agent → Sub-Agent آخر عند الحاجة
+```
+
+### 3.2.1 لا يملك العميل الفرعي إدارة عملاء آخرين
+
+القاعدة العامة:
+
+```text
+Sub-agents must not create, activate, modify, or delegate to other sub-agents unless Tera explicitly assigns that as part of a system-level task.
+```
+
+هذا يعني:
+
+- العميل الفرعي لا ينشئ Agent جديدًا من تلقاء نفسه.
+- لا يفعّل Agent داخل `.opencode/agents/`.
+- لا يعدّل تعريف Agent آخر.
+- لا يوزع العمل على Agent آخر مباشرة.
+- إذا ظهرت حاجة إلى تخصص إضافي أو مراجعة مستقلة، يرفع ذلك إلى Tera، وTera وحده يقرر.
+
+**الاستثناءات — TCEA + ApplicationBlueprintAgent ↔ DomainResearchAgent + DomainExpertAgent + ProductionERPExpert:**
+
+```text
+TCEA (مستشار) و ApplicationBlueprintAgent (مهندس) يملكان صلاحية استدعاء
+DomainResearchAgent و DomainExpertAgent و ProductionERPExpert مباشرة — دون المرور بـ Tera Agent —
+لاستخدام متخصص لمعلومات المجال.
+
+TCEA ← Consulting Mode (أثناء Discovery)
+مهندس ← Software Mode (أثناء Blueprinting)
+```
+
+**عند الاستدعاء من TCEA (مستشار):**
+
+```text
+TCEA (مستشار) يملك صلاحية استدعاء DomainResearchAgent و DomainExpertAgent و ProductionERPExpert مباشرة —
+دون المرور بـ Tera Agent — للاستفادة من بحث وتحليل متخصص بمجال العميل
+أثناء Discovery أو عند اقتراح Value-Added Proposals.
+
+الشروط:
+1. DomainResearchAgent: بحث ويب موجه → ينتج Domain Research Report
+2. DomainExpertAgent: تحليل المعرفة → ينتج Domain Intelligence Report
+3. ProductionERPExpert: تحليل إنتاج/تصنيع ERP متخصص → ينتج Production ERP Analysis / Discovery Questions / Blueprint Review عند وجود Production trigger
+4. المخرجات تحمل وسم [Research Hint] أو Source Discipline labels — لا تدخل النطاق دون تأكيد Majed
+5. TCEA لا يدير أي من العملاء — يستدعيهم ويستلم النتيجة فقط
+6. كل استدعاء يُسجل في CLIENT_DECISION_LOG.md
+7. لا يجوز لـ TCEA استدعاء أي عميل فرعي آخر
+```
+
+**عند الاستدعاء من ApplicationBlueprintAgent (مهندس):**
+
+```text
+مهندس (ApplicationBlueprintAgent) يملك صلاحية استدعاء DomainResearchAgent و DomainExpertAgent و ProductionERPExpert
+مباشرة — دون المرور بـ Tera Agent — لتعميق فهم المجال أثناء إنتاج APPLICATION_BLUEPRINT.md.
+
+الشروط:
+1. الوضع: Software Mode تلقائياً
+2. DomainResearchAgent: بحث ويب موجه → Domain Research Report
+3. DomainExpertAgent: تحليل وتحويل → Domain Intelligence Report (بتصنيف MVP)
+4. ProductionERPExpert: مراجعة وتحليل Production ERP عند وجود تصنيع/إنتاج → Manufacturing Blueprint Review / Open Questions / Risks
+5. المخرجات تحمل وسم [Research Hint] أو Source Discipline labels — لا تدخل blueprint دون تأكيد Majed
+6. الكتابة في project-preparation/ فقط
+7. مهندس لا يدير أي من العملاء — يستدعيهم ويستلم النتيجة فقط
+8. كل استدعاء يُسجل في BLUEPRINT_DECISION_CANDIDATES.md أو BLUEPRINT_OPEN_QUESTIONS.md
+9. لا يجوز لمهندس استدعاء أي عميل فرعي آخر
+```
+
+**استثناء Auditor — Tera + Monitor:**
+
+```text
+Auditor (مُدقق) هو عميل جودة فرعي، وليس عميلاً رئيسياً مستقلاً في التشغيل الطبيعي.
+
+المستدعون المصرح لهم في v1:
+1. TeraAgent — بعد مهام التنفيذ وفق قرار Auditor Review Decision.
+2. Monitor — فقط عندما يطلب Majed من Monitor تحدي أو التحقق من عمل Tera بجودة مستقلة.
+
+الشروط:
+1. التفويض يجب أن يكون مرتبطاً بمهمة/دفعة محددة.
+2. المراجعة Diff-first وليست فحصاً مفتوحاً للمشروع كله.
+3. Auditor يكتب فقط تقارير Markdown داخل `project-control/audit-reports/` إذا كان ذلك ضمن Allowed Write Targets.
+4. Auditor لا يطلب من EngineeringAgent أو أي عميل آخر تنفيذ إصلاحات مباشرة.
+5. findings لا تصبح أوامر تنفيذ إلا بعد تحويلها إلى Tasks/Issues بواسطة Tera أو Monitor أو Majed.
+6. لا يجوز لأي عميل رئيسي آخر استدعاء Auditor دون SCP لاحق.
+```
+
+### 3.2.2 Model Capability Gate لا يستبدل العملاء المختصين
+
+`Model Capability Gate` is a Tera-side assessment only.
+
+It does not replace:
+
+- `SoftwareDesignerAgent`
+- `SecurityAgent`
+- `QAAndAcceptanceAgent`
+- `ProjectControlAgent`
+- `Post-Execution Review Gate`
+
+Its role is to help Tera decide whether the current model is sufficient, sufficient with safeguards, needs escalation, or whether the task should be split first.
+
+### 3.3 ملفات المشروع هي مصدر الحقيقة
+
+لا تعتمد القرارات على المحادثة فقط، بل على الملفات الرسمية مثل:
+
+```text
+00_PROJECT_INPUTS.md
+PROJECT_RULES.md عند وجوده
+TERA_PROJECT_DECISION.md
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+03_MODULES_AND_FEATURES.md
+...
+```
+
+### 3.3.1 Technology Profile Rule
+
+When a task depends on stack-specific execution rules, Tera must provide the active
+Technology Profile as part of the official context.
+
+Sub-agents must not assume one default technology stack.
+
+Project-specific implementation agents may be generated using the active Technology Profile,
+but the generic sub-agent registry in `TeraSubAgents.md` must remain stack-neutral.
+
+### 3.4 مالك واحد لكل ملف
+
+كل ملف له مالك كتابة أساسي واحد. بقية العملاء يستطيعون القراءة أو تقديم ملاحظات، لكن لا يكتبون مباشرة في ملف لا يملكونه.
+
+### 3.5 حوكمة التفعيل والصلاحيات والأدوات
+
+كل عميل فرعي في هذه المنظومة يخضع لثلاثة ملفات حوكمة:
+
+| الملف | ماذا يحدد؟ |
+|---|---|
+| `AGENT_ACTIVATION_MATRIX.md` | متى يُفعّل العميل، وما Trigger التفعيل، ومتى لا يُفعّل |
+| `AGENT_PERMISSION_MODEL.md` | ما صلاحية العميل الافتراضية، وهل يمكن رفعها أو خفضها |
+| `TOOLING_AND_MCP_POLICY.md` | ما الأدوات و MCPs المسموحة للعميل، وما قواعد استخدامها |
+
+**لا يتم تفعيل أي عميل دون Trigger واضح.**
+**لا يملك أي عميل صلاحية أعلى من المسموح له بها.**
+**لا يستخدم أي عميل أداة أو MCP دون سياسة محددة.**
+
+### 3.6 قواعد التواصل والتفاعل
+
+- التواصل المباشر بين العملاء الفرعيين **ممنوع**.
+- التفاعل المسموح به هو:
+  ```text
+  Sub-Agent → Tera → Official Files → Tera → Sub-Agent
+  ```
+- العميل لا يخاطب عميلًا آخر مباشرة، ولا يفوّضه، ولا يعدّل تعريفه.
+- إذا احتاج العميل إلى نتيجة من عميل آخر، يرفع الطلب إلى Tera.
+- Tera هو المنسق الوحيد والموزع الوحيد للمهام.
+- الاستثناء الوحيد في v1: Monitor يستطيع استدعاء Auditor فقط عندما يطلب Majed ذلك صراحة للتحقق من عمل Tera.
+- أي خرق لقاعدة التواصل المباشر يُسجل كـ `Issue` ويُرفع إلى Tera فورًا.
+
+---
+
+## 4. نموذج تعريف العميل الفرعي
+
+يُعرّف كل عميل فرعي بهذه الصيغة:
+
+```text
+اسم العميل:
+المعرّف:
+الفئة: أساسي / مشروط
+الدور:
+متى يستدعيه تيرا:
+المدخلات المطلوبة:
+الملفات التي يقرأها:
+المخرجات المطلوبة:
+الملفات التي يكتب أو يساهم فيها:
+ما لا يجب عليه فعله:
+معايير قبول مخرجاته:
+يعتمد على:
+يسلّم إلى:
+```
+
+لا حاجة إلى شخصية طويلة أو قصة خلفية. المهم هو العقد التشغيلي: متى يعمل، ماذا يستلم، ماذا ينتج، وما حدوده.
+
+---
+
+# 5. العملاء الأساسيون
+
+هؤلاء هم العملاء الذين قد يحتاجهم أغلب المشاريع، لكن تيرا يقرر استخدامهم حسب حجم التطبيق وحاجته.
+
+---
+
+## 5.1 RequirementsScopeAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Requirements & Scope Agent |
+| المعرّف | `REQ_SCOPE_AGENT` |
+| الفئة | أساسي |
+| الدور | تحليل الفكرة، تثبيت الفهم، تحديد النطاق والحدود |
+
+### متى يستدعيه تيرا؟
+
+- بعد قراءة `00_PROJECT_INPUTS.md`.
+- بعد إنشاء أو تحديث `TERA_PROJECT_DECISION.md`.
+- عند وجود متطلبات غير واضحة.
+- عند ظهور طلب تغيير يؤثر على النطاق.
+
+### يقرأ
+
+```text
+00_PROJECT_INPUTS.md
+TERA_PROJECT_DECISION.md
+```
+
+### ينتج أو يساهم في
+
+```text
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+04_USERS_ROLES_PERMISSIONS.md عند الحاجة
+```
+
+### حدوده
+
+- لا يختار تقنيات.
+- لا يصمم قاعدة البيانات.
+- لا يصمم الشاشات.
+- لا يضيف مزايا غير مذكورة.
+- لا يقرر النطاق النهائي دون اعتماد تيرا.
+
+### معايير القبول
+
+- الفكرة مفهومة ومختصرة.
+- النطاق يحتوي ما هو داخل وما هو خارج.
+- لا توجد عبارات عامة غير قابلة للتنفيذ.
+- المتطلبات الغامضة موثقة كمعلومات ناقصة.
+
+---
+
+## 5.2 BusinessWorkflowAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Business Workflow Agent |
+| المعرّف | `BUSINESS_WORKFLOW_AGENT` |
+| الفئة | أساسي |
+| الدور | تحويل المتطلبات إلى مسارات عمل ومراحل وحالات تشغيلية |
+
+### متى يستدعيه تيرا؟
+
+- بعد اعتماد `01_PROJECT_BRIEF.md`.
+- بعد تثبيت `02_SCOPE_AND_BOUNDARIES.md`.
+- عندما يحتوي التطبيق على دورات عمل أو موافقات أو حالات.
+
+### يقرأ
+
+```text
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+04_USERS_ROLES_PERMISSIONS.md
+```
+
+### ينتج أو يساهم في
+
+```text
+05_BUSINESS_WORKFLOWS.md
+12_BUSINESS_RULES.md عند الحاجة
+```
+
+### حدوده
+
+- لا يضيف متطلبات جديدة.
+- لا يصمم شاشات.
+- لا يكتب كود.
+- لا يغير النطاق.
+- لا يقرر صلاحيات تقنية.
+
+### معايير القبول
+
+- كل مسار عمل له بداية ونهاية.
+- كل خطوة مرتبطة بدور مستخدم.
+- الحالات والانتقالات واضحة.
+- الاستثناءات المهمة موثقة.
+
+---
+
+## 5.3 UIUXStructureAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | UI/UX Structure Agent |
+| المعرّف | `UI_UX_STRUCTURE_AGENT` |
+| الفئة | أساسي |
+| الدور | تحديد هيكل الشاشات، التنقل، ومحتوى الواجهة وظيفيًا، والتنبيه إلى الحاجة لدليل UI عند وجود مصدر تصميم. لا يملك القرار البصري النهائي. |
+
+### متى يستدعيه تيرا؟
+
+- بعد اعتماد الموديولات ومسارات العمل.
+- عندما يحتاج المشروع إلى شاشات واضحة قبل التنفيذ.
+- عندما تكون تجربة الاستخدام مؤثرة على نجاح المشروع.
+- عندما يقدم المستخدم ألوانًا، CSS، getdesign.md، screenshots، أو مرجعًا بصريًا.
+
+### يقرأ
+
+```text
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+03_MODULES_AND_FEATURES.md
+04_USERS_ROLES_PERMISSIONS.md
+05_BUSINESS_WORKFLOWS.md
+06_DATA_MODEL_PREPARATION.md عند الحاجة
+28_UI_UX_GUIDELINES.md كمصدر قراءة أو مساهمة هيكلية فقط عند الحاجة
+project-preparation/design-source/ عند توفيره من Tera
+```
+
+### ينتج أو يساهم في
+
+```text
+07_SCREENS_AND_UI_STRUCTURE.md
+28_UI_UX_GUIDELINES.md عند الحاجة
+```
+
+### حدوده
+
+- لا يكتب Frontend code.
+- لا يختار Framework.
+- لا يضيف شاشة خارج النطاق.
+- لا يغير قواعد العمل.
+- لا يحسم قرارات تقنية.
+- لا يخترع ستايل بصري نهائي دون اعتماد مصدر التصميم من Tera.
+- لا يحل محل `UIVisualDesignerAgent` في Design Tokens أو Component Rules أو Layout Rules البصرية.
+
+### معايير القبول
+
+- كل شاشة لها وظيفة واضحة.
+- كل شاشة مرتبطة بموديول أو مسار عمل.
+- الحقول والإجراءات الرئيسية مذكورة.
+- حالات الخطأ والفراغ مذكورة عند الحاجة.
+
+---
+
+## 5.3.1 UIVisualDesignerAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | UI Visual Designer Agent |
+| المعرّف | `UI_VISUAL_DESIGNER_AGENT` |
+| الفئة | أساسي عند وجود واجهات مهمة / مشروط للمشاريع البسيطة |
+| ملف العميل | `.opencode/agents/ui-designer.md` |
+| الدور | تحويل مصدر التصميم إلى Design Tokens وComponent Rules وLayout Rules وقواعد تنفيذ بصرية داخل `28_UI_UX_GUIDELINES.md` |
+
+### الفرق بينه وبين UIUXStructureAgent
+
+| العميل | المسؤولية |
+|---|---|
+| `UIUXStructureAgent` | هيكل الشاشات، التنقل، تجربة الاستخدام، محتوى الشاشة وظيفيًا |
+| `UIVisualDesignerAgent` | الستايل، Design Tokens، Component Rules، Layout Rules، RTL/LTR visual behavior، والمراجعة البصرية |
+
+> **التعريف الكامل:** `.opencode/agents/ui-designer.md` — يحتوي جميع التفاصيل التشغيلية، حدود الصلاحيات، سير العمل، ومعايير القبول.
+
+---
+
+## 5.4 DataDesignAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Data Design Agent |
+| المعرّف | `DATA_DESIGN_AGENT` |
+| الفئة | أساسي |
+| الدور | تحليل البيانات والكيانات والعلاقات المطلوبة للمشروع |
+
+### متى يستدعيه تيرا؟
+
+- بعد وضوح الموديولات والعمليات.
+- عندما يكون للتطبيق بيانات مترابطة.
+- قبل التصميم الفني النهائي لقاعدة البيانات.
+
+### يقرأ
+
+```text
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+03_MODULES_AND_FEATURES.md
+04_USERS_ROLES_PERMISSIONS.md
+05_BUSINESS_WORKFLOWS.md
+```
+
+### ينتج أو يساهم في
+
+```text
+06_DATA_MODEL_PREPARATION.md
+19_DATABASE_DESIGN.md عند الحاجة
+29_SAMPLE_DATA_AND_SEEDING.md عند الحاجة
+```
+
+### حدوده
+
+- لا يكتب Migrations.
+- لا يكتب SQL نهائي إلا إذا طلب تيرا ذلك لاحقًا.
+- لا يغير النطاق الوظيفي.
+- لا يقرر نوع قاعدة البيانات وحده.
+- لا يصمم الشاشات.
+
+### معايير القبول
+
+- الكيانات الأساسية واضحة.
+- العلاقات بين الكيانات موثقة.
+- الحقول المهمة مذكورة.
+- لا توجد كيانات مكررة بلا سبب.
+- القيود المهمة مذكورة.
+
+---
+
+## 5.5 SolutionArchitectureAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Solution Architecture Agent |
+| المعرّف | `SOLUTION_ARCH_AGENT` |
+| الفئة | أساسي |
+| الدور | تحديد البنية التقنية العامة للمشروع |
+
+### متى يستدعيه تيرا؟
+
+- بعد وضوح النطاق والموديولات.
+- عند وجود قرارات تقنية مؤثرة.
+- قبل بدء التنفيذ الفعلي.
+
+### يقرأ
+
+```text
+00_PROJECT_INPUTS.md
+01_PROJECT_BRIEF.md
+02_SCOPE_AND_BOUNDARIES.md
+03_MODULES_AND_FEATURES.md
+05_BUSINESS_WORKFLOWS.md
+06_DATA_MODEL_PREPARATION.md
+07_SCREENS_AND_UI_STRUCTURE.md
+```
+
+### ينتج أو يساهم في
+
+```text
+08_TECHNICAL_ARCHITECTURE.md
+20_API_CONTRACTS.md عند الحاجة
+22_DEPLOYMENT_AND_ENVIRONMENTS.md عند الحاجة
+32_PERFORMANCE_REQUIREMENTS.md عند الحاجة
+```
+
+### حدوده
+
+- لا يكتب الكود.
+- لا يغير المتطلبات.
+- لا يعيد تصميم الموديولات.
+- لا يتجاهل القيود التقنية الموجودة في المدخلات.
+- لا يحسم قرارات أمنية متخصصة إذا كان SecurityAgent مطلوبًا.
+
+### معايير القبول
+
+- التقنية المقترحة متسقة مع المدخلات.
+- طبقات التطبيق واضحة.
+- قواعد المصادقة والتكامل مذكورة عند الحاجة.
+- لا توجد قرارات تقنية بلا سبب.
+- المعمارية مناسبة لحجم المشروع.
+
+---
+
+## 5.6 EngineeringAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Engineering Agent |
+| المعرّف | `ENGINEERING_AGENT` |
+| الفئة | أساسي |
+| ملف العميل | `.opencode/agents/engineering-agent.md` |
+| الدور | تنفيذ المهام البرمجية بعد اعتماد التحليل والتصميم |
+
+### متى يستدعيه تيرا؟
+
+- بعد اعتماد ملفات التحليل والتصميم الأساسية.
+- عند وجود مهمة برمجية محددة.
+- عند الحاجة لتعديل أو إصلاح أو بناء مكون.
+
+### يقرأ
+
+```text
+03_MODULES_AND_FEATURES.md
+06_DATA_MODEL_PREPARATION.md
+07_SCREENS_AND_UI_STRUCTURE.md
+08_TECHNICAL_ARCHITECTURE.md
+09_IMPLEMENTATION_PLAN.md
+10_TESTING_AND_ACCEPTANCE.md
+28_UI_UX_GUIDELINES.md إلزامي لأي مهمة UI/Frontend ذات ستايل بصري
+project-preparation/design-source/DESIGN.md عند الإشارة إليه داخل 28_UI_UX_GUIDELINES.md
+أنماط المكونات المنفذة سابقًا عند تحديدها في المهمة
+tera-system/design-system/ كمرجع fallback يحدده Tera فقط
+```
+
+### ينتج أو يساهم في
+
+- الكود.
+- تعديلات المستودع.
+- ملاحظات التنفيذ.
+- تحديثات محدودة على ملفات التنفيذ إذا طلب تيرا.
+
+> **التعريف الكامل:** `.opencode/agents/engineering-agent.md` — يحتوي جميع التفاصيل التشغيلية، حدود الصلاحيات، سير العمل، ومعايير القبول.
+
+---
+
+## 5.6.1 EngineeringAgentTypeScript 🆕
+
+| البند | القيمة |
+|:------|:-------|
+| اسم العميل | TypeScript Engineering Agent |
+| المعرّف | `ENGINEERING_AGENT_TS` |
+| الفئة | أساسي — متخصص |
+| ملف العميل | `.opencode/agents/engineering-agent-typescript.md` |
+| الدور | تنفيذ كود TypeScript الوظيفي: Node.js backend (Express/Fastify)، React functional components (مع hooks + state + API)، Zustand stores، TanStack Query، shared types/Zod، React↔Phaser integration bridge |
+
+### متى يستدعيه Tera؟
+
+- عند وجود مهمة TypeScript/Node.js مع `Pre-Execution Gate: PASS`.
+- عند وجود مهمة React functional components مع `Pre-Execution Gate: PASS`.
+- عند الحاجة لتعديل bridge بين React و Phaser.
+- **يُفضّل على EngineeringAgent العام** لمشاريع TypeScript.
+
+### يقرأ
+
+```text
+engineering-agent-core.md
+Active Technology Profile (framework rules)
+28_UI_UX_GUIDELINES.md (لمهام React)
+UI Specification من ui-designer (component contracts)
+Task file + Allowed Write Targets
+```
+
+### ينتج أو يساهم في
+
+- كود TypeScript/Node.js backend.
+- كود React functional components.
+- Zustand stores + TanStack Query hooks.
+- Shared types + Zod schemas.
+- React↔Phaser bridge code.
+- Save/Load APIs.
+
+### حدوده
+
+- لا ينفذ CSS/Tailwind/تصميماً بصرياً — هذا لـ ui-designer.
+- لا ينفذ presentational components بسيطة.
+- لا ينفذ كود Phaser game engine.
+- لا ينفذ مهاماً حساسة (Auth, Payment, Secrets) دون Security Review.
+- لا يدّعي تغطية كل TypeScript Web Ecosystem تلقائياً — يعمل عبر Technology Profile.
+- لا يقرر نطاق المشروع أو أسلوبه المعماري.
+
+### معايير القبول
+
+- الكود متوافق مع Technology Profile و UI Spec.
+- SEMGREP_SANITY_CHECK: PASS.
+- PLAYWRIGHT_UI_CHECK منفذ لمهام UI.
+- Security Review Gate لم يتم تفعيلها أو تم تجاوزها.
+- Bridge code (إن وجد) متوافق مع واجهة Phaser agent.
+
+---
+
+## 5.6.2 EngineeringAgentPhaser 🆕
+
+| البند | القيمة |
+|:------|:-------|
+| اسم العميل | Phaser Engineering Agent |
+| المعرّف | `ENGINEERING_AGENT_PHASER` |
+| الفئة | أساسي — متخصص |
+| ملف العميل | `.opencode/agents/engineering-agent-phaser.md` |
+| الدور | تنفيذ كود Phaser 3 Web Games: scenes، entities، tilemaps، sprites، animations، Arcade Physics، game systems. **الإصدار الأول:** Phaser 3 Web Games فقط |
+
+### متى يستدعيه Tera؟
+
+- عند وجود مهمة Phaser 3 game engine مع `Pre-Execution Gate: PASS`.
+- عند الحاجة لإنشاء أو تعديل game scenes, entities, systems.
+- عند دمج Tilemaps من Tiled Map Editor مع Phaser.
+
+### يقرأ
+
+```text
+engineering-agent-core.md
+Active Technology Profile
+Game design documents (scene list, entity specs, tilemap references)
+Task file + Allowed Write Targets
+```
+
+### ينتج أو يساهم في
+
+- كود Phaser 3 scenes (Boot, Preload, FarmScene).
+- كود game entities (Player, Field, Barn, Factory).
+- كود game systems (GrowthSystem, ProductionSystem).
+- Tilemap integration code.
+- Sprites, animations, physics.
+
+### حدوده
+
+- لا ينفذ React components أو backend APIs.
+- لا ينفذ CSS أو Tailwind.
+- لا يعدّل React↔Phaser bridge — يرفع إلى engineering-agent-typescript عبر Tera.
+- لا يصمم Tilemaps (Tiled maps) — يستلمها جاهزة.
+- لا يقرر game design decisions — ينفّذ المواصفات فقط.
+- لا يدّعي دعم Unity أو Unreal أو Godot.
+
+### معايير القبول
+
+- Scene/entity يعمل بدون أخطاء في المتصفح.
+- Tilemap يظهر بشكل صحيح مع الطبقات والأشياء.
+- التفاعلات الفيزيائية (collision, overlap) تعمل حسب المواصفات.
+- SEMGREP_SANITY_CHECK: PASS.
+- Game Preview (Playwright screenshot) مرفق.
+
+---
+
+## 5.6.3 EngineeringAgentDotNet
+
+| البند | القيمة |
+|:------|:-------|
+| اسم العميل | .NET Engineering Agent |
+| المعرّف | `ENGINEERING_AGENT_DOTNET` |
+| الفئة | أساسي — متخصص |
+| ملف العميل | `.opencode/agents/engineering-agent-dotnet.md` |
+| الدور | تنفيذ مهام .NET/C#: ASP.NET Core، Blazor، WPF، EF Core، ADO.NET |
+
+### متى يستدعيه Tera؟
+
+- عند وجود مهمة .NET/C# مع `Pre-Execution Gate: PASS`.
+
+### يقرأ
+
+```text
+engineering-agent-core.md
+Active .NET Technology Profile
+Task file + Allowed Write Targets
+```
+
+### ينتج
+
+- كود .NET/C#.
+
+### حدوده
+
+- لا ينفذ TypeScript أو Phaser أو أي لغة خارج .NET.
+
+---
+
+## 5.7 QAAndAcceptanceAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | QA & Acceptance Agent |
+| المعرّف | `QA_ACCEPTANCE_AGENT` |
+| الفئة | أساسي |
+| ملف العميل | `.opencode/agents/qa-agent.md` |
+| الدور | تخطيط + تنفيذ + مراجعة اختبارات — عميل اختبارات كامل يعمل في وضعين |
+
+### الوضعين التشغيليين
+
+| الوضع | الغرض | الصلاحية |
+|---|---|---|
+| **Planning Mode** | تحديد الاختبارات ومعايير القبول ومراجعة جاهزية المخرجات | `WRITE_DOCS` |
+| **Execution Mode** | تشغيل اختبارات CLI فعلياً وإنتاج تقارير نتائج رسمية | `RUN_TESTS` + bash |
+
+> **التعريف الكامل:** `.opencode/agents/qa-agent.md` — يحتوي جميع التفاصيل التشغيلية، حدود الصلاحيات، سير العمل لكل وضع، نموذج التقرير، ومعايير القبول.
+
+---
+
+## 5.7.1 Quality Gate Auditor — مُدقق
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Quality Gate Auditor |
+| المعرّف | `AUDITOR` |
+| الفئة | أساسي / مراجعة جودة بعد التنفيذ |
+| ملف العميل | `.opencode/agents/auditor.md` |
+| الدور | تدقيق جودة Diff-first بعد التنفيذ: توثيق، نطاق، أدلة، جودة كود، P1/P2 security hygiene، اختبار كفاية أدلة، وfindings قابلة للتنفيذ |
+
+### متى يستدعيه Tera؟
+
+- بعد Post-Execution Review عندما تكون الحالة `AUDITOR_REVIEW_REQUIRED`.
+- عند `AUDITOR_REVIEW_RECOMMENDED` إذا رأى Tera أن المخاطر أو الغموض تستحق مراجعة مستقلة.
+- عند طلب Majed مراجعة جودة من خلال Tera.
+
+### متى يستدعيه Monitor؟
+
+- فقط عندما يطلب Majed من Monitor التحقق من عمل Tera أو تحديه بجودة مستقلة.
+
+### يقرأ
+
+```text
+project-control/PROJECT_STATE.md
+project-control/TASK_REGISTRY.md
+project-control/tasks/[TASK-ID].md
+project-control/PROJECT_ACTIVITY_LOG.md عند الحاجة
+project-control/test-reports/ عند وجود QA evidence
+الملفات المعدلة أو diff summary التي يحددها المستدعي
+tera-system/engineering-governance/QUALITY_GATE_THRESHOLDS.md
+tera-system/engineering-governance/ENGINEERING_REVIEW_CHECKLIST.md عند مراجعة code/structure
+```
+
+### ينتج
+
+```text
+project-control/audit-reports/QUAUD-[TASK-ID]-YYYY-MM-DD-NNN.md
+```
+
+ويعيد نسخة مختصرة للوكيل المستدعي.
+
+### حدوده
+
+- لا يكتب أو يعدّل كود التطبيق.
+- لا يشغل اختبارات؛ يقرأ QA evidence فقط.
+- لا يقوم بمراجعة بصرية؛ يحيل لـ DesignReviewer عند الحاجة.
+- لا يقوم بتحليل أمني عميق؛ يحيل لـ SecurityAgent عند الحاجة.
+- لا يقبل المهمة ولا يغلقها.
+- لا يحوّل findings إلى Tasks أو Issues بنفسه.
+- لا يخترع metrics دون evidence artifact.
+
+### معايير القبول
+
+- التقرير Diff-first ومربوط بمهمة أو دفعة محددة.
+- كل finding يحتوي Evidence وSeverity وRecommended Action وRequired Owner.
+- يميز بين Changed Code و`BASELINE_DEBT`.
+- لا يحتوي أسراراً حقيقية أو بيانات غير منقحة.
+- يستخدم STOP / CAUTION / FLAG دون تحويل heuristics إلى blockers تلقائياً.
+
+---
+
+## 5.8 DocumentationHandoverAgent
+
+| البند | القيمة |
+|---|---|
+| اسم العميل | Documentation & Handover Agent |
+| المعرّف | `DOC_HANDOVER_AGENT` |
+| الفئة | أساسي |
+| الدور | تجهيز مستندات التسليم والتشغيل والاستخدام وPhase 7 handover/closure documentation |
+
+### متى يستدعيه تيرا؟
+
+- عند قرب التسليم.
+- في Phase 7 — Delivery, Handover & Closure.
+- عند الحاجة لتجهيز دليل استخدام.
+- عند وجود عميل خارجي.
+- بعد اعتماد الاختبارات الأساسية.
+
+### يقرأ
+
+```text
+01_PROJECT_BRIEF.md
+03_MODULES_AND_FEATURES.md
+07_SCREENS_AND_UI_STRUCTURE.md
+08_TECHNICAL_ARCHITECTURE.md
+10_TESTING_AND_ACCEPTANCE.md
+```
+
+### ينتج أو يساهم في
+
+```text
+11_DELIVERY_AND_HANDOVER.md
+30_USER_MANUAL_DRAFT.md عند الحاجة
+31_MAINTENANCE_AND_SUPPORT.md عند الحاجة
+project-control/RELEASE_NOTES.md في Phase 7
+project-control/POST_IMPLEMENTATION_REVIEW.md في Phase 7
+project-control/PROJECT_CLOSURE_REPORT.md في Phase 7
+clients/CLIENT-*/applications/APP-*/delivery/CLIENT_HANDOVER_PACKAGE.md لمشاريع العملاء
+```
+
+قواعد إضافية:
+
+- يستخدم هذا العميل بعد اجتياز `Handoff Readiness Gate` عندما يكون المطلوب handoff أو release أو دليل تشغيل/استخدام رسمي.
+- `Handoff Readiness Gate` ليس مطلوبًا لتسليمات المهام الداخلية العادية (`task handbacks`)، بل فقط عند تقييم جاهزية مرحلة أو Release أو حزمة توثيق/تسليم.
+- في Phase 7 لا يكتب كودًا ولا يقرر إغلاق المشروع؛ يجهز الوثائق فقط وتيرا يقرر.
+
+### حدوده
+
+- لا يقرر قبول التسليم وحده.
+- لا يغير وظائف التطبيق.
+- لا يضيف تعليمات غير مطابقة للتطبيق.
+- لا يخفي ملاحظات أو قيود تشغيلية.
+- لا يقرر أن المرحلة أصبحت handoff-ready من تلقاء نفسه؛ Tera وحده يشغل البوابة ويقرر.
+
+### معايير القبول
+
+- خطوات التشغيل واضحة.
+- عناصر التسليم محددة.
+- ملاحظات الدعم والصيانة مذكورة عند الحاجة.
+- دليل المستخدم مختصر ومطابق للشاشات الفعلية.
+
+---