speccrew 0.1.0

package/README.ar.md

@@ -0,0 +1,318 @@
+# SpecCrew - إطار عمل هندسة البرمجيات المدعوم بالذكاء الاصطناعي
+
+<p align="center">
+  <a href="./README.md">中文</a> |
+  <a href="./README.en.md">English</a> |
+  <a href="./README.ar.md">العربية</a> |
+  <a href="./README.es.md">Español</a>
+</p>
+
+> فريق تطوير افتراضي بالذكاء الاصطناعي يتيح التنفيذ الهندسي السريع لأي مشروع برمجي
+
+## ما هو SpecCrew؟
+
+SpecCrew هو إطار عمل مدمج لفريق تطوير افتراضي بالذكاء الاصطناعي. يحول سير عمل هندسة البرمجيات المهنية (PRD → Feature Design → System Design → Dev → Test) إلى سير عمل وكلاء (Agent) قابلة لإعادة الاستخدام، مما يساعد فرق التطوير على تحقيق التطوير المدفوع بالمواصفات (SDD)، ومناسب بشكل خاص للمشاريع الحالية.
+
+من خلال دمج الوكلاء والمهارات في المشاريع الحالية، يمكن للفرق تهيئة أنظمة توثيق المشاريع وفريق البرمجيات الافتراضي بسرعة، وتنفيذ الميزات الجديدة والتعديلات باتباع سير عمل الهندسة القياسية.
+
+---
+
+## 8 مشاكل أساسية تم حلها
+
+### 1. الذكاء الاصطناعي يتجاهل توثيق المشروع الحالي (فجوة المعرفة)
+**المشكلة**: تعتمد أساليب SDD أو Vibe Coding الحالية على الذكاء الاصطناعي لتلخيص المشاريع في الوقت الفعلي، مما يسهل إغفال السياق الحرج ويسبب انحراف نتائج التطوير عن التوقعات.
+
+**الحل**: يعمل مستودع `knowledge/` كـ"مصدر الحقيقة الوحيد" للمشروع، حيث يتراكم تصميم الهندسة المعمارية والوحدات الوظيفية وعمليات الأعمال لضمان بقاء المتطلبات على المسار الصحيح من المصدر.
+
+### 2. الانتقال المباشر من PRD إلى التوثيق التقني (حذف المحتوى)
+**المشكلة**: الانتقال المباشر من PRD إلى التصميم التفصيلي يسهل إغفال تفاصيل المتطلبات، مما يتسبب في انحراف الميزات المنفذة عن المتطلبات.
+
+**الحل**: إدخال مرحلة **وثيقة الحل (Solution)**، مع التركيز فقط على هيكل المتطلبات دون التفاصيل التقنية:
+- ما هي الصفحات والمكونات المضمنة
+- تدفقات عمليات الصفحات
+- منطق المعالجة الخلفية
+- هيكل تخزين البيانات
+
+يحتاج التطوير فقط إلى "ملء اللحم" بناءً على المكدس التقني المحدد، مما يضمن نمو الميزات "بالقرب من العظم (المتطلبات)."
+
+### 3. نطاق البحث غير المؤكد للوكيل (عدم اليقين)
+**المشكلة**: في المشاريع المعقدة، يؤدي البحث الواسع للذكاء الاصطناعي في الكود والمستندات إلى نتائج غير مؤكدة، مما يجعل ضمان الاتساق صعباً.
+
+**الحل**: هياكل دليل واضحة وقوالب للمستندات، مصممة بناءً على احتياجات كل وكيل، تنفذ **الإفصاح التدريجي والتحميل عند الطلب** لضمان الحتمية.
+
+### 4. نقص الخطوات والمهام (انقطاع العملية)
+**المشكلة**: نقص التغطية الكاملة لسير عمل الهندسة يسهل إغفال الخطوات الحرجة، مما يجعل ضمان الجودة صعباً.
+
+**الحل**: تغطية دورة حياة هندسة البرمجيات الكاملة:
+```
+PRD (المتطلبات) → Solution (التخطيط) → API Contract
+    → Design → Dev (التطوير) → Test (الاختبار)
+```
+- مخرجات كل مرحلة هي مدخلات المرحلة التالية
+- كل خطوة تتطلب تأكيداً بشرياً قبل المتابعة
+- جميع تنفيذات الوكلاء لها قوائم مهام مع فحص ذاتي بعد الانتهاء
+
+### 5. كفاءة التعاون المنخفضة في الفريق (جزر المعرفة)
+**المشكلة**: من الصعب مشاركة خبرة البرمجة بالذكاء الاصطناعي عبر الفرق، مما يؤدي إلى أخطاء متكررة.
+
+**الحل**: جميع الوكلاء والمهارات والمستندات ذات الصلة تخضع للتحكم في الإصدار مع الكود المصدري:
+- تحسين شخص واحد، يشاركه الفريق
+- تراكم المعرفة في قاعدة الكود
+- تحسين كفاءة التعاون في الفريق
+
+### 7. سياق الوكيل الواحد طويل جداً (اختناق الأداء)
+**المشكلة**: المهام المعقدة الكبيرة تتجاوز نوافذ سياق الوكيل الواحد، مما يسبب انحرافاً في الفهم وانخفاضاً في جودة المخرجات.
+
+**الحل**: **آلية الإرسال التلقائي للوكلاء الفرعيين**:
+- يتم تحديد المهام المعقدة تلقائياً وتقسيمها إلى مهام فرعية
+- كل مهمة فرعية تنفذها وكيل فرعي مستقل بسياق معزول
+- يقوم الوكيل الأب بالتنسيق والتجميع لضمان الاتساق العام
+- يتجنب تضخم سياق الوكيل الواحد، مما يضمن جودة المخرجات
+
+### 8. فوضى تكرار المتطلبات (صعوبة الإدارة)
+**المشكلة**: المتطلبات المتعددة المختلطة في نفس الفرع تؤثر على بعضها البعض، مما يجعل التتبع والاسترجاع صعباً.
+
+**الحل**: **كل متطلب كمشروع مستقل**:
+- كل متطلب ينشئ دليل تكرار مستقل `iterations/iXXX-[اسم-المتطلب]/`
+- عزل كامل: المستندات والتصميم والكود والاختبارات تدار بشكل مستقل
+- تكرار سريع: تسليم بحبوب صغيرة، تحقق سريع، نشر سريع
+- أرشفة مرنة: بعد الانتهاء، الأرشفة إلى `archive/` مع إمكانية تتبع تاريخي واضح
+
+### 6. تأخر تحديث المستندات (تحلل المعرفة)
+**المشكلة**: تصبح المستندات قديمة مع تطور المشاريع، مما يتسبب في عمل الذكاء الاصطناعي بمعلومات غير صحيحة.
+
+**الحل**: الوكلاء لديهم قدرات تحديث المستندات التلقائي، مما يزامن تغييرات المشروع في الوقت الفعلي للحفاظ على دقة قاعدة المعرفة.
+
+---
+
+## سير العمل الأساسي
+
+```mermaid
+graph LR
+    A[PRD<br/>المتطلبات] --> B[Solution<br/>التخطيط التقني]
+    B --> C[API Contract<br/>عقد الواجهة]
+    C --> D[Design<br/>التصميم التفصيلي]
+    D --> E[Dev<br/>التنفيذ]
+    E --> F[Test<br/>الاختبار]
+    F --> G[Archive<br/>الأرشفة]
+    
+    H[Knowledge<br/>المستودع] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### أوصاف المراحل
+
+| المرحلة | الوكيل | المدخلات | المخرجات | التأكيد البشري |
+|---------|--------|----------|----------|---------------|
+| PRD | PM | متطلبات المستخدم | وثيقة متطلبات المنتج | ✅ مطلوب |
+| Solution | Planner | PRD | الحل التقني + عقد API | ✅ مطلوب |
+| Design | Designer | Solution | مستندات التصميم الأمامي/الخلفي | ✅ مطلوب |
+| Dev | Dev | Design | الكود + سجلات المهام | ✅ مطلوب |
+| Test | Test | مخرجات Dev + معايير قبول PRD | تقرير الاختبار | ✅ مطلوب |
+
+---
+
+## المقارنة مع الحلول الموجودة
+
+| البُعد | Vibe Coding | Ralph Loop | **SpecCrew** |
+|--------|-------------|------------|-------------|
+| الاعتماد على المستندات | يتجاهل المستندات الموجودة | يعتمد على AGENTS.md | **قاعدة معرفة منظمة** |
+| نقل المتطلبات | ترميز مباشر | PRD → Code | **PRD → Feature Design → System Design → Code** |
+| المشاركة البشرية | الحد الأدنى | عند البدء | **في كل مرحلة** |
+| اكتمال العملية | ضعيف | متوسط | **سير عمل هندسي كامل** |
+| التعاون في الفريق | صعب المشاركة | كفاءة شخصية | **مشاركة المعرفة في الفريق** |
+| إدارة السياق | مثيل واحد | حلقة مثيل واحد | **إرسال تلقائي للوكلاء الفرعيين** |
+| إدارة التكرار | مختلط | قائمة المهام | **المتطلب كمشروع، تكرار مستقل** |
+| الحتمية | منخفضة | متوسطة | **عالية (الإفصاح التدريجي)** |
+
+---
+
+## البدء السريع
+
+### 1. تثبيت SpecCrew
+
+**الطريقة 1: سكريبت التثبيت بنقرة واحدة (موصى به، Qoder IDE فقط)**
+
+```bash
+# macOS / Linux / WSL - التثبيت من GitHub
+curl -fsSL https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/install-qoder.sh | bash
+
+# macOS / Linux / WSL - التثبيت من Gitee (مرآة الصين)
+curl -fsSL https://gitee.com/amutek/speccrew/raw/main/scripts/install-qoder.sh | bash
+```
+
+```powershell
+# Windows - التثبيت من GitHub
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/install-qoder.ps1").Content
+
+# Windows - التثبيت من Gitee (مرآة الصين)
+Invoke-Expression (Invoke-WebRequest -Uri "https://gitee.com/amutek/speccrew/raw/main/scripts/install-qoder.ps1").Content
+```
+
+> **ملاحظة**: سكريبت التثبيت بنقرة واحدة يدعم حالياً Qoder IDE فقط. للـ IDEs الأخرى (VS Code, Cursor, إلخ)، يرجى استخدام طريقة النسخ اليدوي أدناه.
+
+**الطريقة 2: النسخ اليدوي (عالمي لجميع IDEs)**
+
+```bash
+# استنساخ المستودع والنسخ إلى مشروع موجود
+git clone https://github.com/charlesmu99/SpecCrew.git
+# أو: git clone https://gitee.com/amutek/SpecCrew.git
+
+# نسخ إلى المشروع الهدف (تعديل حسب دليل تكوين IDE الخاص بك)
+cp -r SpecCrew/.speccrew /path/to/your-project/
+cp -r SpecCrew/SpecCrew-workspace /path/to/your-project/
+
+# لـ Qoder IDE، انسخ أيضًا إلى دليل .qoder/
+cp -r SpecCrew/.speccrew/agents/* /path/to/your-project/.qoder/agents/
+cp -r SpecCrew/.speccrew/skills/* /path/to/your-project/.qoder/skills/
+```
+
+### 2. تهيئة المشروع
+
+```bash
+# تشغيل مهارة التهيئة لإنشاء قاعدة المعرفة وهيكل المشروع تلقائياً
+# يتم تنفيذها تلقائياً بواسطة مهارة SpecCrew-project-init
+```
+
+### 3. بدء سير عمل التطوير
+
+```bash
+# 1. إنشاء PRD
+# 2. إنشاء Solution
+# 3. تأكيد عقد API
+# 4. التصميم التفصيلي
+# 5. تنفيذ التطوير
+# 6. الاختبار
+```
+
+### 4. إلغاء تثبيت SpecCrew
+
+**الطريقة 1: سكريبت إلغاء التثبيت بنقرة واحدة (موصى به، Qoder IDE فقط)**
+
+```bash
+# macOS / Linux / WSL - إلغاء التثبيت من GitHub
+curl -fsSL https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/uninstall-qoder.sh | bash
+
+# macOS / Linux / WSL - إلغاء التثبيت من Gitee (مرآة الصين)
+curl -fsSL https://gitee.com/amutek/speccrew/raw/main/scripts/uninstall-qoder.sh | bash
+```
+
+```powershell
+# Windows - إلغاء التثبيت من GitHub
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/uninstall-qoder.ps1").Content
+
+# Windows - إلغاء التثبيت من Gitee (مرآة الصين)
+Invoke-Expression (Invoke-WebRequest -Uri "https://gitee.com/amutek/speccrew/raw/main/scripts/uninstall-qoder.ps1").Content
+```
+
+> **ملاحظة**: سكريبت إلغاء التثبيت بنقرة واحدة يدعم حالياً Qoder IDE فقط.
+
+**الطريقة 2: إلغاء التثبيت اليدوي (عالمي لجميع IDEs)**
+
+```bash
+# حذف دليل SpecCrew-workspace
+rm -rf SpecCrew-workspace/
+
+# حذف الملفات ببادئة SpecCrew- في .speccrew/ (الحفاظ على المحتوى المخصص)
+rm -rf .speccrew/agents/SpecCrew-*.md
+rm -rf .speccrew/skills/SpecCrew-*/
+
+# لـ Qoder IDE، نظف أيضًا دليل .qoder/
+rm -rf .qoder/agents/SpecCrew-*.md
+rm -rf .qoder/skills/SpecCrew-*/
+```
+
+> **ملاحظة**: سيؤدي إلغاء التثبيت إلى الحفاظ على ملفات المصدر والمحتوى المخصص في `.speccrew/`. لإزالة تكوينات IDE بالكامل، احذف دليل التكوين المقابل يدوياً (مثل `.qoder/`).
+
+---
+
+## هيكل الدليل
+
+```
+your-project/
+├── .speccrew/                       # ملفات مصدر SpecCrew (قابلة للتحكم في الإصدار)
+├── .qoder/                          # تكوين Qoder IDE (وقت التشغيل)
+│   ├── agents/                      # 6 وكلاء الأدوار
+│   └── skills/                      # 16 مهارة
+│
+└── SpecCrew-workspace/              # مساحة العمل (يتم إنشاؤها أثناء التهيئة)
+    ├── docs/                        # المستندات الإدارية
+    │   ├── rules/                   # تكوينات القواعد
+    │   └── solutions/               # مستندات الحلول
+    │       └── agent-knowledge-map.md
+    │
+    ├── iterations/                  # مشاريع التكرار (يتم إنشاؤها ديناميكياً)
+    │   └── {رقم}-{نوع}-{اسم}/       # مثال: 001-feature-order
+    │       ├── 00.docs/             # المتطلبات الأصلية
+    │       ├── 01.product-requirement/ # متطلبات المنتج
+    │       ├── 02.feature-design/   # تصميم الميزات
+    │       ├── 03.system-design/    # تصميم النظام
+    │       ├── 04.development/      # مرحلة التطوير
+    │       ├── 05.test/             # مرحلة الاختبار
+    │       └── 06.delivery/         # مرحلة التسليم
+    │
+    ├── iteration-archives/          # أرشيف التكرار
+    │   └── {رقم}-{نوع}-{اسم}-{تاريخ}/
+    │
+    └── knowledges/                  # قاعدة المعرفة
+        ├── base/                    # البيانات الوصفية الأساسية
+        │   ├── diagnosis-reports/   # تقارير التشخيص
+        │   ├── sync-state/          # حالة المزامنة
+        │   └── tech-debts/          # الديون التقنية
+        │
+        ├── bizs/                    # المعرفة التجارية
+        │   └── {نوع-المنصة}/
+        │       └── {اسم-الوحدة}/
+        │
+        └── techs/                   # المعرفة التقنية
+            └── {معرف-المنصة}/
+```
+
+---
+
+## المبادئ التصميمية الأساسية
+
+1. **المدفوع بالمواصفات**: كتابة المواصفات أولاً، ثم السماح للكود بال"نمو" منها
+2. **الإفصاح التدريجي**: الوكلاء يبدأون من نقاط دخول دنيا، تحميل المعلومات عند الطلب
+3. **التأكيد البشري**: مخرجات كل مرحلة تتطلب تأكيداً بشرياً لمنع انحراف الذكاء الاصطناعي
+4. **عزل السياق**: المهام الكبيرة مقسمة إلى مهام فرعية صغيرة معزولة السياق
+5. **التعاون الوكيل الفرعي**: المهام المعقدة ترسل تلقائياً للوكلاء الفرعيين لتجنب تضخم سياق الوكيل الواحد
+6. **التكرار السريع**: كل متطلب كمشروع مستقل للتسليم السريع والتحقق
+7. **مشاركة المعرفة**: جميع التكوينات تخضع للتحكم في الإصدار مع الكود المصدري
+
+---
+
+## حالات الاستخدام
+
+### ✅ موصى به لـ
+- المشاريع المتوسطة إلى الكبيرة التي تتطلب سير عمل موحد
+- تطوير البرمجيات التعاوني للفرق
+- تحويل الهندسة للمشاريع القديمة
+- المنتجات التي تتطلب صيانة طويلة الأجل
+
+### ❌ غير مناسب لـ
+- التحقق السريع من النماذج الأولية الشخصية
+- المشاريع الاستكشافية بمتطلبات غير مؤكدة للغاية
+- البرامج النصية أو الأدوات لمرة واحدة
+
+---
+
+## مزيد من المعلومات
+
+- **خريطة معرفة الوكيل**: [SpecCrew-workspace/docs/agent-knowledge-map.md](./SpecCrew-workspace/docs/agent-knowledge-map.md)
+- **GitHub**: https://github.com/charlesmu99/SpecCrew
+- **Gitee**: https://gitee.com/amutek/SpecCrew
+- **Qoder IDE**: https://qoder.com/
+
+---
+
+> **SpecCrew لا يهدف إلى استبدال المطورين، بل إلى أتمتة الأجزاء المملة حتى يمكن للفرق التركيز على عمل أكثر قيمة.**
+
+---
+
+

package/README.en.md

@@ -0,0 +1,318 @@
+# SpecCrew - AI-Driven Software Engineering Framework
+
+<p align="center">
+  <a href="./README.md">中文</a> |
+  <a href="./README.en.md">English</a> |
+  <a href="./README.ar.md">العربية</a> |
+  <a href="./README.es.md">Español</a>
+</p>
+
+> A virtual AI development team that enables rapid engineering implementation for any software project
+
+## What is SpecCrew?
+
+SpecCrew is an embedded virtual AI development team framework. It transforms professional software engineering workflows (PRD → Feature Design → System Design → Dev → Test) into reusable Agent workflows, helping development teams achieve Specification-Driven Development (SDD), especially suitable for existing projects.
+
+By integrating Agents and Skills into existing projects, teams can quickly initialize project documentation systems and virtual software teams, implementing new features and modifications following standard engineering workflows.
+
+---
+
+## 8 Core Problems Solved
+
+### 1. AI Ignores Existing Project Documentation (Knowledge Gap)
+**Problem**: Existing SDD or Vibe Coding methods rely on AI to summarize projects in real-time, easily missing critical context and causing development results to deviate from expectations.
+
+**Solution**: The `knowledge/` repository serves as the project's "single source of truth," accumulating architecture design, functional modules, and business processes to ensure requirements stay on track from the source.
+
+### 2. Direct PRD-to-Technical Documentation (Content Omission)
+**Problem**: Jumping directly from PRD to detailed design easily misses requirement details, causing implemented features to deviate from requirements.
+
+**Solution**: Introduce the **Solution document** phase, focusing only on the requirement skeleton without technical details:
+- What pages and components are included
+- Page operation flows
+- Backend processing logic
+- Data storage structure
+
+Development only needs to "fill in the flesh" based on the specific tech stack, ensuring features grow "close to the bone (requirements)."
+
+### 3. Uncertain Agent Search Scope (Uncertainty)
+**Problem**: In complex projects, AI's broad search of code and documents yields uncertain results, making consistency difficult to guarantee.
+
+**Solution**: Clear document directory structures and templates, designed based on each Agent's needs, implementing **progressive disclosure and on-demand loading** to ensure determinism.
+
+### 4. Missing Steps and Tasks (Process Breakdown)
+**Problem**: Lack of complete engineering process coverage easily misses critical steps, making quality difficult to guarantee.
+
+**Solution**: Cover the full software engineering lifecycle:
+```
+PRD (Requirements) → Solution (Planning) → API Contract
+    → Design → Dev (Development) → Test (Testing)
+```
+- Each phase's output is the next phase's input
+- Each step requires human confirmation before proceeding
+- All Agent executions have todo lists with self-check after completion
+
+### 5. Low Team Collaboration Efficiency (Knowledge Silos)
+**Problem**: AI programming experience is difficult to share across teams, leading to repeated mistakes.
+
+**Solution**: All Agents, Skills, and related documents are version-controlled with source code:
+- One person's optimization, shared by the team
+- Knowledge accumulated in the codebase
+- Improved team collaboration efficiency
+
+### 7. Single Agent Context Too Long (Performance Bottleneck)
+**Problem**: Large complex tasks exceed single Agent context windows, causing understanding deviation and decreased output quality.
+
+**Solution**: **Sub-Agent Auto-Dispatch Mechanism**:
+- Complex tasks are automatically identified and split into subtasks
+- Each subtask is executed by an independent sub-Agent with isolated context
+- Parent Agent coordinates and aggregates to ensure overall consistency
+- Avoids single Agent context expansion, ensuring output quality
+
+### 8. Requirement Iteration Chaos (Management Difficulty)
+**Problem**: Multiple requirements mixed in the same branch affect each other, making tracking and rollback difficult.
+
+**Solution**: **Each Requirement as an Independent Project**:
+- Each requirement creates an independent iteration directory `iterations/iXXX-[requirement-name]/`
+- Complete isolation: documents, design, code, and tests managed independently
+- Rapid iteration: small granularity delivery, rapid verification, rapid deployment
+- Flexible archiving: after completion, archive to `archive/` with clear historical traceability
+
+### 6. Document Update Lag (Knowledge Decay)
+**Problem**: Documents become outdated as projects evolve, causing AI to work with incorrect information.
+
+**Solution**: Agents have automatic document update capabilities, synchronizing project changes in real-time to keep the knowledge base accurate.
+
+---
+
+## Core Workflow
+
+```mermaid
+graph LR
+    A[PRD<br/>Requirements] --> B[Solution<br/>Technical Planning]
+    B --> C[API Contract<br/>Interface Contract]
+    C --> D[Design<br/>Detailed Design]
+    D --> E[Dev<br/>Implementation]
+    E --> F[Test<br/>Testing]
+    F --> G[Archive<br/>Archiving]
+    
+    H[Knowledge<br/>Repository] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Phase Descriptions
+
+| Phase | Agent | Input | Output | Human Confirmation |
+|-------|-------|-------|--------|-------------------|
+| PRD | PM | User Requirements | Product Requirements Document | ✅ Required |
+| Solution | Planner | PRD | Technical Solution + API Contract | ✅ Required |
+| Design | Designer | Solution | Frontend/Backend Design Documents | ✅ Required |
+| Dev | Dev | Design | Code + Task Records | ✅ Required |
+| Test | Test | Dev Output + PRD Acceptance Criteria | Test Report | ✅ Required |
+
+---
+
+## Comparison with Existing Solutions
+
+| Dimension | Vibe Coding | Ralph Loop | **SpecCrew** |
+|-----------|-------------|------------|-------------|
+| Document Dependency | Ignores existing docs | Relies on AGENTS.md | **Structured Knowledge Base** |
+| Requirement Transfer | Direct coding | PRD → Code | **PRD → Feature Design → System Design → Code** |
+| Human Involvement | Minimal | At startup | **At every phase** |
+| Process Completeness | Weak | Medium | **Complete engineering workflow** |
+| Team Collaboration | Hard to share | Personal efficiency | **Team knowledge sharing** |
+| Context Management | Single instance | Single instance loop | **Sub-Agent auto-dispatch** |
+| Iteration Management | Mixed | Task list | **Requirement as project, independent iteration** |
+| Determinism | Low | Medium | **High (progressive disclosure)** |
+
+---
+
+## Quick Start
+
+### 1. Install SpecCrew
+
+**Method 1: One-click Install Script (Recommended, Qoder IDE only)**
+
+```bash
+# macOS / Linux / WSL - Install from GitHub
+curl -fsSL https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/install-qoder.sh | bash
+
+# macOS / Linux / WSL - Install from Gitee (China Mirror)
+curl -fsSL https://gitee.com/amutek/speccrew/raw/main/scripts/install-qoder.sh | bash
+```
+
+```powershell
+# Windows - Install from GitHub
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/install-qoder.ps1").Content
+
+# Windows - Install from Gitee (China Mirror)
+Invoke-Expression (Invoke-WebRequest -Uri "https://gitee.com/amutek/speccrew/raw/main/scripts/install-qoder.ps1").Content
+```
+
+> **Note**: One-click installation script currently only supports Qoder IDE. For other IDEs (VS Code, Cursor, etc.), please use manual copy method below.
+
+**Method 2: Manual Copy (Universal for all IDEs)**
+
+```bash
+# Clone repository and copy to existing project
+git clone https://github.com/charlesmu99/speccrew.git
+# or: git clone https://gitee.com/amutek/speccrew.git
+
+# Copy to target project (adjust based on your IDE config directory)
+cp -r SpecCrew/.speccrew /path/to/your-project/
+cp -r SpecCrew/SpecCrew-workspace /path/to/your-project/
+
+# For Qoder IDE, also copy to .qoder/ directory
+cp -r SpecCrew/.speccrew/agents/* /path/to/your-project/.qoder/agents/
+cp -r SpecCrew/.speccrew/skills/* /path/to/your-project/.qoder/skills/
+```
+
+### 2. Initialize Project
+
+```bash
+# Run initialization Skill to automatically generate knowledge base and project structure
+# Executed automatically by speccrew-project-init Skill
+```
+
+### 3. Start Development Workflow
+
+```bash
+# 1. Create PRD
+# 2. Generate Solution
+# 3. Confirm API Contract
+# 4. Detailed Design
+# 5. Development Implementation
+# 6. Testing
+```
+
+### 4. Uninstall SpecCrew
+
+**Method 1: One-Click Uninstall Script (Recommended, Qoder IDE only)**
+
+```bash
+# macOS / Linux / WSL - Uninstall from GitHub
+curl -fsSL https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/uninstall-qoder.sh | bash
+
+# macOS / Linux / WSL - Uninstall from Gitee (China Mirror)
+curl -fsSL https://gitee.com/amutek/speccrew/raw/main/scripts/uninstall-qoder.sh | bash
+```
+
+```powershell
+# Windows - Uninstall from GitHub
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/charlesmu99/SpecCrew/main/scripts/uninstall-qoder.ps1").Content
+
+# Windows - Uninstall from Gitee (China Mirror)
+Invoke-Expression (Invoke-WebRequest -Uri "https://gitee.com/amutek/speccrew/raw/main/scripts/uninstall-qoder.ps1").Content
+```
+
+> **Note**: One-click uninstall script currently only supports Qoder IDE.
+
+**Method 2: Manual Uninstall (Universal for all IDEs)**
+
+```bash
+# Remove speccrew-workspace directory
+rm -rf speccrew-workspace/
+
+# Remove SpecCrew-prefixed files in .speccrew/ (preserve custom content)
+rm -rf .speccrew/agents/SpecCrew-*.md
+rm -rf .speccrew/skills/SpecCrew-*/
+
+# For Qoder IDE, also clean up .qoder/ directory
+rm -rf .qoder/agents/SpecCrew-*.md
+rm -rf .qoder/skills/SpecCrew-*/
+```
+
+> **Note**: Uninstallation will preserve source files and custom content in `.speccrew/`. To completely remove IDE configurations, manually delete the corresponding IDE config directory (e.g., `.qoder/`).
+
+---
+
+## Directory Structure
+
+```
+your-project/
+├── .speccrew/                       # SpecCrew source files (version controllable)
+├── .qoder/                          # Qoder IDE configuration (runtime)
+│   ├── agents/                      # 6 role Agents
+│   └── skills/                      # 16 Skills
+│
+└── speccrew-workspace/              # Workspace (generated during initialization)
+    ├── docs/                        # Management documents
+    │   ├── rules/                   # Rule configurations
+    │   └── solutions/               # Solution documents
+    │       └── agent-knowledge-map.md
+    │
+    ├── iterations/                  # Iteration projects (dynamically generated)
+    │   └── {number}-{type}-{name}/  # e.g., 001-feature-order
+    │       ├── 00.docs/             # Original requirements
+    │       ├── 01.product-requirement/ # Product requirements
+    │       ├── 02.feature-design/   # Feature design
+    │       ├── 03.system-design/    # System design
+    │       ├── 04.development/      # Development phase
+    │       ├── 05.test/             # Testing phase
+    │       └── 06.delivery/         # Delivery phase
+    │
+    ├── iteration-archives/          # Iteration archives
+    │   └── {number}-{type}-{name}-{date}/
+    │
+    └── knowledges/                  # Knowledge base
+        ├── base/                    # Base metadata
+        │   ├── diagnosis-reports/   # Diagnosis reports
+        │   ├── sync-state/          # Sync state
+        │   └── tech-debts/          # Technical debts
+        │
+        ├── bizs/                    # Business knowledge
+        │   └── {platform-type}/
+        │       └── {module-name}/
+        │
+        └── techs/                   # Technical knowledge
+            └── {platform-id}/
+```
+
+---
+
+## Core Design Principles
+
+1. **Specification-Driven**: Write specifications first, then let code "grow" from them
+2. **Progressive Disclosure**: Agents start from minimal entry points, loading information on demand
+3. **Human Confirmation**: Each phase's output requires human confirmation to prevent AI deviation
+4. **Context Isolation**: Large tasks are split into small, context-isolated subtasks
+5. **Sub-Agent Collaboration**: Complex tasks automatically dispatch sub-Agents to avoid single Agent context expansion
+6. **Rapid Iteration**: Each requirement as an independent project for rapid delivery and verification
+7. **Knowledge Sharing**: All configurations are version-controlled with source code
+
+---
+
+## Use Cases
+
+### ✅ Recommended For
+- Medium to large projects requiring standardized workflows
+- Team collaboration software development
+- Legacy project engineering transformation
+- Products requiring long-term maintenance
+
+### ❌ Not Suitable For
+- Personal rapid prototype validation
+- Exploratory projects with highly uncertain requirements
+- One-off scripts or tools
+
+---
+
+## More Information
+
+- **Agent Knowledge Map**: [speccrew-workspace/docs/agent-knowledge-map.md](./speccrew-workspace/docs/agent-knowledge-map.md)
+- **GitHub**: https://github.com/charlesmu99/speccrew
+- **Gitee**: https://gitee.com/amutek/speccrew
+- **Qoder IDE**: https://qoder.com/
+
+---
+
+> **SpecCrew is not about replacing developers, but automating the tedious parts so teams can focus on more valuable work.**
+
+---
+
+