speccrew 0.2.0 → 0.2.1

package/.speccrew/skills/speccrew-knowledge-bizs-api-analyze/SKILL.md

@@ -76,8 +76,8 @@ This skill operates in **strict sequential execution mode**:
 
 **Generated Files:**
 1. `{{documentPath}}` - Controller documentation file
-2. `{{completed_dir}}/{{fileName}}.done.json` - Completion status marker
-3. `{{completed_dir}}/{{fileName}}.graph.json` - Graph data marker
+2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
+3. `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json` - Graph data marker
 
 **Return Value:**
 ```json
@@ -856,7 +856,7 @@ Or in case of failure:
 > **ASSUMPTION**: The `completed_dir` directory already exists (pre-created by dispatch Stage 2). If write fails, report error — do NOT attempt to create directories.
 
 ### Pre-write Checklist (VERIFY before writing each file):
-- [ ] Filename follows `{fileName}` pattern (Java class name only)
+- [ ] Filename follows `{module}-{subpath}-{fileName}` pattern (see naming convention below)
 - [ ] File content is valid JSON (not empty)
 - [ ] All required fields are present and non-empty
 - [ ] File is written with UTF-8 encoding
@@ -875,30 +875,57 @@ Or in case of failure:
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.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.
+
+**How to Extract Each Component from `{{sourcePath}}`:**
+
+1. **module**: Use `{{module}}` input variable directly (e.g., `system`, `trade`, `ai`)
+
+2. **subpath**: Extract the middle path between the module package root and the controller file:
+   - For Java: Remove package prefix up to the business layer (e.g., `controller/admin/`, `controller/app/`)
+   - Remove the file name at the end
+   - Replace path separators (`/`) with hyphens (`-`)
+   - If the file is at the module root directory, subpath will be empty → omit from filename
+
+3. **fileName**: Use `{{fileName}}` input variable (Java class name WITHOUT `.java` extension)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+
+| sourcePath | module | subpath | fileName | Marker Filename |
+|------------|--------|---------|----------|-----------------|
+| `yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/notify/NotifyMessageController.java` | `system` | `controller-admin-notify` | `NotifyMessageController` | `system-controller-admin-notify-NotifyMessageController.done.json` |
+| `yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/user/UserController.java` | `system` | `controller-admin-user` | `UserController` | `system-controller-admin-user-UserController.done.json` |
+| `yudao-module-ai/yudao-module-ai-biz/src/main/java/cn/iocoder/yudao/module/ai/controller/admin/chat/ChatConversationController.java` | `ai` | `controller-admin-chat` | `ChatConversationController` | `ai-controller-admin-chat-ChatConversationController.done.json` |
+
+**Special Case - Empty subpath:**
+- If the controller is directly in the controller root directory (no subpath), use format: `{module}-{fileName}.done.json`
+- Example: `.../controller/admin/SystemController.java` → `system-SystemController.done.json`
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-notify-NotifyMessageController.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/ai-controller-admin-chat-ChatConversationController.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{module}-{fileName}.done.json     ← WRONG: missing subpath (may still conflict)
+{fileName}.completed.json         ← WRONG extension
+{fileName}.done                   ← WRONG extension (missing .json)
+{fileName}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `UserController.done.json` - WRONG: missing module and subpath (conflicts with other `UserController.java` files)
+- `system-UserController.done.json` - WRONG: missing subpath (if file is in `controller/admin/user/`)
 - `UserController.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `UserController.done` - WRONG: uses `.done` instead of `.done.json`
-- `UserController.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `UserController_done.json` - WRONG: uses underscore and wrong extension
-- `dict-UserController.done.json` - WRONG: has module prefix
-- `system-UserController.done.json` - WRONG: has module prefix
 
 ---
 
@@ -959,9 +986,9 @@ Or in case of failure:
 > {"fileName": "UserController", "status": "success", ...}
 > ```
 
-Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
+Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json`:
 
-**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
+**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.done.json`
 
 **Complete JSON Template (ALL fields required):**
 ```json
@@ -998,12 +1025,13 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
 
 > **⚠️ CRITICAL**: The `documentPath` field is MANDATORY. It MUST match the `{{documentPath}}` variable from Step 5a. This is used to verify the document was created successfully.
 
-⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.done.json`, where `fileName` is the Java class name (e.g., `UserController`, `AiKnowledgeDocumentCreateListReqVO`).
-- ✅ CORRECT: `UserController.done.json` (using Java class name directly)
-- ✅ CORRECT: `AiKnowledgeDocumentCreateListReqVO.done.json` (using Java class name directly)
+⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.done.json` to prevent conflicts between same-named files.
+- ✅ CORRECT: `system-controller-admin-user-UserController.done.json` (full composite naming)
+- ✅ CORRECT: `ai-controller-admin-chat-ChatConversationController.done.json` (full composite naming)
+- ✅ CORRECT: `system-SystemController.done.json` (when subpath is empty, controller at root)
+- ❌ WRONG: `UserController.done.json` (missing module and subpath - will conflict)
 - ❌ WRONG: `UserController.done` (missing .json extension)
-- ❌ WRONG: `dict-UserController.done.json` (using old featureId format)
-- ❌ WRONG: `system-UserController.done.json` (using module prefix)
+- ❌ WRONG: `system-UserController.done.json` (missing subpath when controller is in nested package)
 
 ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -1011,9 +1039,9 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
 
 > **⚠️ CRITICAL FORMAT REQUIREMENT**: The `.graph.json` file MUST be valid JSON and **MUST include the root-level `module` field**. Do NOT rely on scripts to infer the module from `.done` file - the `module` field MUST be explicitly present at the root level of `.graph.json`.
 
-Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`:
+Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json`:
 
-**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+**Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.graph.json`
 
 ```json
 {
@@ -1045,11 +1073,13 @@ Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`
 > - Do NOT assume scripts will fall back to reading from `.done` file
 > - Missing `module` field will cause the graph merge pipeline to reject this file
 
-⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.graph.json`, where `fileName` is the Java class name (e.g., `UserController`, `AiKnowledgeDocumentCreateListReqVO`).
-- ✅ CORRECT: `UserController.graph.json` (using Java class name directly)
-- ✅ CORRECT: `AiKnowledgeDocumentCreateListReqVO.graph.json` (using Java class name directly)
+⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.graph.json` to prevent conflicts between same-named files.
+- ✅ CORRECT: `system-controller-admin-user-UserController.graph.json` (full composite naming)
+- ✅ CORRECT: `ai-controller-admin-chat-ChatConversationController.graph.json` (full composite naming)
+- ✅ CORRECT: `system-SystemController.graph.json` (when subpath is empty, controller at root)
+- ❌ WRONG: `UserController.graph.json` (missing module and subpath - will conflict)
 - ❌ WRONG: `dict-UserController.graph.json` (using old featureId format)
-- ❌ WRONG: `system-UserController.graph.json` (using module prefix)
+- ❌ WRONG: `system-UserController.graph.json` (missing subpath when controller is in nested package)
 
 ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 

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

@@ -426,30 +426,52 @@ Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneo
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.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.
+
+**How Workers Generate the Filename:**
+
+1. **module**: Use the `{{module}}` input variable directly
+
+2. **subpath**: Extract from `{{sourcePath}}`:
+   - 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)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/UserController.graph.json`
+
+| Source File | module | subpath | fileName | 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` |
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-controller-admin-user-UserController.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{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
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `index.done.json` - WRONG: missing module and subpath (conflicts with other `index.vue` files)
+- `UserController.done.json` - WRONG: missing module and subpath (conflicts with other controllers)
 - `UserController.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `UserController.done` - WRONG: uses `.done` instead of `.done.json`
-- `UserController.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `UserController_done.json` - WRONG: uses underscore and wrong extension
-- `dict-UserController.done.json` - WRONG: has module prefix
-- `system-UserController.done.json` - WRONG: has module prefix
 
 ---
 
@@ -508,8 +530,8 @@ Example: If batch has 5 features → create and launch 5 Worker Tasks simultaneo
 
 | Marker Type | File Name Format | Example |
 |-------------|------------------|---------|
-| Completion marker | `{fileName}.done.json` | `index.done.json`, `UserController.done.json`, `AiKnowledgeDocumentCreateListReqVO.done.json` |
-| Graph data | `{fileName}.graph.json` | `index.graph.json`, `UserController.graph.json`, `AiKnowledgeDocumentCreateListReqVO.graph.json` |
+| Completion marker | `{module}-{subpath}-{fileName}.done.json` | `system-notify-message-index.done.json`, `system-controller-admin-user-UserController.done.json` |
+| Graph data | `{module}-{subpath}-{fileName}.graph.json` | `system-notify-message-index.graph.json`, `system-controller-admin-user-UserController.graph.json` |
 
 **Worker Completion Requirements:**
 

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/STATUS-FORMATS.md

@@ -6,6 +6,32 @@ This document defines the status tracking formats for the bizs pipeline.
 
 ---
 
+## Marker File Naming Convention
+
+Marker files (`.done.json` and `.graph.json`) use a composite naming pattern to prevent conflicts between same-named source files.
+
+**Format:** `{module}-{subpath}-{fileName}.{type}.json`
+
+**Components:**
+- **module**: Business module name (e.g., `system`, `ai`, `bpm`, `trade`)
+- **subpath**: Middle path extracted from sourcePath, with `/` replaced by `-` (e.g., `notify-message`, `controller-admin-user`)
+- **fileName**: Source file name without extension (e.g., `index`, `UserController`)
+- **type**: `done` or `graph`
+
+**Examples:**
+
+| Source File | Marker Filename |
+|-------------|-----------------|
+| `yudao-ui/.../views/system/notify/message/index.vue` | `system-notify-message-index.done.json` |
+| `yudao-ui/.../views/system/user/index.vue` | `system-user-index.done.json` |
+| `yudao-module-system/.../controller/admin/user/UserController.java` | `system-controller-admin-user-UserController.done.json` |
+
+**Special Case:** If subpath is empty (file at module root), use format: `{module}-{fileName}.{type}.json`
+
+**Legacy Format Support:** The processing scripts support both new format (`{module}-{subpath}-{fileName}`) and legacy format (`{fileName}`) for backward compatibility.
+
+---
+
 ## Feature Status Tracking (Stage 2)
 
 Feature analysis status is tracked directly in `features-{platform}.json` files located at:
@@ -61,11 +87,10 @@ Module summarization status is determined by aggregating feature statuses from `
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `features[].id` | string | Unique feature identifier (used for marker file naming) |
-| `features[].fileName` | string | Feature file name |
-| `features[].sourcePath` | string | Source code file path |
+| `features[].fileName` | string | Feature file name (without extension) - used as part of marker file naming |
+| `features[].sourcePath` | string | Source code file path - used to extract subpath for marker file naming |
 | `features[].documentPath` | string | Generated documentation path |
-| `features[].module` | string | Module code_name |
+| `features[].module` | string | Module code_name - used as prefix for marker file naming |
 | `features[].analyzed` | boolean | Whether feature has been analyzed |
 | `features[].status` | string | `pending`, `in_progress`, `completed`, `failed` |
 | `features[].startedAt` | string | ISO timestamp when analysis started |

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/scripts/process-batch-results.js

@@ -11,6 +11,53 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
+// Helper: Parse marker filename to extract components
+// New format: {module}-{subpath}-{fileName}.done.json
+// Legacy format: {fileName}.done.json
+function parseMarkerFilename(markerFile, fileType) {
+    // fileType: 'done' or 'graph'
+    const ext = `.${fileType}.json`;
+    if (!markerFile.endsWith(ext)) {
+        return null;
+    }
+    
+    const baseName = markerFile.slice(0, -ext.length);
+    const parts = baseName.split('-');
+    
+    // New format: must have at least 3 parts (module-subpath-fileName)
+    // But subpath can be empty, so minimum is 2 parts (module-fileName)
+    if (parts.length >= 2) {
+        // Try to identify if this is new format or legacy format
+        // New format has module prefix (known modules are usually short names like 'system', 'ai', 'bpm', 'trade')
+        // Legacy format is just fileName (e.g., 'index', 'UserController')
+        
+        // Heuristic: if first part is a known module-like name and there are more parts,
+        // treat it as new format
+        // For now, we'll return both possible interpretations and let the caller decide
+        return {
+            baseName: baseName,
+            parts: parts,
+            // For new format: fileName is the last part
+            newFormatFileName: parts[parts.length - 1],
+            // For new format: module is the first part
+            newFormatModule: parts[0],
+            // For new format: subpath is everything in between
+            newFormatSubpath: parts.length > 2 ? parts.slice(1, -1).join('-') : '',
+            // For legacy format: fileName is the entire baseName
+            legacyFileName: baseName,
+            // Detect likely format based on pattern
+            isLikelyNewFormat: parts.length > 1 && parts[0].length < 20 // module names are usually short
+        };
+    }
+    
+    return {
+        baseName: baseName,
+        parts: parts,
+        legacyFileName: baseName,
+        isLikelyNewFormat: false
+    };
+}
+
 // Helper: Validate and normalize .done.json file content
 function validateAndNormalizeDoneContent(content, doneFile) {
     // Strip file extensions from fileName if present
@@ -371,12 +418,16 @@ function main() {
 
     // Fallback: recover minimal info from filename and context when .done.json is non-JSON
     function recoverDoneFileFromContext(doneFile, completedDir, syncStatePath) {
-        const fileName = doneFile.replace(/\.done\.json$/, '');
+        const parseResult = parseMarkerFilename(doneFile, 'done');
+        
+        // Determine fileName: prefer content from .done.json, fall back to filename parsing
+        let fileName = parseResult ? parseResult.legacyFileName : doneFile.replace(/\.done\.json$/, '');
+        
         console.warn(`[WARN] .done.json file is not valid JSON: ${doneFile}. Attempting recovery from filename...`);
-
+        
         // Try to get module from same-named .graph.json
         let module = 'unknown';
-        const graphFilePath = path.join(completedDir, fileName + '.graph.json');
+        const graphFilePath = path.join(completedDir, doneFile.replace('.done.json', '.graph.json'));
         if (fs.existsSync(graphFilePath)) {
             try {
                 const graphContent = JSON.parse(fs.readFileSync(graphFilePath, 'utf8'));
@@ -387,6 +438,11 @@ function main() {
                 // Ignore parse errors
             }
         }
+        
+        // If module is still unknown, try to extract from new-format filename
+        if (module === 'unknown' && parseResult && parseResult.isLikelyNewFormat) {
+            module = parseResult.newFormatModule;
+        }
 
         // Try to match sourceFile from features-*.json files
         let sourceFile = 'unknown';
@@ -399,7 +455,18 @@ function main() {
                 try {
                     const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
                     if (content.features && Array.isArray(content.features)) {
-                        const found = content.features.find(feat => feat.fileName === fileName);
+                        // Try both new format and legacy format matching
+                        let found = content.features.find(feat => feat.fileName === fileName);
+                        
+                        // If not found with legacy fileName and we have new format info,
+                        // try matching with newFormatFileName
+                        if (!found && parseResult && parseResult.isLikelyNewFormat) {
+                            found = content.features.find(feat => feat.fileName === parseResult.newFormatFileName);
+                            if (found) {
+                                fileName = parseResult.newFormatFileName;
+                            }
+                        }
+                        
                         if (found) {
                             sourceFile = f;
                             break;

package/.speccrew/skills/speccrew-knowledge-bizs-ui-analyze/SKILL.md

@@ -71,8 +71,8 @@ Analyze one specific UI feature from source code, extract business functionality
 
 **Generated Files (MANDATORY - Task is NOT complete until all files are written):**
 1. `{{documentPath}}` - Feature documentation file
-2. `{{completed_dir}}/{{fileName}}.done.json` - Completion status marker
-3. `{{completed_dir}}/{{fileName}}.graph.json` - Graph data marker
+2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
+3. `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json` - Graph data marker
 
 **Return Value (JSON format):**
 ```json
@@ -808,7 +808,7 @@ After analysis is complete, write the results to marker files for dispatch to pr
 > **ASSUMPTION**: The `completed_dir` directory already exists (pre-created by dispatch Stage 2). If write fails, report error — do NOT attempt to create directories.
 
 ### Pre-write Checklist (VERIFY before writing each file):
-- [ ] Filename follows `{fileName}` pattern (file name only)
+- [ ] Filename follows `{module}-{subpath}-{fileName}` pattern (see naming convention below)
 - [ ] File content is valid JSON (not empty)
 - [ ] All required fields are present and non-empty
 - [ ] File is written with UTF-8 encoding
@@ -829,30 +829,57 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.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.
+
+**How to Extract Each Component from `{{sourcePath}}`:**
+
+1. **module**: Use `{{module}}` input variable directly (e.g., `system`, `trade`, `bpm`)
+
+2. **subpath**: Extract the middle path between the platform source root and the file name:
+   - Remove the top-level directory prefix (e.g., `yudao-ui/yudao-ui-admin-vue3/src/views/`)
+   - Remove the file name at the end
+   - Replace path separators (`/`) with hyphens (`-`)
+   - If the file is at the module root directory, subpath will be empty → omit from filename
+
+3. **fileName**: Use `{{fileName}}` input variable (file name WITHOUT extension)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.graph.json`
+
+| sourcePath | module | subpath | fileName | Marker Filename |
+|------------|--------|---------|----------|-----------------|
+| `yudao-ui/yudao-ui-admin-vue3/src/views/system/notify/message/index.vue` | `system` | `notify-message` | `index` | `system-notify-message-index.done.json` |
+| `yudao-ui/yudao-ui-admin-vue3/src/views/system/user/index.vue` | `system` | `user` | `index` | `system-user-index.done.json` |
+| `yudao-ui/yudao-ui-admin-vue3/src/views/bpm/process-instance/index.vue` | `bpm` | `process-instance` | `index` | `bpm-process-instance-index.done.json` |
+
+**Special Case - Empty subpath:**
+- If the file is directly in the module root directory (no subpath), use format: `{module}-{fileName}.done.json`
+- Example: `yudao-ui/yudao-ui-admin-vue3/src/views/system/index.vue` → `system-index.done.json`
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-user-index.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{module}-{fileName}.done.json     ← WRONG: missing subpath (may still conflict)
+{fileName}.completed.json         ← WRONG extension
+{fileName}.done                   ← WRONG extension (missing .json)
+{fileName}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `index.done.json` - WRONG: missing module and subpath (conflicts with other `index.vue` files)
+- `system-index.done.json` - WRONG: missing subpath (if file is in `system/notify/message/`)
 - `index.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `index.done` - WRONG: uses `.done` instead of `.done.json`
-- `index.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `index_done.json` - WRONG: uses underscore and wrong extension
-- `dict-index.done.json` - WRONG: has module prefix
-- `system-index.done.json` - WRONG: has module prefix
 
 ---
 
@@ -942,9 +969,9 @@ After analysis is complete, write the results to marker files for dispatch to pr
    > {"fileName": "index", "status": "success", ...}
    > ```
 
-   Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
+   Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json`:
    
-   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.done.json`
+   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
 
    **Complete JSON Template (ALL fields required):**
    ```json
@@ -981,12 +1008,13 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
    > **⚠️ CRITICAL**: The `documentPath` field is MANDATORY. It MUST match the `{{documentPath}}` variable from Step 5a. This is used to verify the document was created successfully.
 
-   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.done.json`, where `fileName` is the feature file name (e.g., `index`, `UserForm`, `AiKnowledgeDocumentCreateListReqVO`).
-   - ✅ CORRECT: `index.done.json` (using file name directly)
-   - ✅ CORRECT: `UserForm.done.json` (using file name directly)
+   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.done.json` to prevent conflicts between same-named files.
+   - ✅ CORRECT: `system-notify-message-index.done.json` (full composite naming)
+   - ✅ CORRECT: `system-user-index.done.json` (full composite naming)
+   - ✅ CORRECT: `bpm-index.done.json` (when subpath is empty, file at module root)
+   - ❌ WRONG: `index.done.json` (missing module and subpath - will conflict)
    - ❌ WRONG: `index.done` (missing .json extension)
-   - ❌ WRONG: `dict-index.done.json` (using old featureId format)
-   - ❌ WRONG: `system-index.done.json` (using module prefix)
+   - ❌ WRONG: `system-index.done.json` (missing subpath when file is in nested directory)
 
    ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -994,9 +1022,9 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
    > **⚠️ CRITICAL FORMAT REQUIREMENT**: The `.graph.json` file MUST be valid JSON and **MUST include the root-level `module` field**. Do NOT rely on scripts to infer the module from `.done` file - the `module` field MUST be explicitly present at the root level of `.graph.json`.
 
-   Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`:
+   Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json`:
    
-   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.graph.json`
+   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.graph.json`
 
    ```json
    {
@@ -1031,11 +1059,13 @@ After analysis is complete, write the results to marker files for dispatch to pr
    > - Do NOT assume scripts will fall back to reading from `.done` file
    > - Missing `module` field will cause the graph merge pipeline to reject this file
 
-   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.graph.json`, where `fileName` is the feature file name (e.g., `index`, `UserForm`, `AiKnowledgeDocumentCreateListReqVO`).
-   - ✅ CORRECT: `index.graph.json` (using file name directly)
-   - ✅ CORRECT: `UserForm.graph.json` (using file name directly)
+   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.graph.json` to prevent conflicts between same-named files.
+   - ✅ CORRECT: `system-notify-message-index.graph.json` (full composite naming)
+   - ✅ CORRECT: `system-user-index.graph.json` (full composite naming)
+   - ✅ CORRECT: `bpm-index.graph.json` (when subpath is empty, file at module root)
+   - ❌ WRONG: `index.graph.json` (missing module and subpath - will conflict)
    - ❌ WRONG: `dict-index.graph.json` (using old featureId format)
-   - ❌ WRONG: `system-index.graph.json` (using module prefix)
+   - ❌ WRONG: `system-index.graph.json` (missing subpath when file is in nested directory)
 
    ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -1047,7 +1077,7 @@ After analysis is complete, write the results to marker files for dispatch to pr
    - [ ] Each `calls` edge has proper metadata with trigger information
    - [ ] No API import is left without a corresponding edge
 
-**Output:** "Step 7 Status: ✅ COMPLETED - Marker files written ({{completed_dir}}/{{fileName}}.done, .graph.json)"
+**Output:** "Step 7 Status: ✅ COMPLETED - Marker files written ({{completed_dir}}/{module}-{subpath}-{fileName}.done.json, .graph.json)"
 
 **On Failure:** "Step 7 Status: ⚠️ PARTIAL - Marker file write failed, but analysis completed"
 

package/package.json

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