speccrew 0.2.0 → 0.2.2

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

@@ -221,9 +221,9 @@ When there is only one Feature Spec and one platform:
 
 ### 5.4 Parallel Execution (Feature × Platform)
 
-> **IMPORTANT**: Use the **Skill tool** (not the Agent tool) to invoke each design skill.
+> **IMPORTANT**: Dispatch `speccrew-task-worker` agents (via Agent tool) for parallel design execution. Do NOT call design skills directly — each Feature×Platform combination MUST run in an independent Worker Agent for progress visibility and error isolation.
 
-When multiple Feature Specs and/or multiple platforms exist, create a matrix of **Feature × Platform** and use the **Skill tool** to invoke per-platform design skills in parallel:
+When multiple Feature Specs and/or multiple platforms exist, create a matrix of **Feature × Platform** and dispatch `speccrew-task-worker` agents in parallel:
 
 **Worker Matrix:**
 
@@ -245,19 +245,19 @@ Each worker receives:
 
 **Before dispatch**: Update each task status to `in_progress` with `started_at` timestamp.
 
-**Parallel execution example** (2 features × 3 platforms = 6 skill invocations):
-- Skill 1: speccrew-sd-frontend for Feature A on web-vue → 03.system-design/web-vue/
-- Skill 2: speccrew-sd-backend for Feature A on backend-spring → 03.system-design/backend-spring/
-- Skill 3: speccrew-sd-mobile for Feature A on mobile-uniapp → 03.system-design/mobile-uniapp/
-- Skill 4: speccrew-sd-frontend for Feature B on web-vue → 03.system-design/web-vue/
-- Skill 5: speccrew-sd-backend for Feature B on backend-spring → 03.system-design/backend-spring/
-- Skill 6: speccrew-sd-mobile for Feature B on mobile-uniapp → 03.system-design/mobile-uniapp/
+**Parallel execution example** (2 features × 3 platforms = 6 workers):
+- Worker 1: speccrew-sd-frontend for Feature A on web-vue → 03.system-design/web-vue/
+- Worker 2: speccrew-sd-backend for Feature A on backend-spring → 03.system-design/backend-spring/
+- Worker 3: speccrew-sd-mobile for Feature A on mobile-uniapp → 03.system-design/mobile-uniapp/
+- Worker 4: speccrew-sd-frontend for Feature B on web-vue → 03.system-design/web-vue/
+- Worker 5: speccrew-sd-backend for Feature B on backend-spring → 03.system-design/backend-spring/
+- Worker 6: speccrew-sd-mobile for Feature B on mobile-uniapp → 03.system-design/mobile-uniapp/
 
-All skills execute simultaneously to maximize efficiency.
+All workers execute simultaneously to maximize efficiency.
 
 ### 5.5 Update DISPATCH-PROGRESS.json
 
-After each skill completes, parse its **Task Completion Report** and update:
+After each worker completes, parse its **Task Completion Report** and update:
 
 ```json
 {
@@ -275,7 +275,7 @@ After each skill completes, parse its **Task Completion Report** and update:
 }
 ```
 
-Wait for all skills to complete before proceeding to Phase 6.
+Wait for all workers to complete before proceeding to Phase 6.
 
 ## Phase 6: Joint Confirmation
 

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

@@ -184,7 +184,7 @@ If any pre-check fails:
 
 ## Step 4: Dispatch Per-Module Dev Skills
 
-> **IMPORTANT**: Use the **Skill tool** to dispatch dev skills for parallel execution.
+> **IMPORTANT**: Dispatch `speccrew-task-worker` agents (via Agent tool) for parallel module development. Do NOT call dev skills directly — each module MUST run in an independent Worker Agent for progress visibility and error isolation.
 
 ### 4.0 Initialize DISPATCH-PROGRESS.json
 
@@ -282,11 +282,11 @@ for each platform_id:
    }
    ```
 
-### 4.3 Dispatch Skills with Concurrency Limit
+### 4.3 Dispatch Workers with Concurrency Limit
 
-**Max concurrent child agents: 10**
+**Max concurrent workers: 10**
 
-Process `task_list` using a queue-based concurrency limit model:
+Process `task_list` using a queue-based concurrency limit model. Each task runs in an independent `speccrew-task-worker` agent:
 
 ```
 MAX_CONCURRENT = 10
@@ -303,24 +303,24 @@ while pending is not empty or running is not empty:
       - Set task.status = "in_progress"
       - Set task.started_at = current timestamp
     
-    // Use Skill tool (not Agent tool)
-    skill_result = invoke Skill tool with:
-      - skill: {task.skill_name}
-      - args: |
-          platform_id: {task.platform_id}
-          iteration_path: {task.iteration_path}
-          design_doc_path: {task.module_design_path}
-          api_contract_path: {task.api_contract_path}
-          techs_knowledge_paths: {task.techs_knowledge_paths}
-          task_id: {task.id}  // Pass task ID for completion report
+    // Dispatch speccrew-task-worker agent (NOT Skill tool directly)
+    Invoke `speccrew-task-worker` agent with:
+      - skill_name: {task.skill_name}
+      - context:
+        - platform_id: {task.platform_id}
+        - iteration_path: {task.iteration_path}
+        - design_doc_path: {task.module_design_path}
+        - api_contract_path: {task.api_contract_path}
+        - techs_knowledge_paths: {task.techs_knowledge_paths}
+        - task_id: {task.id}  // Pass task ID for completion report
     
-    running.add({task_id: task.id, skill_handle: skill_result})
+    running.add({task_id: task.id})
   
-  wait until at least one skill in running completes
+  wait until at least one worker in running completes
   
-  // Process completed skill result
-  for each finished skill in running:
-    Parse Task Completion Report from skill output
+  // Process completed worker result
+  for each finished worker in running:
+    Parse Task Completion Report from worker output
     
     if report.status == "SUCCESS":
       Update DISPATCH-PROGRESS.json:
@@ -339,17 +339,17 @@ while pending is not empty or running is not empty:
 ```
 
 **Dispatch rules:**
-- Each skill invocation handles **one module** on **one platform** (not all modules)
+- Each worker handles **one module** on **one platform** (not all modules)
 - Pass complete context including `design_doc_path`, `skill_name`, platform info, and `task_id`
-- Up to 10 skills execute simultaneously (concurrency limit)
+- Up to 10 workers execute simultaneously (concurrency limit)
 - Update DISPATCH-PROGRESS.json **before** dispatch (status → "in_progress")
 - Update DISPATCH-PROGRESS.json **after** completion based on Task Completion Report
 - Track all dispatched tasks: completed / failed / pending counts
-- If a skill fails, log the failure and continue with remaining tasks
-- Wait for all skills to complete before proceeding to Step 5 (Integration Check)
+- If a worker fails, log the failure and continue with remaining tasks
+- Wait for all workers to complete before proceeding to Step 5 (Integration Check)
 
 **Progress Update After Each Batch:**
-After processing a batch of completed skills:
+After processing a batch of completed workers:
 1. Read current DISPATCH-PROGRESS.json
 2. Update counts: `completed`, `failed`, `pending`
 3. Write updated DISPATCH-PROGRESS.json

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

@@ -163,7 +163,7 @@ Design test cases based on loaded knowledge:
 
 After reading `DESIGN-OVERVIEW.md`:
 - **Single Platform**: Invoke Skill directly
-- **Multiple Platforms**: Use **Skill tool** to invoke per-platform skills in parallel
+- **Multiple Platforms**: Dispatch `speccrew-task-worker` agents in parallel (via Agent tool)
 
 ### 3.2 Single Platform Execution
 
@@ -177,7 +177,7 @@ Invoke Skill directly with parameters:
 
 ### 3.3 Multi-Platform Parallel Execution
 
-> **IMPORTANT**: Use the **Skill tool** (not the Agent tool) to invoke each test skill.
+> **IMPORTANT**: Dispatch `speccrew-task-worker` agents (via Agent tool) for parallel test execution. Do NOT call test skills directly — each platform MUST run in an independent Worker Agent for progress visibility and error isolation.
 
 > **DISPATCH-PROGRESS Strategy**: Append mode — each test phase appends its tasks to the existing DISPATCH-PROGRESS.json with a distinct `phase` field. Previous phase records are preserved for full traceability.
 
@@ -210,7 +210,7 @@ Before dispatching, create or update `DISPATCH-PROGRESS.json`:
 
 **Dispatch Workers:**
 
-Use the **Skill tool** to invoke `speccrew-test-case-design` for each platform in parallel:
+Dispatch `speccrew-task-worker` agents for `speccrew-test-case-design` for each platform in parallel:
 - Each worker receives:
   - `skill_name`: `speccrew-test-case-design`
   - `context`:
@@ -321,7 +321,7 @@ Update `DISPATCH-PROGRESS.json` with new phase:
 
 **Dispatch Workers:**
 
-Use the **Skill tool** to invoke `speccrew-test-code-gen` for each platform in parallel:
+Dispatch `speccrew-task-worker` agents for `speccrew-test-code-gen` for each platform in parallel:
   - `context`:
     - `test_cases_path`: Path to the platform-specific test cases document
     - `system_design_path`: Path to the platform system design document
@@ -430,7 +430,7 @@ Update `DISPATCH-PROGRESS.json` with new phase:
 
 **Dispatch Workers:**
 
-Use the **Skill tool** to invoke `speccrew-test-execute` for each platform in parallel:
+Dispatch `speccrew-task-worker` agents for `speccrew-test-execute` for each platform in parallel:
   - `context`:
     - `test_code_path`: Path to the platform test code directory
     - `platform_id`: Platform identifier
@@ -575,7 +575,7 @@ Update `WORKFLOW-PROGRESS.json`:
 **Must do:**
 - Execute three phases in strict order: test case design → code generation → test execution
 - Each phase must have a Checkpoint with user confirmation before proceeding
-- Multi-platform scenarios must use the **Skill tool** to invoke per-platform skills in parallel
+- Multi-platform scenarios must dispatch `speccrew-task-worker` agents (via Agent tool) for parallel execution per platform
 - Test cases must be traceable to Feature Spec requirements
 - Bug reports must reference specific test case IDs
 - Use platform_id from design overview as directory names

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.2",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {