speccrew 0.1.1 → 0.1.2

package/README.fr.md

@@ -0,0 +1,321 @@
+# SpecCrew - Framework d'Ingénierie Logicielle Piloté par l'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>
+
+> Une équipe de développement IA virtuelle permettant une implémentation d'ingénierie rapide pour tout projet logiciel
+
+## Qu'est-ce que SpecCrew ?
+
+SpecCrew est un framework d'équipe de développement IA virtuelle intégré. Il transforme les flux de travail d'ingénierie logicielle professionnels (PRD → Feature Design → System Design → Dev → Test) en flux de travail Agent réutilisables, aidant les équipes de développement à réaliser le Development piloté par les spécifications (SDD), particulièrement adapté aux projets existants.
+
+En intégrant des Agents et des Skills dans des projets existants, les équipes peuvent rapidement initialiser les systèmes de documentation de projet et les équipes logicielles virtuelles, en implémentant de nouvelles fonctionnalités et modifications selon des flux de travail d'ingénierie standard.
+
+---
+
+## 8 Problèmes Principaux Résolus
+
+### 1. L'IA Ignore la Documentation de Projet Existante (Lacune de Connaissances)
+**Problème** : Les méthodes SDD ou Vibe Coding existantes s'appuient sur l'IA pour résumer les projets en temps réel, manquant facilement le contexte critique et causant des résultats de développement qui s'écartent des attentes.
+
+**Solution** : Le référentiel `knowledge/` sert de "source unique de vérité" du projet, accumulant la conception d'architecture, les modules fonctionnels et les processus métier pour garantir que les exigences restent sur la bonne voie depuis la source.
+
+### 2. Documentation Technique Directe depuis le PRD (Omission de Contenu)
+**Problème** : Passer directement du PRD à la conception détaillée manque facilement les détails des exigences, causant des fonctionnalités implémentées qui s'écartent des exigences.
+
+**Solution** : Introduire la phase de **Document Feature Design**, se concentrant uniquement sur le squelette des exigences sans détails techniques :
+- Quelles pages et composants sont inclus ?
+- Flux d'opérations de page
+- Logique de traitement backend
+- Structure de stockage de données
+
+Le développement doit seulement "remplir la chair" basé sur la pile technologique spécifique, garantissant que les fonctionnalités grandissent "près de l'os (exigences)".
+
+### 3. Portée de Recherche Agent Incertaine (Incertitude)
+**Problème** : Dans les projets complexes, la recherche large de code et de documents par l'IA donne des résultats incertains, rendant la cohérence difficile à garantir.
+
+**Solution** : Des structures de répertoires de documents claires et des modèles, conçus selon les besoins de chaque Agent, implémentant **la divulgation progressive et le chargement à la demande** pour garantir le déterminisme.
+
+### 4. Étapes et Tâches Manquantes (Rupture de Processus)
+**Problème** : Le manque de couverture complète du processus d'ingénierie manque facilement des étapes critiques, rendant la qualité difficile à garantir.
+
+**Solution** : Couvrir tout le cycle de vie de l'ingénierie logicielle :
+```
+PRD (Exigences) → Feature Design (Conception Fonctionnelle) → API Contract (Contrat)
+    → System Design (Conception Système) → Dev (Développement) → Test (Tests)
+```
+- La sortie de chaque phase est l'entrée de la phase suivante
+- Chaque étape nécessite une confirmation humaine avant de procéder
+- Toutes les exécutions d'Agent ont des listes todo avec auto-vérification après achèvement
+
+### 5. Faible Efficacité de Collaboration d'Équipe (Silos de Connaissances)
+**Problème** : L'expérience de programmation IA est difficile à partager entre les équipes, entraînant des erreurs répétées.
+
+**Solution** : Tous les Agents, Skills et documents associés sont versionnés avec le code source :
+- L'optimisation d'une personne est partagée par l'équipe
+- Les connaissances s'accumulent dans la base de code
+- Amélioration de l'efficacité de collaboration d'équipe
+
+### 7. Contexte d'Agent Unique Trop Long (Goulot d'Étranglement de Performance)
+**Problème** : Les tâches complexes importantes dépassent les fenêtres de contexte d'Agent unique, causant des déviations de compréhension et une diminution de la qualité de sortie.
+
+**Solution** : **Mécanisme d'Auto-Répartition de Sous-Agent** :
+- Les tâches complexes sont automatiquement identifiées et divisées en sous-tâches
+- Chaque sous-tâche est exécutée par un sous-Agent indépendant avec un contexte isolé
+- L'Agent parent coordonne et agrège pour assurer la cohérence globale
+- Évite l'expansion du contexte d'Agent unique, garantissant la qualité de sortie
+
+### 8. Chaos d'Itération d'Exigences (Difficulté de Gestion)
+**Problème** : Plusieurs exigences mélangées dans la même branche s'affectent mutuellement, rendant le suivi et la restauration difficiles.
+
+**Solution** : **Chaque Exigence comme Projet Indépendant** :
+- Chaque exigence crée un répertoire d'itération indépendant `iterations/iXXX-[nom-exigence]/`
+- Isolation complète : documents, conception, code et tests gérés indépendamment
+- Itération rapide : livraison à petite granularité, vérification rapide, déploiement rapide
+- Archivage flexible : après achèvement, archivage dans `archive/` avec traçabilité historique claire
+
+### 6. Retard de Mise à Jour des Documents (Décomposition des Connaissances)
+**Problème** : Les documents deviennent obsolètes à mesure que les projets évoluent, faisant travailler l'IA avec des informations incorrectes.
+
+**Solution** : Les Agents ont des capacités de mise à jour automatique des documents, synchronisant les changements de projet en temps réel pour maintenir la base de connaissances précise.
+
+---
+
+## Flux de Travail Principal
+
+```mermaid
+graph LR
+    A[PRD<br/>Document d'Exigences] --> B[Feature Design<br/>Conception Fonctionnelle]
+    B --> C[API Contract<br/>Contrat d'Interface]
+    C --> D[System Design<br/>Conception Système]
+    D --> E[Dev<br/>Implémentation]
+    E --> F[System Test<br/>Tests]
+    F --> G[Archive<br/>Archivage]
+    
+    H[Knowledge<br/>Référentiel] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Descriptions des Phases
+
+| Phase | Agent | Entrée | Sortie | Confirmation Humaine |
+|-------|-------|--------|--------|---------------------|
+| PRD | PM | Exigences Utilisateur | Document d'Exigences Produit | ✅ Requise |
+| Feature Design | Feature Designer | PRD | Document Feature Design + Contrat API | ✅ Requise |
+| System Design | System Designer | Feature Spec | Documents de Conception Frontend/Backend | ✅ Requise |
+| Dev | Dev | Design | Code + Enregistrements de Tâches | ✅ Requise |
+| System Test | Test Manager | Sortie Dev + Feature Spec | Cas de Test + Code de Test + Rapport de Test + Rapport de Bug | ✅ Requise |
+
+---
+
+## Comparaison avec les Solutions Existantes
+
+| Dimension | Vibe Coding | Ralph Loop | **SpecCrew** |
+|-----------|-------------|------------|-------------|
+| Dépendance aux Documents | Ignore les docs existants | S'appuie sur AGENTS.md | **Base de Connaissances Structurée** |
+| Transfert d'Exigences | Codage direct | PRD → Code | **PRD → Feature Design → System Design → Code** |
+| Implication Humaine | Minimale | Au démarrage | **À chaque phase** |
+| Complétude du Processus | Faible | Moyenne | **Flux de travail d'ingénierie complet** |
+| Collaboration d'Équipe | Difficile à partager | Efficacité personnelle | **Partage de connaissances d'équipe** |
+| Gestion du Contexte | Instance unique | Boucle d'instance unique | **Auto-répartition de sous-Agent** |
+| Gestion d'Itération | Mélangée | Liste de tâches | **Exigence comme projet, itération indépendante** |
+| Déterminisme | Faible | Moyen | **Élevé (divulgation progressive)** |
+
+---
+
+## Démarrage Rapide
+
+### Prérequis
+
+- Node.js >= 16.0.0
+- IDEs supportés : Qoder (par défaut), Cursor, Claude Code
+
+> **Note** : Les adaptateurs pour Cursor et Claude Code n'ont pas été testés dans des environnements IDE réels (implémentés au niveau du code et vérifiés par des tests E2E, mais pas encore testés dans Cursor/Claude Code réel).
+
+### 1. Installer SpecCrew
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Initialiser le Projet
+
+Naviguez vers le répertoire racine de votre projet et exécutez la commande d'initialisation :
+
+```bash
+cd /path/to/your-project
+
+# Utilise Qoder par défaut
+speccrew init
+
+# Ou spécifier l'IDE
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Après l'initialisation, les éléments suivants seront générés dans votre projet :
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 définitions de rôles Agent
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 flux de travail Skill
+- `speccrew-workspace/` — Espace de travail (répertoires d'itération, base de connaissances, modèles de documents)
+- `.speccrewrc` — Fichier de configuration SpecCrew
+
+Pour mettre à jour les Agents et Skills pour un IDE spécifique ultérieurement :
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Démarrer le Flux de Travail de Développement
+
+Suivez le flux de travail d'ingénierie standard étape par étape :
+
+1. **PRD** : L'Agent Product Manager analyse les exigences et génère le document d'exigences produit
+2. **Feature Design** : L'Agent Feature Designer génère le document de conception fonctionnelle + contrat API
+3. **System Design** : L'Agent System Designer génère les documents de conception système par plateforme (frontend/backend/mobile/desktop)
+4. **Dev** : L'Agent System Developer implémente le développement par plateforme en parallèle
+5. **System Test** : L'Agent Test Manager coordonne les tests en trois phases (conception de cas → génération de code → rapport d'exécution)
+6. **Archive** : Archiver l'itération
+
+> Les livrables de chaque phase nécessitent une confirmation humaine avant de passer à la phase suivante.
+
+### 4. Autres Commandes CLI
+
+```bash
+speccrew list       # Lister les agents et skills installés
+speccrew doctor     # Diagnostiquer l'environnement et l'état d'installation
+speccrew update     # Mettre à jour les agents et skills vers la dernière version
+speccrew uninstall  # Désinstaller SpecCrew (--all supprime aussi l'espace de travail)
+```
+
+📖 **Guide Détaillé** : Après l'installation, consultez le [Guide de Démarrage](docs/GETTING-STARTED.fr.md) pour le flux de travail complet et le guide de conversation Agent.
+
+---
+
+## Structure de Répertoire
+
+```
+your-project/
+├── .qoder/                          # Répertoire de configuration IDE (exemple Qoder)
+│   ├── agents/                      # 7 Agents de rôles
+│   │   ├── speccrew-team-leader.md       # Chef d'équipe : Planification globale et gestion d'itération
+│   │   ├── speccrew-product-manager.md   # Product Manager : Analyse des exigences et PRD
+│   │   ├── speccrew-feature-designer.md  # Feature Designer : Feature Design + Contrat API
+│   │   ├── speccrew-system-designer.md   # System Designer : Conception système par plateforme
+│   │   ├── speccrew-system-developer.md  # System Developer : Développement parallèle par plateforme
+│   │   ├── speccrew-test-manager.md      # Test Manager : Coordination de test en trois phases
+│   │   └── speccrew-task-worker.md       # Task Worker : Exécution parallèle de sous-tâches
+│   └── skills/                      # 38 Skills (groupés par fonction)
+│       ├── speccrew-pm-*/                # Gestion Produit (analyse d'exigences, évaluation)
+│       ├── speccrew-fd-*/                # Feature Design (Feature Design, Contrat API)
+│       ├── speccrew-sd-*/                # System Design (frontend/backend/mobile/desktop)
+│       ├── speccrew-dev-*/               # Développement (frontend/backend/mobile/desktop)
+│       ├── speccrew-test-*/              # Test (conception de cas/génération de code/rapport d'exécution)
+│       ├── speccrew-knowledge-bizs-*/    # Connaissances Métier (analyse API/analyse UI/classification module etc.)
+│       ├── speccrew-knowledge-techs-*/   # Connaissances Techniques (génération stack tech/conventions/index etc.)
+│       ├── speccrew-knowledge-graph-*/   # Graphe de Connaissances (lecture/écriture/requête)
+│       └── speccrew-*/                   # Utilitaires (diagnostic/horodatage/workflow etc.)
+│
+└── speccrew-workspace/              # Espace de travail (généré lors de l'initialisation)
+    ├── docs/                        # Documents de gestion
+    │   ├── configs/                 # Fichiers de configuration (mappage plateforme, mappage stack tech etc.)
+    │   ├── rules/                   # Configurations de règles
+    │   └── solutions/               # Documents de solutions
+    │
+    ├── iterations/                  # Projets d'itération (générés dynamiquement)
+    │   └── {numéro}-{type}-{nom}/
+    │       ├── 00.docs/             # Exigences originales
+    │       ├── 01.product-requirement/ # Exigences produit
+    │       ├── 02.feature-design/   # Conception fonctionnelle
+    │       ├── 03.system-design/    # Conception système
+    │       ├── 04.development/      # Phase de développement
+    │       ├── 05.system-test/      # Test système
+    │       └── 06.delivery/         # Phase de livraison
+    │
+    ├── iteration-archives/          # Archives d'itération
+    │
+    └── knowledges/                  # Base de connaissances
+        ├── base/                    # Base/métadonnées
+        │   ├── diagnosis-reports/   # Rapports de diagnostic
+        │   ├── sync-state/          # État de synchronisation
+        │   └── tech-debts/          # Dettes techniques
+        ├── bizs/                    # Connaissances métier
+        │   └── {platform-type}/{module-name}/
+        └── techs/                   # Connaissances techniques
+            └── {platform-id}/
+```
+
+---
+
+## Principes de Conception Principaux
+
+1. **Piloté par les Spécifications** : Écrire les spécifications d'abord, puis laisser le code "grandir" depuis elles
+2. **Divulgation Progressive** : Les Agents commencent à partir de points d'entrée minimaux, chargeant les informations à la demande
+3. **Confirmation Humaine** : La sortie de chaque phase nécessite une confirmation humaine pour prévenir la déviation de l'IA
+4. **Isolation du Contexte** : Les grandes tâches sont divisées en sous-tâches petites et isolées par le contexte
+5. **Collaboration de Sous-Agent** : Les tâches complexes répartissent automatiquement des sous-Agents pour éviter l'expansion du contexte d'Agent unique
+6. **Itération Rapide** : Chaque exigence comme projet indépendant pour livraison et vérification rapides
+7. **Partage de Connaissances** : Toutes les configurations sont versionnées avec le code source
+
+---
+
+## Cas d'Utilisation
+
+### ✅ Recommandé Pour
+- Projets moyens à grands nécessitant des flux de travail standardisés
+- Développement logiciel en collaboration d'équipe
+- Transformation d'ingénierie de projet hérité
+- Produits nécessitant une maintenance à long terme
+
+### ❌ Non Adapté Pour
+- Validation de prototype rapide personnelle
+- Projets exploratoires avec des exigences très incertaines
+- Scripts ou outils à usage unique
+
+---
+
+## Plus d'Informations
+
+- **Carte de Connaissances 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 ne vise pas à remplacer les développeurs, mais à automatiser les parties fastidieuses pour que les équipes puissent se concentrer sur un travail plus précieux.**

package/README.it.md

@@ -0,0 +1,321 @@
+# SpecCrew - Framework di Ingegneria del Software Basato sull'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>
+
+> Un team di sviluppo IA virtuale che consente una rapida implementazione ingegneristica per qualsiasi progetto software
+
+## Cos'è SpecCrew?
+
+SpecCrew è un framework di team di sviluppo IA virtuale integrato. Trasforma i workflow di ingegneria software professionale (PRD → Feature Design → System Design → Dev → Test) in workflow Agent riutilizzabili, aiutando i team di sviluppo a raggiungere lo Specification-Driven Development (SDD), particolarmente adatto per progetti esistenti.
+
+Integrando Agent e Skill nei progetti esistenti, i team possono rapidamente inizializzare i sistemi di documentazione del progetto e i team software virtuali, implementando nuove funzionalità e modifiche seguendo i workflow di ingegneria standard.
+
+---
+
+## 8 Problemi Principali Risolti
+
+### 1. L'IA Ignora la Documentazione del Progetto Esistente (Lacuna di Conoscenza)
+**Problema**: I metodi SDD o Vibe Coding esistenti si affidano all'IA per riassumere i progetti in tempo reale, mancando facilmente il contesto critico e causando risultati di sviluppo che si discostano dalle aspettative.
+
+**Soluzione**: Il repository `knowledge/` funge da "fonte unica di verità" del progetto, accumulando design architetturale, moduli funzionali e processi aziendali per garantire che i requisiti rimangano in pista dalla fonte.
+
+### 2. Documentazione Tecnica Diretta da PRD (Omissione di Contenuto)
+**Problema**: Passare direttamente dal PRD al design dettagliato manca facilmente i dettagli dei requisiti, causando funzionalità implementate che si discostano dai requisiti.
+
+**Soluzione**: Introdurre la fase di **Documento Feature Design**, concentrandosi solo sullo scheletro dei requisiti senza dettagli tecnici:
+- Quali pagine e componenti sono inclusi?
+- Flussi di operazioni delle pagine
+- Logica di elaborazione backend
+- Struttura di archiviazione dati
+
+Lo sviluppo deve solo "riempire la carne" basandosi sullo stack tecnologico specifico, garantendo che le funzionalità crescano "vicino all'osso (requisiti)".
+
+### 3. Portata di Ricerca Agent Incerta (Incertezza)
+**Problema**: Nei progetti complessi, la ricerca ampia di codice e documenti da parte dell'IA produce risultati incerti, rendendo la coerenza difficile da garantire.
+
+**Soluzione**: Strutture di directory documenti chiare e template, progettate in base alle esigenze di ogni Agent, implementando **divulgazione progressiva e caricamento su richiesta** per garantire determinismo.
+
+### 4. Fasi e Attività Mancanti (Rottura del Processo)
+**Problema**: La mancanza di copertura completa del processo di ingegneria manca facilmente le fasi critiche, rendendo la qualità difficile da garantire.
+
+**Soluzione**: Coprire l'intero ciclo di vita dell'ingegneria software:
+```
+PRD (Requisiti) → Feature Design (Design Funzionale) → API Contract (Contratto)
+    → System Design (Design Sistema) → Dev (Sviluppo) → Test (Testing)
+```
+- L'output di ogni fase è l'input della fase successiva
+- Ogni passaggio richiede conferma umana prima di procedere
+- Tutte le esecuzioni Agent hanno liste todo con auto-controllo dopo il completamento
+
+### 5. Bassa Efficienza di Collaborazione del Team (Silos di Conoscenza)
+**Problema**: L'esperienza di programmazione IA è difficile da condividere tra i team, portando a errori ripetuti.
+
+**Soluzione**: Tutti gli Agent, Skill e documenti correlati sono versionati con il codice sorgente:
+- L'ottimizzazione di una persona è condivisa dal team
+- La conoscenza si accumula nella base di codice
+- Migliorata l'efficienza di collaborazione del team
+
+### 7. Contesto Singolo Agent Troppo Lungo (Collo di Bottiglia di Performance)
+**Problema**: Attività complesse di grandi dimensioni superano le finestre di contesto del singolo Agent, causando deviazioni di comprensione e diminuzione della qualità dell'output.
+
+**Soluzione**: **Meccanismo di Auto-Dispatch Sotto-Agent**:
+- Le attività complesse vengono identificate automaticamente e divise in sotto-attività
+- Ogni sotto-attività è eseguita da un sotto-Agent indipendente con contesto isolato
+- L'Agent genitore coordina e aggrega per garantire la coerenza globale
+- Evita l'espansione del contesto del singolo Agent, garantendo la qualità dell'output
+
+### 8. Caos di Iterazione dei Requisiti (Difficoltà di Gestione)
+**Problema**: Requisiti multipli mescolati nello stesso branch si influenzano a vicenda, rendendo il tracciamento e il rollback difficili.
+
+**Soluzione**: **Ogni Requisito come Progetto Indipendente**:
+- Ogni requisito crea una directory di iterazione indipendente `iterations/iXXX-[nome-requisito]/`
+- Isolamento completo: documenti, design, codice e test gestiti indipendentemente
+- Iterazione rapida: consegna a piccola granularità, verifica rapida, distribuzione rapida
+- Archiviazione flessibile: dopo il completamento, archiviazione in `archive/` con chiara tracciabilità storica
+
+### 6. Ritardo nell'Aggiornamento dei Documenti (Decadimento della Conoscenza)
+**Problema**: I documenti diventano obsoleti man mano che i progetti evolvono, facendo lavorare l'IA con informazioni errate.
+
+**Soluzione**: Gli Agent hanno capacità di aggiornamento automatico dei documenti, sincronizzando le modifiche del progetto in tempo reale per mantenere la base di conoscenza accurata.
+
+---
+
+## Workflow Principale
+
+```mermaid
+graph LR
+    A[PRD<br/>Documento Requisiti] --> B[Feature Design<br/>Design Funzionale]
+    B --> C[API Contract<br/>Contratto Interfaccia]
+    C --> D[System Design<br/>Design Sistema]
+    D --> E[Dev<br/>Implementazione]
+    E --> F[System Test<br/>Testing]
+    F --> G[Archive<br/>Archiviazione]
+    
+    H[Knowledge<br/>Repository] -.-> A
+    H -.-> B
+    H -.-> D
+    H -.-> E
+    
+    E -.-> H
+    F -.-> H
+```
+
+### Descrizioni delle Fasi
+
+| Fase | Agent | Input | Output | Conferma Umana |
+|------|-------|-------|--------|----------------|
+| PRD | PM | Requisiti Utente | Documento Requisiti Prodotto | ✅ Richiesta |
+| Feature Design | Feature Designer | PRD | Documento Feature Design + Contratto API | ✅ Richiesta |
+| System Design | System Designer | Feature Spec | Documenti Design Frontend/Backend | ✅ Richiesta |
+| Dev | Dev | Design | Codice + Registrazioni Attività | ✅ Richiesta |
+| System Test | Test Manager | Output Dev + Feature Spec | Casi di Test + Codice Test + Rapporto Test + Rapporto Bug | ✅ Richiesta |
+
+---
+
+## Confronto con Soluzioni Esistenti
+
+| Dimensione | Vibe Coding | Ralph Loop | **SpecCrew** |
+|------------|-------------|------------|-------------|
+| Dipendenza Documenti | Ignora doc esistenti | Si affida a AGENTS.md | **Base di Conoscenza Strutturata** |
+| Trasferimento Requisiti | Codifica diretta | PRD → Codice | **PRD → Feature Design → System Design → Codice** |
+| Coinvolgimento Umano | Minimale | All'avvio | **In ogni fase** |
+| Completezza Processo | Debole | Media | **Workflow ingegneristico completo** |
+| Collaborazione Team | Difficile da condividere | Efficienza personale | **Condivisione conoscenza team** |
+| Gestione Contesto | Istanza singola | Ciclo istanza singola | **Auto-dispatch sotto-Agent** |
+| Gestione Iterazione | Mista | Lista attività | **Requisito come progetto, iterazione indipendente** |
+| Determinismo | Basso | Medio | **Alto (divulgazione progressiva)** |
+
+---
+
+## Avvio Rapido
+
+### Prerequisiti
+
+- Node.js >= 16.0.0
+- IDE supportati: Qoder (predefinito), Cursor, Claude Code
+
+> **Nota**: Gli adattatori per Cursor e Claude Code non sono stati testati in ambienti IDE reali (implementati a livello di codice e verificati attraverso test E2E, ma non ancora testati in Cursor/Claude Code reali).
+
+### 1. Installare SpecCrew
+
+```bash
+npm install -g speccrew
+```
+
+### 2. Inizializzare il Progetto
+
+Navigare nella directory radice del progetto ed eseguire il comando di inizializzazione:
+
+```bash
+cd /path/to/your-project
+
+# Usa Qoder per impostazione predefinita
+speccrew init
+
+# O specificare l'IDE
+speccrew init --ide qoder
+speccrew init --ide cursor
+speccrew init --ide claude
+```
+
+Dopo l'inizializzazione, saranno generati nel progetto:
+- `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 definizioni di ruoli Agent
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 workflow Skill
+- `speccrew-workspace/` — Workspace (directory iterazione, base di conoscenza, template documenti)
+- `.speccrewrc` — File di configurazione SpecCrew
+
+Per aggiornare Agent e Skill per un IDE specifico successivamente:
+
+```bash
+speccrew update --ide cursor
+speccrew update --ide claude
+```
+
+### 3. Avviare il Workflow di Sviluppo
+
+Seguire il workflow di ingegneria standard passo dopo passo:
+
+1. **PRD**: L'Agent Product Manager analizza i requisiti e genera il documento requisiti prodotto
+2. **Feature Design**: L'Agent Feature Designer genera il documento feature design + contratto API
+3. **System Design**: L'Agent System Designer genera documenti system design per piattaforma (frontend/backend/mobile/desktop)
+4. **Dev**: L'Agent System Developer implementa lo sviluppo per piattaforma in parallelo
+5. **System Test**: L'Agent Test Manager coordina il testing in tre fasi (design casi → generazione codice → rapporto esecuzione)
+6. **Archive**: Archiviare l'iterazione
+
+> I deliverable di ogni fase richiedono conferma umana prima di procedere alla fase successiva.
+
+### 4. Altri Comandi CLI
+
+```bash
+speccrew list       # Elenca agent e skill installati
+speccrew doctor     # Diagnostica ambiente e stato installazione
+speccrew update     # Aggiorna agent e skill all'ultima versione
+speccrew uninstall  # Disinstalla SpecCrew (--all rimuove anche il workspace)
+```
+
+📖 **Guida Dettagliata**: Dopo l'installazione, consulta la [Guida Introduttiva](docs/GETTING-STARTED.it.md) per il workflow completo e la guida conversazione Agent.
+
+---
+
+## Struttura Directory
+
+```
+your-project/
+├── .qoder/                          # Directory configurazione IDE (esempio Qoder)
+│   ├── agents/                      # 7 Agent di ruoli
+│   │   ├── speccrew-team-leader.md       # Team Leader: Pianificazione globale e gestione iterazione
+│   │   ├── speccrew-product-manager.md   # Product Manager: Analisi requisiti e PRD
+│   │   ├── speccrew-feature-designer.md  # Feature Designer: Feature Design + Contratto API
+│   │   ├── speccrew-system-designer.md   # System Designer: System design per piattaforma
+│   │   ├── speccrew-system-developer.md  # System Developer: Sviluppo parallelo per piattaforma
+│   │   ├── speccrew-test-manager.md      # Test Manager: Coordinamento testing in tre fasi
+│   │   └── speccrew-task-worker.md       # Task Worker: Esecuzione parallela sotto-attività
+│   └── skills/                      # 38 Skill (raggruppate per funzione)
+│       ├── speccrew-pm-*/                # Gestione Prodotto (analisi requisiti, valutazione)
+│       ├── speccrew-fd-*/                # Feature Design (Feature Design, Contratto API)
+│       ├── speccrew-sd-*/                # System Design (frontend/backend/mobile/desktop)
+│       ├── speccrew-dev-*/               # Sviluppo (frontend/backend/mobile/desktop)
+│       ├── speccrew-test-*/              # Testing (design casi/generazione codice/rapporto esecuzione)
+│       ├── speccrew-knowledge-bizs-*/    # Conoscenza Business (analisi API/analisi UI/classificazione moduli ecc.)
+│       ├── speccrew-knowledge-techs-*/   # Conoscenza Tecnica (generazione stack tech/convenzioni/indice ecc.)
+│       ├── speccrew-knowledge-graph-*/   # Grafo Conoscenza (lettura/scrittura/query)
+│       └── speccrew-*/                   # Utilità (diagnostica/timestamp/workflow ecc.)
+│
+└── speccrew-workspace/              # Workspace (generato durante inizializzazione)
+    ├── docs/                        # Documenti di gestione
+    │   ├── configs/                 # File di configurazione (mappatura piattaforma, mappatura stack tech ecc.)
+    │   ├── rules/                   # Configurazioni regole
+    │   └── solutions/               # Documenti soluzioni
+    │
+    ├── iterations/                  # Progetti iterazione (generati dinamicamente)
+    │   └── {numero}-{tipo}-{nome}/
+    │       ├── 00.docs/             # Requisiti originali
+    │       ├── 01.product-requirement/ # Requisiti prodotto
+    │       ├── 02.feature-design/   # Feature design
+    │       ├── 03.system-design/    # System design
+    │       ├── 04.development/      # Fase sviluppo
+    │       ├── 05.system-test/      # Test sistema
+    │       └── 06.delivery/         # Fase consegna
+    │
+    ├── iteration-archives/          # Archivi iterazione
+    │
+    └── knowledges/                  # Base di conoscenza
+        ├── base/                    # Base/metadati
+        │   ├── diagnosis-reports/   # Rapporti diagnostica
+        │   ├── sync-state/          # Stato sincronizzazione
+        │   └── tech-debts/          # Debito tecnico
+        ├── bizs/                    # Conoscenza business
+        │   └── {platform-type}/{module-name}/
+        └── techs/                   # Conoscenza tecnica
+            └── {platform-id}/
+```
+
+---
+
+## Principi di Design Principali
+
+1. **Specification-Driven**: Scrivere prima le specifiche, poi lasciare che il codice "cresca" da esse
+2. **Divulgazione Progressiva**: Gli Agent iniziano da punti di ingresso minimi, caricando informazioni su richiesta
+3. **Conferma Umana**: L'output di ogni fase richiede conferma umana per prevenire deviazioni dell'IA
+4. **Isolamento Contesto**: Attività grandi sono divise in sotto-attività piccole e isolate per contesto
+5. **Collaborazione Sotto-Agent**: Attività complesse inviano automaticamente sotto-Agent per evitare l'espansione del contesto del singolo Agent
+6. **Iterazione Rapida**: Ogni requisito come progetto indipendente per consegna e verifica rapide
+7. **Condivisione Conoscenza**: Tutte le configurazioni sono versionate con il codice sorgente
+
+---
+
+## Casi d'Uso
+
+### ✅ Raccomandato Per
+- Progetti da medi a grandi che richiedono workflow standardizzati
+- Sviluppo software in collaborazione di team
+- Trasformazione ingegneristica di progetti legacy
+- Prodotti che richiedono manutenzione a lungo termine
+
+### ❌ Non Adatto Per
+- Validazione rapida di prototipi personali
+- Progetti esplorativi con requisiti molto incerti
+- Script o strumenti monouso
+
+---
+
+## Ulteriori Informazioni
+
+- **Mappa Conoscenza 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 non mira a sostituire gli sviluppatori, ma ad automatizzare le parti noiose così che i team possano concentrarsi su lavori più preziosi.**