---
name: saas-project-handbook
description: Build and maintain a complete project handbook and delivery packs for SaaS, workflows, automations, and AI systems. Use for docs-as-code, decision records, architecture/product/security references, build packs, release packs, upgrade packs, add-on packs, handover, audit, and investor-ready summaries. استخدمها للتجميع والتسليم القابل لإعادة الاستخدام.
---

# SaaS Project Handbook

## عقد التشغيل

- **استخدمها عندما:** تحتاج حزمة بناء أو إصدار أو تسليم أو سجل قرارات وأدلة قابل للنقل.
- **لا تستخدمها عندما:** لا توجد قرارات أو أدلة جاهزة بعد، أو المطلوب إصلاح كود محدود.
- **تستلم:** النسخ المثبتة من مخرجات المالكين، نتائج الاختبارات، المخاطر، وخطة الإطلاق.
- **تملك وتنتج:** handbook وفهارس الأدلة وBuild/Release/Handover packs ومصدرًا واحدًا للروابط.
- **لا تملك:** اختراع قرار معماري أو أمني أو منتجي لم يحسمه مالكه.
- **بوابة الخروج:** يستطيع فريق مستقل معرفة ما يبنى أو يطلق أو يعكسه، ومن يملك كل قرار.
- **التسليم التالي:** فريق البناء أو الإطلاق، ثم `saas-audit-repair` لمراجعة readiness عند الحاجة.

اتبع نموذج المسارات والملكية في `../../shared/references/operating-model.md`.

## المهمة

أنشئ **مصدر حقيقة قابلًا للإصدار والتسليم** يستطيع وكيل أو مبرمج أو فريق أو مراجع أو مستثمر استخدامه دون اعتماد على معرفة شفوية حرجة. لا تجمع ملفات متفرقة؛ ابنِ نظام وثائق بملكية وتتبع وحالات وصلاحية.

## مبادئ

1. Docs as code: versioned، reviewed، linted، linked to source/tests/releases.
2. Single source of truth: لا تنسخ نفس الحقيقة في خمسة ملفات؛ اربط إليها.
3. Audience views, shared facts: غيّر العرض لا الحقيقة.
4. Decision provenance: من قرر، متى، لماذا، البدائل، والآثار.
5. Executable where possible: OpenAPI/AsyncAPI/schemas/tests/scripts أفضل من وصف يدوي قابل للانحراف.
6. Every document has owner، status، version، last reviewed، and supersession link.
7. لا توثق ادعاءً غير مثبت بلهجة تقريرية. استخدم evidence/assumption markers.
8. لا تعتبر الوثائق «نهائية»؛ حدد freshness policy ومشغلات التحديث.

## هيكل الكتاب

ابدأ من `../../shared/templates/project-handbook-index.md` وأنشئ:

```text
handbook/
├── 00-executive/
├── 01-product/
├── 02-requirements/
├── 03-experience/
├── 04-visual-system/
├── 05-architecture/
├── 06-data/
├── 07-ai/
├── 08-security/
├── 09-implementation/
├── 10-testing/
├── 11-operations/
├── 12-release/
├── 13-governance/
├── 14-commercial/
├── 15-decisions/
├── packs/
└── INDEX.md
```

## سير العمل

### 1. جرد المصادر

حدد:

- repositories/branches/commits.
- tickets/PRDs/designs/diagrams.
- API/schema/model configs.
- test/eval evidence.
- cloud/infrastructure configs.
- policies/contracts/compliance evidence.
- owners and authoritative locations.

صنف كل مصدر: authoritative، derived، historical، unverified، obsolete.

### 2. مصفوفة التتبع

أنشئ روابط:

```text
Outcome → Requirement → Design/ADR → Implementation → Test/Eval → Control → Release
```

لكل عنصر ID ثابت. ارفض عناصر تنفيذ بلا متطلب أو اختبارات بلا سلوك مستهدف عندما تكون حرجة.

### 3. طبقات الجمهور

أنشئ عروضًا متسقة:

- Executive/investor: المشكلة، القيمة، traction/evidence، economics، risks، milestones.
- Product/experience: users، journeys، requirements، experiments.
- Visual design: art direction، color/type systems، tokens، page specs، assets، themes، visual QA.
- Engineering: architecture، contracts، data، conventions، ADRs.
- AI: capability cards، models، tools، evals، safety.
- Security/audit: threats، controls، evidence، residual risk.
- Operations/support: SLOs، runbooks، incidents، escalation.
- New agent/developer: setup، commands، repo map، constraints، DoD.

لا تعرض secrets أو تفاصيل هجومية حساسة في حزم المستثمرين أو الجمهور غير المخول.

### 4. توثيق القرار

استخدم ADRs للقرارات التقنية، وDecision Log للقرارات التجارية/منتجية. كل قرار يتضمن:

- context and drivers.
- options.
- evidence and assumptions.
- decision and owner.
- consequences/debt.
- validation and review trigger.
- supersession chain.

### 5. تعليمات البناء والتنفيذ

أنشئ `07-implementation/BUILD.md` يتضمن:

- prerequisites and supported versions.
- environment setup without secrets.
- install/build/test/lint/typecheck commands.
- database migration/seed/reset.
- local dependencies and mocks.
- feature flags.
- troubleshooting known failures.
- definition of done.

اختبر التعليمات من بيئة نظيفة أو صرّح بأنها غير متحققة.

### 6. حزم التسليم

#### Build Pack

يحتوي:

- scope and commit/version.
- requirements slice.
- architecture/ADRs.
- API/data contracts.
- implementation plan and DoD.
- test/security/eval plan.
- dependencies/risks/open questions.

#### Release Pack

يحتوي:

- release manifest and checksums/artifact IDs.
- changelog and migration notes.
- test/eval/security evidence.
- rollout/canary/feature flags.
- monitoring/alerts.
- rollback and restore.
- communication/support notes.
- approvals.

#### Upgrade Pack

يحتوي:

- current → target versions.
- compatibility matrix.
- breaking changes and deprecations.
- data/config migrations.
- dependency/model/API changes.
- rehearsal and rollback.
- post-upgrade verification.

#### Add-on Pack

يحتوي:

- capability and boundaries.
- contracts/permissions/data access.
- installation/configuration.
- compatibility and dependencies.
- tests/security/evals.
- uninstall/rollback.
- ownership and support.

#### Handover Pack

يحتوي:

- system map.
- access/ownership matrix دون أسرار.
- operational calendar.
- known debt/risks.
- incidents and recurring tasks.
- vendor contacts/contracts references.
- competency gaps and onboarding route.

#### Investor/Review Pack

يحتوي:

- evidence-backed thesis.
- product/market/technical status.
- architecture scalability summary.
- security/privacy posture دون ادعاء امتثال زائف.
- unit economics assumptions.
- roadmap dependencies.
- top risks and mitigations.
- data room index.

### 7. إدارة الإصدارات والتغيير

حدد:

- semantic/document version policy.
- release tags and commit linkage.
- changelog categories.
- deprecation windows.
- document review cadence based on volatility.
- automatic stale checks where possible.
- generated vs manually maintained content.
- owner escalation for stale critical docs.

### 8. الجودة والاتساق

افحص:

- broken links.
- duplicate/conflicting facts.
- missing owners/status/version.
- diagrams inconsistent with code/deployment.
- API docs inconsistent with schemas.
- stale model/provider/version names.
- undocumented migrations/flags.
- tests not linked to acceptance criteria.
- inaccessible terms or acronyms without glossary.
- sensitive data leakage.

### 9. حزمة قرار تنفيذي

في نهاية كل مرحلة أنشئ صفحة واحدة:

- decision requested.
- current evidence.
- options and recommendation.
- unresolved assumptions.
- top risks.
- cost/time range and confidence.
- next irreversible decision.
- explicit owner and deadline.

## المخرجات الإلزامية

```text
handbook/
├── INDEX.md
├── GLOSSARY.md
├── SOURCE-MAP.md
├── TRACEABILITY.md
├── CHANGELOG.md
├── 00-executive/...
├── 01-product/...
├── 02-requirements/...
├── 03-experience/...
├── 04-visual-system/...
├── 05-architecture/...
├── 06-data/...
├── 07-ai/...
├── 08-security/...
├── 09-implementation/...
├── 10-testing/...
├── 11-operations/...
├── 12-release/...
├── 13-governance/...
├── 14-commercial/...
├── 15-decisions/...
└── packs/
    ├── build-pack-<version>/
    ├── release-pack-<version>/
    ├── upgrade-pack-<version>/
    ├── addon-pack-<name>-<version>/
    ├── handover-pack-<date>/
    └── review-investor-pack-<date>/
```

## تعريف النجاح

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