speccrew 0.5.13 → 0.5.16

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/SKILL.md

@@ -8,6 +8,30 @@ tools: Read, Write, Task, Bash
 
 Orchestrate **bizs knowledge base generation** with a 5-stage pipeline: Feature Inventory → Feature Analysis + Graph Write → Module Summarize → UI Style Pattern Extract → System Summary.
 
+## Quick Reference — Execution Flow
+
+```
+Stage 0: Platform Detection
+  └─ Read techs-manifest → Identify platforms
+        ↓
+Stage 1: Feature Inventory Init
+  └─ 1a: bizs-init-features per platform
+  └─ 1b: Merge features
+  └─ 1c: Validate inventory
+        ↓
+Stage 2: Feature Analysis (PARALLEL)
+  └─ Dispatch api-analyze + ui-analyze workers per platform
+  └─ After each analyze worker completes → dispatch corresponding graph worker
+  └─ Monitor completion markers
+        ↓
+Stage 3: Module Summarize (PARALLEL)
+  └─ 3.0: module-summarize per module
+  └─ 3.5: UI style extraction
+        ↓
+Stage 4: System Summary
+  └─ system-summarize → system-overview.md
+```
+
 ## Language Adaptation
 
 **CRITICAL**: All generated documents must match the user's language. Detect the language from the user's input and pass it to all downstream Worker Agents.
@@ -144,6 +168,8 @@ flowchart TB
 
 > **CRITICAL**: NEVER hardcode a fixed number of platforms. Always scan the project directory to discover ALL modules. Missing a platform means incomplete knowledge base generation.
 
+> ✅ **Stage 0 Milestone**: Platform detection complete. Platforms: {platform_list}. → Proceed to Stage 1.
+
 ---
 
 ## Stage 1a: Entry Directory Recognition (LLM-Driven)
@@ -158,14 +184,14 @@ flowchart TB
 
 ### Step 1: Read Directory Tree
 
-Use `ListDir` or `Bash(tree)` to read the platform's `sourcePath` directory structure (3 levels deep):
+Use `ListDir` or `Bash(tree)` to read the platform's `{source_path}` directory structure (3 levels deep):
 
 ```bash
 # Windows (PowerShell)
-tree /F /A "{sourcePath}" | Select-Object -First 100
+tree /F /A "{source_path}" | Select-Object -First 100
 
 # Unix/Linux/Mac
-tree -L 3 "{sourcePath}"
+tree -L 3 "{source_path}"
 ```
 
 ### Step 2: LLM Analysis - Identify Entry Directories
@@ -196,11 +222,11 @@ Based on the directory tree and technology stack, analyze and identify entry dir
 - Configuration directories: `.git`, `.idea`, `.vscode`, `.speccrew`
 
 **Root Module Handling**:
-- If an entry file is not under any subdirectory (directly under `sourcePath`), assign it to the `_root` module
+- If an entry file is not under any subdirectory (directly under `{source_path}`), assign it to the `_root` module
 
 ### Step 3: Generate entry-dirs JSON
 
-Output file: `{speccrew-workspace}/knowledges/base/sync-state/knowledge-bizs/entry-dirs-{platformId}.json`
+Output file: `{speccrew_workspace}/knowledges/base/sync-state/knowledge-bizs/entry-dirs-{platform_id}.json`
 
 **JSON Format**:
 ```json
@@ -222,17 +248,17 @@ Output file: `{speccrew-workspace}/knowledges/base/sync-state/knowledge-bizs/ent
 
 **Field Definitions**:
 - `platformId`: Platform identifier (e.g., `backend-ai`, `web-vue`, `mobile-uniapp`)
-- `platformName`: (Optional) Human-readable platform name. Auto-generated as `{platformType}-{platformSubtype}` if missing
-- `platformType`: (Optional) Platform type: `backend`, `web`, `mobile`, `desktop`. Inferred from platformId if missing
-- `platformSubtype`: (Optional) Platform subtype (e.g., `ai`, `vue`, `uniapp`). Inferred from platformId if missing
+- `platformName`: (Optional) Human-readable platform name. Auto-generated as `{platform_type}-{platform_subtype}` if missing
+- `platformType`: (Optional) Platform type: `backend`, `web`, `mobile`, `desktop`. Inferred from platform_id if missing
+- `platformSubtype`: (Optional) Platform subtype (e.g., `ai`, `vue`, `uniapp`). Inferred from platform_id if missing
 - `sourcePath`: Absolute path to the platform source root
-- `techStack`: (Optional) Array of tech stack names (e.g., `["spring-boot", "mybatis-plus"]`). Default inferred from platformType
+- `techStack`: (Optional) Array of tech stack names (e.g., `["spring-boot", "mybatis-plus"]`). Default inferred from platform_type
 - `modules`: Array of business modules
   - `name`: Module name (business-meaningful, e.g., `chat`, `system`, `order`)
-  - `entryDirs`: Array of entry directory paths (relative to `sourcePath`)
+  - `entryDirs`: Array of entry directory paths (relative to `{source_path}`)
 
 **Path Rules**:
-- All `entryDirs` paths must be relative to `sourcePath`
+- All `entryDirs` paths must be relative to `{source_path}`
 - Use forward slashes `/` as path separators (even on Windows)
 - Do not include leading or trailing slashes
 
@@ -255,7 +281,7 @@ After generating the entry-dirs JSON:
 > **IMPORTANT**: This stage is executed **directly by the dispatch agent (Leader)**, NOT delegated to a Worker Agent.
 > Worker Agents do not have `run_in_terminal` capability, which is required for script execution.
 
-**Prerequisite**: Stage 1a completed. `entry-dirs-{platformId}.json` files exist in `{sync_state_path}/knowledge-bizs/`.
+**Prerequisite**: Stage 1a completed. `entry-dirs-{platform_id}.json` files exist in `{sync_state_path}/knowledge-bizs/`.
 
 **Action** (dispatch executes directly via `run_in_terminal`):
 
@@ -270,7 +296,7 @@ After generating the entry-dirs JSON:
    ```
 
 **Script Parameters**:
-- `--entryDirsFile`: Path to the `entry-dirs-{platformId}.json` file generated in Stage 1a (required)
+- `--entryDirsFile`: Path to the `entry-dirs-{platform_id}.json` file generated in Stage 1a (required)
 
 **Note**: `platformId` and `sourcePath` are read from the entry-dirs JSON file. Platform mapping and output directory are automatically derived by the script.
 
@@ -280,7 +306,7 @@ After generating the entry-dirs JSON:
 - `--excludeDirs`: Additional directories to exclude
 
 **Output**:
-- `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-{platformId}.json` — Per-platform feature inventory files
+- `{speccrew_workspace}/knowledges/base/sync-state/knowledge-bizs/features-{platform_id}.json` — Per-platform feature inventory files
 - Each file contains: platform metadata, modules list, and flat features array with `analyzed` status
 
 **Features JSON Structure**:
@@ -358,6 +384,17 @@ After generating the entry-dirs JSON:
 
 **Error handling**: If the merge script exits with non-zero code, STOP and report the error. Do NOT proceed to Stage 2 until merge is resolved.
 
+> ✅ **Stage 1 Milestone**: Feature inventory initialized. {feature_count} features across {platform_count} platforms. → Proceed to Stage 2.
+
+---
+
+> **⚠️ MANDATORY RULES FOR PARALLEL EXECUTION (Stage 2-3)**:
+> 1. ALL workers for the same stage MUST be dispatched in PARALLEL — sequential execution is FORBIDDEN
+> 2. Each worker runs independently — do NOT wait for one worker before dispatching the next
+> 3. Monitor completion via marker files, NOT by polling worker status
+> 4. Failed workers can be retried independently without affecting successful ones
+> 5. Do NOT proceed to next Stage until ALL workers in current Stage have completed or failed
+
 ---
 
 ## Stage 2: Feature Analysis (Batch Processing)
@@ -420,9 +457,68 @@ For each feature in the `batch` array, prepare a Worker Task:
 **Execution sequence**:
 1. Prepare ALL Worker Tasks first (do NOT launch yet)
 2. Launch ALL Workers at the SAME TIME in a single batch dispatch
-3. Wait for ALL Workers to complete before proceeding to Step 3
+3. Wait for ALL Workers to complete before proceeding to Step 2.5
 4. Each Worker writes `.done` and `.graph.json` marker files to `completed_dir` upon completion
 
+**Step 2.5: Launch Graph Workers — PARALLEL per Completed Analyze Worker**
+
+After each analyze worker completes (writes `.done.json` marker), immediately dispatch the corresponding graph worker:
+
+| Analyze Worker | Graph Worker | Input |
+|----------------|--------------|-------|
+| `speccrew-knowledge-bizs-api-analyze` | `speccrew-knowledge-bizs-api-graph` | `documentPath` from analyze output |
+| `speccrew-knowledge-bizs-ui-analyze` | `speccrew-knowledge-bizs-ui-graph` | `documentPath` from analyze output |
+
+**Graph Worker Task Prompt Format**:
+
+**For API Graph Worker**:
+```json
+{
+  "skill_name": "speccrew-knowledge-bizs-api-graph",
+  "instructions": "Generate graph data nodes and edges from the analyzed API feature document.\\n\\nRequirements:\\n- Read the API analysis document at api_analysis_path\\n- Extract entities (APIs, services, tables, DTOs)\\n- Generate graph nodes and edges\\n- Write graph JSON to output_dir\\n- Create .graph-done.json completion marker at output_dir",
+  "context": {
+    "api_analysis_path": "<feature.documentPath>",
+    "platform_id": "<feature.platform_id>",
+    "output_dir": "<completed_dir_absolute_path>",
+    "module": "<feature.module>",
+    "fileName": "<feature.fileName>",
+    "sourcePath": "<feature.sourcePath>",
+    "sourceFile": "<feature.sourceFile>",
+    "language": "<user language>",
+    "subpath": "<computed_subpath_from_sourcePath>"
+  }
+}
+```
+
+**For UI Graph Worker**:
+```json
+{
+  "skill_name": "speccrew-knowledge-bizs-ui-graph",
+  "instructions": "Generate graph data nodes and edges from the analyzed UI feature document.\\n\\nRequirements:\\n- Read the UI analysis document at documentPath\\n- Extract entities (pages, components, API calls, navigations)\\n- Generate graph nodes and edges\\n- Write graph JSON to completed_dir\\n- Create .graph-done.json completion marker at completed_dir",
+  "context": {
+    "feature": "<complete_feature_object>",
+    "fileName": "<feature.fileName>",
+    "sourcePath": "<feature.sourcePath>",
+    "documentPath": "<feature.documentPath>",
+    "module": "<feature.module>",
+    "platform_type": "<feature.platform_type>",
+    "platform_subtype": "<feature.platform_subtype>",
+    "completed_dir": "<completed_dir_absolute_path>",
+    "sourceFile": "<feature.sourceFile>",
+    "status": "<analysis_status>",
+    "analysisNotes": "<analysis_notes>",
+    "language": "<user language>"
+  }
+}
+```
+
+**Execution sequence**:
+1. Scan `completed_dir` for new `.done.json` files from Step 2
+2. For each completed analyze worker, prepare corresponding graph worker task
+3. Launch ALL graph workers for the current batch in PARALLEL
+4. Wait for ALL graph workers to complete
+5. Each graph worker writes `.graph-done.json` marker to `completed_dir`
+
 Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneously, NOT one by one.
 
 **Worker Task Prompt Format**:
@@ -471,30 +567,30 @@ Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneo
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{module}-{subpath}-{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{file_name}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{file_name}.graph.json    ← Graph data marker (JSON format)
 ```
 
 **Naming Rule Explanation:**
 
-The marker filename MUST follow the composite naming pattern `{module}-{subpath}-{fileName}` to prevent conflicts between same-named source files.
+The marker filename MUST follow the composite naming pattern `{module}-{subpath}-{file_name}` to prevent conflicts between same-named source files.
 
 **How Workers Generate the Filename:**
 
 1. **module**: Use the `{{module}}` input variable directly
 
-2. **subpath**: Extract from `{{sourcePath}}`:
+2. **subpath**: Extract from `{{source_path}}`:
    - For UI (Vue/React): Middle path between `views/` or `pages/` and the file name
    - For API (Java): Middle path between controller root and the file name
    - Replace path separators (`/`) with hyphens (`-`)
    - Omit if file is at module root (empty subpath)
 
-3. **fileName**: Use `{{fileName}}` input variable (file name WITHOUT extension)
+3. **file_name**: Use `{{file_name}}` input variable (file name WITHOUT extension)
 
 **Examples:**
 
-| Source File | module | subpath | fileName | Marker Filename |
-|-------------|--------|---------|----------|-----------------|
+| Source File | module | subpath | file_name | Marker Filename |
+|-------------|--------|---------|-----------|-----------------|
 | `yudao-ui/.../views/system/notify/message/index.vue` | `system` | `notify-message` | `index` | `system-notify-message-index.done.json` |
 | `yudao-ui/.../views/system/user/index.vue` | `system` | `user` | `index` | `system-user-index.done.json` |
 | `yudao-module-system/.../controller/admin/user/UserController.java` | `system` | `controller-admin-user` | `UserController` | `system-controller-admin-user-UserController.done.json` |
@@ -505,11 +601,11 @@ The marker filename MUST follow the composite naming pattern `{module}-{subpath}
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
-{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
-{fileName}.completed.json         ← WRONG extension
-{fileName}.done                   ← WRONG extension (missing .json)
-{fileName}_done.json              ← WRONG separator and extension
+{file_name}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{file_name}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{file_name}.completed.json         ← WRONG extension
+{file_name}.done                   ← WRONG extension (missing .json)
+{file_name}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
@@ -597,11 +693,12 @@ The marker filename MUST follow the composite naming pattern `{module}-{subpath}
 
 2. **Execute process-results**:
    ```
-   node "{path_to_batch_orchestrator_js}" process-results --syncStatePath "{sync_state_path}" --graphRoot "{graph_root}" --graphWriteScript "{graph_write_script_path}" --platformId "{platformId}"
+   node "{path_to_batch_orchestrator_js}" process-results --syncStatePath "{sync_state_path}" --graphRoot "{graph_root}" --platformId "{platformId}"
    ```
 
 This script:
-- Scans `.done` files → updates feature status to `completed` in features-*.json
+- Scans `.done.json` files → updates feature status to `completed` in features-*.json
+- Scans `.graph-done.json` files → confirms graph data generation completed
 - Scans `.graph.json` files → writes graph data (nodes + edges) grouped by module
 - Cleans up all marker files
 
@@ -617,10 +714,13 @@ Dispatch 采用完全无状态的文件驱动设计。如果执行过程中发
 
 #### Stage 2 Output
 
-- Generated by Workers: Feature documentation at `feature.documentPath` (one .md per feature); marker files (`.done` + `.graph.json`) in `completed_dir`
-- Updated by `process-results`: Each `features-{platform}.json` updated with analysis timestamps and status; graph data written to `speccrew-workspace/knowledges/bizs/graph/`
+- Generated by Analyze Workers: Feature documentation at `feature.documentPath` (one .md per feature); marker files (`.done.json`) in `completed_dir`
+- Generated by Graph Workers: Graph data files (`.graph.json`) in `completed_dir`; consolidated graph data in `speccrew-workspace/knowledges/bizs/graph/`
+- Updated by `process-results`: Each `features-{platform}.json` updated with analysis timestamps and status
 - Marker files cleaned up after each batch
 
+**Stage 2 Completion Condition**: ALL analyze workers AND ALL graph workers completed (both `.done.json` and `.graph-done.json` markers present)
+
 **Feature Status Flow**: `pending` → `in_progress` → `completed` / `failed`
 
 ### Large-Scale Scenario Guidance
@@ -632,6 +732,8 @@ When dealing with modules containing more than **20 features**, consider the fol
 - **Resume Support**: The `get-next-batch` script naturally supports resume across sessions — it skips features that already have `.done` files. To resume after a session break, simply restart the Stage 2 loop.
 - **Validation After Completion**: After all features are marked `analyzed=true`, run `process-batch-results` with `--validateDocs --syncStatePath "{sync_state_path}"` to verify document completeness.
 
+> ✅ **Stage 2 Milestone**: Feature analysis complete. {analyzed_count} features analyzed, {failed_count} failed. {graph_count} graph data files generated. → Proceed to Stage 3.
+
 ---
 
 ## Stage 3: Module Summarize (Parallel)
@@ -716,6 +818,8 @@ speccrew-workspace/knowledges/techs/{platform_id}/ui-style-patterns/
     └── {pattern-name}.md
 ```
 
+> ✅ **Stage 3 & 3.5 Milestone**: Module summaries and UI style patterns complete. {module_count} modules summarized, {pattern_count} patterns extracted. → Proceed to Stage 4.
+
 ---
 
 ## Stage 4: System Summarize (Single Task)
@@ -738,6 +842,8 @@ Expected Worker Return: `{ "status": "success|failed", "output_file": "system-ov
 **Output**:
 - `speccrew-workspace/knowledges/bizs/system-overview.md` (complete with platform index and module hierarchy)
 
+> ✅ **Stage 4 Milestone**: System overview generated. All stages complete. Pipeline finished successfully.
+
 ---
 
 ## Error Handling
@@ -756,6 +862,34 @@ Expected Worker Return: `{ "status": "success|failed", "output_file": "system-ov
 
 ---
 
+## Task Completion Report
+
+Upon completing all stages, output the following structured report:
+
+```json
+{
+  "status": "success | partial | failed",
+  "skill": "speccrew-knowledge-bizs-dispatch",
+  "stages_completed": ["stage_0", "stage_1", "stage_2", "stage_3", "stage_4"],
+  "stages_failed": [],
+  "output_summary": {
+    "platforms_processed": ["frontend", "backend"],
+    "features_analyzed": 32,
+    "modules_summarized": 8,
+    "system_overview_generated": true
+  },
+  "output_files": [
+    "knowledges/bizs/{platform}/features/",
+    "knowledges/bizs/{platform}/modules/",
+    "knowledges/bizs/system-overview.md"
+  ],
+  "errors": [],
+  "next_steps": ["Initialize techs knowledge base"]
+}
+```
+
+---
+
 ## Return
 
 After all 5 stages complete, return a summary object to the caller: