speccrew 0.7.45 → 0.7.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.speccrew/agents/speccrew-team-leader.md +6 -6
  2. package/README.ar.md +5 -17
  3. package/README.de.md +5 -17
  4. package/README.en.md +5 -17
  5. package/README.es.md +5 -17
  6. package/README.fr.md +5 -17
  7. package/README.hi.md +384 -0
  8. package/README.ja.md +5 -17
  9. package/README.md +5 -17
  10. package/README.pt-BR.md +5 -17
  11. package/README.ru.md +5 -17
  12. package/docs/GETTING-STARTED.ar.md +39 -40
  13. package/docs/GETTING-STARTED.de.md +39 -40
  14. package/docs/GETTING-STARTED.en.md +39 -40
  15. package/docs/GETTING-STARTED.es.md +39 -40
  16. package/docs/GETTING-STARTED.fr.md +39 -40
  17. package/docs/GETTING-STARTED.hi.md +636 -0
  18. package/docs/GETTING-STARTED.ja.md +39 -40
  19. package/docs/GETTING-STARTED.md +39 -40
  20. package/docs/GETTING-STARTED.pt-BR.md +25 -26
  21. package/docs/GETTING-STARTED.ru.md +37 -38
  22. package/lib/commands/init.js +3 -3
  23. package/package.json +1 -1
  24. package/README.bn.md +0 -174
  25. package/README.bs.md +0 -394
  26. package/README.da.md +0 -394
  27. package/README.el.md +0 -174
  28. package/README.it.md +0 -394
  29. package/README.ko.md +0 -394
  30. package/README.no.md +0 -394
  31. package/README.pl.md +0 -394
  32. package/README.th.md +0 -311
  33. package/README.tr.md +0 -306
  34. package/README.uk.md +0 -306
  35. package/README.vi.md +0 -174
  36. package/README.zh-TW.md +0 -394
  37. package/docs/GETTING-STARTED.bn.md +0 -219
  38. package/docs/GETTING-STARTED.bs.md +0 -219
  39. package/docs/GETTING-STARTED.da.md +0 -637
  40. package/docs/GETTING-STARTED.el.md +0 -633
  41. package/docs/GETTING-STARTED.it.md +0 -639
  42. package/docs/GETTING-STARTED.ko.md +0 -639
  43. package/docs/GETTING-STARTED.no.md +0 -563
  44. package/docs/GETTING-STARTED.pl.md +0 -597
  45. package/docs/GETTING-STARTED.th.md +0 -219
  46. package/docs/GETTING-STARTED.tr.md +0 -597
  47. package/docs/GETTING-STARTED.uk.md +0 -597
  48. package/docs/GETTING-STARTED.vi.md +0 -217
  49. package/docs/GETTING-STARTED.zh-TW.md +0 -639
@@ -1,639 +0,0 @@
1
- # Guida Rapida all'Avvio di SpecCrew
2
-
3
- <p align="center">
4
- <a href="./GETTING-STARTED.md">简体中文</a> |
5
- <a href="./GETTING-STARTED.zh-TW.md">繁體中文</a> |
6
- <a href="./GETTING-STARTED.en.md">English</a> |
7
- <a href="./GETTING-STARTED.ko.md">한국어</a> |
8
- <a href="./GETTING-STARTED.de.md">Deutsch</a> |
9
- <a href="./GETTING-STARTED.es.md">Español</a> |
10
- <a href="./GETTING-STARTED.fr.md">Français</a> |
11
- <a href="./GETTING-STARTED.it.md">Italiano</a> |
12
- <a href="./GETTING-STARTED.da.md">Dansk</a> |
13
- <a href="./GETTING-STARTED.ja.md">日本語</a> |
14
- <a href="./GETTING-STARTED.ar.md">العربية</a>
15
- </p>
16
-
17
- Questo documento ti aiuta a comprendere rapidamente come utilizzare il team di Agenti di SpecCrew per completare lo sviluppo completo dai requisiti alla consegna seguendo processi di ingegneria standard.
18
-
19
- ---
20
-
21
- ## 1. Prerequisiti
22
-
23
- ### Installare SpecCrew
24
-
25
- ```bash
26
- npm install -g speccrew
27
- ```
28
-
29
- ### Inizializzare il Progetto
30
-
31
- ```bash
32
- speccrew init --ide qoder
33
- ```
34
-
35
- IDE supportati: `qoder`, `cursor`, `claude`, `codex`
36
-
37
- ### Struttura delle Directory Dopo l'Inizializzazione
38
-
39
- ```
40
- .
41
- ├── .qoder/
42
- │ ├── agents/ # File di definizione degli Agenti
43
- │ └── skills/ # File di definizione degli Skills
44
- ├── speccrew-workspace/ # Workspace
45
- │ ├── docs/ # Configurazioni, regole, template, soluzioni
46
- │ ├── iterations/ # Iterazioni in corso
47
- │ ├── iteration-archives/ # Iterazioni archiviate
48
- │ └── knowledges/ # Base di conoscenza
49
- │ ├── base/ # Informazioni di base (rapporti di diagnosi, debiti tecnici)
50
- │ ├── bizs/ # Base di conoscenza di business
51
- │ └── techs/ # Base di conoscenza tecnica
52
- ```
53
-
54
- ### Riferimento Rapido dei Comandi CLI
55
-
56
- | Comando | Descrizione |
57
- |------|------|
58
- | `speccrew list` | Elenca tutti gli Agenti e Skills disponibili |
59
- | `speccrew doctor` | Verifica l'integrità dell'installazione |
60
- | `speccrew update` | Aggiorna la configurazione del progetto all'ultima versione |
61
- | `speccrew uninstall` | Disinstalla SpecCrew |
62
-
63
- ---
64
-
65
- ## 2. Avvio Rapido in 5 Minuti Dopo l'Installazione
66
-
67
- Dopo aver eseguito `speccrew init`, segui questi passaggi per entrare rapidamente in stato di lavoro:
68
-
69
- ### Passaggio 1: Scegli il Tuo IDE
70
-
71
- | IDE | Comando di Inizializzazione | Scenario di Applicazione |
72
- |-----|-----------|----------|
73
- | **Qoder** (Consigliato) | `speccrew init --ide qoder` | Orchestrazione completa degli agenti, worker paralleli |
74
- | **Cursor** | `speccrew init --ide cursor` | Workflow basati su Composer |
75
- | **Claude Code** | `speccrew init --ide claude` | Sviluppo CLI-first |
76
- | **Codex** | `speccrew init --ide codex` | Integrazione ecosistema OpenAI |
77
-
78
- ### Passaggio 2: Inizializzare la Base di Conoscenza (Consigliato)
79
-
80
- Per progetti con codice sorgente esistente, si consiglia di inizializzare prima la base di conoscenza in modo che gli agenti comprendano il tuo codebase:
81
-
82
- ```
83
- @speccrew-team-leader inizializza base di conoscenza tecnica
84
- ```
85
-
86
- Poi:
87
-
88
- ```
89
- @speccrew-team-leader inizializza base di conoscenza di business
90
- ```
91
-
92
- ### Passaggio 3: Inizia il Tuo Primo Compito
93
-
94
- ```
95
- @speccrew-product-manager Ho un nuovo requisito: [descrivi il tuo requisito funzionale]
96
- ```
97
-
98
- > **Suggerimento**: Se non sei sicuro di cosa fare, dì semplicemente `@speccrew-team-leader aiutami a iniziare` — il Team Leader rileverà automaticamente lo stato del tuo progetto e ti guiderà.
99
-
100
- ---
101
-
102
- ## 3. Albero di Decisione Rapido
103
-
104
- Non sei sicuro di cosa fare? Trova il tuo scenario qui sotto:
105
-
106
- - **Ho un nuovo requisito funzionale**
107
- → `@speccrew-product-manager Ho un nuovo requisito: [descrivi il tuo requisito funzionale]`
108
-
109
- - **Voglio scansionare la conoscenza del progetto esistente**
110
- → `@speccrew-team-leader inizializza base di conoscenza tecnica`
111
- → Poi: `@speccrew-team-leader inizializza base di conoscenza di business`
112
-
113
- - **Voglio continuare il lavoro precedente**
114
- → `@speccrew-team-leader qual è lo stato di avanzamento attuale?`
115
-
116
- - **Voglio verificare lo stato di salute del sistema**
117
- → Esegui nel terminale: `speccrew doctor`
118
-
119
- - **Non sono sicuro di cosa fare**
120
- → `@speccrew-team-leader aiutami a iniziare`
121
- → Il Team Leader rileverà automaticamente lo stato del tuo progetto e ti guiderà
122
-
123
- ---
124
-
125
- ## 4. Riferimento Rapido degli Agenti
126
-
127
- | Ruolo | Agente | Responsabilità | Esempio di Comando |
128
- |------|-------|-----------------|-----------------|
129
- | Capo Team | `@speccrew-team-leader` | Navigazione progetto, inizializzazione base di conoscenza, verifica stato | "Aiutami a iniziare" |
130
- | Product Manager | `@speccrew-product-manager` | Analisi dei requisiti, generazione PRD | "Ho un nuovo requisito: ..." |
131
- | Designer Funzionalità | `@speccrew-feature-designer` | Analisi funzionale, progettazione specifiche, contratti API | "Avvia progettazione funzionalità per iterazione X" |
132
- | Designer di Sistema | `@speccrew-system-designer` | Progettazione architettura, progettazione dettagliata per piattaforma | "Avvia progettazione sistema per iterazione X" |
133
- | Sviluppatore di Sistema | `@speccrew-system-developer` | Coordinamento sviluppo, generazione codice | "Avvia sviluppo per iterazione X" |
134
- | Responsabile Test | `@speccrew-test-manager` | Pianificazione test, progettazione casi, esecuzione | "Avvia test per iterazione X" |
135
-
136
- > **Nota**: Non devi ricordare tutti gli agenti. Basta parlare con `@speccrew-team-leader` e instraderà la tua richiesta all'agente giusto.
137
-
138
- ---
139
-
140
- ## 5. Panoramica del Workflow
141
-
142
- ### Diagramma di Flusso Completo
143
-
144
- ```mermaid
145
- flowchart LR
146
- PRD[Fase 1<br/>Analisi Requisiti<br/>Product Manager] --> FD[Fase 2<br/>Feature Design<br/>Feature Designer]
147
- FD --> SD[Fase 3<br/>System Design<br/>System Designer]
148
- SD --> DEV[Fase 4<br/>Sviluppo<br/>System Developer]
149
- DEV --> DEPLOY[Fase 5<br/>Distribuzione<br/>System Deployer]
150
- DEPLOY --> TEST[Fase 6<br/>Test di Sistema<br/>Test Manager]
151
- TEST --> ARCHIVE[Fase 7<br/>Archiviazione]
152
-
153
- KB[(Base di Conoscenza<br/>Per Tutto il Processo)] -.-> PRD
154
- KB -.-> FD
155
- KB -.-> SD
156
- KB -.-> DEV
157
- KB -.-> DEPLOY
158
- KB -.-> TEST
159
- ```
160
-
161
- ### Principi Fondamentali
162
-
163
- 1. **Dipendenze tra Fasi**: Il deliverable di ogni fase è l'input per la fase successiva
164
- 2. **Conferma Checkpoint**: Ogni fase ha un punto di conferma che richiede l'approvazione dell'utente prima di procedere alla fase successiva
165
- 3. **Guidato dalla Base di Conoscenza**: La base di conoscenza attraversa l'intero processo, fornendo contesto per tutte le fasi
166
-
167
- ---
168
-
169
- ## 6. Passaggio Zero: Inizializzazione della Base di Conoscenza
170
-
171
- Prima di avviare il processo di ingegneria formale, è necessario inizializzare la base di conoscenza del progetto.
172
-
173
- ### 6.1 Inizializzazione della Base di Conoscenza Tecnica
174
-
175
- **Esempio di Conversazione**:
176
- ```
177
- @speccrew-team-leader inizializza base di conoscenza tecnica
178
- ```
179
-
180
- **Processo in Tre Fasi**:
181
- 1. Rilevamento Piattaforma — Identificare le piattaforme tecniche nel progetto
182
- 2. Generazione Documentazione Tecnica — Generare documenti di specifica tecnica per ogni piattaforma
183
- 3. Generazione Indice — Stabilire l'indice della base di conoscenza
184
-
185
- **Deliverable**:
186
- ```
187
- speccrew-workspace/knowledges/techs/{platform-id}/
188
- ├── tech-stack.md # Definizione dello stack tecnologico
189
- ├── architecture.md # Convenzioni architetturali
190
- ├── dev-spec.md # Specifiche di sviluppo
191
- ├── test-spec.md # Specifiche di test
192
- └── INDEX.md # File indice
193
- ```
194
-
195
- ### 6.2 Inizializzazione della Base di Conoscenza di Business
196
-
197
- **Esempio di Conversazione**:
198
- ```
199
- @speccrew-team-leader inizializza base di conoscenza di business
200
- ```
201
-
202
- **Processo in Quattro Fasi**:
203
- 1. Inventario Funzionalità — Scansionare il codice per identificare tutte le funzionalità
204
- 2. Analisi Funzionalità — Analizzare la logica di business per ogni funzionalità
205
- 3. Riepilogo per Modulo — Riepilogare le funzionalità per modulo
206
- 4. Riepilogo di Sistema — Generare panoramica di business a livello di sistema
207
-
208
- **Deliverable**:
209
- ```
210
- speccrew-workspace/knowledges/bizs/
211
- ├── {platform-type}/
212
- │ └── {module-name}/
213
- │ └── feature-spec.md
214
- └── system-overview.md
215
- ```
216
-
217
- ---
218
-
219
- ## 7. Guida alla Conversazione Fase per Fase
220
-
221
- ### 7.1 Fase 1: Analisi dei Requisiti (Product Manager)
222
-
223
- **Come Avviare**:
224
- ```
225
- @speccrew-product-manager Ho un nuovo requisito: [descrivi il tuo requisito]
226
- ```
227
-
228
- **Workflow dell'Agente**:
229
- 1. Leggere la panoramica del sistema per comprendere i moduli esistenti
230
- 2. Analizzare i requisiti dell'utente
231
- 3. Generare documento PRD strutturato
232
-
233
- **Deliverable**:
234
- ```
235
- iterations/{numero}-{tipo}-{nome}/01.product-requirement/
236
- ├── [feature-name]-prd.md # Documento Product Requirements
237
- └── [feature-name]-bizs-modeling.md # Modellazione business (per requisiti complessi)
238
- ```
239
-
240
- **Checklist di Conferma**:
241
- - [ ] La descrizione del requisito riflette accuratamente l'intento dell'utente?
242
- - [ ] Le regole di business sono complete?
243
- - [ ] I punti di integrazione con i sistemi esistenti sono chiari?
244
- - [ ] I criteri di accettazione sono misurabili?
245
-
246
- ---
247
-
248
- ### 7.2 Fase 2: Feature Design (Feature Designer)
249
-
250
- **Come Avviare**:
251
- ```
252
- @speccrew-feature-designer avvia feature design
253
- ```
254
-
255
- **Workflow dell'Agente**:
256
- 1. Individuare automaticamente il documento PRD confermato
257
- 2. Caricare la base di conoscenza di business
258
- 3. Generare feature design (inclusi wireframe UI, flussi di interazione, definizioni dati, contratti API)
259
- 4. Per più PRD, usare Task Worker per progettazione parallela
260
-
261
- **Deliverable**:
262
- ```
263
- iterations/{iter}/02.feature-design/
264
- └── [feature-name]-feature-spec.md # Documento feature design
265
- ```
266
-
267
- **Checklist di Conferma**:
268
- - [ ] Tutti gli scenari utente sono coperti?
269
- - [ ] I flussi di interazione sono chiari?
270
- - [ ] Le definizioni dei campi dati sono complete?
271
- - [ ] La gestione delle eccezioni è completa?
272
-
273
- ---
274
-
275
- ### 7.3 Fase 3: System Design (System Designer)
276
-
277
- **Come Avviare**:
278
- ```
279
- @speccrew-system-designer avvia system design
280
- ```
281
-
282
- **Workflow dell'Agente**:
283
- 1. Individuare Feature Spec e API Contract
284
- 2. Caricare la base di conoscenza tecnica (stack tecnologico, architettura, specifiche per ogni piattaforma)
285
- 3. **Checkpoint A**: Valutazione Framework — Analizzare gap tecnici, raccomandare nuovi framework (se necessario), attendere conferma utente
286
- 4. Generare DESIGN-OVERVIEW.md
287
- 5. Usare Task Worker per distribuire parallelamente il design per ogni piattaforma (frontend/backend/mobile/desktop)
288
- 6. **Checkpoint B**: Conferma Congiunta — Mostrare riepilogo di tutti i design di piattaforma, attendere conferma utente
289
-
290
- **Deliverable**:
291
- ```
292
- iterations/{iter}/03.system-design/
293
- ├── DESIGN-OVERVIEW.md # Panoramica del design
294
- ├── {platform-id}/
295
- │ ├── INDEX.md # Indice design per piattaforma
296
- │ └── {module}-design.md # Design modulo livello pseudocodice
297
- ```
298
-
299
- **Checklist di Conferma**:
300
- - [ ] Lo pseudocodice usa la sintassi effettiva del framework?
301
- - [ ] I contratti API cross-piattaforma sono consistenti?
302
- - [ ] La strategia di gestione errori è unificata?
303
-
304
- ---
305
-
306
- ### 7.4 Fase 4: Sviluppo (System Developer)
307
-
308
- **Come Avviare**:
309
- ```
310
- @speccrew-system-developer avvia sviluppo
311
- ```
312
-
313
- **Workflow dell'Agente**:
314
- 1. Leggere i documenti di system design
315
- 2. Caricare conoscenze tecniche per ogni piattaforma
316
- 3. **Checkpoint A**: Pre-verifica Ambiente — Verificare versioni runtime, dipendenze, disponibilità servizi; attendere risoluzione utente se fallisce
317
- 4. Usare Task Worker per distribuire parallelamente lo sviluppo per ogni piattaforma
318
- 5. Verifica integrazione: allineamento contratti API, consistenza dati
319
- 6. Produrre report di consegna
320
-
321
- **Deliverable**:
322
- ```
323
- # Il codice sorgente viene scritto nella directory sorgente effettiva del progetto
324
- iterations/{iter}/04.development/
325
- ├── {platform-id}/
326
- │ └── tasks/ # Registrazioni attività di sviluppo
327
- └── delivery-report.md
328
- ```
329
-
330
- **Checklist di Conferma**:
331
- - [ ] L'ambiente è pronto?
332
- - [ ] I problemi di integrazione sono in un intervallo accettabile?
333
- - [ ] Il codice è conforme alle specifiche di sviluppo?
334
-
335
- ---
336
-
337
- ### 7.5 Fase 5: Distribuzione (System Deployer)
338
-
339
- **Come Avviare**:
340
-
341
- ```
342
- @speccrew-system-deployer avvia distribuzione
343
- ```
344
-
345
- **Workflow dell'Agente**:
346
- 1. Verificare che la fase di sviluppo sia completata (Stage Gate)
347
- 2. Caricare la base di conoscenza tecnica (configurazione build, configurazione migrazione database, comandi avvio servizi)
348
- 3. **Checkpoint**: Pre-verifica Ambiente — Verificare strumenti di build, versioni runtime, disponibilità dipendenze
349
- 4. Eseguire le skill di distribuzione in sequenza: Build → Migrazione Database → Avvio Servizi → Smoke Test
350
- 5. Emettere rapporto di distribuzione
351
-
352
- > 💡 **Suggerimento**: Per progetti senza database, il passaggio di migrazione viene saltato automaticamente; per applicazioni client (desktop/mobile), viene utilizzata la modalità di verifica processo invece del controllo salute HTTP.
353
-
354
- **Deliverable**:
355
-
356
- ```
357
- iterations/{iter}/05.deployment/
358
- ├── {platform-id}/
359
- │ ├── deployment-plan.md # Piano di distribuzione
360
- │ └── deployment-log.md # Log esecuzione distribuzione
361
- └── deployment-report.md # Rapporto distribuzione completata
362
- ```
363
-
364
- **Checklist di Conferma**:
365
- - [ ] Il build è stato completato con successo?
366
- - [ ] Tutti gli script di migrazione database sono stati eseguiti con successo (se applicabile)?
367
- - [ ] L'applicazione si avvia normalmente e supera il controllo salute?
368
- - [ ] Tutti gli smoke test sono passati?
369
-
370
- ---
371
-
372
- ### 7.6 Fase 6: Test di Sistema (Test Manager)
373
-
374
- **Come Avviare**:
375
- ```
376
- @speccrew-test-manager avvia test
377
- ```
378
-
379
- **Processo di Test in Tre Fasi**:
380
-
381
- | Fase | Descrizione | Checkpoint |
382
- |-------|-------------|------------|
383
- | Progettazione Casi di Test | Generare casi di test basati su PRD e Feature Spec | A: Mostrare statistiche copertura casi e matrice di tracciabilità, attendere conferma utente di copertura sufficiente |
384
- | Generazione Codice di Test | Generare codice di test eseguibile | B: Mostrare file di test generati e mappatura casi, attendere conferma utente |
385
- | Esecuzione Test e Report Bug | Eseguire automaticamente test e generare report | Nessuno (esecuzione automatica) |
386
-
387
- **Deliverable**:
388
- ```
389
- iterations/{iter}/06.system-test/
390
- ├── cases/
391
- │ └── {platform-id}/ # Documenti casi di test
392
- ├── code/
393
- │ └── {platform-id}/ # Piano codice di test
394
- ├── reports/
395
- │ └── test-report-{date}.md # Report di test
396
- └── bugs/
397
- └── BUG-{id}-{title}.md # Report bug (un file per bug)
398
- ```
399
-
400
- **Checklist di Conferma**:
401
- - [ ] La copertura dei casi è completa?
402
- - [ ] Il codice di test è eseguibile?
403
- - [ ] La valutazione della gravità dei bug è accurata?
404
-
405
- ---
406
-
407
- ### 7.7 Fase 7: Archiviazione
408
-
409
- Le iterazioni vengono archiviate automaticamente dopo il completamento:
410
-
411
- ```
412
- speccrew-workspace/iteration-archives/
413
- └── {numero}-{tipo}-{nome}-{data}/
414
- ├── 01.product-requirement/
415
- ├── 02.feature-design/
416
- ├── 03.system-design/
417
- ├── 04.development/
418
- ├── 05.deployment/
419
- └── 06.system-test/
420
- ```
421
-
422
- ---
423
-
424
- ## 8. Panoramica della Base di Conoscenza
425
-
426
- ### 8.1 Base di Conoscenza di Business (bizs)
427
-
428
- **Scopo**: Memorizzare descrizioni funzionalità business del progetto, divisioni modulari, caratteristiche API
429
-
430
- **Struttura Directory**:
431
- ```
432
- knowledges/bizs/
433
- ├── {platform-type}/
434
- │ └── {module-name}/
435
- │ └── feature-spec.md
436
- └── system-overview.md
437
- ```
438
-
439
- **Scenari d'Uso**: Product Manager, Feature Designer
440
-
441
- ### 8.2 Base di Conoscenza Tecnica (techs)
442
-
443
- **Scopo**: Memorizzare stack tecnologico del progetto, convenzioni architetturali, specifiche di sviluppo, specifiche di test
444
-
445
- **Struttura Directory**:
446
- ```
447
- knowledges/techs/{platform-id}/
448
- ├── tech-stack.md
449
- ├── architecture.md
450
- ├── dev-spec.md
451
- ├── test-spec.md
452
- └── INDEX.md
453
- ```
454
-
455
- **Scenari d'Uso**: System Designer, System Developer, Test Manager
456
-
457
- ---
458
-
459
- ## 9. Gestione Avanzamento Workflow
460
-
461
- Il team virtuale SpecCrew segue un rigoroso meccanismo di stage-gating in cui ogni fase deve essere confermata dall'utente prima di procedere alla successiva. Supporta anche l'esecuzione riprendibile — quando riavviato dopo un'interruzione, continua automaticamente da dove si era fermato.
462
-
463
- ### 9.1 Tre Livelli di File di Avanzamento
464
-
465
- Il workflow mantiene automaticamente tre tipi di file JSON di avanzamento, situati nella directory di iterazione:
466
-
467
- | File | Posizione | Scopo |
468
- |------|----------|---------|
469
- | `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registra lo stato di ogni fase della pipeline |
470
- | `.checkpoints.json` | Sotto ogni directory di fase | Registra lo stato di conferma dei checkpoint utente |
471
- | `DISPATCH-PROGRESS.json` | Sotto ogni directory di fase | Registra l'avanzamento item per item per attività parallele (multi-piattaforma/multi-modulo) |
472
-
473
- ### 9.2 Flusso di Stato della Fase
474
-
475
- Ogni fase segue questo flusso di stato:
476
-
477
- ```
478
- pending → in_progress → completed → confirmed
479
- ```
480
-
481
- - **pending**: Non ancora avviato
482
- - **in_progress**: In esecuzione
483
- - **completed**: Esecuzione agente completata, in attesa di conferma utente
484
- - **confirmed**: Utente confermato tramite checkpoint finale, la fase successiva può iniziare
485
-
486
- ### 9.3 Esecuzione Riprendibile
487
-
488
- Quando si riavvia un Agente per una fase:
489
-
490
- 1. **Verifica automatica upstream**: Verifica se la fase precedente è confermata, blocca e richiede se non
491
- 2. **Recupero Checkpoint**: Legge `.checkpoints.json`, salta i checkpoint passati, continua dall'ultimo punto di interruzione
492
- 3. **Recupero Attività Parallele**: Legge `DISPATCH-PROGRESS.json`, ri-esegue solo attività con stato `pending` o `failed`, salta attività `completed`
493
-
494
- ### 9.4 Visualizzare Avanzamento Attuale
495
-
496
- Visualizzare lo stato panoramico della pipeline tramite l'Agente Team Leader:
497
-
498
- ```
499
- @speccrew-team-leader visualizza avanzamento iterazione corrente
500
- ```
501
-
502
- Il Team Leader leggerà i file di avanzamento e mostrerà una panoramica dello stato simile a:
503
-
504
- ```
505
- Pipeline Status: i001-user-management
506
- 01 PRD: ✅ Confirmed
507
- 02 Feature Design: 🔄 In Progress (Checkpoint A passed)
508
- 03 System Design: ⏳ Pending
509
- 04 Development: ⏳ Pending
510
- 05 Deployment: ⏳ Pending
511
- 06 System Test: ⏳ Pending
512
- ```
513
-
514
- ### 9.5 Compatibilità all'Indietro
515
-
516
- Il meccanismo dei file di avanzamento è completamente compatibile all'indietro — se i file di avanzamento non esistono (ad es. in progetti legacy o nuove iterazioni), tutti gli Agenti eseguiranno normalmente secondo la logica originale.
517
-
518
- ---
519
-
520
- ## 10. Domande Frequenti (FAQ)
521
-
522
- ### D1: Cosa fare se l'Agente non funziona come previsto?
523
-
524
- 1. Eseguire `speccrew doctor` per verificare l'integrità dell'installazione
525
- 2. Confermare che la base di conoscenza è stata inizializzata
526
- 3. Confermare che il deliverable della fase precedente esiste nella directory di iterazione corrente
527
-
528
- ### D2: Come saltare una fase?
529
-
530
- **Non consigliato** — L'output di ogni fase è l'input per la fase successiva.
531
-
532
- Se devi saltare, prepara manualmente il documento di input della fase corrispondente e assicurati che sia conforme alle specifiche di formato.
533
-
534
- ### D3: Come gestire più requisiti paralleli?
535
-
536
- Crea directory di iterazione indipendenti per ogni requisito:
537
- ```
538
- iterations/
539
- ├── 001-feature-xxx/
540
- ├── 002-feature-yyy/
541
- └── 003-feature-zzz/
542
- ```
543
-
544
- Ogni iterazione è completamente isolata e non influisce sulle altre.
545
-
546
- ### D4: Come aggiornare la versione di SpecCrew?
547
-
548
- L'aggiornamento richiede due passaggi:
549
-
550
- ```bash
551
- # Passaggio 1: Aggiornare lo strumento CLI globale
552
- npm install -g speccrew@latest
553
-
554
- # Passaggio 2: Sincronizzare Agents e Skills nella directory del progetto
555
- cd /path/to/your-project
556
- speccrew update
557
- ```
558
-
559
- - `npm install -g speccrew@latest`: Aggiorna lo strumento CLI stesso (le nuove versioni possono includere nuove definizioni Agent/Skill, correzioni bug, ecc.)
560
- - `speccrew update`: Sincronizza i file di definizione Agent e Skill del tuo progetto all'ultima versione
561
- - `speccrew update --ide cursor`: Aggiorna la configurazione per un IDE specifico soltanto
562
-
563
- > **Nota**: Entrambi i passaggi sono necessari. Eseguire solo `speccrew update` non aggiornerà lo strumento CLI stesso; eseguire solo `npm install` non aggiornerà i file del progetto.
564
-
565
- ### D5: `speccrew update` indica che è disponibile una nuova versione ma `npm install -g speccrew@latest` continua a installare la vecchia versione?
566
-
567
- Questo è solitamente causato dalla cache npm. Soluzione:
568
-
569
- ```bash
570
- # Pulire cache npm e reinstallare
571
- npm cache clean --force
572
- npm install -g speccrew@latest
573
-
574
- # Verificare versione
575
- npm list -g speccrew
576
- ```
577
-
578
- Se ancora non funziona, prova a installare con un numero di versione specifico:
579
- ```bash
580
- npm install -g speccrew@0.5.6
581
- ```
582
-
583
- ### D6: Come visualizzare le iterazioni storiche?
584
-
585
- Dopo l'archiviazione, visualizzare in `speccrew-workspace/iteration-archives/`, organizzato per formato `{numero}-{tipo}-{nome}-{data}/`.
586
-
587
- ### D7: La base di conoscenza necessita di aggiornamenti regolari?
588
-
589
- È richiesta la reinizializzazione nelle seguenti situazioni:
590
- - Modifiche importanti alla struttura del progetto
591
- - Aggiornamento o sostituzione dello stack tecnologico
592
- - Aggiunta/rimozione di moduli business
593
-
594
- ---
595
-
596
- ## 11. Riferimento Rapido
597
-
598
- ### Riferimento Rapido Avvio Agenti
599
-
600
- | Fase | Agente | Conversazione di Avvio |
601
- |-------|-------|-------------------|
602
- | Inizializzazione | Team Leader | `@speccrew-team-leader inizializza base di conoscenza tecnica` |
603
- | Analisi Requisiti | Product Manager | `@speccrew-product-manager Ho un nuovo requisito: [descrizione]` |
604
- | Feature Design | Feature Designer | `@speccrew-feature-designer avvia feature design` |
605
- | System Design | System Designer | `@speccrew-system-designer avvia system design` |
606
- | Sviluppo | System Developer | `@speccrew-system-developer avvia sviluppo` |
607
- | Distribuzione | System Deployer | `@speccrew-system-deployer avvia distribuzione` |
608
- | Test di Sistema | Test Manager | `@speccrew-test-manager avvia test` |
609
-
610
- ### Checklist Checkpoint
611
-
612
- | Fase | Numero Checkpoint | Elementi di Verifica Chiave |
613
- |-------|----------------------|-----------------|
614
- | Analisi Requisiti | 1 | Accuratezza requisiti, completezza regole business, misurabilità criteri accettazione |
615
- | Feature Design | 1 | Copertura scenari, chiarezza interazione, completezza dati, gestione eccezioni |
616
- | System Design | 2 | A: Valutazione framework; B: Sintassi pseudocodice, consistenza cross-piattaforma, gestione errori |
617
- | Sviluppo | 1 | A: Pronto ambiente, problemi integrazione, specifiche codice |
618
- | Distribuzione | 1 | Build riuscito, migrazione completata, servizi avviati, smoke test passati |
619
- | Test di Sistema | 2 | A: Copertura casi; B: Eseguibilità codice test |
620
-
621
- ### Riferimento Rapido Percorsi Deliverable
622
-
623
- | Fase | Directory Output | Formato File |
624
- |-------|-----------------|-------------|
625
- | Analisi Requisiti | `iterations/{iter}/01.product-requirement/` | `[name]-prd.md`, `[name]-bizs-modeling.md` |
626
- | Feature Design | `iterations/{iter}/02.feature-design/` | `[name]-feature-spec.md` |
627
- | System Design | `iterations/{iter}/03.system-design/` | `DESIGN-OVERVIEW.md`, `{platform}/INDEX.md`, `{platform}/{module}-design.md` |
628
- | Sviluppo | `iterations/{iter}/04.development/` | Codice sorgente + `delivery-report.md` |
629
- | Distribuzione | `iterations/{iter}/05.deployment/` | `deployment-plan.md`, `deployment-log.md`, `deployment-report.md` |
630
- | Test di Sistema | `iterations/{iter}/06.system-test/` | `cases/`, `code/`, `reports/`, `bugs/` |
631
- | Archiviazione | `iteration-archives/{iter}-{date}/` | Copia completa dell'iterazione |
632
-
633
- ---
634
-
635
- ## Prossimi Passaggi
636
-
637
- 1. Esegui `speccrew init --ide qoder` per inizializzare il tuo progetto
638
- 2. Esegui Passaggio Zero: Inizializzazione della Base di Conoscenza
639
- 3. Progredisci fase per fase secondo il workflow, goditi l'esperienza di sviluppo guidato dalle specifiche!