speccrew 0.1.11 → 0.2.0

package/docs/GETTING-STARTED.ja.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. よくある質問（FAQ）
+## 6. パイプライン進捗管理
+
+SpecCrew 仮想チームは厳密なフェーズゲートメカニズムに従い、各フェーズはユーザー確認後に次のフェーズに進む必要があります。また、ブレークポイントレジュームをサポート —— 中断後に再起動すると、自動的に前回停止した位置から継続します。
+
+### 6.1 三層進捗ファイル
+
+ワークフローは自動的に3種類の JSON 進捗ファイルを維持し、イテレーションディレクトリに配置されます：
+
+| ファイル | 位置 | 役割 |
+|------|------|------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | パイプライン全体の各フェーズ状態を記録 |
+| `.checkpoints.json` | 各フェーズディレクトリ下 | ユーザーチェックポイント（Checkpoint）の通過状態を記録 |
+| `DISPATCH-PROGRESS.json` | 各フェーズディレクトリ下 | 並行タスク（複数プラットフォーム/モジュール）の個別進捗を記録 |
+
+### 6.2 フェーズ状態の遷移
+
+各フェーズは以下の状態遷移に従います：
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**：未開始
+- **in_progress**：実行中
+- **completed**：Agent 実行完了、ユーザー確認待ち
+- **confirmed**：ユーザーが最終 Checkpoint を確認、次のフェーズを開始可能
+
+### 6.3 ブレークポイントレジューム
+
+あるフェーズの Agent を再起動すると：
+
+1. **上流の自動チェック**：前のフェーズが confirmed されているか検証、未確認の場合はブロックして警告
+2. **Checkpoint の復元**：`.checkpoints.json` を読み込み、通過済みの確認ポイントをスキップし、前回の中断位置から継続
+3. **並行タスクの復元**：`DISPATCH-PROGRESS.json` を読み込み、`pending` または `failed` 状態のタスクのみ再実行、既に `completed` のタスクはスキップ
+
+### 6.4 現在の進捗を確認
+
+Team Leader Agent を通じてパイプラインの全体状態を確認：
+
+```
+@speccrew-team-leader 現在のイテレーション進捗を確認
+```
+
+Team Leader は進捗ファイルを読み込み、以下のような状態概要を表示します：
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Confirmed
+  02 Feature Design: 🔄 In Progress (Checkpoint A passed)
+  03 System Design:  ⏳ Pending
+  04 Development:    ⏳ Pending
+  05 System Test:    ⏳ Pending
+```
+
+### 6.5 下位互換性
+
+進捗ファイルメカニズムは完全に下位互換 —— 進捗ファイルが存在しない場合（古いプロジェクトや新規イテレーションなど）、すべての Agent は元のロジックで正常に実行されます。
+
+---
+
+## 7. よくある質問（FAQ）
 
 ### Q1: エージェントが期待通りに動作しない場合は？
 
@@ -388,8 +448,22 @@ iterations/
 
 ### Q4: SpecCrewのバージョンを更新するには？
 
-- **グローバル更新**：`npm update -g speccrew`
-- **プロジェクト更新**：プロジェクトディレクトリで`speccrew update`を実行
+更新は2つのステップで行います：
+
+```bash
+# ステップ1：グローバルCLIツールを更新
+npm install -g speccrew@latest
+
+# ステップ2：プロジェクトディレクトリでAgentsとSkillsを同期
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`：CLIツール自体を更新（新バージョンには新しいAgent/Skill定義、バグ修正などが含まれる場合があります）
+- `speccrew update`：プロジェクトのAgentおよびSkill定義ファイルを最新バージョンに同期
+- `speccrew update --ide cursor`：指定したIDEの設定のみを更新
+
+> **注意**：両方のステップを実行する必要があります。`speccrew update`のみを実行してもCLIツール自体は更新されません；`npm install`のみを実行してもプロジェクト内のファイルは更新されません。
 
 ### Q5: 過去のイテレーションを表示するには？
 
@@ -404,7 +478,7 @@ iterations/
 
 ---
 
-## 7. クイックリファレンス
+## 8. クイックリファレンス
 
 ### エージェント起動クイックリファレンス表
 
@@ -441,7 +515,7 @@ iterations/
 
 ---
 
-## 次のステップ
+## 9. 次のステップ
 
 1. `speccrew init --ide qoder`を実行してプロジェクトを初期化
 2. ステップ0を実行：プロジェクト診断とナレッジベース初期化

package/docs/GETTING-STARTED.ko.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. 자주 묻는 질문 (FAQ)
+## 6. 파이프라인 진도 관리
+
+SpecCrew 가상 팀은 엄격한 단계 게이트 메커니즘을 따륾며, 각 단계는 사용자 확인 후에야 다음 단계로 진행할 수 있습니다. 또한 중단점 재개를 지원 —— 중단 후 다시 시작하면 자동으로 마지막으로 중단된 위치에서 계속합니다.
+
+### 6.1 3계층 진도 파일
+
+워크플로우는 자동으로 3가지 유형의 JSON 진도 파일을 유지하며, 반복 디렉토리에 위치합니다:
+
+| 파일 | 위치 | 역할 |
+|---------|----------|------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | 전체 파이프라인의 각 단계 상태 기록 |
+| `.checkpoints.json` | 각 단계 디렉토리 하위 | 사용자 확인점(Checkpoint) 통과 상태 기록 |
+| `DISPATCH-PROGRESS.json` | 각 단계 디렉토리 하위 | 병렬 작업(다중 플랫폼/모듈)의 개별 진도 기록 |
+
+### 6.2 단계 상태 전환
+
+각 단계는 다음 상태 전환을 따릅니다:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: 아직 시작되지 않음
+- **in_progress**: 실행 중
+- **completed**: Agent 실행 완료, 사용자 확인 대기 중
+- **confirmed**: 사용자가 최종 Checkpoint 확인, 다음 단계 시작 가능
+
+### 6.3 중단점 재개
+
+특정 단계의 Agent를 다시 시작할 때:
+
+1. **상위 자동 확인**: 이전 단계가 confirmed되었는지 검증, 확인되지 않은 경우 차단하고 알림
+2. **Checkpoint 복원**: `.checkpoints.json`을 읽고, 통과한 확인점을 건ㄴ 뛰고, 마지막 중단 위치에서 계속
+3. **병렬 작업 복원**: `DISPATCH-PROGRESS.json`을 읽고, `pending` 또는 `failed` 상태의 작업만 다시 실행, 이미 `completed`된 작업은 건ㄴ 뛰기
+
+### 6.4 현재 진도 확인
+
+Team Leader Agent를 통해 파이프라인 전체 상태 확인:
+
+```
+@speccrew-team-leader 현재 반복 진도 확인
+```
+
+Team Leader는 진도 파일을 읽고 다음과 유사한 상태 요약을 표시합니다:
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Confirmed
+  02 Feature Design: 🔄 In Progress (Checkpoint A passed)
+  03 System Design:  ⏳ Pending
+  04 Development:    ⏳ Pending
+  05 System Test:    ⏳ Pending
+```
+
+### 6.5 하위 호환성
+
+진도 파일 메커니즘은 완전히 하위 호환 —— 진도 파일이 존재하지 않는 경우(예: 이전 프로젝트 또는 새로운 반복), 모든 Agent는 원래 로직에 따라 정상적으로 실행됩니다.
+
+---
+
+## 7. 자주 묻는 질문 (FAQ)
 
 ### Q1: Agent가 예상대로 작동하지 않으면 어떻게 하나요?
 
@@ -388,8 +448,22 @@ iterations/
 
 ### Q4: SpecCrew 버전을 업데이트하려면 어떻게 하나요?
 
-- **전역 업데이트**: `npm update -g speccrew`
-- **프로젝트 업데이트**: 프로젝트 디렉토리에서 `speccrew update` 실행
+업데이트는 두 단계가 필요합니다:
+
+```bash
+# 1단계: 전역 CLI 도구 업데이트
+npm install -g speccrew@latest
+
+# 2단계: 프로젝트 디렉토리에서 Agent와 Skill 동기화
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: CLI 도구 자체를 업데이트합니다 (새 버전에는 새로운 Agent/Skill 정의, 버그 수정 등이 포함될 수 있음)
+- `speccrew update`: 프로젝트의 Agent 및 Skill 정의 파일을 최신 버전으로 동기화합니다
+- `speccrew update --ide cursor`: 특정 IDE에 대해서만 구성을 업데이트합니다
+
+> **참고**: 두 단계 모두 필요합니다. `speccrew update`만 실행하면 CLI 도구 자체가 업데이트되지 않으며, `npm install`만 실행하면 프로젝트 파일이 업데이트되지 않습니다.
 
 ### Q5: 과거 반복을 보려면 어떻게 하나요?
 
@@ -404,7 +478,7 @@ iterations/
 
 ---
 
-## 7. 빠른 참조
+## 8. 빠른 참조
 
 ### Agent 시작 빠른 참조
 
@@ -441,7 +515,7 @@ iterations/
 
 ---
 
-## 다음 단계
+## 9. 다음 단계
 
 1. `speccrew init --ide qoder`를 실행하여 프로젝트 초기화
 2. 0단계 실행: 프로젝트 진단 및 지식 기반 초기화

package/docs/GETTING-STARTED.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. 常见问题（FAQ）
+## 6. 流水线进度管理
+
+SpecCrew 虚拟团队遵循严格的阶段门控机制，每个阶段必须经过用户确认后才能推进到下一阶段。同时支持断点续传 —— 中断后重新启动时，自动从上次停止的位置继续。
+
+### 6.1 三层进度文件
+
+工作流自动维护三类 JSON 进度文件，位于迭代目录下：
+
+| 文件 | 位置 | 作用 |
+|------|------|------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | 记录整条流水线各阶段状态 |
+| `.checkpoints.json` | 各阶段目录下 | 记录用户确认点（Checkpoint）通过状态 |
+| `DISPATCH-PROGRESS.json` | 各阶段目录下 | 记录并行任务（多平台/多模块）的逐项进度 |
+
+### 6.2 阶段状态流转
+
+每个阶段遵循以下状态流转：
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**：尚未开始
+- **in_progress**：正在执行中
+- **completed**：Agent 执行完成，等待用户确认
+- **confirmed**：用户通过最终 Checkpoint 确认，下一阶段可以启动
+
+### 6.3 断点续传
+
+当重新启动某个阶段的 Agent 时：
+
+1. **自动检查上游**：验证前一阶段是否已 confirmed，未确认则阻塞并提示
+2. **恢复 Checkpoint**：读取 `.checkpoints.json`，跳过已通过的确认点，从上次中断处继续
+3. **恢复并行任务**：读取 `DISPATCH-PROGRESS.json`，只重新执行 `pending` 或 `failed` 状态的任务，跳过已 `completed` 的任务
+
+### 6.4 查看当前进度
+
+通过 Team Leader Agent 查看流水线全景状态：
+
+```
+@speccrew-team-leader 查看当前迭代进度
+```
+
+Team Leader 会读取进度文件并展示类似以下的状态概览：
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Confirmed
+  02 Feature Design: 🔄 In Progress (Checkpoint A passed)
+  03 System Design:  ⏳ Pending
+  04 Development:    ⏳ Pending
+  05 System Test:    ⏳ Pending
+```
+
+### 6.5 向下兼容
+
+进度文件机制完全向下兼容 —— 如果进度文件不存在（如旧项目或全新迭代），所有 Agent 将按照原有逻辑正常执行。
+
+---
+
+## 7. 常见问题（FAQ）
 
 ### Q1: Agent 不按预期工作怎么办？
 
@@ -388,8 +448,22 @@ iterations/
 
 ### Q4: 如何更新 SpecCrew 版本？
 
-- **全局更新**：`npm update -g speccrew`
-- **项目更新**：在项目目录执行 `speccrew update`
+更新分为两步：
+
+```bash
+# Step 1: 更新全局 CLI 工具
+npm install -g speccrew@latest
+
+# Step 2: 在项目目录中同步 Agents 和 Skills
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`：更新 CLI 工具本身（新版本可能包含新的 Agent/Skill 定义、Bug 修复等）
+- `speccrew update`：将项目中的 Agent 和 Skill 定义文件同步到最新版本
+- `speccrew update --ide cursor`：仅更新指定 IDE 的配置
+
+> **注意**：两步都需要执行。仅执行 `speccrew update` 不会更新 CLI 工具本身；仅执行 `npm install` 不会更新项目中的文件。
 
 ### Q5: 如何查看历史迭代？
 
@@ -404,7 +478,7 @@ iterations/
 
 ---
 
-## 7. 快速参考
+## 8. 快速参考
 
 ### Agent 启动速查表
 

package/docs/GETTING-STARTED.no.md

@@ -361,7 +361,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Ofte Stilte Spørsmål (FAQ)
+## 6. Arbeidsflytforløpsstyring
+
+Det virtuelle SpecCrew-teamet følger en streng fase-port-mekanisme hvor hver fase må bekreftes av brukeren før man fortsetter til den neste. Det støtter også gjenopptakbar utførelse — når det startes på nytt etter avbrudd, fortsetter det automatisk fra hvor det slapp.
+
+### 6.1 Trelagsforløpsfiler
+
+Arbeidsflyten vedlikeholder automatisk tre typer JSON-forløpsfiler, plassert i iterasjonskatalogen:
+
+| Fil | Plassering | Formål |
+|------|----------|---------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registrerer status for hver pipeline-fase |
+| `.checkpoints.json` | Under hver fasekatalog | Registrerer brukerens sjekkpunkt-bekreftelsesstatus |
+| `DISPATCH-PROGRESS.json` | Under hver fasekatalog | Registrerer punkt-for-punkt forløp for parallelle oppgaver (multi-plattform/multi-modul) |
+
+### 6.2 Fasestatusforløp
+
+Hver fase følger dette statusforløpet:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Ikke startet ennå
+- **in_progress**: Utføres for øyeblikket
+- **completed**: Agent-utførelse fullført, venter på brukerbekreftelse
+- **confirmed**: Bruker bekreftet gjennom siste sjekkpunkt, neste fase kan starte
+
+### 6.3 Gjenopptakbar Utførelse
+
+Når en Agent startes på nytt for en fase:
+
+1. **Automatisk oppstrømskontroll**: Verifiserer om den forrige fasen er bekreftet, blokkerer og varsler hvis ikke
+2. **Sjekkpunkt-gjenoppretting**: Leser `.checkpoints.json`, hopper over passerte sjekkpunkter, fortsetter fra det siste avbruddspunktet
+3. **Parallell oppgave-gjenoppretting**: Leser `DISPATCH-PROGRESS.json`, utfører kun oppgaver med `pending` eller `failed` status på nytt, hopper over `completed` oppgaver
+
+### 6.4 Vise Nåværende Forløp
+
+Vis pipeline-panorama-status gjennom Team Leader Agent:
+
+```
+@speccrew-team-leader vis nåværende iterasjonsforløp
+```
+
+Team Leader vil lese forløpsfilene og vise en statusoversikt som ligner på:
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Bekreftet
+  02 Feature Design: 🔄 Pågår (Sjekkpunkt A passert)
+  03 System Design:  ⏳ Avventer
+  04 Development:    ⏳ Avventer
+  05 System Test:    ⏳ Avventer
+```
+
+### 6.5 Bakoverkompatibilitet
+
+Forløpsfil-mekanismen er fullstendig bakoverkompatibel — hvis forløpsfiler ikke finnes (f.eks. i eldre prosjekter eller nye iterasjoner), vil alle Agenter utføre normalt i henhold til den opprinnelige logikken.
+
+---
+
+## 7. Ofte Stilte Spørsmål (FAQ)
 
 ### S1: Hva gjør jeg hvis Agenten ikke fungerer som forventet?
 
@@ -389,8 +449,22 @@ Hver iterasjon er fullstendig isolert og påvirker ikke hverandre.
 
 ### S4: Hvordan oppdatere SpecCrew-versjonen?
 
-- **Global Oppdatering**: `npm update -g speccrew`
-- **Prosjektoppdatering**: Kjør `speccrew update` i prosjektkatalogen
+Oppdatering krever to trinn:
+
+```bash
+# Trinn 1: Oppdater globalt CLI-verktøy
+npm install -g speccrew@latest
+
+# Trinn 2: Synkroniser Agenter og Skills i prosjektkatalogen din
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Oppdaterer selve CLI-verktøyet (nye versjoner kan inkludere nye Agent/Skill-definisjoner, feilrettelser osv.)
+- `speccrew update`: Synkroniserer Agent- og Skill-definisjonsfiler i prosjektet ditt til den nyeste versjonen
+- `speccrew update --ide cursor`: Oppdaterer konfigurasjon kun for en spesifikk IDE
+
+> **Merk**: Begge trinnene er nødvendige. Hvis du bare kjører `speccrew update`, oppdateres ikke selve CLI-verktøyet; hvis du bare kjører `npm install`, oppdateres ikke prosjektfilene.
 
 ### S5: Hvordan se historiske iterasjoner?
 
@@ -405,7 +479,7 @@ Re-initialisering kreves i følgende situasjoner:
 
 ---
 
-## 7. Hurtigreferanse
+## 8. Hurtigreferanse
 
 ### Agent-start Hurtigreferanse
 

package/docs/GETTING-STARTED.pl.md

@@ -361,7 +361,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Często zadawane pytania (FAQ)
+## 6. Zarządzanie Postępem Przepływu Pracy
+
+Wirtualny zespół SpecCrew stosuje ścisły mechanizm bramek fazowych, gdzie każda faza musi zostać potwierdzona przez użytkownika przed przejściem do następnej. Obsługuje również wznawialne wykonywanie — po ponownym uruchomieniu po przerwaniu, automatycznie kontynuuje od miejsca przerwania.
+
+### 6.1 Trójwarstwowe Pliki Postępu
+
+Przepływ pracy automatycznie utrzymuje trzy typy plików postępu JSON, zlokalizowanych w katalogu iteracji:
+
+| Plik | Lokalizacja | Cel |
+|------|----------|---------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Rejestruje status każdego etapu pipeline |
+| `.checkpoints.json` | Pod każdym katalogiem fazy | Rejestruje status potwierdzenia punktów kontrolnych użytkownika |
+| `DISPATCH-PROGRESS.json` | Pod każdym katalogiem fazy | Rejestruje postęp punkt po punkcie dla zadań równoległych (wieloplatformowych/wielomodułowych) |
+
+### 6.2 Przebieg Statusu Fazy
+
+Każda faza podąża za tym przebiegiem statusu:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Jeszcze nie rozpoczęte
+- **in_progress**: Obecnie wykonywane
+- **completed**: Wykonanie Agenta zakończone, oczekiwanie na potwierdzenie użytkownika
+- **confirmed**: Użytkownik potwierdził przez końcowy punkt kontrolny, następna faza może się rozpocząć
+
+### 6.3 Wznawialne Wykonywanie
+
+Podczas ponownego uruchamiania Agenta dla fazy:
+
+1. **Automatyczna kontrola upstream**: Weryfikuje czy poprzednia faza jest potwierdzona, blokuje i informuje jeśli nie
+2. **Odzyskiwanie punktów kontrolnych**: Odczytuje `.checkpoints.json`, pomija przekroczone punkty kontrolne, kontynuuje od ostatniego punktu przerwania
+3. **Odzyskiwanie zadań równoległych**: Odczytuje `DISPATCH-PROGRESS.json`, ponownie wykonuje tylko zadania ze statusem `pending` lub `failed`, pomija zadania `completed`
+
+### 6.4 Wyświetlanie Bieżącego Postępu
+
+Wyświetl status panoramy pipeline przez Agenta Team Leader:
+
+```
+@speccrew-team-leader wyświetl bieżący postęp iteracji
+```
+
+Team Leader odczyta pliki postępu i wyświetli podsumowanie statusu podobne do:
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Potwierdzone
+  02 Feature Design: 🔄 W toku (Punkt kontrolny A przekroczony)
+  03 System Design:  ⏳ Oczekujące
+  04 Development:    ⏳ Oczekujące
+  05 System Test:    ⏳ Oczekujące
+```
+
+### 6.5 Wsteczna Kompatybilność
+
+Mechanizm plików postępu jest w pełni wstecznie kompatybilny — jeśli pliki postępu nie istnieją (np. w starszych projektach lub nowych iteracjach), wszyscy Agenci będą wykonywać normalnie zgodnie z oryginalną logiką.
+
+---
+
+## 7. Często zadawane pytania (FAQ)
 
 ### P1: Co zrobić, jeśli Agent nie działa zgodnie z oczekiwaniami?
 
@@ -389,8 +449,22 @@ Każda iteracja jest całkowicie izolowana i nie wpływa na inne.
 
 ### P4: Jak zaktualizować wersję SpecCrew?
 
-- **Aktualizacja globalna**: `npm update -g speccrew`
-- **Aktualizacja projektu**: Uruchom `speccrew update` w katalogu projektu
+Aktualizacja wymaga dwóch kroków:
+
+```bash
+# Krok 1: Zaktualizuj globalne narzędzie CLI
+npm install -g speccrew@latest
+
+# Krok 2: Zsynchronizuj Agentów i Skille w katalogu projektu
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Aktualizuje samo narzędzie CLI (nowe wersje mogą zawierać nowe definicje Agentów/Skilli, poprawki błędów itp.)
+- `speccrew update`: Synchronizuje pliki definicji Agentów i Skilli w projekcie do najnowszej wersji
+- `speccrew update --ide cursor`: Aktualizuje konfigurację tylko dla konkretnego IDE
+
+> **Uwaga**: Oba kroki są wymagane. Uruchomienie tylko `speccrew update` nie zaktualizuje samego narzędzia CLI; uruchomienie tylko `npm install` nie zaktualizuje plików projektu.
 
 ### P5: Jak wyświetlić historyczne iteracje?
 
@@ -405,7 +479,7 @@ Ponowna inicjalizacja jest wymagana w następujących sytuacjach:
 
 ---
 
-## 7. Szybka referencja
+## 8. Szybka referencja
 
 ### Szybka referencja uruchamiania Agentów
 

package/docs/GETTING-STARTED.pt-BR.md

@@ -361,7 +361,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Perguntas Frequentes (FAQ)
+## 6. Gestão do Progresso do Workflow
+
+A equipe virtual SpecCrew segue um rigoroso mecanismo de validação por estágios onde cada fase deve ser confirmada pelo usuário antes de prosseguir para a próxima. Também suporta execução retomável — ao reiniciar após interrupção, continua automaticamente de onde parou.
+
+### 6.1 Arquivos de Progresso de Três Níveis
+
+O workflow mantém automaticamente três tipos de arquivos de progresso JSON, localizados no diretório de iteração:
+
+| Arquivo | Localização | Propósito |
+|---------|-------------|----------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registra o status de cada estágio do pipeline |
+| `.checkpoints.json` | Sob cada diretório de fase | Registra o status de confirmação dos checkpoints do usuário |
+| `DISPATCH-PROGRESS.json` | Sob cada diretório de fase | Registra o progresso item por item para tarefas paralelas (multiplataforma/multimódulo) |
+
+### 6.2 Fluxo de Status dos Estágios
+
+Cada fase segue este fluxo de status:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Ainda não iniciado
+- **in_progress**: Atualmente em execução
+- **completed**: Execução do Agent concluída, aguardando confirmação do usuário
+- **confirmed**: Confirmado pelo usuário através do checkpoint final, a próxima fase pode iniciar
+
+### 6.3 Execução Retomável
+
+Ao reiniciar um Agent para uma fase:
+
+1. **Verificação automática ascendente**: Verifica se a fase anterior está confirmada, bloqueia e notifica se não estiver
+2. **Recuperação de checkpoints**: Lê `.checkpoints.json`, ignora checkpoints passados, continua do último ponto de interrupção
+3. **Recuperação de tarefas paralelas**: Lê `DISPATCH-PROGRESS.json`, reexecuta apenas tarefas com status `pending` ou `failed`, ignora tarefas `completed`
+
+### 6.4 Visualizar o Progresso Atual
+
+Visualizar o status panorâmico do pipeline através do Agent Team Leader:
+
+```
+@speccrew-team-leader visualizar progresso da iteração atual
+```
+
+O Team Leader lerá os arquivos de progresso e exibirá um resumo do status similar a:
+
+```
+Pipeline Status: i001-user-management
+  01 PRD:            ✅ Confirmed
+  02 Feature Design: 🔄 In Progress (Checkpoint A passed)
+  03 System Design:  ⏳ Pending
+  04 Development:    ⏳ Pending
+  05 System Test:    ⏳ Pending
+```
+
+### 6.5 Compatibilidade com Versões Anteriores
+
+O mecanismo de arquivos de progresso é totalmente retrocompatível — se os arquivos de progresso não existirem (por exemplo, em projetos legados ou novas iterações), todos os Agents serão executados normalmente de acordo com a lógica original.
+
+---
+
+## 7. Perguntas Frequentes (FAQ)
 
 ### P1: O que fazer se o Agente não funcionar como esperado?
 
@@ -389,8 +449,22 @@ Cada iteração está completamente isolada e não afeta as outras.
 
 ### P4: Como atualizar a versão do SpecCrew?
 
-- **Atualização Global**: `npm update -g speccrew`
-- **Atualização de Projeto**: Execute `speccrew update` no diretório do projeto
+A atualização requer duas etapas:
+
+```bash
+# Etapa 1: Atualizar a ferramenta CLI global
+npm install -g speccrew@latest
+
+# Etapa 2: Sincronizar Agentes e Skills no diretório do projeto
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Atualiza a própria ferramenta CLI (novas versões podem incluir novas definições de Agent/Skill, correções de bugs, etc.)
+- `speccrew update`: Sincroniza os arquivos de definição de Agent e Skill no seu projeto para a versão mais recente
+- `speccrew update --ide cursor`: Atualiza a configuração apenas para um IDE específico
+
+> **Nota**: Ambas as etapas são necessárias. Executar apenas `speccrew update` não atualizará a própria ferramenta CLI; executar apenas `npm install` não atualizará os arquivos do projeto.
 
 ### P5: Como ver iterações históricas?
 
@@ -405,7 +479,7 @@ Reinicialização é necessária nas seguintes situações:
 
 ---
 
-## 7. Referência Rápida
+## 8. Referência Rápida
 
 ### Referência Rápida de Início de Agentes