speccrew 0.1.1 → 0.1.2

package/README.tr.md

@@ -0,0 +1,239 @@
+# SpecCrew - AI Destekli Yazılım Mühendisliği Çerçevesi
+
+<p align="center">
+  <a href="./README.md">简体中文</a> |
+  <a href="./README.zh-TW.md">繁體中文</a> |
+  <a href="./README.en.md">English</a> |
+  <a href="./README.ko.md">한국어</a> |
+  <a href="./README.de.md">Deutsch</a> |
+  <a href="./README.es.md">Español</a> |
+  <a href="./README.fr.md">Français</a> |
+  <a href="./README.it.md">Italiano</a> |
+  <a href="./README.da.md">Dansk</a> |
+  <a href="./README.ja.md">日本語</a> |
+  <a href="./README.pl.md">Polski</a> |
+  <a href="./README.ru.md">Русский</a> |
+  <a href="./README.bs.md">Bosanski</a> |
+  <a href="./README.ar.md">العربية</a> |
+  <a href="./README.no.md">Norsk</a> |
+  <a href="./README.pt-BR.md">Português (Brasil)</a> |
+  <a href="./README.th.md">ไทย</a> |
+  <a href="./README.tr.md">Türkçe</a> |
+  <a href="./README.uk.md">Українська</a> |
+  <a href="./README.bn.md">বাংলা</a> |
+  <a href="./README.el.md">Ελληνικά</a> |
+  <a href="./README.vi.md">Tiếng Việt</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/v/speccrew.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/dm/speccrew.svg" alt="npm downloads"></a>
+  <a href="https://github.com/charlesmu99/speccrew/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/speccrew.svg" alt="license"></a>
+</p>
+
+> Herhangi bir yazılım projesi için hızlı mühendislik uygulaması sağlayan sanal bir AI geliştirme ekibi
+
+## SpecCrew Nedir?
+
+SpecCrew, gömülü bir sanal AI geliştirme ekibi çerçevesidir. Profesyonel yazılım mühendisliği iş akışlarını (PRD → Feature Design → System Design → Dev → Test) yeniden kullanılabilir Agent iş akışlarına dönüştürerek geliştirme ekiplerinin Specification-Driven Development (SDD) elde etmesine yardımcı olur ve özellikle mevcut projeler için uygundur.
+
+Mevcut projelere Agent'ları ve Skill'leri entegre ederek, ekipler proje dokümantasyon sistemlerini ve sanal yazılım ekiplerini hızla başlatabilir ve standart mühendislik iş akışlarını takip ederek yeni özellikleri ve modifikasyonları adım adım uygulayabilir.
+
+---
+
+## Çözülen 8 Temel Sorun
+
+### 1. AI Mevcut Proje Dokümantasyonunu Görmezden Gelir (Bilgi Boşluğu)
+**Problem**: Mevcut SDD veya Vibe Coding yöntemleri, AI'nın projeleri gerçek zamanlı özetlemesine dayanır, bu da kritik içeriğin kolayca kaçırılmasına ve geliştirme sonuçlarının beklentilerden sapmasına neden olur.
+
+**Çözüm**: `knowledge/` deposu projenin "tek doğruluk kaynağı" olarak hizmet eder, mimari tasarımı, işlevsel modülleri ve iş süreçlerini biriktirerek gereksinimlerin kaynaktan itibaren yolda kalmasını sağlar.
+
+### 2. PRD'den Doğrudan Teknik Dokümantasyon (İçerik Atlama)
+**Problem**: PRD'den doğrudan detaylı tasarıma atlamak, gereksinim detaylarını kolayca kaçırır ve uygulanan özelliklerin gereksinimlerden sapmasına neden olur.
+
+**Çözüm**: Teknik detaylar olmadan yalnızca gereksinim iskeletine odaklanan **Feature Design Dokümanı** aşamasını tanıtın:
+- Hangi sayfalar ve bileşenler dahil?
+- Sayfa operasyon akışları
+- Backend işleme mantığı
+- Veri depolama yapısı
+
+Geliştirme, belirli teknoloji yığınına dayalı olarak sadece "eti doldurmak" zorundadır ve özelliklerin "kemiklere (gereksinimlere) yakın" büyümesini sağlar.
+
+### 3. Belirsiz Agent Arama Kapsamı (Belirsizlik)
+**Problem**: Karmaşık projelerde, AI'nın geniş kod ve doküman araması belirsiz sonuçlar verir ve tutarlılığı garanti etmeyi zorlaştırır.
+
+**Çözüm**: Her Agent'ın ihtiyaçlarına göre tasarlanmış net doküman dizin yapıları ve şablonlar, determinizmi garanti etmek için **aşamalı açıklama ve talep üzerine yükleme** uygular.
+
+### 4. Eksik Aşamalar ve Görevler (Süreç Kopukluğu)
+**Problem**: Eksik mühendislik süreci kapsamı kritik adımları kolayca kaçırır ve kaliteyi garanti etmeyi zorlaştırır.
+
+**Çözüm**: Yazılım mühendisliği yaşam döngüsünün tamamını kapsar:
+```
+PRD (Gereksinimler) → Feature Design (Özellik Tasarımı) → API Contract (Sözleşme)
+    → System Design (Sistem Tasarımı) → Dev (Geliştirme) → Test (Test)
+```
+- Her aşamanın çıktısı bir sonraki aşamanın girdisidir
+- Her adım devam etmeden önce insan onayı gerektirir
+- Tüm Agent yürütmelerinin tamamlanma sonrası kendi kendini kontrol eden todo listeleri vardır
+
+### 5. Düşük Takım İşbirliği Verimliliği (Bilgi Siloları)
+**Problem**: AI programlama deneyimi takımlar arasında paylaşılması zor olduğundan, tekrarlanan hatalara yol açar.
+
+**Çözüm**: Tüm Agent'lar, Skill'ler ve ilgili dokümanlar kaynak koduyla birlikte versiyon kontrol edilir:
+- Bir kişinin optimizasyonu takım tarafından paylaşılır
+- Bilgi kod tabanında birikir
+- Takım işbirliği verimliliği artar
+
+### 7. Tek Agent Bağlamı Çok Uzun (Performans Darboğazı)
+**Problem**: Büyük karmaşık görevler tek Agent bağlam pencerelerini aşar, anlama sapmalarına ve çıktı kalitesinin düşmesine neden olur.
+
+**Çözüm**: **Sub-Agent Otomatik Dispatch Mekanizması**:
+- Karmaşık görevler otomatik olarak tanımlanır ve alt görevlere bölünür
+- Her alt görev, izole bağlam ile bağımsız bir Sub-Agent tarafından yürütülür
+- Parent Agent koordine eder ve birleştirerek genel tutarlılığı sağlar
+- Tek Agent bağlam genişlemesini önler ve çıktı kalitesini garanti eder
+
+### 8. Gereksinim İterasyon Kaosu (Yönetim Zorluğu)
+**Problem**: Aynı dalda karıştırılan birden fazla gereksinim birbirini etkiler, takip ve geri alma işlemlerini zorlaştırır.
+
+**Çözüm**: **Her Gereksinim Bir Bağımsız Proje Olarak**:
+- Her gereksinim bağımsız bir iterasyon dizini oluşturur `iterations/iXXX-[gereksinim-adı]/`
+- Tam izolasyon: dokümanlar, tasarım, kod ve testler bağımsız yönetilir
+- Hızlı iterasyon: küçük parçalı teslimat, hızlı doğrulama, hızlı dağıtım
+- Esnek arşivleme: tamamlandıktan sonra, net tarihsel izlenebilirlikle `archive/` altında arşivlenir
+
+### 6. Doküman Güncelleme Gecikmesi (Bilgi Çürümesi)
+**Problem**: Projeler geliştikçe dokümanlar eskir ve AI yanlış bilgiyle çalışır.
+
+**Çözüm**: Agent'lar otomatik doküman güncelleme yeteneklerine sahiptir, proje değişikliklerini gerçek zamanlı senkronize ederek bilgi tabanının doğruluğunu korur.
+
+---
+
+## Temel İş Akışı
+
+```mermaid
+graph LR
+    A[PRD<br/>Gereksinim Dokümanı] --> B[Feature Design<br/>Özellik Tasarımı]
+    B --> C[API Contract<br/>Arayüz Sözleşmesi]
+    C --> D[System Design<br/>Sistem Tasarımı]
+    D --> E[Dev<br/>Uygulama]
+    E --> F[System Test<br/>Test]
+    F --> G[Archive<br/>Arşivleme]
+    
+    H[Knowledge<br/>Depo] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Aşama Açıklamaları
+
+| Aşama | Agent | Girdi | Çıktı | İnsan Onayı |
+|-------|-------|-------|-------|-------------|
+| PRD | PM | Kullanıcı Gereksinimleri | Ürün Gereksinim Dokümanı | ✅ Gerekli |
+| Feature Design | Feature Designer | PRD | Feature Design Dokümanı + API Sözleşmesi | ✅ Gerekli |
+| System Design | System Designer | Feature Spec | Frontend/Backend Tasarım Dokümanları | ✅ Gerekli |
+| Dev | Dev | Design | Kod + Görev Kayıtları | ✅ Gerekli |
+| System Test | Test Manager | Dev Çıktısı + Feature Spec | Test Senaryoları + Test Kodu + Test Raporu + Bug Raporu | ✅ Gerekli |
+
+---
+
+## Mevcut Çözümlerle Karşılaştırma
+
+| Boyut | Vibe Coding | Ralph Loop | **SpecCrew** |
+|-------|-------------|------------|-------------|
+| Doküman Bağımlılığı | Mevcut dokümanları görmezden gelir | AGENTS.md'e bağımlı | **Yapılandırılmış Bilgi Tabanı** |
+| Gereksinim Transferi | Doğrudan kodlama | PRD → Kod | **PRD → Feature Design → System Design → Kod** |
+| İnsan Katılımı | Minimal | Başlangıçta | **Her aşamada** |
+| Süreç Tamlığı | Zayıf | Orta | **Tam mühendislik iş akışı** |
+| Takım İşbirliği | Paylaşım zor | Kişisel verimlilik | **Takım bilgi paylaşımı** |
+| Bağlam Yönetimi | Tek örnek | Tek örnek döngüsü | **Sub-Agent otomatik dispatch** |
+| İterasyon Yönetimi | Karışık | Görev listesi | **Gereksinim proje olarak, bağımsız iterasyon** |
+| Determinizm | Düşük | Orta | **Yüksek (aşamalı açıklama)** |
+
+---
+
+## Hızlı Başlangıç
+
+### Önkoşullar
+
+- Node.js >= 16.0.0
+- Desteklenen IDE'ler: Qoder (varsayılan), Cursor, Claude Code
+
+> **Not**: Cursor ve Claude Code için adaptörler gerçek IDE ortamlarında test edilmemiştir (kod seviyesinde uygulanmış ve E2E testleri ile doğrulanmış, ancak gerçek Cursor/Claude Code'da henüz test edilmemiştir).
+
+### 1. SpecCrew'ü Kurun
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Projeyi Başlatın
+
+Projenizin kök dizinine gidin ve başlatma komutunu çalıştırın:
+
+```bash
+cd /path/to/your-project
+
+# Varsayılan olarak Qoder kullanır
+speccrew init
+
+# Veya IDE belirtin
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Başlatmadan sonra projenizde şu dosyalar oluşturulacaktır:
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 Agent rol tanımı
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 Skill iş akışı
+- `speccrew-workspace/` — Çalışma alanı (iterasyon dizinleri, bilgi tabanı, doküman şablonları)
+- `.speccrewrc` — SpecCrew yapılandırma dosyası
+
+Daha sonra belirli bir IDE için Agent'ları ve Skill'leri güncellemek için:
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Geliştirme İş Akışını Başlatın
+
+Standart mühendislik iş akışını adım adım takip edin:
+
+1. **PRD**: Product Manager Agent gereksinimleri analiz eder ve ürün gereksinim dokümanı oluşturur
+2. **Feature Design**: Feature Designer Agent feature design dokümanı + API sözleşmesi oluşturur
+3. **System Design**: System Designer Agent platformlara göre sistem tasarım dokümanları oluşturur (frontend/backend/mobile/desktop)
+4. **Dev**: System Developer Agent platformlara göre paralel geliştirme uygular
+5. **System Test**: Test Manager Agent üç aşamalı test koordine eder (senaryo tasarımı → kod üretimi → yürütme raporu)
+6. **Archive**: İterasyonu arşivle
+
+> Her aşamanın teslim edilebilirleri bir sonraki aşamaya geçmeden önce insan onayı gerektirir.
+
+### 4. Diğer CLI Komutları
+
+```bash
+speccrew list       # Yüklü agent'ları ve skill'leri listele
+speccrew doctor     # Ortamı ve kurulum durumunu teşhis et
+speccrew update     # Agent'ları ve skill'leri en son sürüme güncelle
+speccrew uninstall  # SpecCrew'ü kaldır (--all çalışma alanını da siler)
+```
+
+📖 **Detaylı Kılavuz**: Kurulumdan sonra, tam iş akışı ve Agent konuşma kılavuzu için [Başlangıç Kılavuzu](docs/GETTING-STARTED.tr.md)'na bakın.
+
+---
+
+## Daha Fazla Bilgi
+
+- **Agent Bilgi Haritası**: [speccrew-workspace/docs/agent-knowledge-map.md](./speccrew-workspace/docs/agent-knowledge-map.md)
+- **npm**: https://www.npmjs.com/package/speccrew
+- **GitHub**: https://github.com/charlesmu99/speccrew
+- **Gitee**: https://gitee.com/amutek/speccrew
+- **Qoder IDE**: https://qoder.com/
+
+---
+
+> **SpecCrew geliştiricilerin yerini almayı değil, sıkıcı kısımları otomatikleştirerek ekiplerin daha değerli işlere odaklanmasını sağlar.**

package/README.uk.md

@@ -0,0 +1,239 @@
+# SpecCrew - AI-орієнтований фреймворк програмної інженерії
+
+<p align="center">
+  <a href="./README.md">简体中文</a> |
+  <a href="./README.zh-TW.md">繁體中文</a> |
+  <a href="./README.en.md">English</a> |
+  <a href="./README.ko.md">한국어</a> |
+  <a href="./README.de.md">Deutsch</a> |
+  <a href="./README.es.md">Español</a> |
+  <a href="./README.fr.md">Français</a> |
+  <a href="./README.it.md">Italiano</a> |
+  <a href="./README.da.md">Dansk</a> |
+  <a href="./README.ja.md">日本語</a> |
+  <a href="./README.pl.md">Polski</a> |
+  <a href="./README.ru.md">Русский</a> |
+  <a href="./README.bs.md">Bosanski</a> |
+  <a href="./README.ar.md">العربية</a> |
+  <a href="./README.no.md">Norsk</a> |
+  <a href="./README.pt-BR.md">Português (Brasil)</a> |
+  <a href="./README.th.md">ไทย</a> |
+  <a href="./README.tr.md">Türkçe</a> |
+  <a href="./README.uk.md">Українська</a> |
+  <a href="./README.bn.md">বাংলা</a> |
+  <a href="./README.el.md">Ελληνικά</a> |
+  <a href="./README.vi.md">Tiếng Việt</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/v/speccrew.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/dm/speccrew.svg" alt="npm downloads"></a>
+  <a href="https://github.com/charlesmu99/speccrew/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/speccrew.svg" alt="license"></a>
+</p>
+
+> Віртуальна команда розробки на базі ШІ, що забезпечує швидку інженерну реалізацію для будь-якого програмного проекту
+
+## Що таке SpecCrew?
+
+SpecCrew — це вбудований фреймворк віртуальної команди розробки на базі ШІ. Він перетворює професійні робочі процеси програмної інженерії (PRD → Feature Design → System Design → Dev → Test) у багаторазові робочі процеси Агентів, допомагаючи командам розробників досягти Specification-Driven Development (SDD), особливо підходить для існуючих проектів.
+
+Інтегруючи Агентів та Навички в існуючі проекти, команди можуть швидко ініціалізувати системи документації проекту та віртуальні програмні команди, реалізуючи нові функції та модифікації відповідно до стандартних інженерних робочих процесів.
+
+---
+
+## Вирішення 8 ключових проблем
+
+### 1. ШІ ігнорує існуючу документацію проекту (розрив знань)
+**Проблема**: Існуючі методи SDD або Vibe Coding покладаються на те, що ШІ резюмує проекти в реальному часі, легко пропускаючи критичний контекст і призводячи до результатів розробки, що відхиляються від очікувань.
+
+**Рішення**: Репозиторій `knowledge/` служить "єдиним джерелом істини" проекту, накопичуючи архітектурний дизайн, функціональні модулі та бізнес-процеси, забезпечуючи відповідність вимог джерелу.
+
+### 2. Пряма технічна документація з PRD (пропуск змісту)
+**Проблема**: Прямий перехід від PRD до детального проектування легко пропускає деталі вимог, призводячи до того, що реалізовані функції відхиляються від вимог.
+
+**Рішення**: Впровадження фази **Документа Feature Design**, що фокусується лише на скелеті вимог без технічних деталей:
+- Які сторінки та компоненти включені?
+- Потоки операцій сторінок
+- Логіка обробки бекенду
+- Структура зберігання даних
+
+Розробка повинна лише "наростити м'ясо" на основі конкретного технічного стеку, забезпечуючи зростання функцій "близько до кісток (вимог)".
+
+### 3. Невизначена область пошуку Агента (невизначеність)
+**Проблема**: У складних проектах широкий пошук коду та документів ШІ дає невизначені результати, що ускладнює гарантування узгодженості.
+
+**Рішення**: Чіткі структури каталогів документів та шаблони, розроблені на основі потреб кожного Агента, реалізують **прогресивне розкриття та завантаження за запитом** для забезпечення детермінізму.
+
+### 4. Пропущені етапи та завдання (розрив процесу)
+**Проблема**: Відсутність повного охоплення інженерного процесу легко пропускає критичні кроки, що ускладнює гарантування якості.
+
+**Рішення**: Охоплення повного життєвого циклу програмної інженерії:
+```
+PRD (Вимоги) → Feature Design (Проектування функцій) → API Contract (Контракт)
+    → System Design (Системне проектування) → Dev (Розробка) → Test (Тестування)
+```
+- Вихід кожної фази є входом наступної фази
+- Кожен крок потребує людського підтвердження перед продовженням
+- Всі виконання Агентів мають списки todo з самоперевіркою після завершення
+
+### 5. Низька ефективність командної співпраці (інформаційні силоси)
+**Проблема**: Досвід програмування з ШІ важко розділяти між командами, що призводить до повторних помилок.
+
+**Рішення**: Всі Агенти, Навички та пов'язані документи версіонуються з вихідним кодом:
+- Оптимізація однієї людини розділяється командою
+- Знання накопичуються в кодовій базі
+- Підвищується ефективність командної співпраці
+
+### 7. Занадто довгий контекст одного Агента (вузьке місце продуктивності)
+**Проблема**: Великі складні завдання перевищують контекстні вікна одного Агента, викликаючи відхилення в розумінні та зниження якості виходу.
+
+**Рішення**: **Механізм автодиспетчеризації суб-Агентів**:
+- Складні завдання автоматично ідентифікуються та розділяються на підзавдання
+- Кожне підзавдання виконується незалежним суб-Агентом з ізольованим контекстом
+- Батьківський Агент координує та агрегує для забезпечення загальної узгодженості
+- Уникає розширення контексту одного Агента, забезпечуючи якість виходу
+
+### 8. Хаос ітерації вимог (труднощі управління)
+**Проблема**: Кілька вимог, змішаних в одній гілці, впливають одна на одну, що ускладнює відстеження та відкат.
+
+**Рішення**: **Кожна вимога як незалежний проект**:
+- Кожна вимога створює незалежний каталог ітерації `iterations/iXXX-[ім'я-вимоги]/`
+- Повна ізоляція: документи, дизайн, код та тести керуються незалежно
+- Швидка ітерація: доставка малої гранулярності, швидка верифікація, швидке розгортання
+- Гнучке архівування: після завершення, архівування в `archive/` з чіткою історичною відстежуваністю
+
+### 6. Затримка оновлення документів (старіння знань)
+**Проблема**: Документи застарівають по мірі розвитку проектів, змушуючи ШІ працювати з невірною інформацією.
+
+**Рішення**: Агенти мають можливості автоматичного оновлення документів, синхронізуючи зміни проекту в реальному часі для підтримки точності бази знань.
+
+---
+
+## Основний робочий процес
+
+```mermaid
+graph LR
+    A[PRD<br/>Документ вимог] --> B[Feature Design<br/>Проектування функцій]
+    B --> C[API Contract<br/>Контракт інтерфейсу]
+    C --> D[System Design<br/>Системне проектування]
+    D --> E[Dev<br/>Реалізація]
+    E --> F[System Test<br/>Тестування]
+    F --> G[Archive<br/>Архівування]
+    
+    H[Knowledge<br/>Репозиторій] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Опис фаз
+
+| Фаза | Агент | Вхід | Вихід | Людське підтвердження |
+|------|-------|------|-------|----------------------|
+| PRD | PM | Користувацькі вимоги | Документ вимог продукту | ✅ Обов'язково |
+| Feature Design | Feature Designer | PRD | Документ Feature Design + API контракт | ✅ Обов'язково |
+| System Design | System Designer | Feature Spec | Документи проектування Frontend/Backend | ✅ Обов'язково |
+| Dev | Dev | Design | Код + Записи завдань | ✅ Обов'язково |
+| System Test | Test Manager | Вихід Dev + Feature Spec | Тест-кейси + Тестовий код + Тестовий звіт + Звіт багів | ✅ Обов'язково |
+
+---
+
+## Порівняння з існуючими рішеннями
+
+| Вимір | Vibe Coding | Ralph Loop | **SpecCrew** |
+|-------|-------------|------------|-------------|
+| Залежність від документів | Ігнорує існуючі документи | Покладається на AGENTS.md | **Структурована база знань** |
+| Передача вимог | Пряме кодування | PRD → Код | **PRD → Feature Design → System Design → Код** |
+| Людська участь | Мінімальна | При запуску | **На кожній фазі** |
+| Повнота процесу | Слабка | Середня | **Повний інженерний робочий процес** |
+| Командна співпраця | Важко ділитися | Особиста ефективність | **Розділення знань команди** |
+| Управління контекстом | Один екземпляр | Цикл одного екземпляра | **Автодиспетчеризація суб-Агентів** |
+| Управління ітерацією | Змішане | Список завдань | **Вимога як проект, незалежна ітерація** |
+| Детермінізм | Низький | Середній | **Високий (прогресивне розкриття)** |
+
+---
+
+## Швидкий старт
+
+### Передумови
+
+- Node.js >= 16.0.0
+- Підтримувані IDE: Qoder (за замовчуванням), Cursor, Claude Code
+
+> **Примітка**: Адаптери для Cursor та Claude Code не тестувалися в реальних середовищах IDE (реалізовані на рівні коду та верифіковані через E2E тести, але ще не протестовані в реальних Cursor/Claude Code).
+
+### 1. Встановити SpecCrew
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Ініціалізувати проект
+
+Перейдіть до кореневого каталогу проекту та виконайте команду ініціалізації:
+
+```bash
+cd /path/to/your-project
+
+# За замовчуванням використовує Qoder
+speccrew init
+
+# Або вкажіть IDE
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Після ініціалізації в проекті будуть створені:
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 визначень ролей Агентів
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 робочих процесів Навичок
+- `speccrew-workspace/` — Робочий простір (каталоги ітерацій, база знань, шаблони документів)
+- `.speccrewrc` — Файл конфігурації SpecCrew
+
+Щоб пізніше оновити Агентів та Навички для конкретного IDE:
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Почати робочий процес розробки
+
+Дотримуйтесь стандартного інженерного робочого процесу крок за кроком:
+
+1. **PRD**: Агент Product Manager аналізує вимоги та генерує документ вимог продукту
+2. **Feature Design**: Агент Feature Designer генерує документ feature design + API контракт
+3. **System Design**: Агент System Designer генерує документи system design за платформами (frontend/backend/mobile/desktop)
+4. **Dev**: Агент System Developer реалізує розробку за платформами паралельно
+5. **System Test**: Агент Test Manager координує трифазне тестування (дизайн кейсів → генерація коду → звіт виконання)
+6. **Archive**: Архівувати ітерацію
+
+> Результати кожної фази потребують людського підтвердження перед переходом до наступної фази.
+
+### 4. Інші CLI команди
+
+```bash
+speccrew list       # Список встановлених агентів та навичок
+speccrew doctor     # Діагностика середовища та статусу встановлення
+speccrew update     # Оновлення агентів та навичок до останньої версії
+speccrew uninstall  # Видалити SpecCrew (--all також видаляє робочий простір)
+```
+
+📖 **Детальний посібник**: Після встановлення ознайомтесь з [Посібником початку роботи](docs/GETTING-STARTED.uk.md) для повного робочого процесу та посібника діалогів агентів.
+
+---
+
+## Більше інформації
+
+- **Карта знань Агентів**: [speccrew-workspace/docs/agent-knowledge-map.md](./speccrew-workspace/docs/agent-knowledge-map.md)
+- **npm**: https://www.npmjs.com/package/speccrew
+- **GitHub**: https://github.com/charlesmu99/speccrew
+- **Gitee**: https://gitee.com/amutek/speccrew
+- **Qoder IDE**: https://qoder.com/
+
+---
+
+> **SpecCrew не має на меті замінити розробників, а автоматизувати нудні частини, щоб команди могли зосередитися на більш цінній роботі.**

package/README.vi.md

@@ -0,0 +1,122 @@
+# SpecCrew - Khung Kỹ thuật Phần mềm Điều khiển bởi AI
+
+<p align="center">
+  <a href="./README.md">简体中文</a> |
+  <a href="./README.zh-TW.md">繁體中文</a> |
+  <a href="./README.en.md">English</a> |
+  <a href="./README.ko.md">한국어</a> |
+  <a href="./README.de.md">Deutsch</a> |
+  <a href="./README.es.md">Español</a> |
+  <a href="./README.fr.md">Français</a> |
+  <a href="./README.it.md">Italiano</a> |
+  <a href="./README.da.md">Dansk</a> |
+  <a href="./README.ja.md">日本語</a> |
+  <a href="./README.pl.md">Polski</a> |
+  <a href="./README.ru.md">Русский</a> |
+  <a href="./README.bs.md">Bosanski</a> |
+  <a href="./README.ar.md">العربية</a> |
+  <a href="./README.no.md">Norsk</a> |
+  <a href="./README.pt-BR.md">Português (Brasil)</a> |
+  <a href="./README.th.md">ไทย</a> |
+  <a href="./README.tr.md">Türkçe</a> |
+  <a href="./README.uk.md">Українська</a> |
+  <a href="./README.bn.md">বাংলা</a> |
+  <a href="./README.el.md">Ελληνικά</a> |
+  <a href="./README.vi.md">Tiếng Việt</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/v/speccrew.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/speccrew"><img src="https://img.shields.io/npm/dm/speccrew.svg" alt="npm downloads"></a>
+  <a href="https://github.com/charlesmu99/speccrew/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/speccrew.svg" alt="license"></a>
+</p>
+
+> Một đội phát triển AI ảo cho phép triển khai kỹ thuật nhanh chóng cho bất kỳ dự án phần mềm nào
+
+## SpecCrew là gì?
+
+SpecCrew là một khung đội phát triển AI ảo được nhúng. Nó chuyển đổi các quy trình kỹ thuật phần mềm chuyên nghiệp (PRD → Feature Design → System Design → Dev → Test) thành các quy trình Agent có thể tái sử dụng, giúp các đội phát triển đạt được Specification-Driven Development (SDD), đặc biệt phù hợp cho các dự án hiện có.
+
+Bằng cách tích hợp các Agent và Skill vào các dự án hiện có, các đội có thể nhanh chóng khởi tạo hệ thống tài liệu dự án và đội phần mềm ảo, triển khai các tính năng mới và sửa đổi theo các quy trình kỹ thuật tiêu chuẩn từng bước.
+
+---
+
+## Giải quyết 8 Vấn đề Cốt lõi
+
+### 1. AI Bỏ qua Tài liệu Dự án Hiện có (Khoảng trống Kiến thức)
+**Vấn đề**: Các phương pháp SDD hoặc Vibe Coding hiện có phụ thuộc vào AI tóm tắt các dự án theo thời gian thực, dễ dàng bỏ lỡ bối cảnh quan trọng và gây ra kết quả phát triển lệch khỏi kỳ vọng.
+
+**Giải pháp**: Kho lưu trữ `knowledge/` đóng vai trò là "nguồn sự thật duy nhất" của dự án, tích lũy thiết kế kiến trúc, các mô-đun chức năng và quy trình kinh doanh để đảm bảo các yêu cầu vẫn đúng hướng từ nguồn.
+
+### 2. Tài liệu Kỹ thuật Trực tiếp từ PRD (Bỏ sót Nội dung)
+**Vấn đề**: Nhảy trực tiếp từ PRD đến thiết kế chi tiết dễ dàng bỏ sót các chi tiết yêu cầu, khiến các tính năng được triển khai lệch khỏi yêu cầu.
+
+**Giải pháp**: Giới thiệu giai đoạn **Tài liệu Feature Design**, chỉ tập trung vào khung yêu cầu mà không có chi tiết kỹ thuật:
+- Bao gồm những trang và thành phần nào?
+- Các luồng thao tác trang
+- Logic xử lý backend
+- Cấu trúc lưu trữ dữ liệu
+
+Phát triển chỉ cần "điền nội dung" dựa trên ngăn xếp công nghệ cụ thể, đảm bảo các tính năng phát triển "gần xương (yêu cầu)".
+
+### 3. Phạm vi Tìm kiếm Agent Không chắc chắn (Sự không chắc chắn)
+**Vấn đề**: Trong các dự án phức tạp, tìm kiếm rộng mã và tài liệu bởi AI mang lại kết quả không chắc chắn, làm cho tính nhất quán khó đảm bảo.
+
+**Giải pháp**: Các cấu trúc thư mục tài liệu rõ ràng và các mẫu, được thiết kế dựa trên nhu cầu của từng Agent, triển khai **tiết lộ dần dần và tải theo yêu cầu** để đảm bảo sự tất định.
+
+### 4. Thiếu Các Bước và Nhiệm vụ (Đứt gãy Quy trình)
+**Vấn đề**: Thiếu bao phủ đầy đủ quy trình kỹ thuật dễ dàng bỏ sót các bước quan trọng, làm cho chất lượng khó đảm bảo.
+
+**Giải pháp**: Bao phủ toàn bộ vòng đời kỹ thuật phần mềm:
+```
+PRD (Yêu cầu) → Feature Design (Thiết kế Tính năng) → API Contract (Hợp đồng)
+    → System Design (Thiết kế Hệ thống) → Dev (Phát triển) → Test (Kiểm thử)
+```
+- Đầu ra của mỗi giai đoạn là đầu vào của giai đoạn tiếp theo
+- Mỗi bước yêu cầu xác nhận của con người trước khi tiếp tục
+- Tất cả các thực thi Agent có danh sách todo với tự kiểm tra sau khi hoàn thành
+
+### 5. Hiệu quả Hợp tác Đội thấp (Các hầm chứa Kiến thức)
+**Vấn đề**: Kinh nghiệm lập trình AI khó chia sẻ giữa các đội, dẫn đến các lỗi lặp lại.
+
+**Giải pháp**: Tất cả các Agent, Skill và tài liệu liên quan được kiểm soát phiên bản với mã nguồn:
+- Tối ưu hóa của một người được chia sẻ bởi đội
+- Kiến thức được tích lũy trong cơ sở mã
+- Cải thiện hiệu quả hợp tác đội
+
+### 7. Ngữ cảnh Đơn Agent Quá dài (Điểm nghẽn Hiệu suất)
+**Vấn đề**: Các nhiệm vụ phức tạp lớn vượt qua cửa sổ ngữ cảnh đơn Agent, gây ra sự lệch lạc trong hiểu biết và giảm chất lượng đầu ra.
+
+**Giải pháp**: **Cơ chế Tự động Điều phối Sub-Agent**:
+- Các nhiệm vụ phức tạp được tự động nhận diện và chia thành các nhiệm vụ con
+- Mỗi nhiệm vụ con được thực thi bởi một Sub-Agent độc lập với ngữ cảnh được cô lập
+- Agent cha điều phối và tổng hợp để đảm bảo tính nhất quán tổng thể
+- Tránh mở rộng ngữ cảnh đơn Agent, đảm bảo chất lượng đầu ra
+
+### 8. Sự hỗn loạn Lặp lại Yêu cầu (Khó khăn Quản lý)
+**Vấn đề**: Nhiều yêu cầu trộn lẫn trong cùng một nhánh ảnh hưởng lẫn nhau, làm cho việc theo dõi và quay lại trở nên khó khăn.
+
+**Giải pháp**: **Mỗi Yêu cầu như một Dự án Độc lập**:
+- Mỗi yêu cầu tạo một thư mục lặp lại độc lập `iterations/iXXX-[tên-yêu-cầu]/`
+- Cô lập hoàn toàn: tài liệu, thiết kế, mã và kiểm thử được quản lý độc lập
+- Lặp lại nhanh chóng: giao hàng độ hạt nhỏ, xác minh nhanh, triển khai nhanh
+- Lưu trữ linh hoạt: sau khi hoàn thành, lưu trữ trong `archive/` với khả năng truy xuất lịch sử rõ ràng
+
+### 6. Trì hoãn Cập nhật Tài liệu (Sự xuống cấp Kiến thức)
+**Vấn đề**: Tài liệu trở nên lỗi thời khi các dự án phát triển, khiến AI làm việc với thông tin sai.
+
+**Giải pháp**: Các Agent có khả năng cập nhật tài liệu tự động, đồng bộ hóa các thay đổi dự án theo thời gian thực để giữ cho cơ sở kiến thức chính xác.
+
+---
+
+## Thông tin Bổ sung
+
+- **Bản đồ Kiến thức Agent**: [speccrew-workspace/docs/agent-knowledge-map.md](./speccrew-workspace/docs/agent-knowledge-map.md)
+- **npm**: https://www.npmjs.com/package/speccrew
+- **GitHub**: https://github.com/charlesmu99/speccrew
+- **Gitee**: https://gitee.com/amutek/speccrew
+- **Qoder IDE**: https://qoder.com/
+
+---
+
+> **SpecCrew không nhằm mục đích thay thế các nhà phát triển, mà tự động hóa các phần nhàm chán để các đội có thể tập trung vào công việc có giá trị hơn.**