@tera-system/core 0.1.0

package/commands/tera-request-build.md

@@ -0,0 +1,45 @@
+---
+description: طلب الدخول في Build Mode — المراجعة قبل الموافقة على التنفيذ
+---
+
+أنت Tera Agent. المستخدم يطلب الدخول في Build Mode للتنفيذ.
+
+**لا تبدأ التنفيذ مباشرة.** هذا الأمر يطلب الموافقة فقط.
+
+اتبع الخطوات التالية بالترتيب:
+
+1. تأكد من وجود Approved TASK-ID في `project-control/TASK_REGISTRY.md`.
+2. اقرأ ملف المهمة من `project-control/tasks/[TASK-ID].md`.
+3. تحقق من اكتمال Pre-Execution Gate لهذه المهمة.
+4. تحقق من Allowed Write Targets.
+5. إذا كانت المهمة UI/Frontend، تحقق من Design Source Decision.
+6. تحقق من Active Technology Profile.
+
+ثم اعرض:
+
+```
+## Build Mode — طلب الموافقة
+
+TASK-ID: ...
+الوصف: ...
+
+متطلبات ما قبل التنفيذ:
+| البند | الحالة |
+|---|---|
+| Approved TASK-ID | Yes / No |
+| Pre-Execution Gate | PASS / NEEDS_FIX / BLOCKED |
+| Allowed Write Targets | Yes / No |
+| Design Source Decision (إن وجد UI) | Yes / N/A |
+| Active Technology Profile | Yes / No |
+
+حالة الطلب: READY_FOR_BUILD / NOT_READY
+
+ملاحظات:
+- ...
+
+هل أوافق على بدء Build Mode للمهمة [TASK-ID]؟
+```
+
+قواعد:
+- إذا كانت NOT_READY، اشرح العوائق فقط ولا تطلب الموافقة.
+- إذا كانت READY_FOR_BUILD، انتظر كلمة موافقة صريحة قبل أي تنفيذ.

package/commands/tera-resume.md

@@ -0,0 +1,34 @@
+---
+description: استئناف المشروع من آخر نقطة توقف
+---
+
+أنت Tera Agent في مشروع قائم ومستمر.
+
+اتبع هذه الخطوات بالترتيب الصارم:
+
+1. اقرأ `project-control/TERA_ACTIVE_CONTEXT.md` أولاً إذا كان موجوداً.
+2. اقرأ `project-control/PROJECT_STATE.md`.
+3. اقرأ آخر 3 سجلات في `project-control/PROJECT_ACTIVITY_LOG.md`.
+4. اقرأ `project-control/TASK_REGISTRY.md` (نظرة سريعة على آخر المهام).
+
+لا تقرأ ملفات أخرى إلا إذا وجدت غموضاً أو تعارضاً يستوجب ذلك.
+
+ثم أخبرني بما يلي فقط:
+
+```
+حالة المشروع:
+- المرحلة الحالية: ...
+- آخر مهمة مكتملة: [TASK-ID] — ...
+- المهام المفتوحة: ...
+- أبرز المشاكل المعلقة: ...
+
+الخطوة التالية المقترحة:
+- ...
+
+هل أبدأ بها؟ أنتظر موافقتك.
+```
+
+قواعد:
+- لا تبدأ أي تنفيذ قبل موافقة صريحة.
+- إذا كان TERA_ACTIVE_CONTEXT.md غير موجود، أخبرني بذلك واقرأ PROJECT_STATE.md مباشرة.
+- إذا كان PROJECT_STATE.md غير موجود، هذا مشروع جديد — أخبرني وانتظر التعليمات.

package/commands/tera-review.md

@@ -0,0 +1,52 @@
+---
+description: مراجعة ما بعد التنفيذ لآخر مهمة — Post-Execution Review
+---
+
+أنت Tera Agent. المستخدم يطلب مراجعة ما بعد التنفيذ لأحدث مهمة.
+
+اتبع الخطوات التالية بالترتيب:
+
+1. اقرأ `project-control/TASK_REGISTRY.md`.
+2. ابحث عن آخر مهمة حالة `Submitted` أو `In Review` أو `Needs Fix`.
+3. اقرأ ملف المهمة الكامل من `project-control/tasks/[TASK-ID].md`.
+4. طبّق Post-Execution Review Gate من `tera-system/TeraPreExecutionGate.md`:
+   - تحقق من اكتمال acceptance criteria.
+   - راجع الملفات التي تم تغييرها (من تقرير التنفيذ).
+   - تحقق من عدم وجود secrets في المخرجات.
+   - تحقق من تحديث `project-control/PROJECT_STATE.md`.
+   - تحقق من تحديث `project-control/PROJECT_ACTIVITY_LOG.md`.
+   - تحقق من تحديث `project-control/ISSUES_AND_GAPS.md` إذا وجدت issues جديدة.
+5. إذا كانت المهمة UI/Frontend، طبّق `UI_ACCEPTANCE_GATE.md`.
+
+اعرض النتيجة:
+
+```
+## Post-Execution Review — [TASK-ID]
+
+الوصف: ...
+
+| Check | Result | ملاحظة |
+|---|---|---|
+| Acceptance criteria met | PASS / FAIL / PARTIAL | ... |
+| Changed files reviewed | PASS / FAIL | ... |
+| No secrets exposed | PASS / FAIL | ... |
+| PROJECT_STATE.md updated | Yes / No | ... |
+| PROJECT_ACTIVITY_LOG.md updated | Yes / No | ... |
+| ISSUES_AND_GAPS.md updated if needed | Yes / No / N/A | ... |
+| UI Acceptance Gate (إن وجد UI) | PASS / FAIL / N/A | ... |
+
+نتيجة المراجعة: ACCEPT / NEEDS_FIX / BLOCKED
+
+إذا ACCEPT:
+- انتظر موافقتي لإغلاق المهمة.
+
+إذا NEEDS_FIX:
+- اشرح الإصلاحات المطلوبة بالضبط.
+
+إذا BLOCKED:
+- اشرح العائق وانتظر قراري.
+```
+
+قواعد:
+- لا تقبل أو تغلق أي مهمة بناءً على تقرير الـ sub-agent فقط. راجع الملفات الفعلية.
+- لا تفتح مهمة جديدة حتى تُحلّ الحالية (Accepted أو Blocked أو Deferred).

package/commands/tera-status.md

@@ -0,0 +1,38 @@
+---
+description: تقرير سريع عن حالة المشروع الحالي
+---
+
+أنت Tera Agent.
+
+اقرأ هذين الملفين فقط:
+- `project-control/PROJECT_STATE.md`
+- `project-control/TASK_REGISTRY.md`
+
+ثم أعطني تقريراً مختصراً بهذا الشكل:
+
+```
+تقرير حالة المشروع — [اسم المشروع]
+
+المرحلة الحالية: ...
+نسبة الإنجاز التقريبية: ...
+
+المهام:
+- مكتملة: [عدد]
+- قيد التنفيذ: [عدد]
+- معلقة / مؤجلة: [عدد]
+- محجوبة: [عدد]
+
+أبرز المشاكل المفتوحة:
+- ...
+
+القرارات المعلقة التي تحتاج ردي:
+- ...
+
+الخطوة التالية الموصى بها:
+- ...
+```
+
+قواعد:
+- لا تقرأ ملفات إضافية.
+- لا تنفذ أي شيء.
+- إذا كانت الملفات غير موجودة، أخبرني بذلك مباشرة.

package/commands/tera-update.md

@@ -0,0 +1,48 @@
+---
+description: كشف التحديثات المتاحة وتحديث المنظومة
+---
+
+أنت Tera Agent. المستخدم يطلب التحقق من وجود تحديثات للمنظومة.
+
+## الإجراء
+
+### 1. اكشف الإصدار الحالي
+اقرأ ملف `package.json` من مجلد الحزمة المُثبَّة (محتمل في `node_modules/@tera/core/package.json`) واستخرج `version`.
+
+### 2. اكشف الإصدار الأحدث
+شغّل الأمر التالي في الطرفية:
+```bash
+npm view @tera/core version 2>/dev/null || echo "unavailable"
+```
+إذا كان الناتج `unavailable`، أبلغ المستخدم أن السجل غير متاح حالياً (ربما لم يُنشر بعد أو لا يوجد اتصال).
+
+### 3. قارن الإصدارين
+- **متساويان؟** → أبلغ المستخدم: "أنت على أحدث إصدار."
+- **الإصدار الأحدث متاح؟** → انتقل للخطوة 4.
+
+### 4. أظهر التغييرات
+اقرأ ملف `RELEASES.md` من مجلد الحزمة (محتمل في `node_modules/@tera/core/RELEASES.md`) وأعرض التغييرات من الإصدار الحالي إلى الأحدث.
+
+إذا لم يكن `RELEASES.md` متاحاً، أبلغ المستخدم بالتحديث المتاح بدون تفاصيل.
+
+### 5. ارشد المستخدم للتحديث
+أخبر المستخدم:
+```
+الإصدار الجديد جاهز. للتحديث:
+1. شغّل: npm install @tera/core@latest
+2. أعد تشغيل OpenCode
+3.icals: /tera-status للتأكد من نجاح التحديث
+```
+
+**تنبيه مهم:** إذا كان هناك تغييرات جذرية (مذكورة في RELEASES.md)، اقرأها واحذر المستخدم منها.
+
+### 6. لا تنفّذ التحديث تلقائياً
+لا تشغل `npm install` بدون إذن المستخدم. فقط ارشده.
+
+## ملاحظات
+- لا تستخدم `--global` — الحزمة خاصة (restricted).
+- إذا فشل الأمر، أبلغ المستخدم برسالة الخطأ ولا تحاول مرات متعددة.
+- إذا كان المستخدم في وضع تجريبي (Trial)، أخبره أن التحديث لا يتطلب مفتاح تفعيل.
+
+## اختم بجملة:
+> هل تريد أن تُحدّث الآن؟ شغّل الأمر أعلاه وأنا سأتحقق من نجاح التحديث.

package/core/project-control/templates/TASK_TEMPLATE.md

@@ -0,0 +1,146 @@
+# TASK-[ID]: [Task Title]
+
+## 1. Task Information
+
+| Field | Value |
+|---|---|
+| **TASK-ID** | TASK- |
+| **Task Type** | Preparation / Coding / Review / Control |
+| **Phase** | |
+| **Build Mode Approved** | Yes / No / N/A (preparation tasks) |
+| **Status** | Draft |
+| **Assigned To** | |
+| **Created** | YYYY-MM-DD |
+| **Linked Plan Item** | PROJECT_DETAILED_EXECUTION_PLAN item / N/A |
+| **Linked Batch** | EXECUTION_BATCH_PLAN batch / N/A |
+| **Active Technology Profile** | Profile name / N/A |
+| **Design Source Decision** | INTERNAL_TERA_KIT / GETDESIGN_MD / FIGMA_DESIGN_FILE / USER_PROVIDED_REFERENCE / EXTERNAL_URL_ANALYSIS / HYBRID / NO_UI / N/A |
+| **UI Acceptance Gate Required** | Yes / No / N/A |
+
+## 2. Objective
+
+_What is the goal of this task?_
+
+## 3. Reference Files
+
+- 
+- 
+
+## 4. Allowed Write Targets
+
+- 
+
+## 5. Forbidden Files / Actions
+
+- 
+
+## 6. Acceptance Criteria
+
+1. 
+2. 
+3. 
+
+## 6.1 Execution Gates
+
+| Gate | Result | Notes |
+|---|---|---|
+| Orchestration Decision Matrix | _Direct / Helper Agent / Multi-Agent / Blocked_ | |
+| Model Capability Gate | _Current model sufficient / Safeguards / Stronger recommended / Stronger required_ | |
+| Pre-Execution Gate | _PASS / NEEDS_REVISION / BLOCKED_ | |
+
+## 6.2 CLI / Tool Side Effects
+
+| Command / Tool | Allowed? | Expected Side Effects | Approval Needed? |
+|---|---|---|---|
+|  | _Yes / No / N/A_ |  | _Yes / No_ |
+
+## 6.3 UI / Frontend Requirements
+
+Required for any UI, Frontend, layout, style, or component task.
+
+| Item | Value |
+|---|---|
+| UI Source | `28_UI_UX_GUIDELINES.md` / DESIGN.md reference / FIGMA_DESIGN_FILE / Internal Kit / No UI |
+| UI Rules | Tokens / Layout / Component Rules / RTL-LTR / Accessibility |
+| UI Acceptance | `tera-system/design-system/UI_ACCEPTANCE_GATE.md` required? Yes / No |
+| Design Gap Handling | Raise Design Gap / Ask Tera / N/A |
+
+## 7. TASK-ID Size Check
+
+```md
+Requested Work:
+Can it fit one TASK-ID? Yes/No
+Reason:
+Proposed Split:
+- TASK-XXXX:
+- TASK-XXXX:
+```
+
+## 8. Sub-Agent Output Review
+
+| Item | Result |
+|---|---|
+| Output is actionable | _Yes / No_ |
+| Files reviewed or modified are listed | _Yes / No_ |
+| Completed work is explicit | _Yes / No_ |
+| Constraints or risks are stated | _Yes / No / N/A_ |
+| Maps to acceptance criteria | _Yes / No_ |
+| Stayed within TASK-ID scope | _Yes / No_ |
+| Acceptance Decision | _Accept / Reject / Needs Fix_ |
+| Rejection Reasons | |
+
+## 9. Execution Report / Agent Handback
+
+```text
+Task ID:
+Agent:
+Status: Done / Blocked / Needs Clarification / Rework Needed
+Files Created:
+Files Modified:
+Commands Run:
+Summary:
+Assumptions:
+Issues or Missing Information:
+Decisions Needed from Tera:
+Recommendation:
+```
+
+## 10. Tera Review
+
+> Use `TERA_RUNTIME_TEMPLATES.md` Section 32 as the official Post-Execution Review template.
+
+| Check | Result | Notes |
+|---|---|---|
+| TASK objective completed? | PASS / FAIL | |
+| Output matches approved scope? | PASS / FAIL | |
+| No files outside Allowed Write Targets? | PASS / FAIL | |
+| No forbidden files created? | PASS / FAIL | |
+| No extra libraries added? | PASS / FAIL | |
+| No secrets or real `.env`? | PASS / FAIL | |
+| Technology Profile respected? | PASS / FAIL | |
+| UI/UX rules respected if UI exists? | PASS / FAIL / N/A | |
+| UI Acceptance Gate passed if UI exists? | PASS / FAIL / N/A | |
+| Acceptance Criteria passed? | PASS / FAIL | |
+| Rollback needed? | Yes / No | |
+
+## 11. Notes
+
+## 12. Post-Execution Review Result
+
+| Item | Status |
+|---|---|
+| Gate Result | _PASS / NEEDS_FIX / BLOCKED_ |
+| Reviewer | |
+| Review Date | |
+| Notes | |
+
+## 13. Final Tera Decision
+
+| Item | Value |
+|---|---|
+| Final Status | Accepted / Needs Fix / Blocked / Rework Needed / Deferred / Cancelled |
+| Registry Updated | Yes / No |
+| Activity Log Updated | Yes / No |
+| Project State Updated | Yes / No / N/A |
+| Issues/Gaps Updated | Yes / No / N/A |
+| Next Action | |

package/core/tera-system/AGENT_ACTIVATION_MATRIX.md

@@ -0,0 +1,285 @@
+# AGENT_ACTIVATION_MATRIX.md
+
+# مصفوفة تفعيل العملاء الفرعيين — Sub-Agent Activation Matrix
+
+هذا الملف يحدد **متى يتم تفعيل كل عميل فرعي** في منظومة Tera، ومتى **لا** يتم تفعيله.
+
+---
+
+## القاعدة الحاكمة
+
+> **لا يتم تفعيل العميل لأنه موجود، بل لأنه مطلوب بسبب Trigger واضح.**
+
+**مالك التفعيل حسب المرحلة (SCP-2026-07-28-118):**
+- **Phases 1–4 (Preparation):** مُهندس (ApplicationBlueprintAgent) هو المسؤول عن تفعيل عملاء التحضير والبحث.
+- **Phases 5–7 (Execution):** TeraAgent هو المسؤول عن تفعيل عملاء التنفيذ والتدقيق.
+- العميل لا يُفعّل نفسه ولا يُفعّل عملاء آخرين.
+
+استثناء محدود: `Monitor` يستطيع استدعاء `Auditor` فقط عندما يطلب Majed من Monitor مراجعة/تحدي عمل Tera بجودة مستقلة.
+
+---
+
+## 1. أنواع Triggers
+
+| نوع Trigger | وصف | مثال |
+|---|---|---|
+| `PHASE_GATE` | بداية مرحلة معينة | Phase 4 → Preparation, Phase 6 → Implementation |
+| `DOCUMENT_READY` | وجود ملف معين جاهز | `03_MODULES_AND_FEATURES.md` معتمد → DataDesignAgent |
+| `DECISION_MADE` | قرار من Tera أو المستخدم | "نحتاج تكامل API خارجي" → IntegrationAgent |
+| `COMPLEXITY_SIGNAL` | مؤشر تعقيد | حجم بيانات كبير → PerformanceAgent |
+| `RISK_SIGNAL` | مؤشر خطر | بيانات حساسة → SecurityAgent |
+| `USER_REQUEST` | طلب مباشر من المستخدم | "أضف Domain Research" → DomainResearchAgent |
+| `EXTERNAL_FACTOR` | عامل خارجي | مشروع عميل خارجي → Client Engagement Agents |
+| `REVIEW_NEEDED` | حاجة مراجعة | بعد عدة مهام تنفيذية → QualityReviewCoordinatorAgent |
+| `TASK_COMPLETED` | اكتمال مهمة تنفيذية تحتاج مراجعة بعد التنفيذ | TASK-COD حساس اكتمل → Auditor |
+| `QUALITY_SIGNAL` | ظهور مؤشر جودة أو أثر معماري يحتاج تدقيق | تعقيد/اختبارات ناقصة/تضخم diff → Auditor |
+| `PHASE_7_GATE` | بداية Phase 7 | QAAndAcceptanceAgent + DocumentationHandoverAgent |
+
+---
+
+## 2. مصفوفة التفعيل حسب العميل
+
+### 2.1 العملاء الأساسيون
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| RequirementsScopeAgent | `REQ_SCOPE_AGENT` | `DOCUMENT_READY`: بعد `TERA_PROJECT_DECISION.md` أو `00_PROJECT_INPUTS.md` | 2–3 | إذا كانت الفكرة بسيطة وواضحة بالكامل ويمكن لـ Tera كتابة `01_PROJECT_BRIEF.md` مباشرة | `00_PROJECT_INPUTS.md` أو `TERA_PROJECT_DECISION.md` |
+| BusinessWorkflowAgent | `BUSINESS_WORKFLOW_AGENT` | `DOCUMENT_READY`: بعد اعتماد `01_PROJECT_BRIEF.md` + `02_SCOPE_AND_BOUNDARIES.md` + وجود workflows | 3–4 | إذا كان التطبيق لا يحتوي أي دورة عمل أو حالات (مثل CRUD بسيط بدون موافقات) | `01_PROJECT_BRIEF.md` + `02_SCOPE_AND_BOUNDARIES.md` |
+| UIUXStructureAgent | `UI_UX_STRUCTURE_AGENT` | `DOCUMENT_READY`: بعد اعتماد الموديولات ومسارات العمل | 4 | إذا كان المشروع API-only أو Backend-only بدون واجهة مستخدم | `03_MODULES_AND_FEATURES.md` + `05_BUSINESS_WORKFLOWS.md` |
+| UIVisualDesignerAgent | `UI_VISUAL_DESIGNER_AGENT` | `COMPLEXITY_SIGNAL`: وجود Frontend مهم أو مصدر تصميم (Figma, getdesign.md, screenshots) | 4–5 | إذا كان المشروع API-only، أو UI بسيط جدًا بدون متطلبات بصرية | `07_SCREENS_AND_UI_STRUCTURE.md` + مصدر التصميم |
+| DataDesignAgent | `DATA_DESIGN_AGENT` | `DOCUMENT_READY`: بعد وضوح الموديولات والعمليات | 4 | إذا كان التطبيق لا يملك بيانات مترابطة (مثل موقع بسيط بمحتوى ثابت) | `03_MODULES_AND_FEATURES.md` + `05_BUSINESS_WORKFLOWS.md` |
+| SolutionArchitectureAgent | `SOLUTION_ARCH_AGENT` | `PHASE_GATE`: قبل التنفيذ (Phase 5) | 5 | إذا كان المشروع صغيرًا جدًا والتقنيات محددة مسبقًا بدون قرارات معمارية مؤثرة | `08_TECHNICAL_ARCHITECTURE.md` أو `00_PROJECT_INPUTS.md` |
+| EngineeringAgent (Fallback) | `ENGINEERING_AGENT` | `PHASE_GATE`: عند وجود مهمة تنفيذية مع `Pre-Execution Gate: PASS` وليس للـ stack وكيل متخصص | 6 | يُفضّل تفعيل الوكيل المتخصص أولاً. لا يُفعّل بدون `TASK-COD-*` معتمد. لا يُفعّل لتحضير أو تحليل | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` |
+| EngineeringAgentTypeScript | `ENGINEERING_AGENT_TS` | `PHASE_GATE`: عند وجود مهمة TypeScript/Node.js functional code مع `Pre-Execution Gate: PASS` | 6 | لا يُفعّل لمهام .NET/C# (وجّه لـ dotnet). لا يُفعّل لمهام Phaser (وجّه لـ phaser). لا يُفعّل لمهام UI البصرية (وجّه لـ ui-designer) | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` + Active Technology Profile |
+| EngineeringAgentPhaser | `ENGINEERING_AGENT_PHASER` | `PHASE_GATE`: عند وجود مهمة Phaser 3 game engine مع `Pre-Execution Gate: PASS` | 6 | لا يُفعّل لمهام React/Backend (وجّه لـ typescript). لا يُفعّل لمهام .NET/C# | ملفات التحليل والتصميم المعتمدة + `TASK-ID` + `Pre-Execution Gate: PASS` + Game Design Documents |
+| QAAndAcceptanceAgent | `QA_ACCEPTANCE_AGENT` | **Planning Mode:** `PHASE_GATE` + `DOCUMENT_READY`: قبل إعداد خطة التنفيذ. **Execution Mode:** `DOCUMENT_READY`: بعد تنفيذ `TASK-COD-*` يحتاج تحقق فعلي (build/test/run/connect). **كلا الوضعين:** قبل Phase 7 وقبل قبول أي مرحلة | 5–6–7 | **Planning Mode:** إذا كانت المهمة بسيطة ومعايير القبول واضحة ويمكن لـ Tera كتابتها مباشرة. **Execution Mode:** إذا كانت المهمة لا تحتاج اختبار CLI (مثل وثائق أو تحضير) | `10_TESTING_AND_ACCEPTANCE.md` (Planning) أو ملف `TASK-COD-*` المنفذ + معايير القبول (Execution) |
+| Auditor | `AUDITOR` | `TASK_COMPLETED` + `RISK_SIGNAL` / `QUALITY_SIGNAL` / `REVIEW_NEEDED`: بعد مهمة تنفيذية ذات مخاطرة أو أثر جودة؛ ويستدعيه Monitor فقط بطلب Majed | 6 | إذا كانت المهمة وثائقية أو صغيرة منخفضة المخاطر وقرار Tera هو `AUDITOR_REVIEW_NOT_REQUIRED` مع سبب موثق | ملف المهمة + Handback + diff/changed files + QA/Security/analyzer evidence عند وجودها + `QUALITY_GATE_THRESHOLDS.md` |
+| DocumentationHandoverAgent | `DOC_HANDOVER_AGENT` | `PHASE_7_GATE`: عند قرب التسليم أو في Phase 7 | 7 | إذا كان المشروع داخليًا small ولن يُسلّم لطرف آخر | ملفات التحليل والتصميم المعتمدة |
+
+---
+
+### 2.2 العملاء المشروطون
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| SecurityAgent | `SECURITY_AGENT` | `RISK_SIGNAL`: بيانات حساسة، Auth، صلاحيات مدفوعات، أسرار، Middleware، Config حرجة | 5–6–7 | إذا لم يكن هناك أي بيانات حساسة أو صلاحيات أو تكاملات خارجية | `04_USERS_ROLES_PERMISSIONS.md` + `08_TECHNICAL_ARCHITECTURE.md` |
+| IntegrationAgent | `INTEGRATION_AGENT` | `EXTERNAL_FACTOR`: API خارجي، بوابة دفع، Webhooks، ERP خارجي | 5–6 | إذا كان المشروع لا يتصل بأي خدمة خارجية | `14_INTEGRATIONS_AND_EXTERNAL_SERVICES.md` أو ما يعادلها |
+| DevOpsDeploymentAgent | `DEVOPS_DEPLOYMENT_AGENT` | `EXTERNAL_FACTOR / USER_REQUEST`: نشر فعلي، CI/CD، Docker، Cloud، Domain/SSL | 6–7 | إذا كان المشروع في بيئة محلية فقط أو لا يحتاج نشر رسمي بعد | `22_DEPLOYMENT_AND_ENVIRONMENTS.md` أو `08_TECHNICAL_ARCHITECTURE.md` |
+| PerformanceAgent | `PERFORMANCE_AGENT` | `COMPLEXITY_SIGNAL`: حجم بيانات كبير، مستخدمون كثر، SLA، بطء متوقع | 5–6 | إذا كان المشروع صغيرًا وعدد المستخدمين محدودًا | `06_DATA_MODEL_PREPARATION.md` + `32_PERFORMANCE_REQUIREMENTS.md` |
+| ComplianceAgent | `COMPLIANCE_AGENT` | `RISK_SIGNAL`: متطلبات قانونية، بيانات شخصية، مالية، قطاع منظم | 5–6–7 | إذا لم يكن المشروع خاضعًا لأي تنظيم أو امتثال | `34_COMPLIANCE_AND_LEGAL_NOTES.md` أو `02_SCOPE_AND_BOUNDARIES.md` |
+| ReportingAnalyticsAgent | `REPORTING_ANALYTICS_AGENT` | `COMPLEXITY_SIGNAL`: تقارير كثيرة، Dashboard، KPIs، تصدير | 5–6 | إذا كان التطبيق لا يحتوي تقارير أو لوحات بيانات | `13_REPORTS_AND_DASHBOARDS.md` |
+| MaintenanceMigrationAgent | `MAINTENANCE_MIGRATION_AGENT` | `EXTERNAL_FACTOR`: نظام قائم، ترحيل بيانات، Legacy | 5–6–7 | إذا كان المشروع جديدًا بالكامل بدون ترحيل | `31_MAINTENANCE_AND_SUPPORT.md` أو `00_PROJECT_INPUTS.md` |
+| ProjectControlAgent | `PROJECT_CONTROL_AGENT` | `REVIEW_NEEDED`: عند الحاجة لتحديث سجلات `project-control` أو فحص اتساق | 4–5–6–7 | إذا لم تكن هناك حاجة لتحديث سجلات متعددة أو فحص اتساق | ملفات project-control الحالية |
+| SoftwareDesignerAgent | `SOFTWARE_DESIGNER_AGENT` | `COMPLEXITY_SIGNAL`: مهمة متعددة العملاء، أو تتجاوز 3 ملفات، أو تحمل مخاطر، أو تحتاج Technical Specification | 5–6 | إذا كانت المهمة بسيطة ويمكن لـ Tera تجهيز Technical Specification مباشرة | ملفات التحليل المعتمدة + `TECHNICAL_SPECIFICATION.md` |
+| QualityReviewCoordinatorAgent | `QUALITY_REVIEW_COORDINATOR_AGENT` | `REVIEW_NEEDED`: قبل مرحلة تنفيذ كبيرة، أو بعد عدة مهام، أو قبل Release | 5–6–7 | إذا كان المشروع صغيرًا والمهام قليلة ويمكن لـ Tera متابعتها يدويًا | `PROJECT_STATE.md` + `TASK_REGISTRY.md` |
+| PlanComplianceReviewAgent | `PLAN_COMPLIANCE_REVIEW_AGENT` | `REVIEW_NEEDED`: نهاية Phase، أو بعد دفعة مهام رئيسية، أو قبل قبول MVP | 5–6–7 | إذا كان التنفيذ متوافقًا بوضوح مع الخطة ولا توجد انحرافات ظاهرة | `PROJECT_MASTER_PLAN.md` + `TASK_REGISTRY.md` |
+| DomainResearchAgent | `DOMAIN_RESEARCH_AGENT` | `COMPLEXITY_SIGNAL / USER_REQUEST`: مجال غير مألوف، أو حاجة بحث خارجي | 1–2–3 | إذا كان المجال معروفًا بالكامل أو المستخدم قدم جميع المعلومات المطلوبة | Domain Research Brief من Tera |
+| DomainExpertAgent | `DOMAIN_EXPERT_AGENT` | `COMPLEXITY_SIGNAL`: بعد اكتمال Domain Research، أو عند الحاجة لتحليل متقدم | 2–3–4 | إذا لم يُظهر Domain Research نتائج تستدعي تحليلًا إضافيًا | Domain Research Report + Domain Research Brief |
+| ProductionERPExpert | `PRODUCTION_ERP_EXPERT` | `COMPLEXITY_SIGNAL / USER_REQUEST`: موديول تصنيع/إنتاج ERP، أو حاجة لتحليل BOM/Routing/MRP/WIP/Costing/Quality/Rework/Scrap أو مراجعة Production Blueprint | 1–5 | إذا كان المشروع لا يحتوي تصنيع/إنتاج، أو كانت الأسئلة CRUD عامة لا تحتاج خبرة Production ERP | Production context + ملفات discovery/blueprint ذات الصلة + KB index عند الحاجة |
+
+---
+
+### 2.3 عملاء التعامل مع العملاء الخارجيين
+
+| العميل | المعرف | Trigger التفعيل | المرحلة | متى لا يُفعّل | الحد الأدنى من المدخلات |
+|---|---|---|---|---|---|
+| ClientDiscoveryAgent | `CLIENT_DISCOVERY_AGENT` | `EXTERNAL_FACTOR`: بداية مشروع عميل خارجي | Client Discovery (قبل Phase 1) | إذا كان المشروع داخليًا (غير موجه لعميل خارجي) | `CLIENT_PROFILE.md` + `project-inputs/` |
+| ProposalScopeAgent | `PROPOSAL_SCOPE_AGENT` | `EXTERNAL_FACTOR`: بعد اكتمال Client Discovery واعتماد الفهم | Client Discovery (قبل Phase 1) | إذا لم يكتمل Client Discovery بعد | `project-inputs/` كاملة |
+| ClientApprovalReviewAgent | `CLIENT_APPROVAL_REVIEW_AGENT` | `EXTERNAL_FACTOR`: قبل إرسال حزمة اعتماد العميل أو قبل Build Mode | ما قبل التنفيذ | إذا لم تكتمل حزمة الاعتماد بعد | `clients/.../client-approval/` |
+| ChangeControlAgent | `CHANGE_CONTROL_AGENT` | `EXTERNAL_FACTOR`: طلب تغيير جديد بعد اعتماد النطاق | أي مرحلة بعد اعتماد النطاق | إذا لم يظهر أي طلب تغيير | `11_CHANGE_CONTROL.md` أو طلب التغيير الجديد |
+
+---
+
+## 3. مصفوفة التفعيل حسب نوع المشروع
+
+### 3.1 مشروع صغير (CRUD بسيط)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | اختياري | إذا كانت الفكرة بسيطة وواضحة، يمكن لـ Tera كتابة `01_PROJECT_BRIEF.md` مباشرة |
+| BusinessWorkflowAgent | لا | إذا لم يكن هناك workflows |
+| UIUXStructureAgent | اختياري | إذا كان هناك واجهة بسيطة |
+| UIVisualDesignerAgent | لا | إلا إذا قدم المستخدم ألوانًا أو مصدر تصميم |
+| DataDesignAgent | اختياري | إذا كانت البيانات مترابطة |
+| SolutionArchitectureAgent | لا | التقنيات محددة مسبقًا |
+| EngineeringAgent | نعم | مع `Pre-Execution Gate: PASS` |
+| QAAndAcceptanceAgent | اختياري | يمكن لـ Tera مراجعة المهمة مباشرة |
+| DocumentationHandoverAgent | لا | |
+| SecurityAgent | لا | إلا إذا كان هناك Auth |
+| باقي المشروطون | لا | لا triggers كافية |
+
+### 3.2 مشروع متوسط (تطبيق ويب متكامل مع Dashboard)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | إذا كان هناك workflows |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | اختياري | إذا كان هناك متطلبات بصرية |
+| DataDesignAgent | نعم | |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | اختياري | إذا كان هناك تسليم لطرف آخر |
+| SecurityAgent | نعم | إذا كان هناك Auth أو صلاحيات |
+| PerformanceAgent | اختياري | إذا توقعنا حجم مستخدمين متوسط |
+| ReportingAnalyticsAgent | اختياري | إذا كان هناك Dashboard |
+| ProjectControlAgent | اختياري | عند تعدد المهمات |
+| SoftwareDesignerAgent | اختياري | عند تعقيد المهمات |
+| Auditor | اختياري | مطلوب فقط عند risk/architecture/quality trigger بعد التنفيذ |
+
+### 3.3 مشروع ERP (نظام تخطيط موارد مؤسسة)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | أساسي في ERP |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | نعم | إذا كان UI مهمًا |
+| DataDesignAgent | نعم | أساسي |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | مع تفعيل متكرر عبر موديولات متعددة |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | نعم | ERP يحتاج توثيق تسليم كامل |
+| SecurityAgent | نعم | ERP يحتوي صلاحيات وبيانات حساسة |
+| IntegrationAgent | نعم | تكاملات خارجية متوقعة |
+| DevOpsDeploymentAgent | نعم | نشر في بيئات متعددة |
+| PerformanceAgent | نعم | حجم بيانات كبير |
+| ComplianceAgent | اختياري | حسب المجال |
+| ReportingAnalyticsAgent | نعم | ERP يحتوي تقارير كثيرة |
+| MaintenanceMigrationAgent | نعم | ERP يحتاج ترحيل بيانات |
+| ProjectControlAgent | نعم | إدارة تتبع متقدمة |
+| SoftwareDesignerAgent | نعم | مهام متعددة ومعقدة تحتاج Technical Specification |
+| QualityReviewCoordinatorAgent | نعم | بعد مجموعات مهام |
+| Auditor | نعم | بعد المهام الحساسة أو ذات الأثر المعماري/الجودة |
+| PlanComplianceReviewAgent | نعم | قبل قبول مراحل |
+| DomainResearchAgent | اختياري | لمجالات ERP غير المألوفة |
+| DomainExpertAgent | اختياري | لتحليل متقدم للمجال |
+| ProductionERPExpert | نعم عند وجود موديول تصنيع/إنتاج | أساسي لمشاريع ERP التصنيعية أو أي Production module |
+| Client Engagement Agents | اختياري | إذا كان ERP لعميل خارجي |
+
+### 3.4 مشروع SaaS (منصة خدمية)
+
+| العميل | هل يُفعّل؟ | ملاحظة |
+|---|---|---|
+| RequirementsScopeAgent | نعم | |
+| BusinessWorkflowAgent | نعم | |
+| UIUXStructureAgent | نعم | |
+| UIVisualDesignerAgent | نعم | UI مهم لـ SaaS |
+| DataDesignAgent | نعم | |
+| SolutionArchitectureAgent | نعم | |
+| EngineeringAgent | نعم | |
+| QAAndAcceptanceAgent | نعم | |
+| DocumentationHandoverAgent | نعم | توثيق للمستخدمين |
+| SecurityAgent | نعم | Auth/Multi-tenant أساسي |
+| IntegrationAgent | اختياري | حسب التكاملات |
+| DevOpsDeploymentAgent | نعم | نشر مستمر |
+| PerformanceAgent | نعم | قابلية التوسع |
+| ReportingAnalyticsAgent | اختياري | حسب الاحتياج |
+| ProjectControlAgent | اختياري | عند تعدد المهمات |
+| SoftwareDesignerAgent | اختياري | عند تعقيد المهمات |
+
+---
+
+## 4. قواعد التفعيل الصارمة
+
+### 4.1 لا تفعيل تلقائي للعملاء
+
+```
+تفعيل العميل يتم بقرار من Tera فقط، استنادًا إلى Trigger واضح.
+الاستثناء الوحيد في v1: Monitor → Auditor بطلب Majed الصريح.
+لا يتم تفعيل العميل تلقائيًا لمجرد دخول مرحلة أو وجود ملف جاهز.
+```
+
+### 4.2 لا تفعيل بدون مدخلات كافية
+
+```
+لا يُفعّل عميل إذا لم تتوفر المدخلات الدنيا المطلوبة.
+إذا كانت المدخلات ناقصة، إما:
+  - أن يكمل Tera المدخلات بنفسه
+  - أو يُفعّل عميلًا آخر لتجهيز المدخلات أولاً
+  - أو يطلب من المستخدم إكمالها
+```
+
+### 4.3 لا تفعيل عميل موجود بالفعل في مهمة حاليًا
+
+```
+لا يتم تفعيل نسخة جديدة من عميل موجود حاليًا في مهمة نشطة،
+إلا إذا كان العميل جاهزًا لتسلم مهمة جديدة ومستقلة.
+```
+
+### 4.4 لا تفعيل عميل لمتطلبات مستقبلية
+
+```
+لا يتم تفعيل عميل بناءً على متطلبات أو سيناريوهات قد تحدث في المستقبل.
+التفعيل يكون للحاجة الحالية فقط.
+```
+
+### 4.5 عميل واحد لكل اختصاص في كل مرة
+
+```
+لا يتم تفعيل عميلين لهما نفس الاختصاص (مثل اثنين EngineeringAgent) في وقت واحد
+على نفس الموديول، إلا في حالات المهام المتوازية المستقلة تمامًا.
+```
+
+---
+
+## 5. تسجيل قرار التفعيل
+
+عند تفعيل أي عميل فرعي، يسجل Tera في `PROJECT_ACTIVITY_LOG.md`.
+وعند استدعاء Monitor لـ Auditor بطلب Majed، يسجل Monitor ذلك في تقريره أو في السجل المتاح له:
+
+```
+- Agent ID
+- Activation Trigger
+- Task ID المستهدف
+- المرحلة الحالية
+- Brief reason for activation
+```
+
+---
+
+## 6. إلغاء التفعيل أو التعطيل المؤقت
+
+إذا تم تفعيل عميل ثم تبين أنه غير مطلوب:
+
+1. يتم إنهاء مهمته الحالية بحالة `Cancelled` مع سبب واضح.
+2. يسجل Tera الإلغاء في `PROJECT_ACTIVITY_LOG.md`.
+3. لا يُعاد تفعيله إلا عند ظهور Trigger جديد ومستقل.
+
+---
+
+## 7. أمثلة على تطبيق القواعد
+
+### مثال 1: مشروع ERP جديد — مرحلة التحضير
+
+```
+Trigger: بداية Phase 4 (Preparation)
+مُهندس يقرر: تفعيل RequirementsScopeAgent و BusinessWorkflowAgent و DataDesignAgent
+لا يُفعّل: SolutionArchitectureAgent (يُفعّل لاحقاً في Phase 4 حسب الحاجة)، SecurityAgent (لا يوجد موديول حساس بعد)
+```
+
+### مثال 2: طلب تغيير من عميل
+
+```
+Trigger: طلب إضافة تكامل دفع خارجي
+Tera يقرر: تفعيل IntegrationAgent
+لا يُفعّل: ChangeControlAgent (لأنه سيقترح فقط، ويمكن لـ Tera إدارة ذلك)
+```
+
+### مثال 3: مراجعة بعد 5 مهام تنفيذية
+
+```
+Trigger: REVIEW_NEEDED
+Tera يقرر: تفعيل QualityReviewCoordinatorAgent
+بعد تقريره: قد يُفعّل SecurityAgent إذا وجد findings أمنية
+```
+
+---
+
+## 8. الملخص — قاعدة التفعيل الذهبية
+
+> **عند الشك، لا تُفعّل.**
+>
+> العميل هو أداة متخصصة تُستدعى للحاجة الحالية فقط،
+> وليس عضوا دائمًا في فريق المشروع.