speccrew 0.1.12 → 0.2.1

package/docs/GETTING-STARTED.el.md

@@ -361,7 +361,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Συχνές Ερωτήσεις (FAQ)
+## 6. Διαχείριση Προόδου Ροής Εργασίας
+
+Η εικονική ομάδα SpecCrew ακολουθεί έναν αυστηρό μηχανισμό πύλης σταδίων όπου κάθε φάση πρέπει να επιβεβαιωθεί από τον χρήστη πριν προχωρήσει στην επόμενη. Υποστηρίζει επίσης εκτέλεση με συνέχιση — κατά την επανεκκίνηση μετά από διακοπή, συνεχίζει αυτόματα από εκεί που σταμάτησε.
+
+### 6.1 Αρχεία Προόδου Τριών Επιπέδων
+
+Η ροή εργασίας διατηρεί αυτόματα τρία είδη αρχείων προόδου JSON, που βρίσκονται στον κατάλογο επανάληψης:
+
+| Αρχείο | Τοποθεσία | Σκοπός |
+|--------|-----------|--------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Καταγράφει την κατάσταση κάθε σταδίου αγωγού |
+| `.checkpoints.json` | Κάτω από κάθε κατάλογο φάσης | Καταγράφει την κατάσταση επιβεβαίωσης σημείου ελέγχου χρήστη |
+| `DISPATCH-PROGRESS.json` | Κάτω από κάθε κατάλογο φάσης | Καταγράφει την πρόοδο ανά αντικείμενο για παράλληλες εργασίες (πολλαπλές πλατφόρμες/πολλαπλές μονάδες) |
+
+### 6.2 Ροή Κατάστασης Σταδίου
+
+Κάθε φάση ακολουθεί αυτή τη ροή κατάστασης:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Δεν έχει ξεκινήσει ακόμα
+- **in_progress**: Εκτελείται επί του παρόντος
+- **completed**: Η εκτέλεση του Agent ολοκληρώθηκε, αναμονή επιβεβαίωσης χρήστη
+- **confirmed**: Ο χρήστης επιβεβαίωσε μέσω του τελικού σημείου ελέγχου, η επόμενη φάση μπορεί να ξεκινήσει
+
+### 6.3 Εκτέλεση με Συνέχιση
+
+Κατά την επανεκκίνηση ενός Agent για μια φάση:
+
+1. **Αυτόματος έλεγχος ανάντη**: Επαληθεύει αν η προηγούμενη φάση έχει επιβεβαιωθεί, μπλοκάρει και προτρέπει αν όχι
+2. **Ανάκτηση σημείου ελέγχου**: Διαβάζει το `.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 Οπίσθια Συμβατότητα
+
+Ο μηχανισμός αρχείων προόδου είναι πλήρως συμβατός προς τα πίσω — αν τα αρχεία προόδου δεν υπάρχουν (π.χ. σε παλιά έργα ή νέες επαναλήψεις), όλοι οι Agents θα εκτελούνται κανονικά σύμφωνα με την αρχική λογική.
+
+---
+
+## 7. Συχνές Ερωτήσεις (FAQ)
 
 ### Ε1: Τι να κάνω αν ο Agent δεν λειτουργεί όπως αναμένεται;
 
@@ -389,8 +449,22 @@ iterations/
 
 ### Ε4: Πώς να ενημερώσω την έκδοση SpecCrew;
 
-- **Καθολική Ενημέρωση**: `npm update -g speccrew`
-- **Ενημέρωση Έργου**: Εκτελέστε `speccrew update` στον κατάλογο του έργου
+Η ενημέρωση γίνεται σε δύο βήματα:
+
+```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` δεν θα ενημερώσει τα αρχεία στο έργο.
 
 ### Ε5: Πώς να δω ιστορικές επαναλήψεις;
 
@@ -405,7 +479,7 @@ iterations/
 
 ---
 
-## 7. Γρήγορη Αναφορά
+## 8. Γρήγορη Αναφορά
 
 ### Γρήγορη Αναφορά Εκκίνησης Agent
 

package/docs/GETTING-STARTED.en.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Frequently Asked Questions (FAQ)
+## 6. Workflow Progress Management
+
+The SpecCrew virtual team follows a strict stage-gating mechanism where each phase must be confirmed by the user before proceeding to the next. It also supports resumable execution — when restarted after interruption, it automatically continues from where it left off.
+
+### 6.1 Three-Layer Progress Files
+
+The workflow automatically maintains three types of JSON progress files, located in the iteration directory:
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Records the status of each pipeline stage |
+| `.checkpoints.json` | Under each phase directory | Records user checkpoint confirmation status |
+| `DISPATCH-PROGRESS.json` | Under each phase directory | Records item-by-item progress for parallel tasks (multi-platform/multi-module) |
+
+### 6.2 Stage Status Flow
+
+Each phase follows this status flow:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Not yet started
+- **in_progress**: Currently executing
+- **completed**: Agent execution completed, awaiting user confirmation
+- **confirmed**: User confirmed through final checkpoint, next phase can start
+
+### 6.3 Resumable Execution
+
+When restarting an Agent for a phase:
+
+1. **Automatic upstream check**: Verifies if the previous phase is confirmed, blocks and prompts if not
+2. **Checkpoint recovery**: Reads `.checkpoints.json`, skips passed checkpoints, continues from the last interruption point
+3. **Parallel task recovery**: Reads `DISPATCH-PROGRESS.json`, only re-executes tasks with `pending` or `failed` status, skips `completed` tasks
+
+### 6.4 Viewing Current Progress
+
+View the pipeline panorama status through the Team Leader Agent:
+
+```
+@speccrew-team-leader view current iteration progress
+```
+
+The Team Leader will read the progress files and display a status overview similar to:
+
+```
+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 Backward Compatibility
+
+The progress file mechanism is fully backward compatible — if progress files do not exist (e.g., in legacy projects or new iterations), all Agents will execute normally according to the original logic.
+
+---
+
+## 7. Frequently Asked Questions (FAQ)
 
 ### Q1: What if the Agent doesn't work as expected?
 
@@ -388,8 +448,22 @@ Each iteration is completely isolated and does not affect others.
 
 ### Q4: How to update SpecCrew version?
 
-- **Global Update**: `npm update -g speccrew`
-- **Project Update**: Run `speccrew update` in the project directory
+Update requires two steps:
+
+```bash
+# Step 1: Update the global CLI tool
+npm install -g speccrew@latest
+
+# Step 2: Sync Agents and Skills in your project directory
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Updates the CLI tool itself (new versions may include new Agent/Skill definitions, bug fixes, etc.)
+- `speccrew update`: Syncs Agent and Skill definition files in your project to the latest version
+- `speccrew update --ide cursor`: Updates configuration for a specific IDE only
+
+> **Note**: Both steps are required. Running only `speccrew update` will not update the CLI tool itself; running only `npm install` will not update project files.
 
 ### Q5: How to view historical iterations?
 
@@ -404,7 +478,7 @@ Re-initialization is required in the following situations:
 
 ---
 
-## 7. Quick Reference
+## 8. Quick Reference
 
 ### Agent Start Quick Reference
 

package/docs/GETTING-STARTED.es.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Preguntas Frecuentes (FAQ)
+## 6. Gestión del Progreso del Workflow
+
+El equipo virtual de SpecCrew sigue un estricto mecanismo de validación por etapas donde cada fase debe ser confirmada por el usuario antes de proceder a la siguiente. También soporta ejecución reanudable — al reiniciar después de una interrupción, continúa automáticamente desde donde se detuvo.
+
+### 6.1 Archivos de Progreso de Tres Niveles
+
+El workflow mantiene automáticamente tres tipos de archivos de progreso JSON, ubicados en el directorio de iteración:
+
+| Archivo | Ubicación | Propósito |
+|---------|-----------|----------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registra el estado de cada etapa del pipeline |
+| `.checkpoints.json` | Bajo cada directorio de fase | Registra el estado de confirmación de checkpoints del usuario |
+| `DISPATCH-PROGRESS.json` | Bajo cada directorio de fase | Registra el progreso elemento por elemento para tareas paralelas (multiplataforma/multimódulo) |
+
+### 6.2 Flujo de Estado de las Etapas
+
+Cada fase sigue este flujo de estado:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Aún no iniciado
+- **in_progress**: Actualmente en ejecución
+- **completed**: Ejecución del Agent completada, esperando confirmación del usuario
+- **confirmed**: Confirmado por el usuario a través del checkpoint final, la siguiente fase puede iniciar
+
+### 6.3 Ejecución Reanudable
+
+Al reiniciar un Agent para una fase:
+
+1. **Verificación automática ascendente**: Verifica si la fase anterior está confirmada, bloquea y notifica si no lo está
+2. **Recuperación de checkpoints**: Lee `.checkpoints.json`, omite los checkpoints superados, continúa desde el último punto de interrupción
+3. **Recuperación de tareas paralelas**: Lee `DISPATCH-PROGRESS.json`, solo reejecuta tareas con estado `pending` o `failed`, omite tareas `completed`
+
+### 6.4 Ver el Progreso Actual
+
+Ver el estado panorámico del pipeline a través del Agent Team Leader:
+
+```
+@speccrew-team-leader ver progreso de iteración actual
+```
+
+El Team Leader leerá los archivos de progreso y mostrará un resumen de estado 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 Compatibilidad hacia atrás
+
+El mecanismo de archivos de progreso es completamente retrocompatible — si los archivos de progreso no existen (por ejemplo, en proyectos heredados o nuevas iteraciones), todos los Agents se ejecutarán normalmente según la lógica original.
+
+---
+
+## 7. Preguntas Frecuentes (FAQ)
 
 ### P1: ¿Qué hacer si el Agente no funciona como se espera?
 
@@ -388,8 +448,22 @@ Cada iteración está completamente aislada y no afecta a las demás.
 
 ### P4: ¿Cómo actualizar la versión de SpecCrew?
 
-- **Actualización Global**: `npm update -g speccrew`
-- **Actualización de Proyecto**: Ejecute `speccrew update` en el directorio del proyecto
+La actualización se realiza en dos pasos:
+
+```bash
+# Paso 1: Actualizar la herramienta CLI global
+npm install -g speccrew@latest
+
+# Paso 2: Sincronizar Agents y Skills en el directorio del proyecto
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Actualiza la herramienta CLI en sí (la nueva versión puede contener nuevas definiciones de Agent/Skill, correcciones de errores, etc.)
+- `speccrew update`: Sincroniza los archivos de definición de Agent y Skill en el proyecto a la última versión
+- `speccrew update --ide cursor`: Actualiza solo la configuración del IDE especificado
+
+> **Nota**: Ambos pasos deben ejecutarse. Ejecutar solo `speccrew update` no actualizará la herramienta CLI en sí; ejecutar solo `npm install` no actualizará los archivos en el proyecto.
 
 ### P5: ¿Cómo ver iteraciones históricas?
 
@@ -404,7 +478,7 @@ Se requiere reinicialización en las siguientes situaciones:
 
 ---
 
-## 7. Referencia Rápida
+## 8. Referencia Rápida
 
 ### Referencia Rápida de Inicio de Agentes
 

package/docs/GETTING-STARTED.fr.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Questions Fréquemment Posées (FAQ)
+## 6. Gestion de la Progression du Workflow
+
+L'équipe virtuelle SpecCrew suit un mécanisme strict de validation par étapes où chaque phase doit être confirmée par l'utilisateur avant de passer à la suivante. Elle prend également en charge l'exécution repreneable — lors du redémarrage après interruption, elle continue automatiquement là où elle s'était arrêtée.
+
+### 6.1 Fichiers de Progression à Trois Niveaux
+
+Le workflow maintient automatiquement trois types de fichiers de progression JSON, situés dans le répertoire d'itération :
+
+| Fichier | Emplacement | Objectif |
+|---------|-------------|----------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Enregistre le statut de chaque étape du pipeline |
+| `.checkpoints.json` | Sous chaque répertoire de phase | Enregistre le statut de confirmation des points de contrôle utilisateur |
+| `DISPATCH-PROGRESS.json` | Sous chaque répertoire de phase | Enregistre la progression élément par élément pour les tâches parallèles (multi-plateforme/multi-module) |
+
+### 6.2 Flux de Statut des Étapes
+
+Chaque phase suit ce flux de statut :
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending** : Pas encore démarré
+- **in_progress** : En cours d'exécution
+- **completed** : Exécution de l'Agent terminée, en attente de confirmation utilisateur
+- **confirmed** : Confirmé par l'utilisateur via le checkpoint final, la phase suivante peut démarrer
+
+### 6.3 Exécution Repreneable
+
+Lors du redémarrage d'un Agent pour une phase :
+
+1. **Vérification automatique en amont** : Vérifie si la phase précédente est confirmée, bloque et invite si ce n'est pas le cas
+2. **Récupération des checkpoints** : Lit `.checkpoints.json`, ignore les checkpoints passés, continue depuis le dernier point d'interruption
+3. **Récupération des tâches parallèles** : Lit `DISPATCH-PROGRESS.json`, réexécute uniquement les tâches avec statut `pending` ou `failed`, ignore les tâches `completed`
+
+### 6.4 Consulter la Progression Actuelle
+
+Consulter le statut panoramique du pipeline via l'Agent Team Leader :
+
+```
+@speccrew-team-leader voir la progression de l'itération actuelle
+```
+
+Le Team Leader lira les fichiers de progression et affichera un aperçu du statut similaire à :
+
+```
+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 Compatibilité Ascendante
+
+Le mécanisme de fichiers de progression est entièrement rétrocompatible — si les fichiers de progression n'existent pas (par exemple, dans les projets existants ou les nouvelles itérations), tous les Agents s'exécuteront normalement selon la logique originale.
+
+---
+
+## 7. Questions Fréquemment Posées (FAQ)
 
 ### Q1 : Que faire si l'Agent ne fonctionne pas comme prévu ?
 
@@ -388,8 +448,22 @@ Chaque itération est complètement isolée et n'affecte pas les autres.
 
 ### Q4 : Comment mettre à jour la version de SpecCrew ?
 
-- **Mise à jour Globale** : `npm update -g speccrew`
-- **Mise à jour du Projet** : Exécuter `speccrew update` dans le répertoire du projet
+La mise à jour se fait en deux étapes :
+
+```bash
+# Étape 1 : Mettre à jour l'outil CLI global
+npm install -g speccrew@latest
+
+# Étape 2 : Synchroniser les Agents et Skills dans le répertoire du projet
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest` : Met à jour l'outil CLI lui-même (la nouvelle version peut contenir de nouvelles définitions Agent/Skill, des corrections de bugs, etc.)
+- `speccrew update` : Synchronise les fichiers de définition Agent et Skill du projet vers la dernière version
+- `speccrew update --ide cursor` : Met à jour uniquement la configuration de l'IDE spécifié
+
+> **Remarque** : Les deux étapes doivent être exécutées. Exécuter uniquement `speccrew update` ne mettra pas à jour l'outil CLI lui-même ; exécuter uniquement `npm install` ne mettra pas à jour les fichiers dans le projet.
 
 ### Q5 : Comment consulter les itérations historiques ?
 
@@ -404,7 +478,7 @@ La réinitialisation est nécessaire dans les situations suivantes :
 
 ---
 
-## 7. Référence Rapide
+## 8. Référence Rapide
 
 ### Référence Rapide de Démarrage Agent
 

package/docs/GETTING-STARTED.it.md

@@ -360,7 +360,67 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Domande Frequenti (FAQ)
+## 6. Gestione del Progresso del Workflow
+
+Il team virtuale SpecCrew segue un rigoroso meccanismo di validazione a stadi in cui ogni fase deve essere confermata dall'utente prima di procedere alla successiva. Supporta anche l'esecuzione riprendibile — al riavvio dopo un'interruzione, continua automaticamente da dove si era fermato.
+
+### 6.1 File di Progresso a Tre Livelli
+
+Il workflow mantiene automaticamente tre tipi di file di progresso JSON, situati nella directory di iterazione:
+
+| File | Posizione | Scopo |
+|------|-----------|-------|
+| `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registra lo stato di ogni fase del pipeline |
+| `.checkpoints.json` | Sotto ogni directory di fase | Registra lo stato di conferma dei checkpoint utente |
+| `DISPATCH-PROGRESS.json` | Sotto ogni directory di fase | Registra il progresso elemento per elemento per task paralleli (multi-piattaforma/multi-modulo) |
+
+### 6.2 Flusso di Stato delle Fasi
+
+Ogni fase segue questo flusso di stato:
+
+```
+pending → in_progress → completed → confirmed
+```
+
+- **pending**: Non ancora avviato
+- **in_progress**: Attualmente in esecuzione
+- **completed**: Esecuzione Agent completata, in attesa di conferma utente
+- **confirmed**: Confermato dall'utente tramite checkpoint finale, la fase successiva può iniziare
+
+### 6.3 Esecuzione Riprendibile
+
+Al riavvio di un Agent per una fase:
+
+1. **Verifica automatica a monte**: Verifica se la fase precedente è confermata, blocca e notifica se non lo è
+2. **Recupero checkpoint**: Legge `.checkpoints.json`, salta i checkpoint superati, continua dall'ultimo punto di interruzione
+3. **Recupero task paralleli**: Legge `DISPATCH-PROGRESS.json`, riesegue solo i task con stato `pending` o `failed`, salta i task `completed`
+
+### 6.4 Visualizzare il Progresso Attuale
+
+Visualizzare lo stato panoramico del pipeline tramite l'Agent Team Leader:
+
+```
+@speccrew-team-leader visualizzare il progresso dell'iterazione corrente
+```
+
+Il Team Leader leggerà i file di progresso e mostrerà un riepilogo dello stato simile 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 Compatibilità all'Indietro
+
+Il meccanismo dei file di progresso è completamente retrocompatibile — se i file di progresso non esistono (ad esempio, in progetti legacy o nuove iterazioni), tutti gli Agent verranno eseguiti normalmente secondo la logica originale.
+
+---
+
+## 7. Domande Frequenti (FAQ)
 
 ### Q1: Cosa fare se l'Agent non funziona come previsto?
 
@@ -388,8 +448,22 @@ Ogni iterazione è completamente isolata e non influenza le altre.
 
 ### Q4: Come aggiornare la versione di SpecCrew?
 
-- **Aggiornamento Globale**: `npm update -g speccrew`
-- **Aggiornamento Progetto**: Eseguire `speccrew update` nella directory del progetto
+L'aggiornamento avviene in due passaggi:
+
+```bash
+# Passaggio 1: Aggiornare lo strumento CLI globale
+npm install -g speccrew@latest
+
+# Passaggio 2: Sincronizzare Agent e Skill nella directory del progetto
+cd /path/to/your-project
+speccrew update
+```
+
+- `npm install -g speccrew@latest`: Aggiorna lo strumento CLI stesso (la nuova versione può contenere nuove definizioni Agent/Skill, correzioni di bug, ecc.)
+- `speccrew update`: Sincronizza i file di definizione Agent e Skill nel progetto all'ultima versione
+- `speccrew update --ide cursor`: Aggiorna solo la configurazione dell'IDE specificato
+
+> **Nota**: Entrambi i passaggi devono essere eseguiti. Eseguire solo `speccrew update` non aggiornerà lo strumento CLI stesso; eseguire solo `npm install` non aggiornerà i file nel progetto.
 
 ### Q5: Come visualizzare le iterazioni storiche?
 
@@ -404,7 +478,7 @@ La re-inizializzazione è necessaria nelle seguenti situazioni:
 
 ---
 
-## 7. Riferimento Rapido
+## 8. Riferimento Rapido
 
 ### Riferimento Rapido Avvio Agent
 

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を実行：プロジェクト診断とナレッジベース初期化