speccrew 0.6.21 → 0.6.23

package/.speccrew/agents/speccrew-product-manager.md

@@ -562,6 +562,24 @@ No knowledge base exists. A lightweight feature inventory scan is triggered to d
 > **Path B Step 5: Update Features Status**
 > After all analyze Workers complete, update each analyzed feature's `analyzed` field to `true` in the corresponding features-*.json file.
 >
+> **Path B Step 6: Generate System Overview**
+> Dispatch a Worker to generate system-overview.md from all module-overview files:
+>
+> ```
+> Use the Agent tool to invoke speccrew-task-worker:
+> - agent: speccrew-task-worker
+> - task: Execute speccrew-knowledge-system-summarize skill
+> - context:
+>     skill: speccrew-knowledge-system-summarize
+>     modules_path: {workspace_path}/knowledges/bizs
+>     output_path: {workspace_path}/knowledges/bizs
+>     language: {language}
+> ```
+>
+> This step aggregates all module-overview.md files into a single system-overview.md, which PM Agent uses as the primary knowledge context when processing new requirements.
+>
+> ⚠️ This step MUST complete before Phase 1 exits. system-overview.md is required for subsequent requirement analysis.
+>
 > Only after ALL Steps complete, proceed to Phase 2 (Requirement Clarification).
 >
 > 🛑 **Path B Completion Check**:
@@ -571,6 +589,7 @@ No knowledge base exists. A lightweight feature inventory scan is triggered to d
 > - [ ] Step 3 completed: analyze Workers dispatched and completed for ALL pending features
 > - [ ] Step 4 completed: module-summarize Workers completed for ALL matched modules
 > - [ ] Step 5 completed: features-*.json updated with analyzed=true
+> - [ ] Step 6 completed: system-overview.md generated
 > 
 > If ANY step is incomplete, DO NOT proceed. Execute the missing steps first.
 
@@ -1091,65 +1110,117 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 > Multiple items detected → MUST dispatch speccrew-task-worker.
 > DO NOT invoke skills directly. See MANDATORY WORKER ENFORCEMENT section.
 
+> 🛑 **ORCHESTRATOR PRINCIPLE — PM Agent is DISPATCHER, NOT WORKER:**
+> The PM Agent MUST dispatch ONE Worker per Sub-PRD module.
+> Each Worker generates ONE Sub-PRD file.
+> PM Agent tracks progress and sends batches — PM Agent NEVER generates Sub-PRD content.
+
 **IF the Skill output includes a Sub-PRD Dispatch Plan (from Step 12c), execute this phase.**
 **IF Single PRD structure, skip to Phase 6.**
 
-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.
+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.
 
-> **Phase 5 Execution Flow:**
+> **CORRECT Phase 5 Execution Flow (Dispatch-Tracked):**
 > ```
 > Generate Skill outputs Dispatch Plan
 >     ↓
 > PM reads Dispatch Plan (module list + contexts)
 >     ↓
-> PM initializes DISPATCH-PROGRESS.json (via script)
+> PM initializes DISPATCH-PROGRESS.json (via script) ← Step 5.2
 >     ↓
-> PM invokes speccrew-task-worker × N (one per module)
->   └─ Each worker internally calls speccrew-pm-sub-prd-generate
+> PM dispatches Workers IN BATCHES ← Step 5.3
+>   ├─ Batch 1: Workers 1-5 (parallel dispatch)
+>   ├─ Wait for Batch 1 completion
+>   ├─ Update DISPATCH-PROGRESS.json per completed worker
+>   ├─ Batch 2: Workers 6-10 (parallel dispatch)
+>   ├─ Wait for Batch 2 completion
+>   └─ ... until all modules done
+>     ↓
+> ALL workers done → PM verifies in Step 5.5
+>     ↓
+> ALL verified → Phase 6
+> ```
+> 
+> **WRONG flow (VIOLATION):**
+> ```
+> PM reads Dispatch Plan
 >     ↓
-> Workers complete → PM updates progress (via script)
+> PM dispatches ONE Worker for ALL modules ← VIOLATION
+>   └─ Worker internally loops to generate all Sub-PRDs
 >     ↓
-> ALL workers done → Phase 6
+> This is serial generation, NOT parallel dispatch
 > ```
 > 
-> **NOT this flow:**
+> **ALSO WRONG:**
 > ```
 > PM reads Dispatch Plan → PM generates Sub-PRDs directly ← VIOLATION
 > ```
 
+---
+
 ### 5.1 Read Dispatch Plan
 
 From the Skill's Step 12c output, collect:
 - `feature_name`: System-level feature name
 - `template_path`: Path to PRD-TEMPLATE.md
 - `master_prd_path`: Path to the generated Master PRD
+- `clarification_file`: Path to `.clarification-summary.md`
+- `module_design_file`: Path to `.module-design.md`
 - `output_dir`: Directory for Sub-PRD files (same as Master PRD directory)
 - Module list with context for each module:
   - `module_name`, `module_key`, `module_scope`, `module_entities`
   - `module_user_stories`, `module_requirements`, `module_features`
   - `module_dependencies`
 
-### 5.1b Initialize Dispatch Progress Tracking
+**Store these values as workflow context variables for use in Worker dispatches.**
+
+---
+
+### 5.2 Initialize Dispatch Progress Tracking
 
-**MANDATORY: Initialize dispatch tracking with script:**
+> 🛑 **HARD STOP: This step MUST complete before ANY Worker dispatch.**
+
+**Step 5.2.1: Prepare tasks array**
+
+Create a temporary file with task definitions for each module:
+
+```json
+[
+  {
+    "id": "{module_key_1}",
+    "name": "{module_name_1}",
+    "status": "pending",
+    "output_file": "{output_dir}/{feature_name}-sub-{module_key_1}.md"
+  },
+  {
+    "id": "{module_key_2}",
+    "name": "{module_name_2}",
+    "status": "pending",
+    "output_file": "{output_dir}/{feature_name}-sub-{module_key_2}.md"
+  }
+]
+```
+
+**Step 5.2.2: Initialize DISPATCH-PROGRESS.json**
 
 > ⚠️ Use --tasks-file instead of --tasks to avoid PowerShell JSON parsing issues.
 
 ```bash
-# Write tasks to temp file inside iteration directory
-# Create .tasks-temp.json with task array content
-node "{update_progress_script}" init \
-  --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
-  --stage sub_prd_dispatch \
-  --tasks-file {iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json
-# Delete .tasks-temp.json after successful init
+# PowerShell compatible command
+node "{update_progress_script}" init `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --stage sub_prd_dispatch `
+  --tasks-file "{iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json"
+
+# Clean up temp file after successful init
+Remove-Item "{iterations_dir}/{iteration}/01.product-requirement/.tasks-temp.json"
 ```
 
 > **PowerShell Compatibility Note:**
 > PowerShell cannot properly parse JSON in command-line arguments. Use file-based approach:
-> 1. Write tasks JSON to a temporary file (e.g., `tasks-temp.json`)
-> 2. Read file content in the command: `node "{update_progress_script}" init --stage sub_prd_dispatch --tasks (Get-Content tasks-temp.json -Raw)`
-> 3. Or use: `Get-Content tasks-temp.json | node "{update_progress_script}" init --stage sub_prd_dispatch --tasks -`
+> 1. Write tasks JSON to a temporary file (e.g., `.tasks-temp.json`)
+> 2. Run the init command with `--tasks-file` pointing to the temp file
+> 3. Delete temp file after successful init
 
 > 🛑 **HARD STOP: DISPATCH-PROGRESS.json MUST be created by script ONLY**
 > - MUST use: `node "{update_progress_script}" init --stage sub_prd_dispatch --tasks-file <TASKS_FILE>`
@@ -1157,116 +1228,281 @@ node "{update_progress_script}" init \
 > - IF script fails → STOP workflow immediately, report error to user, ask "Retry or Abort?"
 > - DO NOT proceed to Worker dispatch without successful script execution
 
-After each worker completes:
-```bash
-node "{update_progress_script}" update-task \
-  --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
-  --task-id {module_key} --status completed
-```
+**Step 5.2.3: Verify initialization**
 
-If a worker fails:
 ```bash
-node "{update_progress_script}" update-task \
-  --file {iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
-  --task-id {module_key} --status failed --error "{error_message}"
+node "{update_progress_script}" read `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --summary
 ```
 
-### 5.3 Dispatch Workers
+Expected output: `Total: N tasks | Pending: N | Completed: 0 | Failed: 0`
+
+---
+
+### 5.3 Dispatch Workers (Batch Parallel)
+
+> 🛑 **CRITICAL: ONE Worker per Module — NO EXCEPTIONS**
+>
+> | Module Count | Dispatch Strategy |
+> |--------------|-------------------|
+> | 1-5 modules | Single batch, all parallel |
+> | 6-10 modules | 2 batches of 5 |
+> | 11-15 modules | 3 batches of 5 |
+> | 16+ modules | Batches of 5, final batch may be smaller |
+>
+> **BATCH SIZE = 5 (maximum parallel Workers per batch)**
 
 **PM Agent Role: ORCHESTRATOR ONLY — Phase 5 EXPLICIT RULES**
 
 **MANDATORY — PM MUST:**
 1. Read the Dispatch Plan from generate skill output
-2. Initialize DISPATCH-PROGRESS.json via update-progress.js script
-3. For EACH module in dispatch plan: invoke `speccrew-task-worker` with `skill_path: speccrew-pm-sub-prd-generate/SKILL.md`
+2. Initialize DISPATCH-PROGRESS.json via update-progress.js script (Step 5.2)
+3. For EACH module in dispatch plan: invoke ONE `speccrew-task-worker`
 4. Pass ALL required context parameters to each worker
-5. Wait for ALL workers to complete
-6. Update DISPATCH-PROGRESS.json via script after each worker completes
+5. Dispatch in batches of 5, wait for each batch to complete
+6. After each Worker completes, update DISPATCH-PROGRESS.json via script
 
 🛑 **FORBIDDEN — PM MUST NOT:**
 - Generate Sub-PRD files directly (via create_file, write, or any file creation)
 - Invoke speccrew-pm-sub-prd-generate skill directly (ONLY speccrew-task-worker invokes it)
+- Dispatch ONE Worker to handle MULTIPLE modules (each module = one Worker)
 - Create or edit any Sub-PRD content as fallback if worker fails
 - Skip worker dispatch and generate Sub-PRDs inline
 - IF PM attempts ANY of above → WORKFLOW VIOLATION → STOP immediately
 
-**Implementation:**
-
-For EACH module in the dispatch plan, invoke a new `speccrew-task-worker` agent:
-- **skill_path**: Search with glob `**/speccrew-pm-sub-prd-generate/SKILL.md`
-- **context**: 
-  - `module_name`: from dispatch plan
-  - `module_key`: from dispatch plan
-  - `master_prd_path`: path to Master PRD
-  - `template_path`: PRD template path (from Step 7 glob search result)
-  - `output_dir`: `{iterations_dir}/{iteration}/01.product-requirement/` (absolute path from Phase 0.6)
-
-Each worker receives:
-- `skill_path`: `speccrew-pm-sub-prd-generate/SKILL.md`
-- `context`:
-  - `module_name`: Module name (e.g., "Customer Management")
-  - `module_key`: Module identifier for file naming (e.g., "customer")
-  - `module_scope`: What this module covers
-  - `module_entities`: Core business entities
-  - `module_user_stories`: Module-specific user stories
-  - `module_requirements`: Module-specific functional requirements (P0/P1/P2)
-  - `module_features`: Feature Breakdown entries for this module
-  - `module_dependencies`: Dependencies on other modules
-  - `master_prd_path`: Path to the Master PRD
-  - `feature_name`: System-level feature name
-  - `template_path`: Path to PRD-TEMPLATE.md
-  - `output_path`: `{output_dir}/{feature_name}-sub-{module_key}.md`
-
-**Batch Strategy:**
-- If modules ≤ 6: dispatch ALL in parallel
-- If modules > 6: dispatch in batches of 6, wait for batch completion before next batch
-
-**Parallel execution pattern:**
+---
+
+#### Step 5.3.1: Determine Batch Plan
+
+<arg_value>Read DISPATCH-PROGRESS.json to get pending tasks:
+
+```bash
+node "{update_progress_script}" read `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json"
+```
+
+Group tasks into batches:
 ```
-Worker 1: Module "customer"     → crm-system-sub-customer.md
-Worker 2: Module "contact"      → crm-system-sub-contact.md
-Worker 3: Module "opportunity"  → crm-system-sub-opportunity.md
-...
-Worker N: Module "{module-N}"   → crm-system-sub-{module-N}.md
+📊 Sub-PRD Dispatch Plan
+├── Total Modules: 14
+├── Batch Size: 5
+├── Batches Required: 3
+│   ├── Batch 1: modules 1-5 (customer, contact, opportunity, lead, activity)
+│   ├── Batch 2: modules 6-10 (report, dashboard, workflow, notification, integration)
+│   └── Batch 3: modules 11-14 (security, audit, config, help)
+└── Strategy: Parallel dispatch within batch, sequential between batches
 ```
 
-**All workers execute simultaneously (or in batches).** Wait for all workers to complete before proceeding.
+---
 
-**Before proceeding to Phase 6, verify:**
-- [ ] All workers were dispatched via speccrew-task-worker
-- [ ] No Sub-PRD was generated by PM Agent directly
-- [ ] All workers completed (check DISPATCH-PROGRESS.json)
+#### Step 5.3.2: Dispatch Batch N
 
-### 5.4 Collect Results
+For EACH module in current batch, dispatch ONE `speccrew-task-worker`:
 
-After all workers complete:
+**Agent Tool Invocation Format (REPEAT for each module):**
 
-1. **Check worker results**: Verify each worker reported success
-2. **List generated files**:
-   ```
-   📊 Sub-PRD Generation Results:
-   ├── Worker 1: {module-1} → ✅ Generated ({file_size})
-   ├── Worker 2: {module-2} → ✅ Generated ({file_size})
-   ├── Worker N: {module-N} → ✅ Generated ({file_size})
-   │
-   Total: N workers | Completed: X | Failed: Y
-   ```
+```
+Use the Agent tool to invoke speccrew-task-worker:
+- agent: speccrew-task-worker
+- task: Generate Sub-PRD for module "{module_name}"
+- context:
+    skill: speccrew-pm-sub-prd-generate
+    module_name: {module_name}
+    module_key: {module_key}
+    module_scope: {module_scope}
+    module_entities: {module_entities}
+    module_user_stories: {module_user_stories}
+    module_requirements: {module_requirements}
+    module_features: {module_features}
+    module_dependencies: {module_dependencies}
+    master_prd_path: {master_prd_path}
+    clarification_file: {clarification_file}
+    module_design_file: {module_design_file}
+    feature_name: {feature_name}
+    template_path: {template_path}
+    output_path: {output_dir}/{feature_name}-sub-{module_key}.md
+    language: {language}
+```
 
-3. **Handle failures**: If any worker failed:
-   - Report which modules failed and why
-   - Re-dispatch failed modules (retry once)
-   - If retry fails, report to user for manual intervention
+**Worker Context Parameters:**
+
+| Parameter | Source | Description |
+|-----------|--------|-------------|
+| `skill` | Fixed | `speccrew-pm-sub-prd-generate` |
+| `module_name` | Dispatch Plan | Display name (e.g., "Customer Management") |
+| `module_key` | Dispatch Plan | Identifier for file naming (e.g., "customer") |
+| `module_scope` | Dispatch Plan | What this module covers |
+| `module_entities` | Dispatch Plan | Core business entities |
+| `module_user_stories` | Dispatch Plan | Module-specific user stories |
+| `module_requirements` | Dispatch Plan | Module-specific functional requirements (P0/P1/P2) |
+| `module_features` | Dispatch Plan | Feature Breakdown entries for this module |
+| `module_dependencies` | Dispatch Plan | Dependencies on other modules |
+| `master_prd_path` | Dispatch Plan | Path to the Master PRD |
+| `clarification_file` | Step 5.1 | Path to `.clarification-summary.md` |
+| `module_design_file` | Step 5.1 | Path to `.module-design.md` |
+| `feature_name` | Dispatch Plan | System-level feature name |
+| `template_path` | Dispatch Plan | Path to PRD-TEMPLATE.md |
+| `output_path` | Computed | `{output_dir}/{feature_name}-sub-{module_key}.md` |
+| `language` | Detected | User's language |
+
+**Dispatch Example (Batch 1 with 5 modules):**
+
+```
+📊 Dispatching Batch 1 (5 modules in parallel)
+├── Worker 1: module="customer"     → output: crm-system-sub-customer.md
+├── Worker 2: module="contact"      → output: crm-system-sub-contact.md
+├── Worker 3: module="opportunity"  → output: crm-system-sub-opportunity.md
+├── Worker 4: module="lead"         → output: crm-system-sub-lead.md
+└── Worker 5: module="activity"     → output: crm-system-sub-activity.md
+
+Waiting for all 5 Workers to complete...
+```
+
+---
+
+#### Step 5.3.3: Update Progress After Each Worker
+
+**When a Worker completes successfully:**
+
+```bash
+node "{update_progress_script}" update-task `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --task-id "{module_key}" `
+  --status completed
+```
+
+**When a Worker fails:**
+
+```bash
+node "{update_progress_script}" update-task `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --task-id "{module_key}" `
+  --status failed `
+  --error "{error_message}"
+```
+
+**After each batch completes, show progress:**
+
+```
+📊 Batch 1 Complete
+├── ✅ customer: completed
+├── ✅ contact: completed
+├── ✅ opportunity: completed
+├── ❌ lead: failed (timeout)
+└── ✅ activity: completed
+
+Progress: 4/14 completed, 1 failed, 9 pending
+Proceeding to Batch 2...
+```
+
+---
+
+#### Step 5.3.4: Continue to Next Batch
+
+After current batch completes:
+1. Check DISPATCH-PROGRESS.json for remaining pending tasks
+2. If pending tasks remain → dispatch next batch (Step 5.3.2)
+3. If all tasks done → proceed to Step 5.4
+
+```bash
+node "{update_progress_script}" read `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --summary
+```
+
+Continue dispatching batches until `counts.pending == 0`.
+
+---
+
+### 5.4 Handle Failures & Retry
+
+After all batches complete, check for failed tasks:
+
+```bash
+node "{update_progress_script}" read `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json"
+```
+
+**If any tasks have `status: "failed"`:**
+
+1. List failed modules
+2. Re-dispatch ONE Worker per failed module (single retry)
+3. Update status after retry
+4. If retry fails again, report to user for manual intervention
+
+```
+📊 Retry Summary
+├── Retrying 2 failed modules...
+│   ├── Worker: module="lead" → retry
+│   └── Worker: module="report" → retry
+├── Retry Results:
+│   ├── ✅ lead: completed (retry successful)
+│   └── ❌ report: failed (retry failed)
+└── Final Status: 13/14 completed, 1 failed
+
+Module "report" failed after retry. Manual intervention required.
+Options:
+- Skip and continue with 13/14 Sub-PRDs
+- Abort and investigate
+```
+
+---
+
+### 5.5 Collect Results & Verify
+
+> 🛑 **Verification before proceeding to Phase 6**
+
+**Step 5.5.1: Read Final Progress**
+
+```bash
+node "{update_progress_script}" read `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json" `
+  --summary
+```
+
+Expected: `Total: N | Pending: 0 | Completed: N | Failed: 0`
+
+**Step 5.5.2: Verify All Sub-PRD Files Exist**
+
+```bash
+# List all Sub-PRD files
+Get-ChildItem "{iterations_dir}/{iteration}/01.product-requirement/" -Filter "*-sub-*.md"
+```
+
+Verify:
+- File count matches DISPATCH-PROGRESS.json completed count
+- Each file has size > 3KB
+
+**Step 5.5.3: Report Final Summary**
 
-After all workers complete, report dispatch summary:
 ```
 📊 Sub-PRD Generation Complete:
-├── Total: 11 modules
-├── ✅ Completed: 10
-├── ❌ Failed: 1 (member — error description)
-└── Retry failed modules? (yes/skip)
+├── Total Modules: {count}
+├── ✅ Completed: {count}
+├── ❌ Failed: {count}
+├── Generated Files:
+│   ├── {feature_name}-sub-{module_1}.md ({size} KB)
+│   ├── {feature_name}-sub-{module_2}.md ({size} KB)
+│   └── ...
+└── All Sub-PRDs ready for Phase 6 Verification
 ```
 
-Update `.checkpoints.json` → `sub_prd_dispatch.passed = true` (only if all succeeded or user skips failures).
+**Step 5.5.4: Update Checkpoint**
+
+```bash
+node "{update_progress_script}" write-checkpoint `
+  --file "{iterations_dir}/{iteration}/01.product-requirement/.checkpoints.json" `
+  --checkpoint sub_prd_dispatch `
+  --status passed
+```
+
+**Before proceeding to Phase 6, verify:**
+- [ ] All workers were dispatched via speccrew-task-worker (one Worker per module)
+- [ ] No Sub-PRD was generated by PM Agent directly
+- [ ] All workers completed (DISPATCH-PROGRESS.json counts.pending == 0)
+- [ ] All Sub-PRD files exist and have valid size
+- [ ] Checkpoint updated
 
 > 🛑 **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.
 

package/.speccrew/agents/speccrew-system-developer.md

@@ -1,7 +1,7 @@
 ---
 name: speccrew-system-developer
 description: SpecCrew System Developer. Reads system design blueprints and coordinates cross-platform development task dispatch. Loads techs knowledge, verifies environment readiness, dispatches per-platform dev skills, performs integration checks, and delivers development completion reports. Supports web, mobile, desktop, and backend platforms.
-tools: Read, Write, Glob, Grep, Bash, Agent
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Quick Reference — Execution Flow

package/.speccrew/skills/speccrew-fd-feature-design/SKILL.md

@@ -364,6 +364,45 @@ Log: "✅ Checkpoint B (feature_design_review) passed and recorded"
 
 ## Step 5: Determine Output Path & Copy Template
 
+> **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
+>
+> Steps 5 and 6 MUST be executed in two phases to ensure consistent document structure.
+
+### Phase A: Skeleton Construction (BEFORE any content filling)
+
+1. Read FEATURE-SPEC-TEMPLATE.md to identify the complete section structure
+2. Count the number of functions from `.feature-analysis.md` input
+3. For Section 2 Function Details, replicate the template's Function block structure for EACH function:
+   - Copy the EXACT template structure (all 4 sub-sections) from FEATURE-SPEC-TEMPLATE.md
+   - Create `### 2.1 Function: {function_name}` through `### 2.N Function: {function_name}`
+   - Each function block MUST contain these 4 sub-section headers (copied from template):
+     ```
+     #### 2.N.1 Frontend Prototype
+     [TO BE FILLED]
+     
+     #### 2.N.2 Interaction Flow
+     [TO BE FILLED]
+     
+     #### 2.N.3 Backend Interface
+     [TO BE FILLED]
+     
+     #### 2.N.4 Data Definition
+     [TO BE FILLED]
+     ```
+4. Verify skeleton: confirm ALL functions have ALL 4 sub-section headers before proceeding
+
+> ⚠️ DO NOT start filling content until the complete skeleton is verified.
+
+### Phase B: Content Filling (AFTER skeleton is complete)
+
+Fill each `[TO BE FILLED]` placeholder with actual content:
+- **Frontend Prototype** → ASCII wireframes (Pattern A/B/C/M-A/M-B/M-C) + Interface Element Description table
+- **Interaction Flow** → Mermaid `sequenceDiagram` + Interaction Rules table
+- **Backend Interface** → Interface List table + Mermaid `flowchart TD` for Processing Logic + Data Access table
+- **Data Definition** → Fields table + Data Source table
+
+---
+
 ### 5.1 Determine Output Path
 
 **Single Feature Mode** (when `feature_id` provided):
@@ -399,6 +438,13 @@ Log: "✅ Checkpoint B (feature_design_review) passed and recorded"
 
 ## Step 6: Fill Sections Using search_replace
 
+> **⚠️ CRITICAL: Section 2 Function Details Skeleton Verification**
+>
+> Before proceeding with content filling, verify the two-phase strategy was correctly applied:
+> 1. Confirm ALL functions in Section 2 have complete 4 sub-section skeletons (Frontend Prototype, Interaction Flow, Backend Interface, Data Definition)
+> 2. Confirm no `[TO BE FILLED]` placeholders remain unfilled after content filling
+> 3. Confirm each function follows the exact template structure from FEATURE-SPEC-TEMPLATE.md
+
 ### Section Mapping Table
 
 | Template Section | Data Source |
@@ -504,6 +550,7 @@ Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review pass
 - [ ] Output path determined
 - [ ] Template copied using `create_file`
 - [ ] All sections filled using `search_replace`
+- [ ] **[CRITICAL]** Section 2 Function Details skeleton verified (all functions have 4 sub-sections)
 - [ ] **[CRITICAL]** Interaction Flow uses Mermaid sequenceDiagram (NOT ASCII)
 - [ ] **[CRITICAL]** Processing Logic uses Mermaid flowchart TD (NOT ASCII)
 - [ ] All Mermaid diagrams follow mermaid-rule.md compliance rules

package/.speccrew/skills/speccrew-knowledge-module-summarize/SKILL.md

@@ -126,6 +126,52 @@ Collect all business rules from feature details:
 
 ### Step 5: Generate Complete MODULE-OVERVIEW.md
 
+> **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
+>
+> This step MUST be executed in two phases to ensure consistent document structure.
+
+### Phase A: Skeleton Construction (BEFORE any content filling)
+
+1. Read MODULE-OVERVIEW-TEMPLATE.md to identify the complete section structure
+2. Count data items from extracted information:
+   - Section 3: Count unique **Entities** (deduplicated by entity name)
+   - Section 4: Count unique **Dependencies** (internal + external)
+   - Section 5: Count unique **Core Business Flows**
+   - Section 6: Count unique **Business Rules**
+3. For each section with repeating data items, create complete skeleton structure:
+   - **Section 3 (Entities)**: For each entity, create table row with ALL column placeholders:
+     ```
+     | [Entity Name] | [TO BE FILLED] | [TO BE FILLED] | [TO BE FILLED] |
+     ```
+   - **Section 4 (Dependencies)**: For each dependency, create table row with ALL column placeholders:
+     ```
+     | [Direction] | [Target] | [Content] | [Method] |
+     ```
+   - **Section 5 (Core Business Flows)**: For each flow, create flow item with placeholders:
+     ```
+     **[Flow Name]**: [TO BE FILLED]
+     ```
+   - **Section 6 (Business Rules)**: For each rule, create table row with ALL column placeholders:
+     ```
+     | [Rule ID] | [Rule Name] | [Description] | [Related Features] |
+     ```
+4. Verify skeleton: confirm ALL data items have ALL required column/field placeholders before proceeding
+
+> ⚠️ DO NOT start filling content until the complete skeleton is verified.
+
+### Phase B: Content Filling (AFTER skeleton is complete)
+
+Fill each `[TO BE FILLED]` placeholder with actual content:
+- Entity Description → Business description of the entity
+- Entity Key Attributes → Field names with types (deduplicated from all features)
+- Entity Business Rules → Constraints and validation rules aggregated from features
+- Dependency Content → What is provided/consumed
+- Dependency Method → How the dependency is realized (API call, import, injection)
+- Core Business Flow → Step sequence with actors and outcomes
+- Business Rule Description → Rule logic and enforcement point
+
+---
+
 **⚠️ CRITICAL CONSTRAINTS (apply to this step):**
 > 1. **FORBIDDEN: `create_file` for overview document** — If skeleton exists, use `search_replace`; if not, copy template first then fill with `search_replace`
 > 2. **FORBIDDEN: Full-file rewrite** — Always use targeted `search_replace` on specific sections

package/.speccrew/skills/speccrew-knowledge-system-summarize/SKILL.md

@@ -208,6 +208,48 @@ Create flow-module mapping matrix:
 
 ### Step 7: Generate system-overview.md
 
+> **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
+>
+> This step MUST be executed in two phases to ensure consistent document structure.
+
+### Phase A: Skeleton Construction (BEFORE any content filling)
+
+1. Read SYSTEM-OVERVIEW-TEMPLATE.md to identify the complete section structure
+2. Count aggregated data items from discovered modules:
+   - Section 2: Count unique **Modules** (including platform_type annotation for duplicates)
+   - Section 3: Count unique **End-to-End Business Flows**
+   - Section 4: Count unique **External Integrations**
+3. For each section with repeating data items, create complete skeleton structure:
+   - **Section 2 (Module Topology)**: For each module, create index table row with ALL column placeholders:
+     ```
+     | [Module Name] | [Domain] | [Purpose] | [Entities] | [APIs] | [Detail Doc] |
+     ```
+   - **Section 3 (Business Flows)**: For each flow, create mapping matrix row:
+     ```
+     | [Flow Name] | [Module 1] | [Module 2] | ... | [Module N] |
+     ```
+   - **Section 4 (External Integrations)**: For each integration, create table row:
+     ```
+     | [System Name] | [Integration Type] | [Data Exchanged] | [Protocol] |
+     ```
+4. Verify skeleton: confirm ALL data items have ALL required column placeholders before proceeding
+
+> ⚠️ DO NOT start filling content until the complete skeleton is verified.
+
+### Phase B: Content Filling (AFTER skeleton is complete)
+
+Fill each `[TO BE FILLED]` placeholder with actual content:
+- Module Domain → Business domain classification from module overview
+- Module Purpose → Business purpose extracted from module overview
+- Module Entities → Entity count and key entity names
+- Module APIs → API/Interface count from module overview
+- Module Detail Doc → Relative link to module-overview.md
+- Flow Module Mapping → ✓ for involved modules, - for not involved
+- Integration Data Exchanged → Data structures and formats exchanged
+- Integration Protocol → HTTP/REST, gRPC, WebSocket, etc.
+
+---
+
 **⚠️ CRITICAL CONSTRAINTS (apply to Step 7a and 7b):**
 > 1. **FORBIDDEN: `create_file` for documents** — Document MUST be created by copying template (Step 7a) then filling with `search_replace` (Step 7b)
 > 2. **FORBIDDEN: Full-file rewrite** — Always use targeted `search_replace` on specific sections

package/.speccrew/skills/speccrew-pm-requirement-analysis/SKILL.md

@@ -179,7 +179,56 @@ ELSE:
 | One list page with filters | Entire reporting subsystem |
 | One form with validation | Multi-step wizard with 10+ steps |
 
-### 4.2 Marking Existing vs New Features
+### 4.2 Section 3.5 Feature Details — Two-Phase Strategy
+
+> **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
+>
+> This step MUST be executed in two phases to ensure consistent document structure.
+
+#### Phase A: Skeleton Construction (BEFORE any content filling)
+
+1. Read PRD-TEMPLATE.md to identify the complete Feature Details structure
+2. Count the number of features from `{module_features}` input
+3. For Section 3.5 Feature Details, replicate the template's Feature block structure for EACH feature:
+   - Copy the EXACT template structure (all 6 sub-sections) from PRD-TEMPLATE.md
+   - Create `#### Feature 1: {feature_name}` through `#### Feature N: {feature_name}`
+   - Each feature block MUST contain these 6 sub-section headers (copied from template):
+     ```
+     **Requirement Description:**
+     [TO BE FILLED]
+     
+     **Interaction Flow:**
+     [TO BE FILLED]
+     
+     **Boundary Conditions:**
+     [TO BE FILLED]
+     
+     **Exception Scenarios:**
+     [TO BE FILLED]
+     
+     **Operation Flow Diagram:**
+     [TO BE FILLED]
+     
+     **Operation Steps Detail:**
+     [TO BE FILLED]
+     ```
+4. Verify skeleton: confirm ALL features have ALL 6 sub-section headers before proceeding
+
+> ⚠️ DO NOT start filling content until the complete skeleton is verified.
+
+#### Phase B: Content Filling (AFTER skeleton is complete)
+
+Fill each `[TO BE FILLED]` placeholder with actual content:
+- **Requirement Description** → Business requirements in business language
+- **Interaction Flow** → User interaction steps (numbered list)
+- **Boundary Conditions** → Table with Condition Type | Scenario | Handling Rule
+- **Exception Scenarios** → Bullet list of exception handling
+- **Operation Flow Diagram** → Mermaid `graph LR` diagram showing operation flow
+- **Operation Steps Detail** → Table: Step | Action | Expected Outcome | Exception Handling
+
+---
+
+### 4.3 Marking Existing vs New Features
 
 | Marker | Meaning |
 |--------|---------|
@@ -189,6 +238,13 @@ ELSE:
 
 ## Step 5: Task Granularity Check
 
+> **⚠️ CRITICAL: Section 3.5 Feature Details Skeleton Verification**
+>
+> Before proceeding, verify the two-phase strategy was correctly applied:
+> 1. Confirm ALL features in Section 3.5 have complete 6 sub-section skeletons
+> 2. Confirm no `[TO BE FILLED]` placeholders remain unfilled
+> 3. Confirm each feature has: Requirement Description, Interaction Flow, Boundary Conditions, Exception Scenarios, Operation Flow Diagram, Operation Steps Detail
+
 **After PRD completion, verify user story granularity:**
 
 **Appropriate Granularity (completable in one iteration):**

package/.speccrew/skills/speccrew-pm-sub-prd-generate/SKILL.md

@@ -68,6 +68,53 @@ tools: Read, Write, Glob, Grep
 
 ## Step 3: Fill Module-Specific Content
 
+> **⚠️ CRITICAL: Two-Phase Strategy (Skeleton-First, Content-After)**
+>
+> This step MUST be executed in two phases to ensure consistent document structure.
+
+### Phase A: Skeleton Construction (BEFORE any content filling)
+
+1. Read PRD-TEMPLATE.md to identify the complete section structure
+2. Count the number of features from `{module_features}` input
+3. For Section 3.5 Feature Details, replicate the template's Feature block structure for EACH feature:
+   - Copy the EXACT template structure (all 6 sub-sections) from PRD-TEMPLATE.md
+   - Create `#### Feature 1: {feature_name}` through `#### Feature N: {feature_name}`
+   - Each feature block MUST contain these 6 sub-section headers (copied from template):
+     ```
+     **Requirement Description:**
+     [TO BE FILLED]
+     
+     **Interaction Flow:**
+     [TO BE FILLED]
+     
+     **Boundary Conditions:**
+     [TO BE FILLED]
+     
+     **Exception Scenarios:**
+     [TO BE FILLED]
+     
+     **Operation Flow Diagram:**
+     [TO BE FILLED]
+     
+     **Operation Steps Detail:**
+     [TO BE FILLED]
+     ```
+4. Verify skeleton: confirm ALL features have ALL 6 sub-section headers before proceeding
+
+> ⚠️ DO NOT start filling content until the complete skeleton is verified.
+
+### Phase B: Content Filling (AFTER skeleton is complete)
+
+Fill each `[TO BE FILLED]` placeholder with actual content:
+- Requirement Description → Business requirements in business language
+- Interaction Flow → User interaction steps (numbered list)
+- Boundary Conditions → Table with Condition Type | Scenario | Handling Rule
+- Exception Scenarios → Bullet list of exception handling
+- Operation Flow Diagram → Mermaid `graph LR` diagram showing operation flow
+- Operation Steps Detail → Table with Step | Action | Expected Outcome | Exception Handling
+
+---
+
 Fill each section using `search_replace`:
 
 ### 3.1 Section 1: Background & Goals
@@ -85,11 +132,17 @@ Fill each section using `search_replace`:
 - 3.4 Feature Breakdown: **REQUIRED** — Fill with `{module_features}` data:
   - Feature ID, Feature Name, Type (User Interaction / Backend Process), Scope, Description
   - Feature Dependencies table
-- 3.5 Feature Details: Detailed descriptions for each feature including:
+- 3.5 Feature Details: **FOR EACH feature in module_features, fill ALL 6 sub-sections below:**
+  
+  **Complete structure (MUST repeat for every Feature 1, 2, ... N):**
   - Requirement Description — **Business requirements in business language**
   - Interaction Flow — **User interaction steps in business terms**
   - Boundary Conditions table — **Business scenarios and business handling rules**
   - Exception Scenarios — **Business exception handling in business language**
+  - Operation Flow Diagram — **Mermaid `graph LR` showing business operation steps (REQUIRED for EVERY feature)**
+  - Operation Steps Detail — **Table: Step | Action | Expected Outcome | Business Exception Handling (REQUIRED for EVERY feature)**
+  
+  > ⚠️ **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.
 
 ### 3.4 Section 4: Non-functional Requirements
 - Module-specific performance, security, compatibility requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {