speccrew 0.6.21 → 0.6.22

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.
@@ -1091,65 +1091,117 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
1091
1091
  > Multiple items detected → MUST dispatch speccrew-task-worker.
1092
1092
  > DO NOT invoke skills directly. See MANDATORY WORKER ENFORCEMENT section.
1093
1093
 
1094
+ > 🛑 **ORCHESTRATOR PRINCIPLE — PM Agent is DISPATCHER, NOT WORKER:**
1095
+ > The PM Agent MUST dispatch ONE Worker per Sub-PRD module.
1096
+ > Each Worker generates ONE Sub-PRD file.
1097
+ > PM Agent tracks progress and sends batches — PM Agent NEVER generates Sub-PRD content.
1098
+
1094
1099
  **IF the Skill output includes a Sub-PRD Dispatch Plan (from Step 12c), execute this phase.**
1095
1100
  **IF Single PRD structure, skip to Phase 6.**
1096
1101
 
1097
- After the Skill generates the Master PRD and outputs the dispatch plan, the PM Agent takes over to generate Sub-PRDs in parallel using worker agents.
1102
+ After the Skill generates the Master PRD and outputs the dispatch plan, the PM Agent takes over to dispatch Sub-PRD generation to worker agents.
1098
1103
 
1099
- > **Phase 5 Execution Flow:**
1104
+ > **CORRECT Phase 5 Execution Flow (Dispatch-Tracked):**
1100
1105
  > ```
1101
1106
  > Generate Skill outputs Dispatch Plan
1102
1107
  > ↓
1103
1108
  > PM reads Dispatch Plan (module list + contexts)
1104
1109
  > ↓
1105
- > PM initializes DISPATCH-PROGRESS.json (via script)
1110
+ > PM initializes DISPATCH-PROGRESS.json (via script) ← Step 5.2
1106
1111
  > ↓
1107
- > PM invokes speccrew-task-worker × N (one per module)
1108
- > └─ Each worker internally calls speccrew-pm-sub-prd-generate
1112
+ > PM dispatches Workers IN BATCHES Step 5.3
1113
+ > ├─ Batch 1: Workers 1-5 (parallel dispatch)
1114
+ > ├─ Wait for Batch 1 completion
1115
+ > ├─ Update DISPATCH-PROGRESS.json per completed worker
1116
+ > ├─ Batch 2: Workers 6-10 (parallel dispatch)
1117
+ > ├─ Wait for Batch 2 completion
1118
+ > └─ ... until all modules done
1109
1119
  > ↓
1110
- > Workers complete → PM updates progress (via script)
1120
+ > ALL workers done → PM verifies in Step 5.5
1111
1121
  > ↓
1112
- > ALL workers done → Phase 6
1122
+ > ALL verified → Phase 6
1113
1123
  > ```
1114
1124
  >
1115
- > **NOT this flow:**
1125
+ > **WRONG flow (VIOLATION):**
1126
+ > ```
1127
+ > PM reads Dispatch Plan
1128
+ > ↓
1129
+ > PM dispatches ONE Worker for ALL modules ← VIOLATION
1130
+ > └─ Worker internally loops to generate all Sub-PRDs
1131
+ > ↓
1132
+ > This is serial generation, NOT parallel dispatch
1133
+ > ```
1134
+ >
1135
+ > **ALSO WRONG:**
1116
1136
  > ```
1117
1137
  > PM reads Dispatch Plan → PM generates Sub-PRDs directly ← VIOLATION
1118
1138
  > ```
1119
1139
 
1140
+ ---
1141
+
1120
1142
  ### 5.1 Read Dispatch Plan
1121
1143
 
1122
1144
  From the Skill's Step 12c output, collect:
1123
1145
  - `feature_name`: System-level feature name
1124
1146
  - `template_path`: Path to PRD-TEMPLATE.md
1125
1147
  - `master_prd_path`: Path to the generated Master PRD
1148
+ - `clarification_file`: Path to `.clarification-summary.md`
1149
+ - `module_design_file`: Path to `.module-design.md`
1126
1150
  - `output_dir`: Directory for Sub-PRD files (same as Master PRD directory)
1127
1151
  - Module list with context for each module:
1128
1152
  - `module_name`, `module_key`, `module_scope`, `module_entities`
1129
1153
  - `module_user_stories`, `module_requirements`, `module_features`
1130
1154
  - `module_dependencies`
1131
1155
 
1132
- ### 5.1b Initialize Dispatch Progress Tracking
1156
+ **Store these values as workflow context variables for use in Worker dispatches.**
1157
+
1158
+ ---
1159
+
1160
+ ### 5.2 Initialize Dispatch Progress Tracking
1161
+
1162
+ > 🛑 **HARD STOP: This step MUST complete before ANY Worker dispatch.**
1163
+
1164
+ **Step 5.2.1: Prepare tasks array**
1133
1165
 
1134
- **MANDATORY: Initialize dispatch tracking with script:**
1166
+ Create a temporary file with task definitions for each module:
1167
+
1168
+ ```json
1169
+ [
1170
+ {
1171
+ "id": "{module_key_1}",
1172
+ "name": "{module_name_1}",
1173
+ "status": "pending",
1174
+ "output_file": "{output_dir}/{feature_name}-sub-{module_key_1}.md"
1175
+ },
1176
+ {
1177
+ "id": "{module_key_2}",
1178
+ "name": "{module_name_2}",
1179
+ "status": "pending",
1180
+ "output_file": "{output_dir}/{feature_name}-sub-{module_key_2}.md"
1181
+ }
1182
+ ]
1183
+ ```
1184
+
1185
+ **Step 5.2.2: Initialize DISPATCH-PROGRESS.json**
1135
1186
 
1136
1187
  > ⚠️ Use --tasks-file instead of --tasks to avoid PowerShell JSON parsing issues.
1137
1188
 
1138
1189
  ```bash
1139
- # Write tasks to temp file inside iteration directory
1140
- # Create .tasks-temp.json with task array content
1141
- node "{update_progress_script}" init \
1142
- --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
1143
- --stage sub_prd_dispatch \
1144
- --tasks-file {iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json
1145
- # Delete .tasks-temp.json after successful init
1190
+ # PowerShell compatible command
1191
+ node "{update_progress_script}" init `
1192
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1193
+ --stage sub_prd_dispatch `
1194
+ --tasks-file "{iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json"
1195
+
1196
+ # Clean up temp file after successful init
1197
+ Remove-Item "{iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json"
1146
1198
  ```
1147
1199
 
1148
1200
  > **PowerShell Compatibility Note:**
1149
1201
  > PowerShell cannot properly parse JSON in command-line arguments. Use file-based approach:
1150
- > 1. Write tasks JSON to a temporary file (e.g., `tasks-temp.json`)
1151
- > 2. Read file content in the command: `node "{update_progress_script}" init --stage sub_prd_dispatch --tasks (Get-Content tasks-temp.json -Raw)`
1152
- > 3. Or use: `Get-Content tasks-temp.json | node "{update_progress_script}" init --stage sub_prd_dispatch --tasks -`
1202
+ > 1. Write tasks JSON to a temporary file (e.g., `.tasks-temp.json`)
1203
+ > 2. Run the init command with `--tasks-file` pointing to the temp file
1204
+ > 3. Delete temp file after successful init
1153
1205
 
1154
1206
  > 🛑 **HARD STOP: DISPATCH-PROGRESS.json MUST be created by script ONLY**
1155
1207
  > - MUST use: `node "{update_progress_script}" init --stage sub_prd_dispatch --tasks-file <TASKS_FILE>`
@@ -1157,116 +1209,281 @@ node "{update_progress_script}" init \
1157
1209
  > - IF script fails → STOP workflow immediately, report error to user, ask "Retry or Abort?"
1158
1210
  > - DO NOT proceed to Worker dispatch without successful script execution
1159
1211
 
1160
- After each worker completes:
1161
- ```bash
1162
- node "{update_progress_script}" update-task \
1163
- --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
1164
- --task-id {module_key} --status completed
1165
- ```
1212
+ **Step 5.2.3: Verify initialization**
1166
1213
 
1167
- If a worker fails:
1168
1214
  ```bash
1169
- node "{update_progress_script}" update-task \
1170
- --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
1171
- --task-id {module_key} --status failed --error "{error_message}"
1215
+ node "{update_progress_script}" read `
1216
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1217
+ --summary
1172
1218
  ```
1173
1219
 
1174
- ### 5.3 Dispatch Workers
1220
+ Expected output: `Total: N tasks | Pending: N | Completed: 0 | Failed: 0`
1221
+
1222
+ ---
1223
+
1224
+ ### 5.3 Dispatch Workers (Batch Parallel)
1225
+
1226
+ > 🛑 **CRITICAL: ONE Worker per Module — NO EXCEPTIONS**
1227
+ >
1228
+ > | Module Count | Dispatch Strategy |
1229
+ > |--------------|-------------------|
1230
+ > | 1-5 modules | Single batch, all parallel |
1231
+ > | 6-10 modules | 2 batches of 5 |
1232
+ > | 11-15 modules | 3 batches of 5 |
1233
+ > | 16+ modules | Batches of 5, final batch may be smaller |
1234
+ >
1235
+ > **BATCH SIZE = 5 (maximum parallel Workers per batch)**
1175
1236
 
1176
1237
  **PM Agent Role: ORCHESTRATOR ONLY — Phase 5 EXPLICIT RULES**
1177
1238
 
1178
1239
  **MANDATORY — PM MUST:**
1179
1240
  1. Read the Dispatch Plan from generate skill output
1180
- 2. Initialize DISPATCH-PROGRESS.json via update-progress.js script
1181
- 3. For EACH module in dispatch plan: invoke `speccrew-task-worker` with `skill_path: speccrew-pm-sub-prd-generate/SKILL.md`
1241
+ 2. Initialize DISPATCH-PROGRESS.json via update-progress.js script (Step 5.2)
1242
+ 3. For EACH module in dispatch plan: invoke ONE `speccrew-task-worker`
1182
1243
  4. Pass ALL required context parameters to each worker
1183
- 5. Wait for ALL workers to complete
1184
- 6. Update DISPATCH-PROGRESS.json via script after each worker completes
1244
+ 5. Dispatch in batches of 5, wait for each batch to complete
1245
+ 6. After each Worker completes, update DISPATCH-PROGRESS.json via script
1185
1246
 
1186
1247
  🛑 **FORBIDDEN — PM MUST NOT:**
1187
1248
  - Generate Sub-PRD files directly (via create_file, write, or any file creation)
1188
1249
  - Invoke speccrew-pm-sub-prd-generate skill directly (ONLY speccrew-task-worker invokes it)
1250
+ - Dispatch ONE Worker to handle MULTIPLE modules (each module = one Worker)
1189
1251
  - Create or edit any Sub-PRD content as fallback if worker fails
1190
1252
  - Skip worker dispatch and generate Sub-PRDs inline
1191
1253
  - IF PM attempts ANY of above → WORKFLOW VIOLATION → STOP immediately
1192
1254
 
1193
- **Implementation:**
1194
-
1195
- For EACH module in the dispatch plan, invoke a new `speccrew-task-worker` agent:
1196
- - **skill_path**: Search with glob `**/speccrew-pm-sub-prd-generate/SKILL.md`
1197
- - **context**:
1198
- - `module_name`: from dispatch plan
1199
- - `module_key`: from dispatch plan
1200
- - `master_prd_path`: path to Master PRD
1201
- - `template_path`: PRD template path (from Step 7 glob search result)
1202
- - `output_dir`: `{iterations_dir}/{iteration}/01.product-requirement/` (absolute path from Phase 0.6)
1203
-
1204
- Each worker receives:
1205
- - `skill_path`: `speccrew-pm-sub-prd-generate/SKILL.md`
1206
- - `context`:
1207
- - `module_name`: Module name (e.g., "Customer Management")
1208
- - `module_key`: Module identifier for file naming (e.g., "customer")
1209
- - `module_scope`: What this module covers
1210
- - `module_entities`: Core business entities
1211
- - `module_user_stories`: Module-specific user stories
1212
- - `module_requirements`: Module-specific functional requirements (P0/P1/P2)
1213
- - `module_features`: Feature Breakdown entries for this module
1214
- - `module_dependencies`: Dependencies on other modules
1215
- - `master_prd_path`: Path to the Master PRD
1216
- - `feature_name`: System-level feature name
1217
- - `template_path`: Path to PRD-TEMPLATE.md
1218
- - `output_path`: `{output_dir}/{feature_name}-sub-{module_key}.md`
1219
-
1220
- **Batch Strategy:**
1221
- - If modules ≤ 6: dispatch ALL in parallel
1222
- - If modules > 6: dispatch in batches of 6, wait for batch completion before next batch
1223
-
1224
- **Parallel execution pattern:**
1255
+ ---
1256
+
1257
+ #### Step 5.3.1: Determine Batch Plan
1258
+
1259
+ <arg_value>Read DISPATCH-PROGRESS.json to get pending tasks:
1260
+
1261
+ ```bash
1262
+ node "{update_progress_script}" read `
1263
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json"
1264
+ ```
1265
+
1266
+ Group tasks into batches:
1225
1267
  ```
1226
- Worker 1: Module "customer" → crm-system-sub-customer.md
1227
- Worker 2: Module "contact" → crm-system-sub-contact.md
1228
- Worker 3: Module "opportunity" → crm-system-sub-opportunity.md
1229
- ...
1230
- Worker N: Module "{module-N}" → crm-system-sub-{module-N}.md
1268
+ 📊 Sub-PRD Dispatch Plan
1269
+ ├── Total Modules: 14
1270
+ ├── Batch Size: 5
1271
+ ├── Batches Required: 3
1272
+ │ ├── Batch 1: modules 1-5 (customer, contact, opportunity, lead, activity)
1273
+ │ ├── Batch 2: modules 6-10 (report, dashboard, workflow, notification, integration)
1274
+ │ └── Batch 3: modules 11-14 (security, audit, config, help)
1275
+ └── Strategy: Parallel dispatch within batch, sequential between batches
1231
1276
  ```
1232
1277
 
1233
- **All workers execute simultaneously (or in batches).** Wait for all workers to complete before proceeding.
1278
+ ---
1234
1279
 
1235
- **Before proceeding to Phase 6, verify:**
1236
- - [ ] All workers were dispatched via speccrew-task-worker
1237
- - [ ] No Sub-PRD was generated by PM Agent directly
1238
- - [ ] All workers completed (check DISPATCH-PROGRESS.json)
1280
+ #### Step 5.3.2: Dispatch Batch N
1239
1281
 
1240
- ### 5.4 Collect Results
1282
+ For EACH module in current batch, dispatch ONE `speccrew-task-worker`:
1241
1283
 
1242
- After all workers complete:
1284
+ **Agent Tool Invocation Format (REPEAT for each module):**
1243
1285
 
1244
- 1. **Check worker results**: Verify each worker reported success
1245
- 2. **List generated files**:
1246
- ```
1247
- 📊 Sub-PRD Generation Results:
1248
- ├── Worker 1: {module-1} → ✅ Generated ({file_size})
1249
- ├── Worker 2: {module-2} → ✅ Generated ({file_size})
1250
- ├── Worker N: {module-N} → ✅ Generated ({file_size})
1251
-
1252
- Total: N workers | Completed: X | Failed: Y
1253
- ```
1286
+ ```
1287
+ Use the Agent tool to invoke speccrew-task-worker:
1288
+ - agent: speccrew-task-worker
1289
+ - task: Generate Sub-PRD for module "{module_name}"
1290
+ - context:
1291
+ skill: speccrew-pm-sub-prd-generate
1292
+ module_name: {module_name}
1293
+ module_key: {module_key}
1294
+ module_scope: {module_scope}
1295
+ module_entities: {module_entities}
1296
+ module_user_stories: {module_user_stories}
1297
+ module_requirements: {module_requirements}
1298
+ module_features: {module_features}
1299
+ module_dependencies: {module_dependencies}
1300
+ master_prd_path: {master_prd_path}
1301
+ clarification_file: {clarification_file}
1302
+ module_design_file: {module_design_file}
1303
+ feature_name: {feature_name}
1304
+ template_path: {template_path}
1305
+ output_path: {output_dir}/{feature_name}-sub-{module_key}.md
1306
+ language: {language}
1307
+ ```
1308
+
1309
+ **Worker Context Parameters:**
1310
+
1311
+ | Parameter | Source | Description |
1312
+ |-----------|--------|-------------|
1313
+ | `skill` | Fixed | `speccrew-pm-sub-prd-generate` |
1314
+ | `module_name` | Dispatch Plan | Display name (e.g., "Customer Management") |
1315
+ | `module_key` | Dispatch Plan | Identifier for file naming (e.g., "customer") |
1316
+ | `module_scope` | Dispatch Plan | What this module covers |
1317
+ | `module_entities` | Dispatch Plan | Core business entities |
1318
+ | `module_user_stories` | Dispatch Plan | Module-specific user stories |
1319
+ | `module_requirements` | Dispatch Plan | Module-specific functional requirements (P0/P1/P2) |
1320
+ | `module_features` | Dispatch Plan | Feature Breakdown entries for this module |
1321
+ | `module_dependencies` | Dispatch Plan | Dependencies on other modules |
1322
+ | `master_prd_path` | Dispatch Plan | Path to the Master PRD |
1323
+ | `clarification_file` | Step 5.1 | Path to `.clarification-summary.md` |
1324
+ | `module_design_file` | Step 5.1 | Path to `.module-design.md` |
1325
+ | `feature_name` | Dispatch Plan | System-level feature name |
1326
+ | `template_path` | Dispatch Plan | Path to PRD-TEMPLATE.md |
1327
+ | `output_path` | Computed | `{output_dir}/{feature_name}-sub-{module_key}.md` |
1328
+ | `language` | Detected | User's language |
1329
+
1330
+ **Dispatch Example (Batch 1 with 5 modules):**
1331
+
1332
+ ```
1333
+ 📊 Dispatching Batch 1 (5 modules in parallel)
1334
+ ├── Worker 1: module="customer" → output: crm-system-sub-customer.md
1335
+ ├── Worker 2: module="contact" → output: crm-system-sub-contact.md
1336
+ ├── Worker 3: module="opportunity" → output: crm-system-sub-opportunity.md
1337
+ ├── Worker 4: module="lead" → output: crm-system-sub-lead.md
1338
+ └── Worker 5: module="activity" → output: crm-system-sub-activity.md
1339
+
1340
+ Waiting for all 5 Workers to complete...
1341
+ ```
1342
+
1343
+ ---
1344
+
1345
+ #### Step 5.3.3: Update Progress After Each Worker
1254
1346
 
1255
- 3. **Handle failures**: If any worker failed:
1256
- - Report which modules failed and why
1257
- - Re-dispatch failed modules (retry once)
1258
- - If retry fails, report to user for manual intervention
1347
+ **When a Worker completes successfully:**
1348
+
1349
+ ```bash
1350
+ node "{update_progress_script}" update-task `
1351
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1352
+ --task-id "{module_key}" `
1353
+ --status completed
1354
+ ```
1355
+
1356
+ **When a Worker fails:**
1357
+
1358
+ ```bash
1359
+ node "{update_progress_script}" update-task `
1360
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1361
+ --task-id "{module_key}" `
1362
+ --status failed `
1363
+ --error "{error_message}"
1364
+ ```
1365
+
1366
+ **After each batch completes, show progress:**
1367
+
1368
+ ```
1369
+ 📊 Batch 1 Complete
1370
+ ├── ✅ customer: completed
1371
+ ├── ✅ contact: completed
1372
+ ├── ✅ opportunity: completed
1373
+ ├── ❌ lead: failed (timeout)
1374
+ └── ✅ activity: completed
1375
+
1376
+ Progress: 4/14 completed, 1 failed, 9 pending
1377
+ Proceeding to Batch 2...
1378
+ ```
1379
+
1380
+ ---
1381
+
1382
+ #### Step 5.3.4: Continue to Next Batch
1383
+
1384
+ After current batch completes:
1385
+ 1. Check DISPATCH-PROGRESS.json for remaining pending tasks
1386
+ 2. If pending tasks remain → dispatch next batch (Step 5.3.2)
1387
+ 3. If all tasks done → proceed to Step 5.4
1388
+
1389
+ ```bash
1390
+ node "{update_progress_script}" read `
1391
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1392
+ --summary
1393
+ ```
1394
+
1395
+ Continue dispatching batches until `counts.pending == 0`.
1396
+
1397
+ ---
1398
+
1399
+ ### 5.4 Handle Failures & Retry
1400
+
1401
+ After all batches complete, check for failed tasks:
1402
+
1403
+ ```bash
1404
+ node "{update_progress_script}" read `
1405
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json"
1406
+ ```
1407
+
1408
+ **If any tasks have `status: "failed"`:**
1409
+
1410
+ 1. List failed modules
1411
+ 2. Re-dispatch ONE Worker per failed module (single retry)
1412
+ 3. Update status after retry
1413
+ 4. If retry fails again, report to user for manual intervention
1414
+
1415
+ ```
1416
+ 📊 Retry Summary
1417
+ ├── Retrying 2 failed modules...
1418
+ │ ├── Worker: module="lead" → retry
1419
+ │ └── Worker: module="report" → retry
1420
+ ├── Retry Results:
1421
+ │ ├── ✅ lead: completed (retry successful)
1422
+ │ └── ❌ report: failed (retry failed)
1423
+ └── Final Status: 13/14 completed, 1 failed
1424
+
1425
+ Module "report" failed after retry. Manual intervention required.
1426
+ Options:
1427
+ - Skip and continue with 13/14 Sub-PRDs
1428
+ - Abort and investigate
1429
+ ```
1430
+
1431
+ ---
1432
+
1433
+ ### 5.5 Collect Results & Verify
1434
+
1435
+ > 🛑 **Verification before proceeding to Phase 6**
1436
+
1437
+ **Step 5.5.1: Read Final Progress**
1438
+
1439
+ ```bash
1440
+ node "{update_progress_script}" read `
1441
+ --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
1442
+ --summary
1443
+ ```
1444
+
1445
+ Expected: `Total: N | Pending: 0 | Completed: N | Failed: 0`
1446
+
1447
+ **Step 5.5.2: Verify All Sub-PRD Files Exist**
1448
+
1449
+ ```bash
1450
+ # List all Sub-PRD files
1451
+ Get-ChildItem "{iterations_dir}/{iteration}/01.product-requirement/" -Filter "*-sub-*.md"
1452
+ ```
1453
+
1454
+ Verify:
1455
+ - File count matches DISPATCH-PROGRESS.json completed count
1456
+ - Each file has size > 3KB
1457
+
1458
+ **Step 5.5.3: Report Final Summary**
1259
1459
 
1260
- After all workers complete, report dispatch summary:
1261
1460
  ```
1262
1461
  📊 Sub-PRD Generation Complete:
1263
- ├── Total: 11 modules
1264
- ├── ✅ Completed: 10
1265
- ├── ❌ Failed: 1 (member — error description)
1266
- └── Retry failed modules? (yes/skip)
1462
+ ├── Total Modules: {count}
1463
+ ├── ✅ Completed: {count}
1464
+ ├── ❌ Failed: {count}
1465
+ ├── Generated Files:
1466
+ │ ├── {feature_name}-sub-{module_1}.md ({size} KB)
1467
+ │ ├── {feature_name}-sub-{module_2}.md ({size} KB)
1468
+ │ └── ...
1469
+ └── All Sub-PRDs ready for Phase 6 Verification
1267
1470
  ```
1268
1471
 
1269
- Update `.checkpoints.json` → `sub_prd_dispatch.passed = true` (only if all succeeded or user skips failures).
1472
+ **Step 5.5.4: Update Checkpoint**
1473
+
1474
+ ```bash
1475
+ node "{update_progress_script}" write-checkpoint `
1476
+ --file "{iterations_dir}/{iteration}/01.product-requirement/.checkpoints.json" `
1477
+ --checkpoint sub_prd_dispatch `
1478
+ --status passed
1479
+ ```
1480
+
1481
+ **Before proceeding to Phase 6, verify:**
1482
+ - [ ] All workers were dispatched via speccrew-task-worker (one Worker per module)
1483
+ - [ ] No Sub-PRD was generated by PM Agent directly
1484
+ - [ ] All workers completed (DISPATCH-PROGRESS.json counts.pending == 0)
1485
+ - [ ] All Sub-PRD files exist and have valid size
1486
+ - [ ] Checkpoint updated
1270
1487
 
1271
1488
  > 🛑 **MANDATORY**: After all Sub-PRDs are generated and checkpoint is recorded, you MUST immediately proceed to Phase 6 (Verification & User Review). DO NOT skip Phase 6. DO NOT directly ask the user if they want to continue to Feature Design. Phase 6 handles the formal verification, user review, and status update.
1272
1489
 
@@ -68,6 +68,53 @@ tools: Read, Write, Glob, Grep
68
68
 
69
69
  ## Step 3: Fill Module-Specific Content
70
70
 
71
+ > **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
72
+ >
73
+ > This step MUST be executed in two phases to ensure consistent document structure.
74
+
75
+ ### Phase A: Skeleton Construction (BEFORE any content filling)
76
+
77
+ 1. Read PRD-TEMPLATE.md to identify the complete section structure
78
+ 2. Count the number of features from `{module_features}` input
79
+ 3. For Section 3.5 Feature Details, replicate the template's Feature block structure for EACH feature:
80
+ - Copy the EXACT template structure (all 6 sub-sections) from PRD-TEMPLATE.md
81
+ - Create `#### Feature 1: {feature_name}` through `#### Feature N: {feature_name}`
82
+ - Each feature block MUST contain these 6 sub-section headers (copied from template):
83
+ ```
84
+ **Requirement Description:**
85
+ [TO BE FILLED]
86
+
87
+ **Interaction Flow:**
88
+ [TO BE FILLED]
89
+
90
+ **Boundary Conditions:**
91
+ [TO BE FILLED]
92
+
93
+ **Exception Scenarios:**
94
+ [TO BE FILLED]
95
+
96
+ **Operation Flow Diagram:**
97
+ [TO BE FILLED]
98
+
99
+ **Operation Steps Detail:**
100
+ [TO BE FILLED]
101
+ ```
102
+ 4. Verify skeleton: confirm ALL features have ALL 6 sub-section headers before proceeding
103
+
104
+ > ⚠️ DO NOT start filling content until the complete skeleton is verified.
105
+
106
+ ### Phase B: Content Filling (AFTER skeleton is complete)
107
+
108
+ Fill each `[TO BE FILLED]` placeholder with actual content:
109
+ - Requirement Description → Business requirements in business language
110
+ - Interaction Flow → User interaction steps (numbered list)
111
+ - Boundary Conditions → Table with Condition Type | Scenario | Handling Rule
112
+ - Exception Scenarios → Bullet list of exception handling
113
+ - Operation Flow Diagram → Mermaid `graph LR` diagram showing operation flow
114
+ - Operation Steps Detail → Table with Step | Action | Expected Outcome | Exception Handling
115
+
116
+ ---
117
+
71
118
  Fill each section using `search_replace`:
72
119
 
73
120
  ### 3.1 Section 1: Background & Goals
@@ -85,11 +132,17 @@ Fill each section using `search_replace`:
85
132
  - 3.4 Feature Breakdown: **REQUIRED** — Fill with `{module_features}` data:
86
133
  - Feature ID, Feature Name, Type (User Interaction / Backend Process), Scope, Description
87
134
  - Feature Dependencies table
88
- - 3.5 Feature Details: Detailed descriptions for each feature including:
135
+ - 3.5 Feature Details: **FOR EACH feature in module_features, fill ALL 6 sub-sections below:**
136
+
137
+ **Complete structure (MUST repeat for every Feature 1, 2, ... N):**
89
138
  - Requirement Description — **Business requirements in business language**
90
139
  - Interaction Flow — **User interaction steps in business terms**
91
140
  - Boundary Conditions table — **Business scenarios and business handling rules**
92
141
  - Exception Scenarios — **Business exception handling in business language**
142
+ - Operation Flow Diagram — **Mermaid `graph LR` showing business operation steps (REQUIRED for EVERY feature)**
143
+ - Operation Steps Detail — **Table: Step | Action | Expected Outcome | Business Exception Handling (REQUIRED for EVERY feature)**
144
+
145
+ > ⚠️ **CRITICAL**: ALL features MUST have the SAME 6-section structure. DO NOT skip Operation Flow Diagram or Operation Steps Detail for ANY feature. Check the PRD-TEMPLATE.md for the exact format.
93
146
 
94
147
  ### 3.4 Section 4: Non-functional Requirements
95
148
  - Module-specific performance, security, compatibility requirements
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "speccrew",
3
- "version": "0.6.21",
3
+ "version": "0.6.22",
4
4
  "description": "Spec-Driven Development toolkit for AI-powered IDEs",
5
5
  "author": "charlesmu99",
6
6
  "repository": {