speccrew 0.6.11 → 0.6.13

package/.speccrew/skills/speccrew-pm-module-initializer/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: speccrew-pm-module-initializer
-description: Initialize knowledge base for a single business module by analyzing its features. Dispatches api-analyze or ui-analyze based on platform type, then generates module summary. Used by Worker Agent, invoked by PM Agent for on-demand module initialization.
+description: Generate analyze task plan for a single business module. Reads features-*.json, filters matched module's pending features, and outputs a task plan JSON (list of features to analyze with analyzer parameters). Used by Worker Agent, invoked by PM Agent for on-demand module task planning.
 tools: Read, Write, Skill, Bash
 ---
 
-# Module Initializer
+# Module Initializer (Task Plan Generator)
 
-Initialize knowledge base for a single business module by analyzing its features. Dispatches api-analyze or ui-analyze based on platform type, then generates module summary. Used by Worker Agent, invoked by PM Agent for on-demand module initialization.
+Generate analyze task plan for a single business module. Reads features-*.json, filters matched module's pending features, and outputs a task plan JSON (list of features to analyze with analyzer parameters). Used by Worker Agent, invoked by PM Agent for on-demand module task planning.
+
+> **Positioning**: Task plan generator for PM phase. Generates task list for PM Agent to orchestrate. Does NOT execute analyze or summarize directly — PM Agent handles Worker dispatch based on task plan output.
 
 ## Language Adaptation
 
 **CRITICAL**: Generate all content in the language specified by the `language` parameter.
 
-- `language: "zh"` → Generate all content in 中文
+- `language: "zh"` → Generate all content in Chinese
 - `language: "en"` → Generate all content in English
 - Other languages → Use the specified language
 
@@ -20,47 +22,66 @@ Initialize knowledge base for a single business module by analyzing its features
 
 ## Trigger Scenarios
 
-- "Initialize module {name}"
-- "Deep analyze module {name}"
-- "Generate knowledge for module {name}"
-- "Start module analysis"
+- "Generate task plan for module {name}"
+- "Plan module {name} initialization"
+- "List pending features for module {name}"
 
 ## Input
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `source_path` | string | Yes | 项目源码根路径 |
-| `module_name` | string | Yes | 模块名称 |
-| `platform_id` | string | Yes | 平台 ID (e.g., "web-vue3", "admin-api") |
+| `source_path` | string | Yes | Project source code root path |
+| `module_name` | string | Yes | Module name |
+| `platform_id` | string | Yes | Platform ID (e.g., "web-vue", "admin-api") |
 | `platform_type` | string | Yes | web / mobile / backend / desktop |
 | `platform_subtype` | string | No | Platform subtype (e.g., "vue", "spring-boot") |
 | `tech_stack` | array | No | Platform tech stack (e.g., ["java", "spring-boot"]) |
-| `features_file` | string | Yes | 该平台的 features-{platform}.json 路径 |
-| `output_path` | string | Yes | 知识库输出根路径 (e.g., speccrew-workspace/knowledges) |
-| `language` | string | Yes | 输出语言 (zh / en) |
+| `features_file` | string | Yes | Path to the platform's features-{platform}.json file |
+| `output_path` | string | Yes | Knowledge base output root path (e.g., speccrew-workspace/knowledges) |
+| `completed_dir` | string | Yes | Marker file output directory for api-analyze .done.json markers. Value from PM Agent: `{sync_state_bizs_dir}/completed` |
+| `sourceFile` | string | Yes | Features JSON filename (e.g., "features-backend-system.json"), used for api-analyze marking |
+| `language` | string | Yes | Output language (zh / en) |
+| `workspace_path` | string | Yes | Workspace root path for constructing absolute paths |
 
 ## Output JSON
 
 ```json
 {
-  "status": "success | partial | failed",
   "module_name": "system",
-  "platform_id": "web-vue3",
-  "features_analyzed": 12,
-  "features_failed": 0,
-  "output_dir": "speccrew-workspace/knowledges/bizs/web-vue3/system/",
-  "overview_file": "system-overview.md",
-  "errors": []
+  "platform_id": "web-vue",
+  "analyzer_skill": "speccrew-knowledge-bizs-ui-analyze",
+  "tasks": [
+    {
+      "fileName": "index",
+      "sourcePath": "src/views/system/user/index.vue",
+      "documentPath": "knowledges/bizs/web-vue/system/features",
+      "module": "system",
+      "platform_type": "web",
+      "platform_subtype": "vue",
+      "tech_stack": ["vue", "typescript"],
+      "language": "zh"
+    }
+  ],
+  "total_pending": 90,
+  "summarize_params": {
+    "skill": "speccrew-knowledge-module-summarize",
+    "module_name": "system",
+    "module_path": "knowledges/bizs/web-vue/system",
+    "language": "zh"
+  }
 }
 ```
 
-**Status Definitions**:
+**Field Definitions**:
 
-| Status | Condition |
-|--------|-----------|
-| `success` | All features analyzed successfully, overview generated |
-| `partial` | Some features analyzed or overview generated with warnings |
-| `failed` | No features analyzed or critical error occurred |
+| Field | Description |
+|-------|-------------|
+| `module_name` | Module being processed |
+| `platform_id` | Platform identifier |
+| `analyzer_skill` | Selected analyzer skill name |
+| `tasks` | Array of pending features to analyze |
+| `total_pending` | Count of pending features |
+| `summarize_params` | Parameters for module-summarize skill (to be executed after all analyze tasks complete) |
 
 ## Workflow
 
@@ -68,9 +89,9 @@ Initialize knowledge base for a single business module by analyzing its features
 flowchart TD
     Start([Start]) --> Step1[Step 1: Read and filter features]
     Step1 --> Step2[Step 2: Select analyzer by platform_type]
-    Step2 --> Step3[Step 3: Analyze each pending feature]
-    Step3 --> Step4[Step 4: Generate module summary]
-    Step4 --> Step5[Step 5: Return result]
+    Step2 --> Step3[Step 3: Build task list]
+    Step3 --> Step4[Step 4: Build summarize params]
+    Step4 --> Step5[Step 5: Output task plan JSON]
     Step5 --> End([End])
 ```
 
@@ -83,7 +104,6 @@ flowchart TD
 3. **Record counts**:
    - Total features for this module
    - Pending features (analyzed = false)
-   - If no pending features found, skip to Step 4 (still generate/update module summary)
 
 **Output**: "Step 1 Status: ✅ COMPLETED - Found {total} total features, {pending} pending for analysis"
 
@@ -100,82 +120,74 @@ Based on `platform_type`, select the appropriate analyzer Skill:
 
 **Output**: "Step 2 Status: ✅ COMPLETED - Selected analyzer: {skill_name}"
 
-### Step 3: Analyze Each Pending Feature
+### Step 3: Build Task List
 
 **Step 3 Status: 🔄 IN PROGRESS**
 
-For each pending feature, invoke the selected analyzer Skill.
-
-**Important**: Process features sequentially (not parallel) since this Skill runs inside a single Worker Agent. The PM Agent handles parallelism at the module level (multiple Workers for different modules).
-
-#### Input Variables Preparation
+For each pending feature from Step 1, build a task object with analyzer parameters.
 
-Prepare input variables matching the analyzer Skill's Input Variables format:
+> 🛑 **IMPORTANT**: This Skill does NOT execute analyze. It ONLY generates the task list. PM Agent will dispatch Workers based on this task plan.
 
-| Variable | Value Source |
-|----------|--------------|
-| `feature` | The complete feature object from features.json |
-| `fileName` | feature's fileName field |
-| `sourcePath` | feature's sourcePath field |
-| `documentPath` | Computed as `{output_path}/bizs/{platform_id}/{module_name}/{fileName}.md` |
-| `module` | module_name |
-| `analyzed` | false |
-| `platform_type` | From input |
-| `platform_subtype` | From input (if available) |
-| `tech_stack` | From input (if available) |
-| `language` | From input |
-| `completed_dir` | `{output_path}/base/sync-state/knowledge-bizs/completed/` |
-| `sourceFile` | Features JSON filename (e.g., "features-web-vue3.json") |
+#### Task object structure for each pending feature:
 
-#### Execution for Each Feature
+```json
+{
+  "fileName": "{feature.fileName}",
+  "sourcePath": "{feature.sourcePath}",
+  "documentPath": "{output_path}/bizs/{platform_id}/{feature.module}/features",
+  "module": "{feature.module}",
+  "platform_type": "{platform_type}",
+  "platform_subtype": "{platform_subtype}",
+  "tech_stack": "{tech_stack}",
+  "language": "{language}"
+}
+```
 
-1. Invoke the selected analyzer Skill with prepared parameters
-2. Track success/failure count
-3. On success, update the feature's `analyzed` field to `true` in features_file
+For backend features (api-analyze), also include:
+```json
+{
+  "completed_dir": "{completed_dir}",
+  "sourceFile": "{sourceFile}"
+}
+```
 
-**Output**: "Step 3 Status: ✅ COMPLETED - Analyzed {success} features, {failed} failed"
+**Output**: "Step 3 Status: ✅ COMPLETED - Built {count} task entries"
 
-### Step 4: Generate Module Summary
+### Step 4: Build Summarize Parameters
 
 **Step 4 Status: 🔄 IN PROGRESS**
 
-Invoke `speccrew-knowledge-module-summarize` Skill to generate/update the module overview document.
-
-**Input Parameters**:
+Build the summarize_params object for module-summarize skill. This will be used by PM Agent after all analyze tasks complete.
 
-| Variable | Value |
-|----------|-------|
-| `module_name` | module_name |
-| `module_path` | `{output_path}/bizs/{platform_id}/{module_name}/` |
-| `language` | From input |
+```json
+{
+  "skill": "speccrew-knowledge-module-summarize",
+  "module_name": "{module_name}",
+  "module_path": "{output_path}/bizs/{platform_id}/{module_name}",
+  "language": "{language}"
+}
+```
 
-**Output**: "Step 4 Status: ✅ COMPLETED - Module overview generated at {module_path}/{module_name}-overview.md"
+**Output**: "Step 4 Status: ✅ COMPLETED - Summarize params ready"
 
-### Step 5: Return Result
+### Step 5: Output Task Plan JSON
 
 **Step 5 Status: 🔄 IN PROGRESS**
 
-Compile and return the final result:
+Compile and output the final task plan:
 
 ```json
 {
-  "status": "success | partial | failed",
   "module_name": "...",
   "platform_id": "...",
-  "features_analyzed": <count>,
-  "features_failed": <count>,
-  "output_dir": "...",
-  "overview_file": "...",
-  "errors": [...]
+  "analyzer_skill": "...",
+  "tasks": [...],
+  "total_pending": <count>,
+  "summarize_params": {...}
 }
 ```
 
-**Status determination**:
-- `success`: All features analyzed successfully, overview generated
-- `partial`: Some features failed but overview generated, or no pending features but overview updated
-- `failed`: All features failed or critical error prevented overview generation
-
-**Output**: "Step 5 Status: ✅ COMPLETED - Module initialization {status}"
+**Output**: "Step 5 Status: ✅ COMPLETED - Task plan generated with {count} pending features"
 
 ## Constraints
 
@@ -187,21 +199,21 @@ Compile and return the final result:
 
 3. **Worker context**: This Skill runs in Worker Agent context, invoked by PM Agent
 
-4. **Sequential execution**: Process features sequentially within this Worker (PM Agent handles module-level parallelism)
+4. **NO execution**: This Skill generates task plan ONLY. It does NOT:
+   - Execute analyzer skills
+   - Execute summarize skills
+   - Update features.json analyzed field
+   - All execution is handled by PM Agent based on task plan output
 
-5. **No sync-state modification**: Do not directly create or modify sync-state directory files (that's dispatch's responsibility), but can update features.json analyzed markers
-
-6. **Mutual exclusion with full dispatch**: Do not run simultaneously with full dispatch process
+5. **Mutual exclusion with full dispatch**: Do not run simultaneously with full dispatch process
 
 ## Error Handling
 
 | Scenario | Action |
 |----------|--------|
-| Features file not found | Return `status: failed` with error message |
-| No features for module | Skip to Step 4, generate overview if possible |
-| No pending features | Skip to Step 4, update existing overview |
-| Analyzer fails for feature | Record in errors array, continue with next feature |
-| Module summarize fails | Return `status: partial` with error details |
+| Features file not found | Return error with message |
+| No features for module | Return empty tasks array with summarize_params |
+| No pending features | Return empty tasks array with summarize_params |
 
 ## Reference: Analyzer Input Parameters
 
@@ -209,10 +221,9 @@ Compile and return the final result:
 
 | Variable | Type | Description | Example |
 |----------|------|-------------|---------|
-| `feature` | object | Complete feature object from features.json | - |
 | `fileName` | string | Controller file name | `"UserController"` |
 | `sourcePath` | string | Relative path to source file | `"src/.../UserController.java"` |
-| `documentPath` | string | Target path for generated document | `"knowledges/bizs/.../UserController.md"` |
+| `documentPath` | string | Target path for generated document | `"knowledges/bizs/.../features"` |
 | `module` | string | Business module name | `"system"` |
 | `analyzed` | boolean | Analysis status flag | `false` |
 | `platform_type` | string | Platform type | `"backend"` |
@@ -226,18 +237,15 @@ Compile and return the final result:
 
 | Variable | Type | Description | Example |
 |----------|------|-------------|---------|
-| `feature` | object | Complete feature object from features.json | - |
 | `fileName` | string | Feature file name | `"index"` |
 | `sourcePath` | string | Relative path to source file | `"src/views/system/user/index.vue"` |
-| `documentPath` | string | Target path for generated document | `"knowledges/bizs/.../index.md"` |
+| `documentPath` | string | Target path for generated document | `"knowledges/bizs/.../features"` |
 | `module` | string | Business module name | `"system"` |
 | `analyzed` | boolean | Analysis status flag | `false` |
 | `platform_type` | string | Platform type | `"web"` |
 | `platform_subtype` | string | Platform subtype | `"vue"` |
 | `tech_stack` | array | Platform tech stack | `["vue", "typescript"]` |
 | `language` | string | Target language | `"zh"` |
-| `completed_dir` | string | Marker output directory (absolute path) | `".../knowledges/base/sync-state/completed"` |
-| `sourceFile` | string | Source features JSON filename | `"features-web-vue3.json"` |
 
 ## Task Completion Report
 
@@ -245,25 +253,16 @@ When the task is complete, report:
 
 ```json
 {
-  "status": "success | failed",
+  "status": "success",
   "skill": "speccrew-pm-module-initializer",
   "output": {
-    "status": "success | partial | failed",
     "module_name": "...",
     "platform_id": "...",
-    "features_analyzed": 12,
-    "features_failed": 0,
-    "output_dir": "...",
-    "overview_file": "...",
-    "errors": []
-  },
-  "metrics": {
-    "features_total": 15,
-    "features_analyzed": 12,
-    "features_skipped": 3,
-    "features_failed": 0
-  },
-  "errors": []
+    "analyzer_skill": "...",
+    "tasks": [...],
+    "total_pending": <count>,
+    "summarize_params": {...}
+  }
 }
 ```
 
@@ -271,6 +270,6 @@ When the task is complete, report:
 
 - [ ] Step 1: Read features file and filtered by module
 - [ ] Step 2: Selected analyzer type based on platform_type
-- [ ] Step 3: Analyzed each pending feature sequentially
-- [ ] Step 4: Generated module summary via module-summarize
-- [ ] Step 5: Returned aggregated result with correct status
+- [ ] Step 3: Built task list with analyzer parameters
+- [ ] Step 4: Built summarize parameters
+- [ ] Step 5: Output task plan JSON

package/lib/commands/doctor.js

@@ -8,7 +8,7 @@ function run(projectRoot, args) {
 
   const results = [];
 
-  // 1. Node.js 版本检查
+  // 1. Node.js version check
   const nodeVersion = process.version;
   const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
   if (majorVersion >= 16) {
@@ -17,7 +17,7 @@ function run(projectRoot, args) {
     results.push({ status: 'FAIL', message: `Node.js ${nodeVersion} (< 16.0.0)` });
   }
 
-  // 2. SpecCrew 安装状态
+  // 2. SpecCrew installation status
   const rc = readSpeccrewRC(projectRoot);
   const version = getPackageVersion();
   if (rc) {
@@ -26,7 +26,7 @@ function run(projectRoot, args) {
     results.push({ status: 'WARN', message: 'Not initialized, run speccrew init' });
   }
 
-  // 3. IDE 目录检查
+  // 3. IDE directory check
   const detectedIDEs = detectIDE(projectRoot);
   if (detectedIDEs.length > 0) {
     const ideNames = detectedIDEs.map(ide => `${ide.name} (${ide.baseDir}/)`).join(', ');
@@ -35,7 +35,7 @@ function run(projectRoot, args) {
     results.push({ status: 'WARN', message: 'No supported IDE detected' });
   }
 
-  // 4. Agents 完整性检查
+  // 4. Agents integrity check
   const sourceRoot = getSourceRoot();
   const sourceAgentsDir = path.join(sourceRoot, 'agents');
   let sourceAgentCount = 0;
@@ -70,7 +70,7 @@ function run(projectRoot, args) {
     results.push({ status: 'WARN', message: 'Agents: source not found' });
   }
 
-  // 5. Skills 完整性检查
+  // 5. Skills integrity check
   const sourceSkillsDir = path.join(sourceRoot, 'skills');
   let sourceSkillCount = 0;
   let installedSkillCount = 0;
@@ -103,7 +103,7 @@ function run(projectRoot, args) {
     results.push({ status: 'WARN', message: 'Skills: source not found' });
   }
 
-  // 6. Workspace 目录检查
+  // 6. Workspace directory check
   const workspaceDir = path.join(projectRoot, 'speccrew-workspace');
   const docsDir = path.join(workspaceDir, 'docs');
   if (fs.existsSync(workspaceDir) && fs.existsSync(docsDir)) {
@@ -114,7 +114,7 @@ function run(projectRoot, args) {
     results.push({ status: 'WARN', message: 'Workspace: speccrew-workspace/ not found' });
   }
 
-  // 输出结果
+  // Output results
   let passCount = 0;
   let warnCount = 0;
   let failCount = 0;