speccrew 0.6.11 → 0.6.13

package/.speccrew/skills/speccrew-knowledge-bizs-module-classify/scripts/reindex-modules.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 /**
- * reindex-modules.js - 确定性脚本，用更新后的 exclude_dirs 对已有 features JSON 重新提取 module 名
+ * reindex-modules.js - Deterministic script to re-extract module names from existing features JSON with updated exclude_dirs
  * 
- * 调用方式:
+ * Usage:
  *   node reindex-modules.js --featuresFile "path/to/features-backend-system.json" --projectRoot "d:\dev\ruoyi-vue-pro"
  * 
- * 可选参数:
- *   --platformType "backend" - 如果不提供，从 features JSON 的 platformType 字段读取
- *   --techIdentifier "spring" - 如果不提供，尝试从 features JSON 推断（如 techStack 数组）
- *   --excludeDirs "controller,admin,api,service" - 如果不提供，从 tech-stack-mappings.json 加载
+ * Optional parameters:
+ *   --platformType "backend" - If not provided, read from features JSON's platformType field
+ *   --techIdentifier "spring" - If not provided, try to infer from features JSON (e.g., techStack array)
+ *   --excludeDirs "controller,admin,api,service" - If not provided, load from tech-stack-mappings.json
  */
 
 const fs = require('fs');
 const path = require('path');
 
-// === 工具函数（从 generate-inventory.js 复用） ===
+// === Utility functions (reused from generate-inventory.js) ===
 
 function normalizePath(filePath) {
   if (!filePath) return '';
@@ -32,7 +32,7 @@ function parseArrayParam(value) {
   return trimmed.split(',').map(s => s.trim()).filter(Boolean);
 }
 
-// Java/Kotlin 标准源码路径前缀
+// Java/Kotlin standard source path prefixes
 const STANDARD_SOURCE_PREFIXES = [
   'src/main/java',
   'src/main/kotlin',
@@ -77,7 +77,7 @@ function getModuleName(dirPath, excludeDirs, fallbackModuleName) {
   return '_root';
 }
 
-// === 辅助函数 ===
+// === Helper functions ===
 
 function parseArgs(argv) {
   const args = {};
@@ -113,10 +113,10 @@ function findProjectRoot(startPath) {
 function loadExcludeDirs(projectRoot, platformType, techIdentifier, featuresData) {
   console.log(`Loading exclude_dirs: platformType="${platformType}", techIdentifier="${techIdentifier || '(auto)'}"`);
   
-  // 尝试推断 techIdentifier
+  // Try to infer techIdentifier
   if (!techIdentifier) {
     const techStack = featuresData.techStack || [];
-    // 常见映射
+    // Common mappings
     const techMap = {
       'spring': 'spring', 'spring-boot': 'spring', 'java': 'spring',
       'vue': 'vue', 'vue3': 'vue', 'vue2': 'vue',
@@ -147,7 +147,7 @@ function loadExcludeDirs(projectRoot, platformType, techIdentifier, featuresData
   // Get fallback dirs for this platformType
   const fallback = FALLBACK_EXCLUDE_DIRS[platformType] || [];
   
-  // 查找 tech-stack-mappings.json
+  // Find tech-stack-mappings.json
   const configPaths = [
     path.join(projectRoot, 'speccrew-workspace', 'docs', 'configs', 'tech-stack-mappings.json'),
     path.join(projectRoot, 'docs', 'configs', 'tech-stack-mappings.json'),
@@ -207,25 +207,25 @@ function loadExcludeDirs(projectRoot, platformType, techIdentifier, featuresData
 }
 
 function extractPlatformId(featuresData) {
-  // 从第一个 feature 的 documentPath 提取 platformId
-  // 格式: "speccrew-workspace/knowledges/bizs/{platformId}/..."
+  // Extract platformId from first feature's documentPath
+  // Format: "speccrew-workspace/knowledges/bizs/{platformId}/..."
   for (const feature of (featuresData.features || [])) {
     if (feature.documentPath) {
       const match = normalizePath(feature.documentPath).match(/knowledges\/bizs\/([^/]+)\//);
       if (match) return match[1];
     }
   }
-  // 如果无法提取，用 platformType-platformSubtype 构建
+  // If unable to extract, build from platformType-platformSubtype
   if (featuresData.platformType && featuresData.platformSubtype) {
     return `${featuresData.platformType}-${featuresData.platformSubtype}`;
   }
   return null;
 }
 
-// === 主逻辑 ===
+// === Main logic ===
 
 function main() {
-  // 1. 解析命令行参数
+  // 1. Parse command line arguments
   const args = parseArgs(process.argv.slice(2));
   const featuresFile = args.featuresFile;
   
@@ -234,7 +234,7 @@ function main() {
     process.exit(1);
   }
   
-  // 2. 读取 features JSON
+  // 2. Read features JSON
   let featuresData;
   try {
     featuresData = JSON.parse(fs.readFileSync(featuresFile, 'utf8'));
@@ -250,16 +250,16 @@ function main() {
   const inventorySourcePath = normalizePath(featuresData.sourcePath || '');
   const platformType = args.platformType || featuresData.platformType || '';
   
-  // 3. 加载 exclude_dirs
+  // 3. Load exclude_dirs
   let excludeDirs = [];
   let stripModulePrefixes = [];
   if (args.excludeDirs) {
     excludeDirs = parseArrayParam(args.excludeDirs);
   } else {
-    // 从 tech-stack-mappings.json 加载，按优先级确定 techIdentifier：
-    // 1. 命令行参数 --techIdentifier
-    // 2. features JSON 中的 techIdentifier
-    // 3. features JSON 中的 platformSubtype (兼容旧数据)
+    // Load from tech-stack-mappings.json, determine techIdentifier by priority:
+    // 1. Command line parameter --techIdentifier
+    // 2. techIdentifier in features JSON
+    // 3. platformSubtype in features JSON (backward compatibility)
     const techId = args.techIdentifier || featuresData.techIdentifier || featuresData.platformSubtype;
     const config = loadExcludeDirs(projectRoot, platformType, techId, featuresData);
     excludeDirs = config.excludeDirs;
@@ -274,29 +274,29 @@ function main() {
   console.log(`Exclude dirs (${excludeDirs.length}): ${excludeDirs.join(', ')}`);
   console.log(`Total features: ${featuresData.features.length}`);
   
-  // 4. 重新计算每个 feature 的 module
+  // 4. Recalculate module for each feature
   const modulesBefore = [...new Set(featuresData.features.map(f => f.module))].sort();
   let reclassifiedCount = 0;
   
-  // 从 features JSON 获取 platformId（用于重建 documentPath）
-  // platformId 格式: "{platformType}-{platformSubtype}" 
-  // 从现有 documentPath 提取: "speccrew-workspace/knowledges/bizs/{platformId}/..."
+  // Get platformId from features JSON (for rebuilding documentPath)
+  // platformId format: "{platformType}-{platformSubtype}"
+  // Extract from existing documentPath: "speccrew-workspace/knowledges/bizs/{platformId}/..."
   const platformId = extractPlatformId(featuresData);
   
   featuresData.features.forEach(feature => {
-    // 计算 feature 源文件相对于 inventorySourcePath 的路径
+    // Calculate feature source file path relative to inventorySourcePath
     let relativePath = normalizePath(feature.sourcePath || '');
     
-    // 如果 feature.sourcePath 是绝对路径或相对于项目根，需要去掉 inventorySourcePath 前缀
+    // If feature.sourcePath is absolute or relative to project root, remove inventorySourcePath prefix
     if (inventorySourcePath && relativePath.startsWith(inventorySourcePath)) {
       relativePath = relativePath.slice(inventorySourcePath.length);
       if (relativePath.startsWith('/')) relativePath = relativePath.slice(1);
     }
-    // 也可能 inventorySourcePath 只是部分匹配
+    // inventorySourcePath may only partially match
     else if (inventorySourcePath) {
       const invParts = inventorySourcePath.split('/');
       const relParts = relativePath.split('/');
-      // 找到重叠部分
+      // Find overlapping part
       let startIdx = 0;
       for (let i = 0; i < relParts.length; i++) {
         if (relParts.slice(i, i + invParts.length).join('/') === inventorySourcePath) {
@@ -309,14 +309,14 @@ function main() {
       }
     }
     
-    // 取目录部分（去掉文件名）
+    // Get directory part (remove filename)
     const dirPath = path.dirname(relativePath).replace(/\\/g, '/');
     
-    // 用 getModuleName 重新提取模块名
+    // Re-extract module name using getModuleName
     const fallback = feature.module || '_root';
     let newModule = getModuleName(dirPath, excludeDirs, fallback);
     
-    // 应用 strip_module_prefixes 前缀去除
+    // Apply strip_module_prefixes prefix removal
     for (const prefix of stripModulePrefixes) {
       if (newModule.startsWith(prefix)) {
         newModule = newModule.substring(prefix.length);
@@ -328,21 +328,21 @@ function main() {
       reclassifiedCount++;
       feature.module = newModule;
       
-      // 重建 documentPath（使用 fileName 而非 feature.id，避免文件名过长）
+      // Rebuild documentPath (use fileName instead of feature.id to avoid long filenames)
       if (platformId) {
         feature.documentPath = `speccrew-workspace/knowledges/bizs/${platformId}/${newModule}/${feature.fileName}.md`;
       }
     }
   });
   
-  // 5. 更新 modules 数组
+  // 5. Update modules array
   const modulesAfter = [...new Set(featuresData.features.map(f => f.module))].sort();
   featuresData.modules = modulesAfter;
   
-  // 6. 写回文件
+  // 6. Write back to file
   fs.writeFileSync(featuresFile, JSON.stringify(featuresData, null, 2), 'utf8');
   
-  // 7. 输出结果
+  // 7. Output results
   const result = {
     status: 'success',
     modules_before: modulesBefore,

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

@@ -59,20 +59,22 @@ Stage 1: Platform Detection
   └─ Read techs-manifest.json → Identify platforms & tech stacks
         ↓
 Stage 2: Tech Doc Generation (PARALLEL)
-  └─ Dispatch techs-generate workers per platform
-  └─ After each generate worker completes → dispatch quality check worker
+  └─ Prepare task plans for techs-generate workers per platform
+  └─ After generate workers complete → prepare quality check worker task plans
   └─ Monitor completion markers
         ↓
 Stage 2.5: Completion Verification
   └─ Step A: Scan completion markers
   └─ Step B: Verify output integrity
-  └─ Step C: Update dispatch progress
+  └─ Step C: Update progress status
         ↓
 Stage 3: Root Index Generation
   └─ Generate techs/README.md root index
   └─ Cross-platform consistency check
 ```
 
+> **NOTE**: All worker dispatch operations are handled by the calling Agent (Team Leader). This Skill only prepares task plans and monitors completion markers.
+
 ## Workflow Overview
 
 ```mermaid
@@ -90,10 +92,14 @@ flowchart TB
 **Step 1a: Read Configuration**
 - Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized platform mapping rules
 
-**Step 1b: Invoke Worker**
-- Invoke 1 Worker Agent (`speccrew-task-worker.md`) with skill `speccrew-knowledge-techs-init/SKILL.md`
-- Task: Analyze project structure, detect technology platforms
-- Parameters to pass to skill:
+**Step 1b: Prepare Task Plan**
+
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
+
+Prepare the following task for the calling Agent to dispatch:
+- **Skill**: `speccrew-knowledge-techs-init/SKILL.md`
+- **Task**: Analyze project structure, detect technology platforms
+- **Parameters**:
   - `source_path`: Source code directory path
   - `output_path`: Output directory (default: `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/`)
   - `language`: User's language — **REQUIRED**
@@ -108,11 +114,13 @@ See [Platform Status Tracking Fields](#platform-status-tracking-fields) for stat
 ---
 
 > **⚠️ MANDATORY RULES FOR PARALLEL EXECUTION (Stage 2)**:
-> 1. ALL platform workers MUST be dispatched in PARALLEL — sequential execution is FORBIDDEN
+> 1. ALL platform task plans should be prepared for parallel dispatch by the calling Agent — sequential execution is NOT recommended
 > 2. Each platform worker runs independently via techs-generate Skill
 > 3. Monitor completion via marker files in each platform directory
 > 4. Failed workers can be retried independently
 > 5. Do NOT proceed to Stage 2.5 until ALL workers have completed or failed
+>
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares task plans.
 
 ## Stage 2: Generate Platform Documents (Parallel)
 
@@ -120,21 +128,27 @@ See [Platform Status Tracking Fields](#platform-status-tracking-fields) for stat
 
 **Action**:
 - Read `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/techs-manifest.json`
-- For each platform in `platforms` array, invoke 2 Worker Agents in PARALLEL:
-  - Worker 1: `speccrew-knowledge-techs-generate-conventions/SKILL.md` (ALL platforms)
-  - Worker 2: `speccrew-knowledge-techs-generate-ui-style/SKILL.md` (frontend platforms ONLY: web, mobile, desktop)
-- Parameters to pass to each skill:
-  - `platform_id`: Platform identifier from manifest
-  - `platform_type`: Platform type (web, mobile, backend, desktop)
-  - `framework`: Primary framework
-  - `source_path`: Platform source directory
-  - `config_files`: List of configuration file paths (conventions worker only)
-  - `convention_files`: List of convention file paths (conventions worker only)
-  - `output_path`: Output directory for platform docs (e.g., `speccrew-workspace/knowledges/techs/{platform_id}/`)
-  - `completed_dir`: Directory for Worker output markers (e.g., `speccrew-workspace/knowledges/techs/.sync-status/`)
-  - `language`: User's language — **REQUIRED**
 
-When launching each platform Worker, the Workers will output:
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
+
+**Prepare Task Plans for Each Platform**:
+
+For each platform in `platforms` array, prepare tasks for parallel execution:
+- **Task 1**: `speccrew-knowledge-techs-generate-conventions/SKILL.md` (ALL platforms)
+- **Task 2**: `speccrew-knowledge-techs-generate-ui-style/SKILL.md` (frontend platforms ONLY: web, mobile, desktop)
+
+**Parameters for each skill**:
+- `platform_id`: Platform identifier from manifest
+- `platform_type`: Platform type (web, mobile, backend, desktop)
+- `framework`: Primary framework
+- `source_path`: Platform source directory
+- `config_files`: List of configuration file paths (conventions worker only)
+- `convention_files`: List of convention file paths (conventions worker only)
+- `output_path`: Output directory for platform docs (e.g., `speccrew-workspace/knowledges/techs/{platform_id}/`)
+- `completed_dir`: Directory for Worker output markers (e.g., `speccrew-workspace/knowledges/techs/.sync-status/`)
+- `language`: User's language — **REQUIRED**
+
+**Expected Worker Output Markers**:
 - `{completed_dir}/{platform_id}.done-conventions.json` — conventions worker completion marker
 - `{completed_dir}/{platform_id}.done-ui-style.json` — ui-style worker completion marker (frontend only)
 - `{completed_dir}/{platform_id}.analysis-conventions.json` — conventions coverage report
@@ -150,9 +164,11 @@ When launching each platform Worker, the Workers will output:
    - IF platform.platform_type IN ["web", "mobile", "desktop"]: SET `platform.workers.ui_style.status = "processing"`
    - WRITE manifest to techs-manifest.json
 
-**Step 2b: Launch Conventions Worker (ALL Platforms)**
+**Step 2b: Prepare Conventions Worker Task Plans (ALL Platforms)**
+
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
 
-For each platform, invoke `speccrew-task-worker` with:
+For each platform, prepare a task with:
 - skill_path: `speccrew-knowledge-techs-generate-conventions/SKILL.md`
 - context:
   - platform_id: platform.platform_id
@@ -165,10 +181,12 @@ For each platform, invoke `speccrew-task-worker` with:
   - completed_dir: completed_dir
   - language: language
 
-**Step 2c: Launch UI-Style Worker (Frontend Platforms ONLY)**
+**Step 2c: Prepare UI-Style Worker Task Plans (Frontend Platforms ONLY)**
+
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
 
 IF platform.platform_type IN ["web", "mobile", "desktop"]:
-1. Invoke `speccrew-task-worker` with:
+1. Prepare a task with:
    - skill_path: `speccrew-knowledge-techs-generate-ui-style/SKILL.md`
    - context:
      - platform_id: platform.platform_id
@@ -179,13 +197,20 @@ IF platform.platform_type IN ["web", "mobile", "desktop"]:
      - completed_dir: completed_dir
      - language: language
 
-**Step 2d: Wait for All Workers**
-- WAIT_ALL workers complete
+**Step 2d: Completion Marker Monitoring**
+
+> **NOTE**: Worker dispatch and wait operations are handled by the calling Agent (Team Leader). This Skill only monitors completion markers.
+
+The calling Agent should:
+- Monitor for `{platform_id}.done-conventions.json` markers
+- Monitor for `{platform_id}.done-ui-style.json` markers (frontend platforms)
 - Both workers run in PARALLEL for the same platform
 
-**Step 2e: Launch Quality Check Workers — PARALLEL per Completed Generate Worker**
+**Step 2e: Prepare Quality Check Worker Task Plans**
+
+> **NOTE**: Quality worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
 
-After each `speccrew-knowledge-techs-generate` worker completes (writes `.done-conventions.json` marker), immediately dispatch the corresponding quality check worker:
+After each `speccrew-knowledge-techs-generate` worker completes (writes `.done-conventions.json` or `.done-ui-style.json` marker), the calling Agent should dispatch the corresponding quality check worker.
 
 | Generate Worker | Quality Worker | Input |
 |-----------------|----------------|-------|
@@ -206,12 +231,25 @@ After each `speccrew-knowledge-techs-generate` worker completes (writes `.done-c
 }
 ```
 
-**Execution sequence**:
-1. Scan `completed_dir` for new `.done-conventions.json` and `.done-ui-style.json` files
-2. For each completed generate worker, prepare corresponding quality worker task
-3. Launch ALL quality workers for the current batch in PARALLEL
-4. Wait for ALL quality workers to complete
-5. Each quality worker writes `.quality-done.json` marker to `completed_dir`
+**Quality Worker Completion Marker**:
+
+Each quality worker writes a `.quality-done.json` marker to `completed_dir` upon completion:
+
+```json
+{
+  "platform_id": "web-vue",
+  "worker_type": "quality",
+  "status": "completed",
+  "quality_score": 85,
+  "issues_found": 2,
+  "completed_at": "2024-01-15T11:00:00Z"
+}
+```
+
+**Expected Completion Markers after Stage 2**:
+1. `{platform_id}.done-conventions.json` — conventions worker marker
+2. `{platform_id}.done-ui-style.json` — ui-style worker marker (frontend only)
+3. `{platform_id}.quality-done.json` — quality worker marker
 
 > **Stage 2 Completion Condition**: ALL generate workers AND ALL quality check workers completed (`.done-*.json` and `.quality-done.json` markers present) before proceeding to Stage 2.5
 
@@ -585,8 +623,12 @@ Write to `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/stage2-s
 
 **Action**:
 - Read `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/techs-manifest.json`
-- Invoke 1 Worker Agent (`speccrew-task-worker.md`) with skill `speccrew-knowledge-techs-index/SKILL.md`
-- Parameters to pass to skill:
+
+> **NOTE**: Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.
+
+**Prepare Task Plan**:
+- **Skill**: `speccrew-knowledge-techs-index/SKILL.md`
+- **Parameters**:
   - `manifest_path`: Path to techs-manifest.json
   - `techs_base_path`: Base path for techs documentation (e.g., `speccrew-workspace/knowledges/techs/`)
   - `output_path`: Output path for root INDEX.md (e.g., `speccrew-workspace/knowledges/techs/`)
@@ -638,17 +680,19 @@ THRESHOLD: warnings > 5 → flag for manual review
 
 ## Execution Flow
 
+> **NOTE**: All worker dispatch and wait operations are handled by the calling Agent (Team Leader). This Skill only prepares task plans and monitors completion markers.
+
 ```
 1. Run Stage 1 (Platform Detection)
-   └─ Wait for completion
+   └─ Prepare task plan → Monitor completion
 
 2. Run Stage 2 (Tech Doc Generation)
    ├─ Read techs-manifest.json
-   ├─ Launch ALL platform Workers in parallel
-   └─ Wait for ALL Workers → generate stage2-status.json
+   ├─ Prepare ALL platform task plans for parallel dispatch
+   └─ Monitor completion markers → generate stage2-status.json
 
 3. Run Stage 3 (Root Index)
-   └─ Wait for completion → generate stage3-status.json
+   └─ Prepare task plan → Monitor completion → generate stage3-status.json
 ```
 
 ---