speccrew 0.1.1 → 0.1.3

package/README.pl.md

@@ -0,0 +1,321 @@
+# SpecCrew - Framework Inżynierii Oprogramowania Napędzany 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>
+
+> Wirtualny zespół deweloperski AI umożliwiający szybką implementację inżynieryjną dla każdego projektu software'owego
+
+## Czym jest SpecCrew?
+
+SpecCrew to wbudowany framework wirtualnego zespołu deweloperskiego AI. Przekształca profesjonalne workflow inżynierii software'owej (PRD → Feature Design → System Design → Dev → Test) w wielokrotnego użytku workflow Agentów, pomagając zespołom deweloperskim osiągnąć Specification-Driven Development (SDD), szczególnie odpowiedni dla istniejących projektów.
+
+Poprzez integrację Agentów i Skilli z istniejącymi projektami, zespoły mogą szybko zainicjować systemy dokumentacji projektu i wirtualne zespoły software'owe, implementując nowe funkcje i modyfikacje zgodnie ze standardowymi workflow inżynieryjnymi.
+
+---
+
+## 8 Rozwiązanych Problemów Rdzeniowych
+
+### 1. AI Ignoruje Istniejącą Dokumentację Projektu (Luka Wiedzy)
+**Problem**: Istniejące metody SDD lub Vibe Coding polegają na AI podsumowującym projekty w czasie rzeczywistym, łatwo gubiąc krytyczny kontekst i powodując, że wyniki rozwoju odchodzą od oczekiwań.
+
+**Rozwiązanie**: Repozytorium `knowledge/` służy jako "jedno źródło prawdy" projektu, akumulując projekt architektury, moduły funkcjonalne i procesy biznesowe, zapewniając, że wymagania pozostają na torze od źródła.
+
+### 2. Bezpośrednia Dokumentacja Techniczna z PRD (Pominięcie Treści)
+**Problem**: Przeskakiwanie bezpośrednio z PRD do szczegółowego projektu łatwo gubi szczegóły wymagań, powodując, że implementowane funkcje odchodzą od wymagań.
+
+**Rozwiązanie**: Wprowadzenie fazy **Dokumentu Feature Design**, skupiającej się tylko na szkielecie wymagań bez szczegółów technicznych:
+- Jakie strony i komponenty są zawarte?
+- Przepływy operacji stron
+- Logika przetwarzania backend
+- Struktura przechowywania danych
+
+Rozwój musi tylko "wypełnić ciało" na podstawie konkretnego tech stacku, zapewniając, że funkcje rosną "blisko kości (wymagań)".
+
+### 3. Niepewny Zakres Wyszukiwania Agenta (Niepewność)
+**Problem**: W złożonych projektach szerokie wyszukiwanie kodu i dokumentów przez AI daje niepewne wyniki, czyniąc spójność trudną do zagwarantowania.
+
+**Rozwiązanie**: Jasne struktury katalogów dokumentów i szablony, zaprojektowane w oparciu o potrzeby każdego Agenta, implementują **stopniowe ujawnianie i ładowanie na żądanie** aby zagwarantować determinizm.
+
+### 4. Brakujące Kroki i Zadania (Załamanie Procesu)
+**Problem**: Brak pełnego pokrycia procesu inżynieryjnego łatwo gubi krytyczne kroki, czyniąc jakość trudną do zagwarantowania.
+
+**Rozwiązanie**: Pokrycie całego cyklu życia inżynierii software'owej:
+```
+PRD (Wymagania) → Feature Design (Projekt Funkcjonalny) → API Contract (Kontrakt)
+    → System Design (Projekt Systemu) → Dev (Rozwój) → Test (Testy)
+```
+- Wyjście każdej fazy jest wejściem następnej fazy
+- Każdy krok wymaga ludzkiego potwierdzenia przed kontynuacją
+- Wszystkie egzekucje Agentów mają listy todo z samosprawdzeniem po zakończeniu
+
+### 5. Niska Efektywność Współpracy Zespołu (Silosy Wiedzy)
+**Problem**: Doświadczenie programowania AI jest trudne do dzielenia między zespołami, prowadząc do powtarzających się błędów.
+
+**Rozwiązanie**: Wszystkie Agenty, Skille i powiązane dokumenty są wersjonowane z kodem źródłowym:
+- Optymalizacja jednej osoby jest dzielona przez zespół
+- Wiedza akumuluje się w bazie kodu
+- Poprawiona efektywność współpracy zespołu
+
+### 7. Zbyt Długi Kontekst Pojedynczego Agenta (Wąskie Gardło Wydajności)
+**Problem**: Duże złożone zadania przekraczają okna kontekstu pojedynczego Agenta, powodując odchylenia w zrozumieniu i spadek jakości wyjścia.
+
+**Rozwiązanie**: **Mechanizm Auto-Dispatch Sub-Agentów**:
+- Złożone zadania są automatycznie identyfikowane i dzielone na podzadania
+- Każdy podzadanie jest wykonywany przez niezależnego sub-Agenta z izolowanym kontekstem
+- Parent Agent koordynuje i agreguje aby zapewnić ogólną spójność
+- Unika ekspansji kontekstu pojedynczego Agenta, zapewniając jakość wyjścia
+
+### 8. Chaos Iteracji Wymagań (Trudności Zarządzania)
+**Problem**: Wiele wymagań zmieszanych w tej samej gałęzi wpływa na siebie nawzajem, czyniąc śledzenie i rollback trudnym.
+
+**Rozwiązanie**: **Każde Wymaganie jako Niezależny Projekt**:
+- Każde wymaganie tworzy niezależny katalog iteracji `iterations/iXXX-[nazwa-wymagania]/`
+- Pełna izolacja: dokumenty, projekt, kod i testy zarządzane niezależnie
+- Szybka iteracja: dostarczanie małej granulacji, szybka weryfikacja, szybkie wdrożenie
+- Elastyczne archiwizowanie: po zakończeniu, archiwizacja do `archive/` z jasną historyczną identyfikowalnością
+
+### 6. Opóźnienie Aktualizacji Dokumentów (Rozkład Wiedzy)
+**Problem**: Dokumenty stają się przestarzałe w miarę jak projekty ewoluują, powodując, że AI pracuje z nieprawidłowymi informacjami.
+
+**Rozwiązanie**: Agenty mają automatyczne możliwości aktualizacji dokumentów, synchronizując zmiany projektu w czasie rzeczywistym aby utrzymać dokładność bazy wiedzy.
+
+---
+
+## Rdzenny Workflow
+
+```mermaid
+graph LR
+    A[PRD<br/>Dokument Wymagań] --> B[Feature Design<br/>Projekt Funkcjonalny]
+    B --> C[API Contract<br/>Kontrakt Interfejsu]
+    C --> D[System Design<br/>Projekt Systemu]
+    D --> E[Dev<br/>Implementacja]
+    E --> F[System Test<br/>Testy]
+    F --> G[Archive<br/>Archiwizacja]
+    
+    H[Knowledge<br/>Repozytorium] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Opisy Faz
+
+| Faza | Agent | Wejście | Wyjście | Ludzkie Potwierdzenie |
+|------|-------|---------|---------|----------------------|
+| PRD | PM | Wymagania Użytkownika | Dokument Wymagań Produktu | ✅ Wymagane |
+| Feature Design | Feature Designer | PRD | Dokument Feature Design + Kontrakt API | ✅ Wymagane |
+| System Design | System Designer | Feature Spec | Dokumenty Projektu Frontend/Backend | ✅ Wymagane |
+| Dev | Dev | Design | Kod + Rejestry Zadań | ✅ Wymagane |
+| System Test | Test Manager | Wyjście Dev + Feature Spec | Przypadki Testowe + Kod Testowy + Raport Testowy + Raport Bugów | ✅ Wymagane |
+
+---
+
+## Porównanie z Istniejącymi Rozwiązaniami
+
+| Wymiar | Vibe Coding | Ralph Loop | **SpecCrew** |
+|--------|-------------|------------|-------------|
+| Zależność od Dokumentów | Ignoruje istniejące docs | Polega na AGENTS.md | **Strukturalna Baza Wiedzy** |
+| Transfer Wymagań | Bezpośrednie kodowanie | PRD → Kod | **PRD → Feature Design → System Design → Kod** |
+| Ludzkie Zaangażowanie | Minimalne | Przy starcie | **W każdej fazie** |
+| Kompletność Procesu | Słaba | Średnia | **Kompletny workflow inżynieryjny** |
+| Współpraca Zespołu | Trudno dzielić | Osobista efektywność | **Dzielenie wiedzy zespołu** |
+| Zarządzanie Kontekstem | Pojedyncza instancja | Pętla pojedynczej instancji | **Auto-dispatch sub-Agentów** |
+| Zarządzanie Iteracją | Mieszane | Lista zadań | **Wymaganie jako projekt, niezależna iteracja** |
+| Determinizm | Niski | Średni | **Wysoki (stopniowe ujawnianie)** |
+
+---
+
+## Szybki Start
+
+### Wymagania Wstępne
+
+- Node.js >= 16.0.0
+- Wspierane IDE: Qoder (domyślne), Cursor, Claude Code
+
+> **Uwaga**: Adaptery dla Cursor i Claude Code nie zostały przetestowane w rzeczywistych środowiskach IDE (zaimplementowane na poziomie kodu i zweryfikowane przez testy E2E, ale jeszcze nie przetestowane w rzeczywistym Cursor/Claude Code).
+
+### 1. Zainstaluj SpecCrew
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Zainicjuj Projekt
+
+Nawiguj do głównego katalogu projektu i uruchom komendę inicjalizacji:
+
+```bash
+cd /path/to/your-project
+
+# Domyślnie używa Qoder
+speccrew init
+
+# Lub określ IDE
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Po inicjalizacji w projekcie zostaną wygenerowane:
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 definicji ról Agentów
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 workflow Skilli
+- `speccrew-workspace/` — Przestrzeń robocza (katalogi iteracji, baza wiedzy, szablony dokumentów)
+- `.speccrewrc` — Plik konfiguracyjny SpecCrew
+
+Aby później zaktualizować Agenty i Skille dla konkretnego IDE:
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Rozpocznij Workflow Rozwoju
+
+Podążaj za standardowym workflow inżynieryjnym krok po kroku:
+
+1. **PRD**: Agent Product Manager analizuje wymagania i generuje dokument wymagań produktu
+2. **Feature Design**: Agent Feature Designer generuje dokument feature design + kontrakt API
+3. **System Design**: Agent System Designer generuje dokumenty system design według platformy (frontend/backend/mobile/desktop)
+4. **Dev**: Agent System Developer implementuje rozwój według platformy równolegle
+5. **System Test**: Agent Test Manager koordynuje testowanie trójfazowe (projekt przypadków → generowanie kodu → raport egzekucji)
+6. **Archive**: Zarchiwizuj iterację
+
+> Deliverable każdej fazy wymaga ludzkiego potwierdzenia przed przejściem do następnej fazy.
+
+### 4. Inne Komendy CLI
+
+```bash
+speccrew list       # Wylistuj zainstalowane agenty i skille
+speccrew doctor     # Zdiagnozuj środowisko i status instalacji
+speccrew update     # Zaktualizuj agenty i skille do najnowszej wersji
+speccrew uninstall  # Odinstaluj SpecCrew (--all usuwa też przestrzeń roboczą)
+```
+
+📖 **Szczegółowy Przewodnik**: Po instalacji, sprawdź [Przewodnik Wprowadzający](docs/GETTING-STARTED.pl.md) dla pełnego workflow i przewodnika rozmów agentów.
+
+---
+
+## Struktura Katalogu
+
+```
+your-project/
+├── .qoder/                          # Katalog konfiguracji IDE (przykład Qoder)
+│   ├── agents/                      # 7 Agentów ról
+│   │   ├── speccrew-team-leader.md       # Lider Zespołu: Globalne planowanie i zarządzanie iteracją
+│   │   ├── speccrew-product-manager.md   # Product Manager: Analiza wymagań i PRD
+│   │   ├── speccrew-feature-designer.md  # Feature Designer: Feature Design + Kontrakt API
+│   │   ├── speccrew-system-designer.md   # System Designer: System design według platformy
+│   │   ├── speccrew-system-developer.md  # System Developer: Równoległy rozwój według platformy
+│   │   ├── speccrew-test-manager.md      # Test Manager: Koordynacja testów trójfazowych
+│   │   └── speccrew-task-worker.md       # Task Worker: Równoległa egzekucja podzadań
+│   └── skills/                      # 38 Skilli (zgrupowane według funkcji)
+│       ├── speccrew-pm-*/                # Zarządzanie Produktem (analiza wymagań, ewaluacja)
+│       ├── speccrew-fd-*/                # Feature Design (Feature Design, Kontrakt API)
+│       ├── speccrew-sd-*/                # System Design (frontend/backend/mobile/desktop)
+│       ├── speccrew-dev-*/               # Rozwój (frontend/backend/mobile/desktop)
+│       ├── speccrew-test-*/              # Testy (projekt przypadków/generowanie kodu/raport egzekucji)
+│       ├── speccrew-knowledge-bizs-*/    # Wiedza Biznesowa (analiza API/analiza UI/klasyfikacja modułów itd.)
+│       ├── speccrew-knowledge-techs-*/   # Wiedza Techniczna (generowanie tech stacku/konwencje/indeks itd.)
+│       ├── speccrew-knowledge-graph-*/   # Graf Wiedzy (odczyt/zapis/zapytanie)
+│       └── speccrew-*/                   # Narzędzia (diagnostyka/timestampy/workflow itd.)
+│
+└── speccrew-workspace/              # Przestrzeń robocza (generowana podczas inicjalizacji)
+    ├── docs/                        # Dokumenty zarządcze
+    │   ├── configs/                 # Pliki konfiguracyjne (mapowanie platform, mapowanie tech stacku itd.)
+    │   ├── rules/                   # Konfiguracje reguł
+    │   └── solutions/               # Dokumenty rozwiązań
+    │
+    ├── iterations/                  # Projekty iteracji (generowane dynamicznie)
+    │   └── {numer}-{typ}-{nazwa}/
+    │       ├── 00.docs/             # Oryginalne wymagania
+    │       ├── 01.product-requirement/ # Wymagania produktu
+    │       ├── 02.feature-design/   # Feature design
+    │       ├── 03.system-design/    # System design
+    │       ├── 04.development/      # Faza rozwoju
+    │       ├── 05.system-test/      # Testy systemowe
+    │       └── 06.delivery/         # Faza dostawy
+    │
+    ├── iteration-archives/          # Archiwa iteracji
+    │
+    └── knowledges/                  # Baza wiedzy
+        ├── base/                    # Podstawa/metadane
+        │   ├── diagnosis-reports/   # Raporty diagnostyczne
+        │   ├── sync-state/          # Stan synchronizacji
+        │   └── tech-debts/          # Dług techniczny
+        ├── bizs/                    # Wiedza biznesowa
+        │   └── {platform-type}/{module-name}/
+        └── techs/                   # Wiedza techniczna
+            └── {platform-id}/
+```
+
+---
+
+## Główne Zasady Projektowania
+
+1. **Specification-Driven**: Pisz specyfikacje najpierw, potem pozwól kodowi "wyrosnąć" z nich
+2. **Stopniowe Ujawnianie**: Agenty zaczynają od minimalnych punktów wejścia, ładując informacje na żądanie
+3. **Ludzkie Potwierdzenie**: Wyjście każdej fazy wymaga ludzkiego potwierdzenia aby zapobiec odchyleniom AI
+4. **Izolacja Kontekstu**: Duże zadania są dzielone na małe, izolowane kontekstowo podzadania
+5. **Współpraca Sub-Agentów**: Złożone zadania automatycznie dispatchują sub-Agentów aby uniknąć ekspansji kontekstu pojedynczego Agenta
+6. **Szybka Iteracja**: Każde wymaganie jako niezależny projekt dla szybkiej dostawy i weryfikacji
+7. **Dzielenie Wiedzy**: Wszystkie konfiguracje są wersjonowane z kodem źródłowym
+
+---
+
+## Przypadki Użycia
+
+### ✅ Zalecane Dla
+- Średnie do dużych projektów wymagających standaryzowanych workflow
+- Rozwój software'u we współpracy zespołowej
+| Transformacja inżynieryjna projektów legacy
+| Produkty wymagające długoterminowego utrzymania
+
+### ❌ Nieodpowiednie Dla
+| Osobista szybka walidacja prototypu
+| Projekty eksploracyjne z bardzo niepewnymi wymaganiami
+| Jednorazowe skrypty lub narzędzia
+
+---
+
+## Więcej Informacji
+
+- **Mapa Wiedzy Agentów**: [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 nie ma na celu zastąpienia deweloperów, ale zautomatyzowanie nudnych części, aby zespoły mogły skupić się na bardziej wartościowej pracy.**

package/README.pt-BR.md

@@ -0,0 +1,321 @@
+# SpecCrew - Framework de Engenharia de Software Impulsionado por IA
+
+<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>
+
+> Uma equipe de desenvolvimento de IA virtual que permite implementação rápida de engenharia para qualquer projeto de software
+
+## O que é SpecCrew?
+
+SpecCrew é um framework de equipe de desenvolvimento de IA virtual incorporado. Ele transforma fluxos de trabalho de engenharia de software profissional (PRD → Feature Design → System Design → Dev → Test) em fluxos de trabalho de Agent reutilizáveis, ajudando equipes de desenvolvimento a alcançar o Specification-Driven Development (SDD), especialmente adequado para projetos existentes.
+
+Ao integrar Agents e Skills em projetos existentes, as equipes podem inicializar rapidamente sistemas de documentação de projetos e equipes de software virtuais, implementando novas funcionalidades e modificações seguindo fluxos de trabalho de engenharia padrão.
+
+---
+
+## 8 Problemas Principais Resolvidos
+
+### 1. IA Ignora Documentação de Projeto Existente (Lacuna de Conhecimento)
+**Problema**: Os métodos SDD ou Vibe Coding existentes dependem da IA resumindo projetos em tempo real, perdendo facilmente o contexto crítico e causando resultados de desenvolvimento que se desviam das expectativas.
+
+**Solução**: O repositório `knowledge/` serve como a "única fonte da verdade" do projeto, acumulando design de arquitetura, módulos funcionais e processos de negócios para garantir que os requisitos permaneçam no caminho certo desde a fonte.
+
+### 2. Documentação Técnica Direta do PRD (Omissão de Conteúdo)
+**Problema**: Pular diretamente do PRD para o design detalhado perde facilmente os detalhes dos requisitos, fazendo com que as funcionalidades implementadas se desviem dos requisitos.
+
+**Solução**: Introduzir a fase de **Documento Feature Design**, focando apenas no esqueleto dos requisitos sem detalhes técnicos:
+- Quais páginas e componentes estão incluídos?
+- Fluxos de operação de páginas
+- Lógica de processamento backend
+- Estrutura de armazenamento de dados
+
+O desenvolvimento só precisa "preencher a carne" com base na stack tecnológica específica, garantindo que as funcionalidades cresçam "perto do osso (requisitos)".
+
+### 3. Escopo de Busca de Agent Incerto (Incerteza)
+**Problema**: Em projetos complexos, a busca ampla de código e documentos pela IA produz resultados incertos, tornando a consistência difícil de garantir.
+
+**Solução**: Estruturas de diretórios de documentos claras e templates, projetadas com base nas necessidades de cada Agent, implementam **divulgação progressiva e carregamento sob demanda** para garantir determinismo.
+
+### 4. Fases e Tarefas Ausentes (Rompimento de Processo)
+**Problema**: A falta de cobertura completa do processo de engenharia perde facilmente fases críticas, tornando a qualidade difícil de garantir.
+
+**Solução**: Cobrir todo o ciclo de vida da engenharia de software:
+```
+PRD (Requisitos) → Feature Design (Design de Funcionalidade) → API Contract (Contrato)
+    → System Design (Design de Sistema) → Dev (Desenvolvimento) → Test (Testes)
+```
+- A saída de cada fase é a entrada da próxima fase
+- Cada passo requer confirmação humana antes de prosseguir
+- Todas as execuções de Agent têm listas de tarefas com auto-verificação após conclusão
+
+### 5. Baixa Eficiência de Colaboração da Equipe (Silos de Conhecimento)
+**Problema**: A experiência de programação com IA é difícil de compartilhar entre equipes, levando a erros repetidos.
+
+**Solução**: Todos os Agents, Skills e documentos relacionados são versionados com o código-fonte:
+- A otimização de uma pessoa é compartilhada pela equipe
+- O conhecimento se acumula na base de código
+- Melhor eficiência de colaboração da equipe
+
+### 7. Contexto de Agent Único Muito Longo (Gargalo de Performance)
+**Problema**: Tarefas complexas grandes excedem as janelas de contexto de Agent único, causando desvios de entendimento e diminuição da qualidade de saída.
+
+**Solução**: **Mecanismo de Auto-Dispatch de Sub-Agent**:
+- Tarefas complexas são automaticamente identificadas e divididas em subtarefas
+- Cada subtarefa é executada por um Sub-Agent independente com contexto isolado
+- O Agent pai coordena e agrega para garantir consistência global
+- Evita expansão de contexto de Agent único, garantindo qualidade de saída
+
+### 8. Caos de Iteração de Requisitos (Dificuldade de Gerenciamento)
+**Problema**: Múltiplos requisitos misturados no mesmo branch afetam uns aos outros, tornando rastreamento e rollback difíceis.
+
+**Solução**: **Cada Requisito como um Projeto Independente**:
+- Cada requisito cria um diretório de iteração independente `iterations/iXXX-[nome-requisito]/`
+- Isolamento completo: documentos, design, código e testes gerenciados independentemente
+- Iteração rápida: entrega de pequena granularidade, verificação rápida, implantação rápida
+- Arquivamento flexível: após conclusão, arquivamento em `archive/` com rastreabilidade histórica clara
+
+### 6. Atraso na Atualização de Documentos (Decaimento de Conhecimento)
+**Problema**: Os documentos ficam desatualizados à medida que os projetos evoluem, fazendo a IA trabalhar com informações incorretas.
+
+**Solução**: Os Agents têm capacidades de atualização automática de documentos, sincronizando mudanças do projeto em tempo real para manter a base de conhecimento precisa.
+
+---
+
+## Fluxo de Trabalho Principal
+
+```mermaid
+graph LR
+    A[PRD<br/>Documento de Requisitos] --> B[Feature Design<br/>Design de Funcionalidade]
+    B --> C[API Contract<br/>Contrato de Interface]
+    C --> D[System Design<br/>Design de Sistema]
+    D --> E[Dev<br/>Implementação]
+    E --> F[System Test<br/>Testes]
+    F --> G[Archive<br/>Arquivamento]
+    
+    H[Knowledge<br/>Repositório] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Descrições das Fases
+
+| Fase | Agent | Entrada | Saída | Confirmação Humana |
+|------|-------|---------|-------|-------------------|
+| PRD | PM | Requisitos do Usuário | Documento de Requisitos do Produto | ✅ Obrigatória |
+| Feature Design | Feature Designer | PRD | Documento Feature Design + Contrato API | ✅ Obrigatória |
+| System Design | System Designer | Feature Spec | Documentos de Design Frontend/Backend | ✅ Obrigatória |
+| Dev | Dev | Design | Código + Registros de Tarefas | ✅ Obrigatória |
+| System Test | Test Manager | Saída Dev + Feature Spec | Casos de Teste + Código de Teste + Relatório de Teste + Relatório de Bugs | ✅ Obrigatória |
+
+---
+
+## Comparação com Soluções Existentes
+
+| Dimensão | Vibe Coding | Ralph Loop | **SpecCrew** |
+|----------|-------------|------------|-------------|
+| Dependência de Documentos | Ignora docs existentes | Depende de AGENTS.md | **Base de Conhecimento Estruturada** |
+| Transferência de Requisitos | Codificação direta | PRD → Código | **PRD → Feature Design → System Design → Código** |
+| Envolvimento Humano | Mínimo | Na inicialização | **Em cada fase** |
+| Completude do Processo | Fraca | Média | **Fluxo de trabalho de engenharia completo** |
+| Colaboração da Equipe | Difícil compartilhar | Eficiência pessoal | **Compartilhamento de conhecimento da equipe** |
+| Gerenciamento de Contexto | Instância única | Loop de instância única | **Auto-dispatch de Sub-Agent** |
+| Gerenciamento de Iteração | Misto | Lista de tarefas | **Requisito como projeto, iteração independente** |
+| Determinismo | Baixo | Médio | **Alto (divulgação progressiva)** |
+
+---
+
+## Início Rápido
+
+### Pré-requisitos
+
+- Node.js >= 16.0.0
+- IDEs suportados: Qoder (padrão), Cursor, Claude Code
+
+> **Nota**: Os adaptadores para Cursor e Claude Code não foram testados em ambientes de IDE reais (implementados em nível de código e verificados através de testes E2E, mas ainda não testados em Cursor/Claude Code reais).
+
+### 1. Instalar SpecCrew
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Inicializar Projeto
+
+Navegue até o diretório raiz do projeto e execute o comando de inicialização:
+
+```bash
+cd /path/to/your-project
+
+# Usa Qoder por padrão
+speccrew init
+
+# Ou especifique o IDE
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Após a inicialização, os seguintes itens serão gerados no projeto:
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 definições de papéis de Agent
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 fluxos de trabalho de Skill
+- `speccrew-workspace/` — Espaço de trabalho (diretórios de iteração, base de conhecimento, templates de documentos)
+- `.speccrewrc` — Arquivo de configuração do SpecCrew
+
+Para atualizar Agents e Skills para um IDE específico posteriormente:
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Iniciar Fluxo de Trabalho de Desenvolvimento
+
+Siga o fluxo de trabalho de engenharia padrão passo a passo:
+
+1. **PRD**: O Agent Product Manager analisa requisitos e gera documento de requisitos do produto
+2. **Feature Design**: O Agent Feature Designer gera documento feature design + contrato API
+3. **System Design**: O Agent System Designer gera documentos system design por plataforma (frontend/backend/mobile/desktop)
+4. **Dev**: O Agent System Developer implementa desenvolvimento por plataforma em paralelo
+5. **System Test**: O Agent Test Manager coordena testes em três fases (design de casos → geração de código → relatório de execução)
+6. **Archive**: Arquivar iteração
+
+> Os entregáveis de cada fase requerem confirmação humana antes de prosseguir para a próxima fase.
+
+### 4. Outros Comandos CLI
+
+```bash
+speccrew list       # Listar agents e skills instalados
+speccrew doctor     # Diagnosticar ambiente e status de instalação
+speccrew update     # Atualizar agents e skills para a versão mais recente
+speccrew uninstall  # Desinstalar SpecCrew (--all também remove o espaço de trabalho)
+```
+
+📖 **Guia Detalhado**: Após a instalação, consulte o [Guia de Introdução](docs/GETTING-STARTED.pt-BR.md) para o fluxo de trabalho completo e guia de conversação com agents.
+
+---
+
+## Estrutura de Diretório
+
+```
+your-project/
+├── .qoder/                          # Diretório de configuração IDE (exemplo Qoder)
+│   ├── agents/                      # 7 Agents de papéis
+│   │   ├── speccrew-team-leader.md       # Líder da Equipe: Agendamento global e gerenciamento de iteração
+│   │   ├── speccrew-product-manager.md   # Gerente de Produto: Análise de requisitos e PRD
+│   │   ├── speccrew-feature-designer.md  # Feature Designer: Feature Design + Contrato API
+│   │   ├── speccrew-system-designer.md   # System Designer: Design de sistema por plataforma
+│   │   ├── speccrew-system-developer.md  # System Developer: Desenvolvimento paralelo por plataforma
+│   │   ├── speccrew-test-manager.md      # Test Manager: Coordenação de testes em três fases
+│   │   └── speccrew-task-worker.md       # Task Worker: Execução paralela de subtarefas
+│   └── skills/                      # 38 Skills (agrupadas por função)
+│       ├── speccrew-pm-*/                # Gestão de Produto (análise de requisitos, avaliação)
+│       ├── speccrew-fd-*/                # Feature Design (Feature Design, Contrato API)
+│       ├── speccrew-sd-*/                # System Design (frontend/backend/mobile/desktop)
+│       ├── speccrew-dev-*/               # Desenvolvimento (frontend/backend/mobile/desktop)
+│       ├── speccrew-test-*/              # Testes (design de casos/geração de código/relatório de execução)
+│       ├── speccrew-knowledge-bizs-*/    # Conhecimento de Negócios (análise de API/análise de UI/classificação de módulos etc.)
+│       ├── speccrew-knowledge-techs-*/   # Conhecimento Técnico (geração de stack tech/convenções/índice etc.)
+│       ├── speccrew-knowledge-graph-*/   # Grafo de Conhecimento (leitura/escrita/consulta)
+│       └── speccrew-*/                   # Utilitários (diagnóstico/timestamps/workflow etc.)
+│
+└── speccrew-workspace/              # Espaço de trabalho (gerado durante inicialização)
+    ├── docs/                        # Documentos de gerenciamento
+    │   ├── configs/                 # Arquivos de configuração (mapeamento de plataforma, mapeamento de stack tech etc.)
+    │   ├── rules/                   # Configurações de regras
+    │   └── solutions/               # Documentos de soluções
+    │
+    ├── iterations/                  # Projetos de iteração (gerados dinamicamente)
+    │   └── {número}-{tipo}-{nome}/
+    │       ├── 00.docs/             # Requisitos originais
+    │       ├── 01.product-requirement/ # Requisitos de produto
+    │       ├── 02.feature-design/   # Feature design
+    │       ├── 03.system-design/    # System design
+    │       ├── 04.development/      # Fase de desenvolvimento
+    │       ├── 05.system-test/      # Testes de sistema
+    │       └── 06.delivery/         # Fase de entrega
+    │
+    ├── iteration-archives/          # Arquivos de iteração
+    │
+    └── knowledges/                  # Base de conhecimento
+        ├── base/                    # Base/metadados
+        │   ├── diagnosis-reports/   # Relatórios de diagnóstico
+        │   ├── sync-state/          # Estado de sincronização
+        │   └── tech-debts/          # Dívida técnica
+        ├── bizs/                    # Conhecimento de negócios
+        │   └── {platform-type}/{module-name}/
+        └── techs/                   # Conhecimento técnico
+            └── {platform-id}/
+```
+
+---
+
+## Princípios de Design Principais
+
+1. **Specification-Driven**: Escreva especificações primeiro, depois deixe o código "crescer" a partir delas
+2. **Divulgação Progressiva**: Os Agents começam a partir de pontos de entrada mínimos, carregando informações sob demanda
+3. **Confirmação Humana**: A saída de cada fase requer confirmação humana para prevenir desvios da IA
+4. **Isolamento de Contexto**: Tarefas grandes são divididas em subtarefas pequenas e isoladas por contexto
+5. **Colaboração de Sub-Agent**: Tarefas complexas automaticamente fazem dispatch de Sub-Agents para evitar expansão de contexto de Agent único
+6. **Iteração Rápida**: Cada requisito como um projeto independente para entrega e verificação rápidas
+7. **Compartilhamento de Conhecimento**: Todas as configurações são versionadas com o código-fonte
+
+---
+
+## Casos de Uso
+
+### ✅ Recomendado Para
+- Projetos médios a grandes que requerem fluxos de trabalho padronizados
+- Desenvolvimento de software em colaboração de equipe
+- Transformação de engenharia de projetos legados
+- Produtos que requerem manutenção de longo prazo
+
+### ❌ Não Adequado Para
+- Validação rápida de protótipo pessoal
+- Projetos exploratórios com requisitos muito incertos
+- Scripts ou ferramentas de uso único
+
+---
+
+## Mais Informações
+
+- **Mapa de Conhecimento dos Agents**: [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 não visa substituir desenvolvedores, mas automatizar as partes tediosas para que as equipes possam se concentrar em trabalho mais valioso.**