GitHub Spec Kit — الدليل الشامل: من Vibe Coding لهندسة Intent-Driven

اقعد معايا شوية. هات كوباية القهوة بتاعتك، لأن اللي جاي ده مش مقالة بتتقرا بالعين — دي جلسة شغل. أنا وانت، قدام terminal واحد، هنبني مشروع من الصفر بـ GitHub Spec Kit. وفي الطريق هتفهم كل حاجة: ليه الـ vibe coding بيبوّظ المشاريع، وإيه اللي بيخلّي spec مكتوب في ملف أقوى من أذكى model في السوق، وإزاي تخلّي الـ AI agent بتاعك يشتغل زي مهندس منضبط مش زي جني بيحقق أمنيات.

66 أمر. 9 مراحل. 30+ integration. extension ecosystem كامل. متقلقش من الأرقام — هناخدهم واحدة واحدة، وفي الآخر هتلاقي نفسك فاهم الصورة كلها من غير ما تحس.

يلا بينا.

Section1. القصة بتبدأ بمشكلة: ليلة الـ Demo

خليني أحكيلك قصة — وانت هتعرفها، لأنها حصلتلك.

فيه developer — سمّيه أحمد — عنده deadline. فتح الـ AI agent بتاعه وكتب: "اعمللي نظام login". من غير spec، من غير constraints، من غير acceptance criteria. الـ AI طلّع كود في دقيقتين. أحمد بصّله بصّة سريعة — شكله كويس — عمله merge. الـ demo نجح، الكل صقّف، وأحمد روّح نام مبسوط.

ده اسمه Vibe Coding. وفي اللحظة دي، بيبان إنه أحلى حاجة في الدنيا. سريع؟ جداً. شغال؟ أيوة. المشكلة فين بقى؟

المشكلة إن القصة مش بتخلص هنا. بعد ستة شهور، الـ team كبر، والـ features اتراكمت، وكل feature جديدة كانت بتتعمل بنفس الطريقة: prompt عشوائي → كود → eyeball review → merge. وفجأة أحمد بيكتشف إن الـ codebase بقى كتلة من الـ assumptions المدفونة في chat sessions قديمة محدش فاكرها. الـ bug بيظهر في مكان، وسببه في مكان تاني خالص. ده اسمه Architectural Drift — وده مش bug، ده مرض مزمن.

وهنا انت هتقول لي: يا باشمهندس، بس الـ AI هو اللي كتب الكود — يبقى الـ AI هو الغلطان! أقولك لأ. الـ AI بيعمل اللي بتقوله بالظبط. المشكلة إن اللي بتقوله مش واضح. الـ intent نفسه — القصد — عمره ما اتكتب في حتة. وبكده بتدخل في الحلقة المفرغة دي:

Developer vague → AI hallucinates → Code drifts → Spec never written → Repeat

بص عليها كويس. كل دورة في الحلقة دي بتزوّد الـ drift، والـ spec اللي كان المفروض يكون الـ source of truth عمره ما بيتكتب — لأن "مفيش وقت". لحد ما الـ production يقع، وساعتها بيبقى فيه وقت لكل حاجة.

1.1 خليني أحطلك الفرق في جدول — Vibe Coding vs SDD

وخد عندك الخلاصة في سطرين، دول أهم سطرين في المقالة كلها:

Spine: GitHub Spec Kit بيحوّل الـ intent من حاجة عابرة في chat session لـ artifact ملتزم بيه في الـ repo — الـ spec يبقى الـ source of truth، والكود يبقى الـ secondary artifact.

Twist: الـ fix مش أكتر compute ولا model أحسن — الـ fix هو structure. لما الـ intent يكون محدد ومُلتزم بيه، حتى mid-tier model بيتفوّق على frontier model شغال في vibe coding mode. فكّر فيها كده: مهندس عادي معاه رسومات كاملة هيبني أحسن من مهندس عبقري شغال من دماغه.

الـ shift الجوهري هنا إن الـ focus بيتنقل من "كتابة كود" لـ "إدارة intent". وده بالظبط الـ governance اللي أي AI-native engineering organization محتاجاه. مش بكرة — دلوقتي.

Section2. طيب إيه الحل؟ تعرّف على GitHub Spec Kit

خليني أديك تشبيه هيوضّح كل حاجة.

لما تيجي تبني عمارة، مش بتقول للمقاول "ابنيلي حاجة حلوة" وتمشي. بيحصل الآتي: بتقعد مع مهندس استشاري يسمعك ويكتب كراسة شروط (ده الـ spec). بعدها بيتعمل رسومات إنشائية (ده الـ plan). بعدها جدول تنفيذ بالبنود (دي الـ tasks). وبعدين المقاول بينفّذ بند بند، وفيه استشاري بيستلم كل مرحلة (ده الـ QA). والعمارة كلها محكومة بـ كود بناء ملزم للجميع (ده الـ Constitution).

Spec Kit بيعمل بالظبط كده — بس للسوفتوير، والمقاول بتاعك هو الـ AI agent.

بشكل رسمي: Spec Kit مش framework ولا library ولا SDK. ده CLI tool + workflow framework بيـ orchestrate التفاعل بين الـ developer والـ AI agent. الفلسفة بتاعته في جملة واحدة: specifications become executable — الـ spec مش مستند بيموت في Confluence، ده living source of truth بيحكم الـ lifecycle كله، وبيفصل فصل صارم بين الـ "What" (إيه اللي عايزه) والـ "How" (إزاي هيتنفذ).

طب إزاي ده بيشتغل على أرض الواقع؟ بدل ما تكتب prompt عشوائي وتتمنى خير، الـ Spec Kit بيـ force الشغل يمر في phases محددة — كل phase ليها output artifact بيتـ commit. والـ AI agent مش حر يـ skip ولا يـ improvise خارج الـ spec.

2.1 التجهيز — نركّب الأداة الأول

الـ SDD الناجح محتاج environment موحّد، و Spec Kit بيستخدم uv package manager للـ isolation.

المتطلبات: Python 3.11+، Git، و uv أو pipx. ده كل اللي محتاجه.

# الطريقة المفضّلة (uv)
uvtoolinstallspecify-cli--fromgit+https://github.com/github/spec-kit.git

# بطريقة pipx
pipxinstallgit+https://github.com/github/spec-kit.git

# تحقق
specifycheck# audit environment
specify--version# confirm official build

نصيحة: أول أمر تجرّبه بعد التثبيت هو specify check — لو فيه حاجة ناقصة في الـ environment، هتكتشفها دلوقتي في ثانيتين، مش في نص الـ workflow وانت مستعجل.

2.2 هو لازم أغيّر الـ AI Agent بتاعي؟ لأ — 30+ Integration

ده أول سؤال بييجي في دماغ أي حد: "أنا شغال بـ Claude Code / Copilot / Cursor... هضطر أسيبه؟" والإجابة: لأ خالص. Spec Kit متصمم بفلسفة "no lock-in" — بيتـ adapt لأي agent:

specifyintegrationlist# عرض كل الـ integrations
specifyinit.--integrationclaude# Claude Code → CLAUDE.md
specifyinit.--integrationcopilot# GitHub Copilot → .github/copilot/
specifyinit.--integrationgemini# Gemini CLI → GEMINI.md
specifyinit.--integrationcodex# Codex CLI → CODEX.md
specifyinit.--integrationcursor-agent# Cursor → .cursor/rules/
specifyinit.--integrationwindsurf# Windsurf → .windsurf/rules/
specifyinit.--integrationhermes# Hermes → HERMES.md
specifyinit.--integrationkimi# Kimi Code → KIMI.md

# لو الـ agent بتاعك مش في القائمة:
specifyinit.--integrationgeneric--integration-options="--commands-dir .myagent/cmds"

# Skills mode (للـ agents اللي بتدعمها):
specifyinit.--integrationcodex--integration-options="--skills"

2.3 نفّذ specify init وتعالَ نشوف حصل إيه

نفّذت الأمر؟ تمام. افتح المشروع وهتلاقي directory جديد اسمه .specify/ — وخليني أقولك من دلوقتي: ده مخ العملية كلها. كل الـ phases اللي جايين بيقرأوا منه وبيكتبوا فيه.

my-project/
├── .specify/
│   ├── memory/constitution.md      ← قواعد المشروع (Project Constitution)
│   ├── templates/
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   ├── templates/overrides/        ← أعلى priority
│   ├── presets/                    ← preset templates
│   ├── extensions/                 ← installed extensions
│   └── features/
│       └── 001-feature-name/
│           ├── spec.md             ← من /speckit.specify
│           ├── plan.md             ← من /speckit.plan
│           ├── tasks.md            ← من /speckit.tasks
│           ├── data-model.md
│           ├── contracts/
│           │   ├── api-spec.json
│           │   └── signalr-spec.md
│           ├── research.md
│           ├── checklist.md
│           ├── blueprint.md
│           └── analysis.md
├── CLAUDE.md     ← أو KIMI.md / COPILOT.md حسب الـ integration
├── .gitignore
└── src/          ← الكود (بيتعمل من /speckit.implement)

وفيه تفصيلة ذكية هنا اسمها Template Resolution Order — لو أكتر من template لنفس الحاجة، مين بيكسب؟ الأعلى في القائمة دي:

1. .specify/templates/overrides/    ← project-local (أعلى priority)
2. .specify/presets/templates/      ← presets
3. .specify/extensions/templates/   ← extensions
4. .specify/templates/              ← spec kit core (أقل priority)

ملحوظة: الـ .specify/ ده مش مجرد folder. لو الـ constitution بتقول "TDD mandatory"، كل command جوا الـ Spec Kit هيـ enforce ده تلقائياً — مش محتاج تفكّر الـ AI في كل prompt. مكتوب مرة، مُلتزم بيه دايماً.

Section3. الرحلة الحقيقية — 9 مراحل هنمشيهم مع بعض خطوة خطوة

دلوقتي جه وقت الشغل الفعلي. عشان الكلام ميبقاش نظري، هنبني مع بعض feature حقيقية: نظام tasks بسيط — المستخدم يضيف task، يعلّم عليها إنها خلصت، ويشوف إحصائيات إنتاجيته. هنمشي بيها من أول أمر لآخر أمر، وكل مرحلة هقولك: بنعمل إيه، وليه، وإيه اللي بيطلع في إيدك في الآخر.

 الرحلة الكاملة:
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 0.Setup → 1.Constitution → 2.Specify → 3.Plan → 4.Tasks                 │
 │         → 5.Implement → 6.QA & Review → 7.Ship → 8.Maintenance          │
 │                                                                          │
 │ 🖥️ Terminal = specify CLI commands  │  🤖 Agent = /speckit.* slash cmds  │
 │ ❌ Built-in = بدون extension       │  ✅ Extension = يحتاج تثبيت        │
 └──────────────────────────────────────────────────────────────────────────┘

خد بالك من التقسيمة دي كويس: فيه أوامر بتتكتب في الـ Terminal (بتبدأ بـ specify)، وفيه أوامر بتتكتب جوا الـ AI agent نفسه (بتبدأ بـ /speckit). والأوامر اللي عليها ✅ محتاجة extension يتثبّت الأول.

Phase 0 — الإعداد (Setup): بنجهّز الورشة

قبل ما نبني، بنجهّز الورشة. المرحلة دي كلها أوامر terminal، وهي الأساس اللي كل حاجة هتقعد عليه:

⚠️ تحذير: الـ built-in extensions الوحيدة اللي بتتثبّت بالاسم بدون --from هي الـ git extension. كل الـ community extensions بتحتاج --from <zip-url>. يعني specify extension add review لوحدها مش هتشتغل — لازم الـ URL.

في مشروعنا؟ نفّذنا specify init task-tracker --integration claude و specify check. الورشة جاهزة. ننتقل.

Phase 1 — الـ Constitution: دستور المشروع

هنا بقى أول حاجة بتفرّق الـ SDD عن أي طريقة تانية. قبل ما نكتب سطر واحد عن الـ feature، بنكتب دستور المشروع — الـ "engineering rulebook" اللي الـ AI agent ملزم بيه في كل مرحلة جاية، ومن غير ما تفكّره.

/speckit.constitutionSecurity-first.TDDmandatory.TTFB<200ms.

الأمر ده بيولّد constitution.md في .specify/memory/، وبيـ encode جواه:

• Tech Stack Constraints: إصدارات libraries إلزامية (مثلاً "Must use Next.js 14 SSG")
• Testing Mandates: حد أدنى للـ coverage و TDD requirements
• Compliance: Accessibility (WCAG)، Security (OWASP)، design system standards

هنا انت هتسألني السؤال المنطقي: "طيب هو الـ AI بيلتزم بالكلام ده فعلاً؟" أقولك آه — لأن الـ constitution بيشتغل كـ hard gate مش كنصيحة. الـ /speckit.analyze (هنوصلها كمان شوية) بترفض أي plan بيخالف الدستور. constitution "صارم" بيزوّد الـ complexity بس بيضمن production readiness — و constitution "خفيف" أنسب للـ exploratory spikes. انت اللي بتختار مستوى الصرامة حسب طبيعة المشروع.

والفايدة الخفية الأهم: الـ constitution بيحل مشكلة اسمها context saturation. بدل ما تفضل تكرر للـ agent في كل prompt "متنساش الـ TDD، متنساش الـ security" — بتكتبها مرة واحدة، وبتتقري تلقائياً مع كل command. دماغك فاضية، والقواعد شغالة.

specifyextensionaddred-team--fromhttps://github.com/ashbrener/spec-kit-red-team/archive/refs/heads/main.zip
specifyextensionaddbrownfield--fromhttps://github.com/Quratulain-bilal/spec-kit-brownfield/archive/refs/heads/main.zip
specifyextensionaddrepoindex--fromhttps://github.com/liuyiyu/spec-kit-repoindex/archive/refs/heads/main.zip

نصيحة: جرّب /speckit-red-team على الدستور بتاعك — ده بيعمل adversarial review، يعني بيحاول "يهاجم" الـ constitution ويلاقي الثغرات فيه قبل ما تبني عليه. أرخص وقت تكتشف فيه ثغرة هو قبل ما يتكتب أي كود.

في مشروعنا؟ كتبنا: /speckit.constitution "Vanilla JS only. TDD mandatory. No external UI frameworks. All data local-first." — كده الـ agent عمره ما هيقترح React ولا يكتب كود من غير test. اتقفلت الأبواب دي خلاص.

Phase 2 — الـ Specify: بنكتب "إيه" مش "إزاي"

دلوقتي بنكتب كراسة الشروط. وهنا فيه قاعدة ذهبية لو مش هتاخد من المقالة دي غيرها يبقى كفاية:

القاعدة الذهبية في specify: قول "إيه" و"ليه" — متقولش "إزاي". الـ agent هيفكّر في التقنية بعدين.

/speckit.specify"Users can create tasks, mark them done, and see a productivity summary. A task has a title, optional due date, and status. The summary shows tasks completed per day over the last week."

الأمر بيولّد spec.md — وجواه user stories و acceptance criteria بس. مفيش database، مفيش framework، مفيش API design. ليه الإصرار ده؟

تعالَ أقولك السبب بمثال: لو كتبت في الـ spec "نستخدم React + Node"، وبعد سنة قررتوا تنقلوا لـ Vue أو حتى CLI tool — الـ spec كله بقى outdated رغم إن الـ requirements نفسها ما اتغيرتش. الـ spec بيعيش أطول من التقنية، فلازم يفضل technology-agnostic. الـ "إزاي" ليه مكان تاني اسمه الـ plan، جاي في المرحلة الجاية على طول.

بس استنى — إحنا لسه مخلصناش المرحلة دي. أخطر حاجة في أي spec هي الجُمل الغامضة. وعشان كده فيه quality gates لازم الـ spec يعدي منها:

خليني أقف عند اتنين منهم لأنهم جواهر حقيقية:

• /speckit.clarify — ده sequential, coverage-based questioning layer. الـ agent بيقرا الـ spec، يستخرج كل نقطة غامضة، ويسألك عليها سؤال سؤال — وإجاباتك بتتسجل جوا الـ spec نفسه. في مشروعنا سألنا: "الـ due date بالساعة ولا باليوم بس؟" و"الـ task المحذوفة تدخل في الإحصائيات؟" — أسئلة لو ما اتسألتش دلوقتي، الـ AI كان هيـ guess إجاباتها وانت مش واخد بالك.
• /speckit.checklist — بيولّد validation checklist، أو زي ما بحب أسميها: "unit tests للغة الإنجليزي". بتتأكد إن الـ requirements نفسها complete و clear و consistent قبل ما تتحول لكود.

specifyextensionaddcritique--fromhttps://github.com/arunt14/spec-kit-critique/archive/refs/heads/main.zip
specifyextensionaddspec-validate--fromhttps://github.com/aeltayeb/spec-kit-spec-validate/archive/refs/heads/main.zip
specifyextensionaddwhatif--fromhttps://github.com/DevAbdullah90/spec-kit-whatif/archive/refs/heads/main.zip
specifyextensionaddscope--fromhttps://github.com/Quratulain-bilal/spec-kit-scope-/archive/refs/heads/main.zip
specifyextensionaddmemory-loader--fromhttps://github.com/KevinBrown5280/spec-kit-memory-loader/archive/refs/heads/main.zip

Phase 3 — الـ Plan: دلوقتي بس نتكلم تقنية

الـ spec اتقفل؟ حلو. دلوقتي بقى وقت الـ "إزاي". وخد بالك من الجمال هنا: التقنية بتتحدد وانت معاك spec واضح ومتـ clarify — يعني بتختار الـ tech على أساس requirements حقيقية، مش على أساس "آخر حاجة شفتها في تويتر".

/speckit.plan"Vite + SQLite + vanilla JS"

الأمر ده بيـ synthesize الـ technical architecture كاملة من الـ spec، وبيحدد:

• Data models — الـ schema بالظبط
• API contracts — شكل الـ endpoints والـ payloads
• File structures — الملفات هتتحط فين

وأهم حاجة: بيـ cross-reference الـ Constitution. فاكر إحنا كتبنا "Vanilla JS only"؟ لو حاولت تكتب /speckit.plan "React + Firebase" هيقولك: ده بيخالف الدستور. الأبواب اللي قفلناها في Phase 1 لسه مقفولة.

الـ output الكامل لـ /speckit.plan:

specs/<feature>/
├── plan.md           ← الخطة التقنية
├── data-model.md     ← الـ schema
├── contracts/
│   ├── api-spec.json ← API contracts
│   └── signalr-spec.md
├── research.md
└── quickstart.md

specifyextensionaddblueprint--fromhttps://github.com/chordpli/spec-kit-blueprint/archive/refs/heads/main.zip
specifyextensionaddversion-guard--fromhttps://github.com/KevinBrown5280/spec-kit-version-guard/archive/refs/heads/main.zip
specifyextensionadddiagram--fromhttps://github.com/Quratulain-bilal/spec-kit-diagram-/archive/refs/heads/main.zip

Phase 4 — الـ Tasks: نقطّع الفيل حتت صغيرة

سؤال: إيه أكبر عدو للـ AI models؟ ... الـ limited context window. لو رميت plan كامل على الـ agent وقلتله "نفّذ"، هينسى الأول وهو بيعمل الآخر. الحل؟ نقطّع الخطة لـ chunks صغيرة atomic — كل واحدة تتنفذ وتتراجع لوحدها.

/speckit.tasks

بيولّد tasks.md — قايمة مهام مرتبة بذكاء:

• Dependency Management: الـ infrastructure والـ models بيتبنوا قبل الـ UI components — مش هتلاقي task بيبني شاشة لحاجة لسه متخزنتش
• Parallel Execution: الـ tasks المعلّمة بـ [P] ممكن تشتغل بالتوازي — بـ agents متعددة لو حبيت
• TDD Enforcement: الـ tasks متركّبة بحيث الـ failing test يتكتب قبل كود الـ implementation — دستورنا قال TDD، فالـ tasks نفسها بتطلع TDD

specifyextensionaddjira--fromhttps://github.com/mbachorik/spec-kit-jira/archive/refs/heads/main.zip

⚠️ تحذير — ودي أهم قاعدة في المقالة كلها: /speckit.analyze قبل /speckit.implement دايماً. الـ analyze ده read-only validator بيراجع الـ spec والـ plan والـ tasks مع بعض ويكتشف أي تعارض أو Constitutional Violation. غلطة consistency هنا بتتصلح في دقيقتين — نفس الغلطة بعد implement بتاخد ساعات debugging. دقيقتين مقابل ساعات. متفاوضش على دي.

Phase 5 — الـ Implement: أخيراً... الكود

تسع مراحل وإحنا لسه بنكتب كود دلوقتي؟! أيوة. وده مش عيب — ده الميزة نفسها. لأن اللحظة اللي الـ agent هيكتب فيها الكود، هو معاه: دستور واضح، spec متـ clarify، خطة تقنية متراجعة، و tasks مرتبة بالـ dependencies. مفيش guessing. مفيش hallucination. فيه تنفيذ.

/speckit.implement

الـ agent بيبني task-by-task، بيعلّم على كل task خلصت ✅ في tasks.md، وبيحل بنفسه الـ issues اللي بتظهر في الـ build cycles.

specifyextensionaddcheckpoint--fromhttps://github.com/aaronrsun/spec-kit-checkpoint/archive/refs/heads/main.zip
specifyextensionaddworktree--fromhttps://github.com/Quratulain-bilal/spec-kit-worktree/archive/refs/heads/main.zip
specifyextensionaddworktrees--fromhttps://github.com/dango85/spec-kit-worktree-parallel/archive/refs/heads/main.zip
specifyextensionaddconduct--fromhttps://github.com/twbrandon7/spec-kit-conduct-ext/archive/refs/heads/main.zip

نصيحة: ثبّت /speckit-checkpoint — بدل commit عملاق واحد في الآخر اسمه "done"، بتاخد commits منظّمة أثناء الشغل. لو حاجة باظت، الـ rollback بيبقى جراحة دقيقة مش بتر.

Phase 6 — الـ QA & Review: هنا بيتفصل الجد عن الهزل

اسمعني كويس في الجزء ده، لأن هنا فيه فخ نفسي بيقع فيه الكل: الكود اتكتب، شكله حلو، والـ agent بيقولك "تمام، خلصت كل الـ tasks!" — إغراء الـ merge المباشر رهيب. متعملهاش.

ليه؟ لأن الـ AI agents عندها عادة وحشة اسمها phantom completions: بتعلّم على الـ task إنها ✅ وهي فعلياً ما اتنفذتش، أو اتنفذت نص تنفيذ. ولو مفيش حد بيتحقق، بتكتشفها في الـ production.

عشان كده في الـ Phase دي، اتنين ضروريين والباقي حسب الحالة:

specifyextensionaddverify--fromhttps://github.com/ismaelJimenez/spec-kit-verify/archive/refs/heads/main.zip
specifyextensionaddverify-tasks--fromhttps://github.com/datastone-inc/spec-kit-verify-tasks/archive/refs/heads/main.zip
specifyextensionaddreview--fromhttps://github.com/ismaelJimenez/spec-kit-review/archive/refs/heads/main.zip
specifyextensionaddstaff-review--fromhttps://github.com/arunt14/spec-kit-staff-review/archive/refs/heads/main.zip
specifyextensionaddsecurity-review--fromhttps://github.com/DyanGalih/spec-kit-security-review/archive/refs/heads/main.zip
specifyextensionaddqa--fromhttps://github.com/ismaelJimenez/spec-kit-qa/archive/refs/heads/main.zip
specifyextensionaddspectest--fromhttps://github.com/Quratulain-bilal/spec-kit-spectest/archive/refs/heads/main.zip
specifyextensionaddripple--fromhttps://github.com/chordpli/spec-kit-ripple/archive/refs/heads/main.zip
specifyextensionaddcleanup--fromhttps://github.com/dsrednicki/spec-kit-cleanup/archive/refs/heads/main.zip
specifyextensionaddreconcile--fromhttps://github.com/stn1slv/spec-kit-reconcile/archive/refs/heads/main.zip

في مشروعنا؟ /speckit-verify طلّع إن الـ productivity summary بيعرض 7 أيام صح، بس نسي يستبعد الـ tasks المحذوفة — بالظبط النقطة اللي /speckit.clarify سجّلها في الـ spec. من غير الـ verify، دي كانت هتعدي.

Phase 7 — الـ Ship: يوم التسليم

specifyextensionaddstatus--fromhttps://github.com/KhawarHabibKhan/spec-kit-status/archive/refs/heads/main.zip
specifyextensionaddci-guard--fromhttps://github.com/Quratulain-bilal/spec-kit-ci-guard/archive/refs/heads/main.zip
specifyextensionaddpr-bridge--fromhttps://github.com/Quratulain-bilal/spec-kit-pr-bridge-/archive/refs/heads/main.zip
specifyextensionaddship--fromhttps://github.com/arunt14/spec-kit-ship/archive/refs/heads/main.zip
specifyextensionaddretrospective--fromhttps://github.com/emi-dm/spec-kit-retrospective/archive/refs/heads/main.zip
specifyextensionaddmemory-md--fromhttps://github.com/DyanGalih/spec-kit-memory-hub/archive/refs/heads/main.zip

ملحوظة: متفوّتش /speckit-retrospective — بيطلّعلك "درجة adherence": التزمت قد إيه بالـ workflow في الـ feature دي؟ والدروس بتتحفظ بـ /speckit-memory-hub في .specify/memory/ — يعني الـ feature الجاية بتبدأ أذكى من اللي قبلها.

Phase 8 — الـ Maintenance: الشغل مبيخلصش يوم الـ Ship

العمارة اتسلمت — بس العمارات محتاجة صيانة. والـ codebase الحي بيتحرك: bugs بتظهر، requirements بتتغير، والـ specs ممكن تحيد عن الكود مع الوقت (drift):

specifyextensionadddoctor--fromhttps://github.com/KhawarHabibKhan/spec-kit-doctor/archive/refs/heads/main.zip
specifyextensionaddsync--fromhttps://github.com/bgervin/spec-kit-sync/archive/refs/heads/main.zip
specifyextensionaddbugfix--fromhttps://github.com/Quratulain-bilal/spec-kit-bugfix/archive/refs/heads/main.zip
specifyextensionadditerate--fromhttps://github.com/imviancagrace/spec-kit-iterate/archive/refs/heads/main.zip
specifyextensionaddrefine--fromhttps://github.com/Quratulain-bilal/spec-kit-refine/archive/refs/heads/main.zip

كده خلصنا الرحلة كاملة: من ورشة فاضية لـ feature شغالة في production ومعاها specs حية بتتصان. خد نفس، لأن دلوقتي هندخل في العدة الإضافية.

Section4. الـ Extension Catalog — العِدّة الإضافية

فاكر لما قلتلك في الأول إن Spec Kit بييجي "بعدّة أساسية" و"عدّة إضافية"؟ وصلنا للعدّة الإضافية.

المفهوم بسيط: الـ core بتاع Spec Kit فيه 19 أمر بس — دول الأساسيات. أي حاجة تانية بتيجي كـ extension بتثبّتها لما تحتاجها. زي ما الموبايل بييجي بتطبيقات أساسية وانت بتنزّل الباقي من الـ store.

بص على الخريطة دي كويس. تقوللي "ده كتير أوي يا هندسة"؟ أقولك — بالظبط كده، وده المقصود. الـ beauty إنك مش لازم تثبّتهم كلهم. اختار اللي بتحتاجه حسب الـ workflow بتاعك. بس خلّي بالك من حاجة مهمة: الـ extensions دي مش optional nice-to-have — كل واحدة بتحل مشكلة حقيقية اتوجعنا منها في الـ SDD lifecycle.

خلّيني أقولك ليه محتاج كل واحدة — مش بس "بتعمل إيه":

• Verify Tasks → عارف لما الـ AI يقولك "خلّصت التاسكات كلها ✅" وانت تفتح الكود تلاقي نص الحاجات مش موجودة؟ دي اسمها phantom completions — والـ extension ده بيكشفها واحدة واحدة.
• Review → مش مجرد linting. ده 6 agents بيراجعوا الكود من 6 زوايا مختلفة: quality وtypes وlogic وغيرهم.
• Ripple → أي تعديل — مهما كان صغير — ليه side effects في 9 domains. من غير الـ extension ده هتكتشف الكسر بعد فوات الأوان، غالباً في production.
• Red Team → ده بيهاجم الـ spec نفسها قبل ما تتـ implement. ليه؟ لأن المشكلة اللي بتتحل وهي لسه على الورق أرخص 100 مرة من اللي بتتحل في الكود.

Master Extension Table

دي أهم 10 extensions — اتفرج على عمود الـ Value Proposition بالذات:

والتثبيت دايماً بنفس الشكل:

specifyextensionadd<name>--from<zip-url>

ملحوظة: لاحظ الـ --from دي — هنرجعلها في قسم القواعد المهمة، لأنها بتلخبط ناس كتير.

Section5. Greenfield vs Brownfield — تعالى نمشيها مرتين

نظري كفاية — تعالى نمشي الرحلة مرتين كاملتين: مرة بمشروع جديد من الصفر (Greenfield — أرض خضرا مفيهاش حاجة)، ومرة بمشروع قديم شغال عليه ناس قبلك (Brownfield — أرض بنى عليها ناس قبلك وسابولك الميراث).

5.1 Greenfield (مشروع جديد)

ده السيناريو السهل — الورشة فاضية وانت هتبني من أول طوبة. بص على التسلسل كله مرة واحدة، وخد بالك من علامات (✅ ضروري) و(اختياري):

[Phase 0] specify init . --integration claude
specifycheck
specifyextensionaddreview,security-review,qa,ship,...
[Phase 1] /speckit.constitution "Security-first. TDD. TTFB < 200ms."
/speckit-red-team(اختياري—هاجمالـconstitution)
[Phase 2] /speckit.specify "Feature description"
/speckit.clarify(إزالةالغموض)
/speckit-critique(اختياري—dual-lensreview)
/speckit.checklist(اختياري—qualityvalidation)
[Phase 3] /speckit.plan "Vite + SQLite + vanilla JS"
/speckit-blueprint(اختياري—خريطةالكودقبلالتنفيذ)
/speckit-version-guard(اختياري—تحققمنالـdependencies)
[Phase 4] /speckit.tasks
/speckit.analyze(✅ضروريقبلimplementدايماً)
/speckit.taskstoissues(اختياري—ربطبـGitHubIssues)
[Phase 5] /speckit.implement
/speckit-checkpoint(اختياري—commitsمنظّمة)
[Phase 6] /speckit-verify            (✅ ضروري)
/speckit-verify-tasks(✅ضروري)
/speckit-review(اختياري—codereview)
/speckit-security-review(اختياري—securityaudit)
/speckit-qa(اختياري—acceptancetesting)
[Phase 7] /speckit-status
/speckit-ship(اختياري—releasepipeline)

شايف؟ الـ spine بتاع الرحلة هو نفس الستة اللي حفظناهم: constitution → specify → plan → tasks → implement → verify. الباقي كله إضافات بتقوّي النقط اللي تهمك.

5.2 Brownfield (مشروع موجود)

هنا القصة مختلفة. انت واقف قدام codebase عمره 3 سنين، اللي كتبوه مشيوا من الشركة، والـ documentation آخر تحديث ليها كان "قريباً". أول غلطة ممكن تعملها؟ إنك تبدأ تكتب specs لحاجات جديدة قبل ما تفهم الموجود.

عشان كده الـ Brownfield workflow بيبدأ بخطوة عكسية: بدل ما تكتب spec وتطلّع منها كود، بتاخد الكود الموجود وتطلّع منه specs — دي عملية الـ reverse-engineering اللي بيعملها /speckit-brownfield:

[Phase 0] specify init . --integration copilot
specifyextensionaddbrownfield,repoindex,verify,reconcile,...
[Phase 1] /speckit-repoindex          (افهم الكود الموجود)
/speckit-brownfield(عملreverse-engineeringللـmodules)
/speckit.constitution(حدّدقواعدالمشروع)
[Phase 2] /speckit-brownfield "Reverse-engineer the auth module"
/speckit-brownfield"Reverse-engineer the API layer"
...(كرّرلكلmoduleرئيسي)
[Phase 3] /speckit.plan               (لو بتضيف feature جديدة)
[Phase 4] /speckit.tasks + /speckit.analyze
[Phase 5] /speckit.implement
[Phase 6] /speckit-review
/speckit-security-review
/speckit-spectest(اعملtestsمنالـspecs)
/speckit-verify
/speckit-reconcile(تحققمنالـconsistency)
[Phase 7] /speckit-checkpoint
/speckit-ship
[Phase 8] /speckit-bugfix             (لأي bug جديد)
/speckit-ripple(بعدأيتعديل)
/speckit-verify(تحققإنالتعديلماكسرشحاجة)

5.3 القاعدة الدهبية للـ Brownfield

دي احفظها زي اسمك. أي تعديل في كود موجود — أي تعديل — يمشي على السبع خطوات دول:

قبل ما تعدّل أي كود موجود:
  1. /speckit-status          ← اعرف فين حاجاتك دلوقتي
  2. اقرأ spec.md للـ module  ← افهم الـ contract
  3. عدّل الكود
  4. /speckit-verify          ← هل كسرت الـ contract؟
  5. /speckit-ripple          ← أي side effects؟
  6. /speckit-spectest        ← الـ tests لسه aligned؟
  7. /speckit-reconcile       ← consistency check أخير

نصيحة: لو هتاخد من القسم ده حاجة واحدة بس، خد القاعدة دي. أغلب الكوارث في المشاريع القديمة سببها خطوة 2 اللي محدش بيعملها — بيعدّلوا كود من غير ما يفهموا الـ contract بتاعه.

Section6. طب ليه Spec Kit تحديداً؟ — المقارنة مع السوق

سؤال منطقي هتسأله: "هو Spec Kit ده الوحيد؟ مفيش غيره؟" في غيره طبعاً — والاختيار بينهم بيعتمد على حاجة اسمها الـ Maturity Level.

تقوللي "كل الـ tools دي بتعمل نفس الحاجة"؟ قولك لأ — كل واحدة واقفة على درجة مختلفة من السلم:

SDD Maturity Hierarchy

والفرق بين المستويات دي مش theoretical — ده فرق عملي هتحس بيه:

• في Level 1، الـ spec بيتكتب في الأول وبعدين... بينتسي. زي كراسة الشروط اللي بتترمي في الدرج بعد ما العمارة تخلص.
• في Level 2، الـ spec بيفضل living document — بيتحدث مع الكود ويفضل contract ساري. وهنا Spec Kit بالـ extensions بتاعته (sync وreconcile وverify) بيلعب.
• في Level 3، القصة تتقلب: الـ spec هو الأصل والكود مجرد مشتق بيتولّد منه. ده مستقبل لسه بيتشكّل — وTessl هي اللي بتجرّبه دلوقتي.

SDD Tool Comparison

الخلاصة؟ لو عايز أداة open source متجرّبة في المعارك وبتكبر معاك من Level 1 لـ Level 2 — Spec Kit هو الاختيار الأوسع انتشاراً والأنضج ecosystem.

Section7. الـ Bug Workflow — سياسة الـ "No-Shortcut"

دلوقتي أصعب امتحان لأي methodology: إيه اللي بيحصل لما bug يظهر في production والدنيا ولعانة؟

هنا أغلب الفرق بترمي الـ methodology من الشباك: "مفيش وقت لـ specs، هنعمل hotfix سريع وخلاص". وده بالظبط أول خيط في فتلة الـ drift اللي اتكلمنا عنها في الأول — أول "استثناء صغير" بيجيب وراه عشرة.

Spec Kit واخد موقف صارم من ده اسمه الـ No-Shortcut Policy، وعامل للـ bugs مسار خاص بيها:

الـ Bug Extension (namespaced تحت speckit.bug.*) بيسجّل كل حاجة في audit trail منظّم جوه .specify/bugs/<slug>/ — يعني بعد 6 شهور تقدر ترجع تشوف الـ bug ده كان إيه، اتصلح إزاي، وليه:

يعني التسلسل دايماً: assess (افهم الانحراف عن الـ spec) → fix (صلّح من غير ما تكسر الـ compliance) → test (اتأكد إن السيناريو اللي وقع مش هيقع تاني).

والقاعدة الأساسية: الـ bug fixes ممنوع تعدّي من غير الـ spec workflow. حتى fix السطر الواحد بيحتاج retroactive specification pass.

وهنا انت هتقولي: "يا باشمهندس ده bug سطر واحد، ليه لازم أعمله spec؟!"

أقولك ليه. لأن الـ bug السطر الواحد ده عرض مش مرض — ممكن يكون مؤشر على مشكلة أكبر في الـ spec نفسها. لو الـ spec كانت سليمة، السطر ده كان غلط ليه أصلاً؟ والـ bug workflow مش بيبطّأك — بيحميك من الـ regressions اللي مش بتشوفها غير لما الـ production يقع الساعة 3 الفجر. الـ "simple change" اللي من غير spec هو بالظبط اللي بيعمل الـ "ripples" اللي محدش حسبها.

Section8. الجدول الكامل — الـ 66 أمر في مكان واحد

خد نفس. إحنا لفّينا الرحلة كلها، ودلوقتي جه وقت الخريطة الشاملة — كل أمر في Spec Kit في جدول واحد تقدر ترجعله في أي وقت.

إزاي تقرا الجدول:

• ❌/✅ → ❌ يعني built-in جاي مع Spec Kit نفسه، ✅ يعني extension لازم تثبّته الأول
• 🖥️/🤖 → 🖥️ يعني أمر terminal (CLI)، 🤖 يعني slash command جوه الـ AI agent
• Project → 🟢 New للمشاريع الجديدة، 🟤 Existing للقديمة، وBoth للاتنين

ملحوظة: لاحظ حاجة مهمة في الجدول: أول 19 أمر بس هما الـ built-in (❌). الـ 47 الباقيين كلهم extensions من الـ community — وده اللي بيخلي الـ ecosystem ده حي وبيكبر كل يوم.

Section9. دليل القرار السريع — "أنا فين وأعمل إيه؟"

تاه منك الطريق في نص الشغل؟ عادي، بيحصل. الجدول ده بيجاوب على سؤال واحد بس: "أنا واقف هنا... أبدأ منين؟"

Section10. قواعد مهمة — الحاجات اللي بتفرق بين مبتدئ ومحترف

قبل ما نقفل، في شوية قواعد لو مشيت عليها هتوفّر على نفسك أسابيع من التخبط. كل قاعدة جنبها ليه — لأني مش عايزك تحفظ، عايزك تفهم:

تحذير: القاعدة الأولى دي أكتر غلطة بيقع فيها الناس الجداد. أول ما بيمسكوا /speckit.specify بيكتبوا "React app with Express backend..." — لأ. الـ specify للـ إيه وليه، والـ plan للـ إزاي. لو خلطتهم، رجعت تاني لنفس عادات الـ vibe coding بس بخطوات أكتر.

Section11. الخلاصة: مستقبل الـ Intent-Based Development

وصلنا لآخر الرحلة. فاكر أحمد اللي قابلناه في أول المقال — اللي الـ demo بتاعه اتلغبط قدام العميل؟ تعالى نلخّص إيه اللي كان هيتغير لو كان ماشي بالـ SDD من الأول — ودي خلاصة كل اللي اتعلمناه:

أولاً: الـ specification هي الـ fundamental unit of programming — مش الكود. الكود ده secondary artifact مُشتق من intent متـ validate. أحمد كان بيراكم prompts فوق بعضها من غير ذاكرة — الـ spec هي الذاكرة دي.

ثانياً: الـ structure مش luxury — ده الـ difference بين team بيـ drift وteam بيـ stay on course. الـ vibe coding سريع بس مش sustainable. والـ SDD مش بطيء — ده disciplined. الفرق بين الاتنين بيظهر مش في اليوم الأول... في الشهر التالت.

ثالثاً: الـ AI agent مش المشكلة — الـ vague intent هو المشكلة. لما الـ intent يكون محدد ومُلتزم بيه، حتى mid-tier model بيتفوق على frontier model شغال في vibe coding mode. يعني قبل ما تدفع أكتر في موديل أقوى، جرّب تدفع وقت أكتر في spec أوضح.

كل ما الـ AI بيتطور، الـ specification هتبقى هي وحدة البرمجة الأساسية. وSpec Kit بيديك العدّة اللي بتدير الـ transition ده — مش بكرة، دلوقتي.

يلا نبدأ — أول SDD project ليك

قوم افتح الترمينال دلوقتي — مش بكرة — وامشي على الستة دول:

1. Init: specify init .
2. Constitution: /speckit.constitution
3. Specify: /speckit.specify
4. Plan: /speckit.plan
5. Tasks: /speckit.tasks
6. Implement: /speckit.implement

وقبل ما تمشي، سيبني أسيبك مع السؤال اللي المقال كله كان بيبني ليه: الـ vibe coding سريع وبسيط — بس هل السرعة من غير structure تستاهل الـ drift اللي جاي بعدها؟ ولا الوقت جه إنك تنقل الـ source of truth من الكود للـ spec؟

الإجابة عندك. والعدّة قدامك. 🚀

• GitHub Spec Kit Repository
• Spec Kit Documentation
• Integrations Reference
• Spec Kit Cheatsheet — الـ reference اللي تعلّقه جنب الشاشة

المقالة دي جزء من سلسلة Agentic AI على Learn-in-Depth Journal.