speccrew 0.5.9 → 0.5.11

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 (44) hide show
  1. package/.speccrew/agents/speccrew-feature-designer.md +67 -0
  2. package/.speccrew/agents/speccrew-product-manager.md +69 -0
  3. package/.speccrew/agents/speccrew-system-designer.md +77 -0
  4. package/.speccrew/agents/speccrew-system-developer.md +311 -8
  5. package/.speccrew/agents/speccrew-task-worker.md +34 -0
  6. package/.speccrew/agents/speccrew-team-leader.md +84 -0
  7. package/.speccrew/agents/speccrew-test-manager.md +27 -0
  8. package/.speccrew/skills/{speccrew-dev-desktop → speccrew-dev-desktop-electron}/SKILL.md +38 -50
  9. package/.speccrew/skills/{speccrew-dev-desktop → speccrew-dev-desktop-electron}/templates/TASK-RECORD-TEMPLATE.md +14 -28
  10. package/.speccrew/skills/speccrew-dev-desktop-tauri/SKILL.md +341 -0
  11. package/.speccrew/skills/speccrew-dev-desktop-tauri/templates/TASK-RECORD-TEMPLATE.md +145 -0
  12. package/.speccrew/skills/speccrew-dev-review-backend/SKILL.md +212 -0
  13. package/.speccrew/skills/speccrew-dev-review-backend/templates/REVIEW-REPORT-TEMPLATE.md +94 -0
  14. package/.speccrew/skills/speccrew-dev-review-desktop/SKILL.md +181 -0
  15. package/.speccrew/skills/speccrew-dev-review-desktop/templates/REVIEW-REPORT-TEMPLATE.md +90 -0
  16. package/.speccrew/skills/speccrew-dev-review-frontend/SKILL.md +177 -0
  17. package/.speccrew/skills/speccrew-dev-review-frontend/templates/REVIEW-REPORT-TEMPLATE.md +83 -0
  18. package/.speccrew/skills/speccrew-dev-review-mobile/SKILL.md +181 -0
  19. package/.speccrew/skills/speccrew-dev-review-mobile/templates/REVIEW-REPORT-TEMPLATE.md +90 -0
  20. package/docs/GETTING-STARTED.ar.md +249 -176
  21. package/docs/GETTING-STARTED.bn.md +108 -412
  22. package/docs/GETTING-STARTED.bs.md +103 -407
  23. package/docs/GETTING-STARTED.da.md +267 -190
  24. package/docs/GETTING-STARTED.de.md +190 -115
  25. package/docs/GETTING-STARTED.el.md +245 -169
  26. package/docs/GETTING-STARTED.en.md +97 -22
  27. package/docs/GETTING-STARTED.es.md +179 -104
  28. package/docs/GETTING-STARTED.fr.md +191 -116
  29. package/docs/GETTING-STARTED.it.md +233 -156
  30. package/docs/GETTING-STARTED.ja.md +242 -167
  31. package/docs/GETTING-STARTED.ko.md +211 -136
  32. package/docs/GETTING-STARTED.md +97 -22
  33. package/docs/GETTING-STARTED.no.md +86 -417
  34. package/docs/GETTING-STARTED.pl.md +213 -135
  35. package/docs/GETTING-STARTED.pt-BR.md +94 -396
  36. package/docs/GETTING-STARTED.ru.md +241 -162
  37. package/docs/GETTING-STARTED.th.md +104 -405
  38. package/docs/GETTING-STARTED.tr.md +223 -144
  39. package/docs/GETTING-STARTED.uk.md +273 -194
  40. package/docs/GETTING-STARTED.vi.md +98 -399
  41. package/docs/GETTING-STARTED.zh-TW.md +213 -138
  42. package/lib/commands/init.js +18 -0
  43. package/package.json +1 -1
  44. package/.speccrew/skills/speccrew-dev-review/SKILL.md +0 -451
@@ -11,17 +11,16 @@
11
11
  <a href="./GETTING-STARTED.it.md">Italiano</a> |
12
12
  <a href="./GETTING-STARTED.da.md">Dansk</a> |
13
13
  <a href="./GETTING-STARTED.ja.md">日本語</a> |
14
- <a href="./GETTING-STARTED.ar.md">العربية</a> |
15
- <a href="./GETTING-STARTED.pt-BR.md">Português (Brasil)</a>
14
+ <a href="./GETTING-STARTED.ar.md">العربية</a>
16
15
  </p>
17
16
 
18
- Este documento ajuda você a entender rapidamente como usar a equipe de Agentes do SpecCrew para completar o ciclo completo de desenvolvimento desde os requisitos até a entrega, seguindo processos de engenharia padrão.
17
+ Este documento ajuda você a entender rapidamente como usar a equipe de Agentes do SpecCrew para completar o desenvolvimento completo dos requisitos à entrega seguindo processos de engenharia padrão.
19
18
 
20
19
  ---
21
20
 
22
21
  ## 1. Pré-requisitos
23
22
 
24
- ### Instalar o SpecCrew
23
+ ### Instalar SpecCrew
25
24
 
26
25
  ```bash
27
26
  npm install -g speccrew
@@ -42,20 +41,20 @@ IDEs suportados: `qoder`, `cursor`, `claude`, `codex`
42
41
  ├── .qoder/
43
42
  │ ├── agents/ # Arquivos de definição de Agentes
44
43
  │ └── skills/ # Arquivos de definição de Skills
45
- ├── speccrew-workspace/ # Espaço de trabalho
46
- │ ├── docs/ # Configurações, regras, modelos, soluções
44
+ ├── speccrew-workspace/ # Workspace
45
+ │ ├── docs/ # Configurações, regras, templates, soluções
47
46
  │ ├── iterations/ # Iterações em andamento
48
47
  │ ├── iteration-archives/ # Iterações arquivadas
49
48
  │ └── knowledges/ # Base de conhecimento
50
49
  │ ├── base/ # Informações básicas (relatórios de diagnóstico, dívidas técnicas)
51
- │ ├── bizs/ # Base de conhecimento de negócios
50
+ │ ├── bizs/ # Base de conhecimento de negócio
52
51
  │ └── techs/ # Base de conhecimento técnica
53
52
  ```
54
53
 
55
54
  ### Referência Rápida de Comandos CLI
56
55
 
57
56
  | Comando | Descrição |
58
- |---------|-------------|
57
+ |------|------|
59
58
  | `speccrew list` | Listar todos os Agentes e Skills disponíveis |
60
59
  | `speccrew doctor` | Verificar integridade da instalação |
61
60
  | `speccrew update` | Atualizar configuração do projeto para a versão mais recente |
@@ -63,457 +62,156 @@ IDEs suportados: `qoder`, `cursor`, `claude`, `codex`
63
62
 
64
63
  ---
65
64
 
66
- ## 2. Visão Geral do Fluxo de Trabalho
65
+ ## 2. Início Rápido em 5 Minutos Após Instalação
67
66
 
68
- ### Diagrama de Fluxo Completo
69
-
70
- ```mermaid
71
- flowchart LR
72
- PRD[Fase 1<br/>Análise de Requisitos<br/>Product Manager] --> FD[Fase 2<br/>Design de Funcionalidades<br/>Feature Designer]
73
- FD --> SD[Fase 3<br/>Design do Sistema<br/>System Designer]
74
- SD --> DEV[Fase 4<br/>Desenvolvimento<br/>System Developer]
75
- DEV --> TEST[Fase 5<br/>Teste do Sistema<br/>Test Manager]
76
- TEST --> ARCHIVE[Fase 6<br/>Arquivo]
77
-
78
- KB[(Base de Conhecimento<br/>Durante Todo o Processo)] -.-> PRD
79
- KB -.-> FD
80
- KB -.-> SD
81
- KB -.-> DEV
82
- KB -.-> TEST
83
- ```
67
+ Após executar `speccrew init`, siga estas etapas para entrar rapidamente em estado de trabalho:
84
68
 
85
- ### Princípios Fundamentais
86
-
87
- 1. **Dependências de Fases**: A entrega de cada fase é a entrada para a próxima fase
88
- 2. **Confirmação de Checkpoint**: Cada fase tem um ponto de confirmação que requer aprovação do usuário antes de prosseguir
89
- 3. **Orientado por Base de Conhecimento**: A base de conhecimento percorre todo o processo, fornecendo contexto para todas as fases
90
-
91
- ---
69
+ ### Etapa 1: Escolha Seu IDE
92
70
 
93
- ## 3. Passo Zero: Inicialização da Base de Conhecimento
71
+ | IDE | Comando de Inicialização | Cenário de Aplicação |
72
+ |-----|-----------|----------|
73
+ | **Qoder** (Recomendado) | `speccrew init --ide qoder` | Orquestração completa de agentes, workers paralelos |
74
+ | **Cursor** | `speccrew init --ide cursor` | Workflows baseados em Composer |
75
+ | **Claude Code** | `speccrew init --ide claude` | Desenvolvimento CLI-first |
76
+ | **Codex** | `speccrew init --ide codex` | Integração ecossistema OpenAI |
94
77
 
95
- Antes de iniciar o processo formal de engenharia, você precisa inicializar a base de conhecimento do projeto.
78
+ ### Etapa 2: Inicializar Base de Conhecimento (Recomendado)
96
79
 
97
- ### 3.1 Inicialização da Base de Conhecimento Técnica
80
+ Para projetos com código fonte existente, recomenda-se inicializar primeiro a base de conhecimento para que os agentes compreendam seu codebase:
98
81
 
99
- **Exemplo de Conversa**:
100
82
  ```
101
83
  @speccrew-team-leader inicializar base de conhecimento técnica
102
84
  ```
103
85
 
104
- **Processo de Três Fases**:
105
- 1. Detecção de Plataforma — Identificar plataformas tecnológicas no projeto
106
- 2. Geração de Documentação Técnica — Gerar documentos de especificação técnica para cada plataforma
107
- 3. Geração de Índice — Estabelecer índice da base de conhecimento
86
+ Depois:
108
87
 
109
- **Entregável**:
110
- ```
111
- speccrew-workspace/knowledges/techs/{platform-id}/
112
- ├── tech-stack.md # Definição do stack tecnológico
113
- ├── architecture.md # Convenções de arquitetura
114
- ├── dev-spec.md # Especificações de desenvolvimento
115
- ├── test-spec.md # Especificações de teste
116
- └── INDEX.md # Arquivo de índice
117
- ```
118
-
119
- ### 3.2 Inicialização da Base de Conhecimento de Negócio
120
-
121
- **Exemplo de Conversa**:
122
88
  ```
123
89
  @speccrew-team-leader inicializar base de conhecimento de negócio
124
90
  ```
125
91
 
126
- **Processo de Quatro Fases**:
127
- 1. Inventário de Funcionalidades — Escanear código para identificar todas as funcionalidades
128
- 2. Análise de Funcionalidades — Analisar lógica de negócio de cada funcionalidade
129
- 3. Resumo por Módulo — Resumir funcionalidades por módulo
130
- 4. Resumo do Sistema — Gerar visão geral de negócios em nível de sistema
92
+ ### Etapa 3: Comece Sua Primeira Tarefa
131
93
 
132
- **Entregável**:
133
94
  ```
134
- speccrew-workspace/knowledges/bizs/
135
- ├── {platform-type}/
136
- │ └── {module-name}/
137
- │ └── feature-spec.md
138
- └── system-overview.md
95
+ @speccrew-product-manager Tenho um novo requisito: [descreva seu requisito funcional]
139
96
  ```
140
97
 
98
+ > **Dica**: Se não tiver certeza do que fazer, basta dizer `@speccrew-team-leader me ajude a começar` — o Team Leader detectará automaticamente o status do seu projeto e o guiará.
99
+
141
100
  ---
142
101
 
143
- ## 4. Guia de Conversa Fase a Fase
102
+ ## 3. Árvore de Decisão Rápida
144
103
 
145
- ### 4.1 Fase 1: Análise de Requisitos (Product Manager)
104
+ Não tem certeza do que fazer? Encontre seu cenário abaixo:
146
105
 
147
- **Como Iniciar**:
148
- ```
149
- @speccrew-product-manager tenho um novo requisito: [descreva seu requisito]
150
- ```
106
+ - **Tenho um novo requisito funcional**
107
+ → `@speccrew-product-manager Tenho um novo requisito: [descreva seu requisito funcional]`
151
108
 
152
- **Fluxo de Trabalho do Agente**:
153
- 1. Ler visão geral do sistema para entender módulos existentes
154
- 2. Analisar requisitos do usuário
155
- 3. Gerar documento PRD estruturado
156
-
157
- **Entregável**:
158
- ```
159
- iterations/{número}-{tipo}-{nome}/01.product-requirement/
160
- ├── [feature-name]-prd.md # Documento de Requisitos do Produto
161
- └── [feature-name]-bizs-modeling.md # Modelagem de negócio (para requisitos complexos)
162
- ```
109
+ - **Quero escanear o conhecimento do projeto existente**
110
+ `@speccrew-team-leader inicializar base de conhecimento técnica`
111
+ Depois: `@speccrew-team-leader inicializar base de conhecimento de negócio`
163
112
 
164
- **Lista de Verificação de Confirmação**:
165
- - [ ] A descrição do requisito reflete precisamente a intenção do usuário?
166
- - [ ] As regras de negócio estão completas?
167
- - [ ] Os pontos de integração com sistemas existentes estão claros?
168
- - [ ] Os critérios de aceitação são mensuráveis?
113
+ - **Quero continuar o trabalho anterior**
114
+ → `@speccrew-team-leader qual é o progresso atual?`
169
115
 
170
- ---
116
+ - **Quero verificar o status de saúde do sistema**
117
+ → Executar no terminal: `speccrew doctor`
171
118
 
172
- ### 4.2 Fase 2: Design de Funcionalidades (Feature Designer)
119
+ - **Não tenho certeza do que fazer**
120
+ → `@speccrew-team-leader me ajude a começar`
121
+ → O Team Leader detectará automaticamente o status do seu projeto e o guiará
173
122
 
174
- **Como Iniciar**:
175
- ```
176
- @speccrew-feature-designer iniciar design de funcionalidades
177
- ```
123
+ ---
178
124
 
179
- **Fluxo de Trabalho do Agente**:
180
- 1. Localizar automaticamente o documento PRD confirmado
181
- 2. Carregar base de conhecimento de negócio
182
- 3. Gerar design de funcionalidades (incluindo wireframes UI, fluxos de interação, definições de dados, contratos API)
183
- 4. Para múltiplos PRDs, usar Task Worker para design paralelo
125
+ ## 4. Referência Rápida de Agentes
184
126
 
185
- **Entregável**:
186
- ```
187
- iterations/{iter}/02.feature-design/
188
- └── [feature-name]-feature-spec.md # Documento de design de funcionalidades
189
- ```
127
+ | Função | Agente | Responsabilidades | Exemplo de Comando |
128
+ |------|-------|-----------------|-----------------|
129
+ | Líder de Equipe | `@speccrew-team-leader` | Navegação do projeto, inicialização da base de conhecimento, verificação de status | "Me ajude a começar" |
130
+ | Gerente de Produto | `@speccrew-product-manager` | Análise de requisitos, geração de PRD | "Tenho um novo requisito: ..." |
131
+ | Designer de Funcionalidades | `@speccrew-feature-designer` | Análise funcional, design de especificações, contratos API | "Iniciar design de funcionalidades para iteração X" |
132
+ | Designer de Sistema | `@speccrew-system-designer` | Design de arquitetura, design detalhado por plataforma | "Iniciar design de sistema para iteração X" |
133
+ | Desenvolvedor de Sistema | `@speccrew-system-developer` | Coordenação de desenvolvimento, geração de código | "Iniciar desenvolvimento para iteração X" |
134
+ | Gerente de Testes | `@speccrew-test-manager` | Planejamento de testes, design de casos, execução | "Iniciar testes para iteração X" |
190
135
 
191
- **Lista de Verificação de Confirmação**:
192
- - [ ] Todos os cenários de usuário estão cobertos?
193
- - [ ] Os fluxos de interação estão claros?
194
- - [ ] As definições de campos de dados estão completas?
195
- - [ ] O tratamento de exceções é abrangente?
136
+ > **Nota**: Você não precisa lembrar todos os agentes. Basta conversar com `@speccrew-team-leader` e ele roteará sua solicitação para o agente certo.
196
137
 
197
138
  ---
198
139
 
199
- ### 4.3 Fase 3: Design do Sistema (System Designer)
200
-
201
- **Como Iniciar**:
202
- ```
203
- @speccrew-system-designer iniciar design do sistema
204
- ```
140
+ ## 5. Visão Geral do Workflow
205
141
 
206
- **Fluxo de Trabalho do Agente**:
207
- 1. Localizar Feature Spec e API Contract
208
- 2. Carregar base de conhecimento técnica (stack tecnológico, arquitetura, especificações para cada plataforma)
209
- 3. **Checkpoint A**: Avaliação de Framework — Analisar lacunas técnicas, recomendar novos frameworks (se necessário), aguardar confirmação do usuário
210
- 4. Gerar DESIGN-OVERVIEW.md
211
- 5. Usar Task Worker para despacho paralelo de design para cada plataforma (frontend/backend/móvel/desktop)
212
- 6. **Checkpoint B**: Confirmação Conjunta — Mostrar resumo de todos os designs de plataforma, aguardar confirmação do usuário
142
+ ### Diagrama de Fluxo Completo
213
143
 
214
- **Entregável**:
215
- ```
216
- iterations/{iter}/03.system-design/
217
- ├── DESIGN-OVERVIEW.md # Visão geral do design
218
- ├── {platform-id}/
219
- │ ├── INDEX.md # Índice de design de plataforma
220
- │ └── {module}-design.md # Design de módulo em nível de pseudocódigo
144
+ ```mermaid
145
+ flowchart LR
146
+ PRD[Fase 1<br/>Análise de Requisitos<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/>Desenvolvimento<br/>System Developer]
149
+ DEV --> TEST[Fase 5<br/>Teste de Sistema<br/>Test Manager]
150
+ TEST --> ARCHIVE[Fase 6<br/>Arquivamento]
151
+
152
+ KB[(Base de Conhecimento<br/>Durante Todo o Processo)] -.-> PRD
153
+ KB -.-> FD
154
+ KB -.-> SD
155
+ KB -.-> DEV
156
+ KB -.-> TEST
221
157
  ```
222
158
 
223
- **Lista de Verificação de Confirmação**:
224
- - [ ] O pseudocódigo usa sintaxe de framework real?
225
- - [ ] Os contratos API multiplataforma são consistentes?
226
- - [ ] A estratégia de tratamento de erros é unificada?
227
-
228
- ---
229
-
230
- ### 4.4 Fase 4: Implementação de Desenvolvimento (System Developer)
231
-
232
- **Como Iniciar**:
233
- ```
234
- @speccrew-system-developer iniciar desenvolvimento
235
- ```
159
+ ### Princípios Fundamentais
236
160
 
237
- **Fluxo de Trabalho do Agente**:
238
- 1. Ler documentos de design do sistema
239
- 2. Carregar conhecimento técnico para cada plataforma
240
- 3. **Checkpoint A**: Pré-verificação de Ambiente — Verificar versões de runtime, dependências, disponibilidade de serviços; aguardar resolução do usuário se falhar
241
- 4. Usar Task Worker para despacho paralelo de desenvolvimento para cada plataforma
242
- 5. Verificação de integração: Alinhamento de contratos API, consistência de dados
243
- 6. Gerar relatório de entrega
161
+ 1. **Dependências de Fases**: O entregável de cada fase é a entrada para a próxima fase
162
+ 2. **Confirmação de Checkpoint**: Cada fase tem um ponto de confirmação que requer aprovação do usuário antes de prosseguir para a próxima fase
163
+ 3. **Orientado pela Base de Conhecimento**: A base de conhecimento percorre todo o processo, fornecendo contexto para todas as fases
244
164
 
245
- **Entregável**:
246
- ```
247
- # Código fonte escrito no diretório de código fonte real do projeto
248
- iterations/{iter}/04.development/
249
- ├── {platform-id}/
250
- │ └── tasks/ # Registros de tarefas de desenvolvimento
251
- └── delivery-report.md
252
- ```
165
+ ---
253
166
 
254
- **Lista de Verificação de Confirmação**:
255
- - [ ] O ambiente está pronto?
256
- - [ ] Os problemas de integração estão dentro do range aceitável?
257
- - [ ] O código está em conformidade com as especificações de desenvolvimento?
167
+ ## 6. Etapa Zero: Inicialização da Base de Conhecimento
258
168
 
259
- ---
169
+ Antes de iniciar o processo formal de engenharia, você precisa inicializar a base de conhecimento do projeto.
260
170
 
261
- ### 4.5 Fase 5: Teste do Sistema (Test Manager)
171
+ ### 6.1 Inicialização da Base de Conhecimento Técnica
262
172
 
263
- **Como Iniciar**:
173
+ **Exemplo de Conversa**:
264
174
  ```
265
- @speccrew-test-manager iniciar teste
175
+ @speccrew-team-leader inicializar base de conhecimento técnica
266
176
  ```
267
177
 
268
- **Processo de Teste de Três Fases**:
269
-
270
- | Fase | Descrição | Checkpoint |
271
- |------|-----------|------------|
272
- | Design de Casos de Teste | Gerar casos de teste baseados em PRD e Feature Spec | A: Mostrar estatísticas de cobertura de casos e matriz de rastreabilidade, aguardar confirmação do usuário de cobertura suficiente |
273
- | Geração de Código de Teste | Gerar código de teste executável | B: Mostrar arquivos de teste gerados e mapeamento de casos, aguardar confirmação do usuário |
274
- | Execução de Teste e Relatório de Bugs | Executar testes automaticamente e gerar relatórios | Nenhum (execução automática) |
178
+ **Processo de Três Fases**:
179
+ 1. Detecção de Plataforma — Identificar plataformas técnicas no projeto
180
+ 2. Geração de Documentação Técnica Gerar documentos de especificação técnica para cada plataforma
181
+ 3. Geração de Índice — Estabelecer índice da base de conhecimento
275
182
 
276
183
  **Entregável**:
277
184
  ```
278
- iterations/{iter}/05.system-test/
279
- ├── cases/
280
- │ └── {platform-id}/ # Documentos de casos de teste
281
- ├── code/
282
- │ └── {platform-id}/ # Plano de código de teste
283
- ├── reports/
284
- │ └── test-report-{date}.md # Relatório de teste
285
- └── bugs/
286
- └── BUG-{id}-{title}.md # Relatórios de bugs (um arquivo por bug)
185
+ speccrew-workspace/knowledges/techs/{platform-id}/
186
+ ├── tech-stack.md # Definição do stack tecnológico
187
+ ├── architecture.md # Convenções de arquitetura
188
+ ├── dev-spec.md # Especificações de desenvolvimento
189
+ ├── test-spec.md # Especificações de teste
190
+ └── INDEX.md # Arquivo de índice
287
191
  ```
288
192
 
289
- **Lista de Verificação de Confirmação**:
290
- - [ ] A cobertura de casos está completa?
291
- - [ ] O código de teste é executável?
292
- - [ ] A avaliação de severidade de bugs é precisa?
293
-
294
- ---
295
-
296
- ### 4.6 Fase 6: Arquivo
297
-
298
- Iterações são arquivadas automaticamente ao serem concluídas:
193
+ ### 6.2 Inicialização da Base de Conhecimento de Negócio
299
194
 
195
+ **Exemplo de Conversa**:
300
196
  ```
301
- speccrew-workspace/iteration-archives/
302
- └── {número}-{tipo}-{nome}-{data}/
303
- ├── 01.product-requirement/
304
- ├── 02.feature-design/
305
- ├── 03.system-design/
306
- ├── 04.development/
307
- └── 05.system-test/
197
+ @speccrew-team-leader inicializar base de conhecimento de negócio
308
198
  ```
309
199
 
310
- ---
311
-
312
- ## 5. Visão Geral da Base de Conhecimento
313
-
314
- ### 5.1 Base de Conhecimento de Negócio (bizs)
315
-
316
- **Propósito**: Armazenar descrições de funções de negócio do projeto, divisões de módulos, características API
200
+ **Processo de Quatro Fases**:
201
+ 1. Inventário de Funcionalidades — Escanear código para identificar todas as funcionalidades
202
+ 2. Análise de Funcionalidades Analisar lógica de negócio para cada funcionalidade
203
+ 3. Resumo por Módulo — Resumir funcionalidades por módulo
204
+ 4. Resumo do Sistema — Gerar visão geral de negócio em nível de sistema
317
205
 
318
- **Estrutura de Diretórios**:
206
+ **Entregável**:
319
207
  ```
320
- knowledges/bizs/
208
+ speccrew-workspace/knowledges/bizs/
321
209
  ├── {platform-type}/
322
210
  │ └── {module-name}/
323
211
  │ └── feature-spec.md
324
212
  └── system-overview.md
325
213
  ```
326
214
 
327
- **Cenários de Uso**: Product Manager, Feature Designer
328
-
329
- ### 5.2 Base de Conhecimento Técnica (techs)
330
-
331
- **Propósito**: Armazenar stack tecnológico do projeto, convenções de arquitetura, especificações de desenvolvimento, especificações de teste
332
-
333
- **Estrutura de Diretórios**:
334
- ```
335
- knowledges/techs/{platform-id}/
336
- ├── tech-stack.md
337
- ├── architecture.md
338
- ├── dev-spec.md
339
- ├── test-spec.md
340
- └── INDEX.md
341
- ```
342
-
343
- **Cenários de Uso**: System Designer, System Developer, Test Manager
344
-
345
215
  ---
346
216
 
347
- ## 6. Gestão do Progresso do Workflow
348
-
349
- 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.
350
-
351
- ### 6.1 Arquivos de Progresso de Três Níveis
352
-
353
- O workflow mantém automaticamente três tipos de arquivos de progresso JSON, localizados no diretório de iteração:
354
-
355
- | Arquivo | Localização | Propósito |
356
- |---------|-------------|----------|
357
- | `WORKFLOW-PROGRESS.json` | `iterations/{iter}/` | Registra o status de cada estágio do pipeline |
358
- | `.checkpoints.json` | Sob cada diretório de fase | Registra o status de confirmação dos checkpoints do usuário |
359
- | `DISPATCH-PROGRESS.json` | Sob cada diretório de fase | Registra o progresso item por item para tarefas paralelas (multiplataforma/multimódulo) |
360
-
361
- ### 6.2 Fluxo de Status dos Estágios
362
-
363
- Cada fase segue este fluxo de status:
364
-
365
- ```
366
- pending → in_progress → completed → confirmed
367
- ```
368
-
369
- - **pending**: Ainda não iniciado
370
- - **in_progress**: Atualmente em execução
371
- - **completed**: Execução do Agent concluída, aguardando confirmação do usuário
372
- - **confirmed**: Confirmado pelo usuário através do checkpoint final, a próxima fase pode iniciar
373
-
374
- ### 6.3 Execução Retomável
375
-
376
- Ao reiniciar um Agent para uma fase:
377
-
378
- 1. **Verificação automática ascendente**: Verifica se a fase anterior está confirmada, bloqueia e notifica se não estiver
379
- 2. **Recuperação de checkpoints**: Lê `.checkpoints.json`, ignora checkpoints passados, continua do último ponto de interrupção
380
- 3. **Recuperação de tarefas paralelas**: Lê `DISPATCH-PROGRESS.json`, reexecuta apenas tarefas com status `pending` ou `failed`, ignora tarefas `completed`
381
-
382
- ### 6.4 Visualizar o Progresso Atual
383
-
384
- Visualizar o status panorâmico do pipeline através do Agent Team Leader:
385
-
386
- ```
387
- @speccrew-team-leader visualizar progresso da iteração atual
388
- ```
389
-
390
- O Team Leader lerá os arquivos de progresso e exibirá um resumo do status similar a:
391
-
392
- ```
393
- Pipeline Status: i001-user-management
394
- 01 PRD: ✅ Confirmed
395
- 02 Feature Design: 🔄 In Progress (Checkpoint A passed)
396
- 03 System Design: ⏳ Pending
397
- 04 Development: ⏳ Pending
398
- 05 System Test: ⏳ Pending
399
- ```
400
-
401
- ### 6.5 Compatibilidade com Versões Anteriores
402
-
403
- 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.
404
-
405
- ---
406
-
407
- ## 7. Perguntas Frequentes (FAQ)
408
-
409
- ### P1: O que fazer se o Agente não funcionar como esperado?
410
-
411
- 1. Execute `speccrew doctor` para verificar integridade da instalação
412
- 2. Confirme que a base de conhecimento foi inicializada
413
- 3. Confirme que o entregável da fase anterior existe no diretório de iteração atual
414
-
415
- ### P2: Como pular uma fase?
416
-
417
- **Não recomendado** — A saída de cada fase é a entrada para a próxima fase.
418
-
419
- Se precisar pular, prepare manualmente o documento de entrada da fase correspondente e certifique-se de que siga as especificações de formato.
420
-
421
- ### P3: Como lidar com múltiplos requisitos em paralelo?
422
-
423
- Crie diretórios de iteração independentes para cada requisito:
424
- ```
425
- iterations/
426
- ├── 001-feature-xxx/
427
- ├── 002-feature-yyy/
428
- └── 003-feature-zzz/
429
- ```
430
-
431
- Cada iteração está completamente isolada e não afeta as outras.
432
-
433
- ### P4: Como atualizar a versão do SpecCrew?
434
-
435
- A atualização requer duas etapas:
436
-
437
- ```bash
438
- # Etapa 1: Atualizar a ferramenta CLI global
439
- npm install -g speccrew@latest
440
-
441
- # Etapa 2: Sincronizar Agentes e Skills no diretório do projeto
442
- cd /path/to/your-project
443
- speccrew update
444
- ```
445
-
446
- - `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.)
447
- - `speccrew update`: Sincroniza os arquivos de definição de Agent e Skill no seu projeto para a versão mais recente
448
- - `speccrew update --ide cursor`: Atualiza a configuração apenas para um IDE específico
449
-
450
- > **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.
451
-
452
- ### P5: `speccrew update` mostra nova versão mas após instalação ainda é a antiga?
453
-
454
- Geralmente é causado pelo cache do npm. Solução:
455
- ```bash
456
- npm cache clean --force
457
- npm install -g speccrew@latest
458
- npm list -g speccrew
459
- ```
460
- Se ainda não funcionar, instale uma versão específica:
461
- ```bash
462
- npm install -g speccrew@0.5.6
463
- ```
464
-
465
- ### P6: Como ver iterações históricas?
466
-
467
- Após arquivar, consulte em `speccrew-workspace/iteration-archives/`, organizado no formato `{número}-{tipo}-{nome}-{data}/`.
468
-
469
- ### P7: A base de conhecimento precisa de atualizações regulares?
470
-
471
- Reinicialização é necessária nas seguintes situações:
472
- - Mudanças significativas na estrutura do projeto
473
- - Upgrade ou substituição do stack tecnológico
474
- - Adição/remoção de módulos de negócio
475
-
476
- ---
477
-
478
- ## 8. Referência Rápida
479
-
480
- ### Referência Rápida de Início de Agentes
481
-
482
- | Fase | Agente | Conversa de Início |
483
- |------|--------|-------------------|
484
-
485
- | Inicialização | Team Leader | `@speccrew-team-leader inicializar base de conhecimento técnica` |
486
- | Análise de Requisitos | Product Manager | `@speccrew-product-manager tenho um novo requisito: [descrição]` |
487
- | Design de Funcionalidades | Feature Designer | `@speccrew-feature-designer iniciar design de funcionalidades` |
488
- | Design do Sistema | System Designer | `@speccrew-system-designer iniciar design do sistema` |
489
- | Desenvolvimento | System Developer | `@speccrew-system-developer iniciar desenvolvimento` |
490
- | Teste do Sistema | Test Manager | `@speccrew-test-manager iniciar teste` |
491
-
492
- ### Lista de Verificação de Checkpoints
493
-
494
- | Fase | Número de Checkpoints | Elementos Chave de Verificação |
495
- |------|----------------------|--------------------------------|
496
- | Análise de Requisitos | 1 | Precisão de requisitos, completude de regras de negócio, mensurabilidade de critérios de aceitação |
497
- | Design de Funcionalidades | 1 | Cobertura de cenários, clareza de interação, completude de dados, tratamento de exceções |
498
- | Design do Sistema | 2 | A: Avaliação de framework; B: Sintaxe de pseudocódigo, consistência multiplataforma, tratamento de erros |
499
- | Desenvolvimento | 1 | A: Preparação do ambiente, problemas de integração, especificações de código |
500
- | Teste do Sistema | 2 | A: Cobertura de casos; B: Executabilidade do código de teste |
501
-
502
- ### Referência Rápida de Caminhos de Entregáveis
503
-
504
- | Fase | Diretório de Saída | Formato de Arquivo |
505
- |------|-------------------|-------------------|
506
- | Análise de Requisitos | `iterations/{iter}/01.product-requirement/` | `[name]-prd.md`, `[name]-bizs-modeling.md` |
507
- | Design de Funcionalidades | `iterations/{iter}/02.feature-design/` | `[name]-feature-spec.md` |
508
- | Design do Sistema | `iterations/{iter}/03.system-design/` | `DESIGN-OVERVIEW.md`, `{platform}/INDEX.md`, `{platform}/{module}-design.md` |
509
- | Desenvolvimento | `iterations/{iter}/04.development/` | Código fonte + `delivery-report.md` |
510
- | Teste do Sistema | `iterations/{iter}/05.system-test/` | `cases/`, `code/`, `reports/`, `bugs/` |
511
- | Arquivo | `iteration-archives/{iter}-{data}/` | Cópia completa da iteração |
512
-
513
- ---
514
-
515
- ## Próximos Passos
516
-
517
- 1. Execute `speccrew init --ide qoder` para inicializar seu projeto
518
- 2. Execute o Passo Zero: Inicialização da Base de Conhecimento
519
- 3. Avance através de cada fase seguindo o fluxo de trabalho, aproveitando a experiência de desenvolvimento orientada por especificações!
217
+ [Continuação do documento com as seções 7-11...]