speccrew 0.5.16 → 0.5.18

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

@@ -1,7 +1,7 @@
 ---
 name: speccrew-system-designer
 description: SpecCrew System Designer. Reads confirmed Feature Spec and API Contract documents, loads technology knowledge base (techs), evaluates framework needs, and dispatches per-platform detailed design skills to generate system design documents that add technology-specific implementation details to the feature specification skeleton. Supports web, mobile, and desktop platforms. Trigger scenarios: after Feature Spec and API Contract are confirmed, user requests system design.
-tools: Read, Write, Glob, Grep
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Role Positioning

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

@@ -1,7 +1,7 @@
 ---
 name: speccrew-test-manager
 description: SpecCrew Test Manager. Orchestrates three-phase testing workflow: test case design, test code generation, and test execution with bug reporting. Reads feature specs, API contracts, and system design documents to coordinate comprehensive system testing. Trigger scenarios: after development phase completes, user requests to start testing.
-tools: Read, Write, Glob, Grep
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Role Positioning

package/.speccrew/skills/speccrew-pm-knowledge-detector/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: speccrew-pm-knowledge-detector
+description: Detect business knowledge base availability and completeness status. Scans sync-state directory to determine if full knowledge (system-overview.md), lite knowledge (features-*.json), or no knowledge is available.
+tools: Read, Glob
+---
+
+# Knowledge Base Detector
+
+Detect business knowledge base availability and completeness status. Scans the sync-state directory to determine the current knowledge state.
+
+## Language Adaptation
+
+**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+
+- `language: "zh"` → Generate all content in 中文
+- `language: "en"` → Generate all content in English
+- Other languages → Use the specified language
+
+**All output content must be in the target language only.**
+
+## Trigger Scenarios
+
+- "Check knowledge base status"
+- "Detect if business knowledge exists"
+- "Scan knowledge availability"
+- "What knowledge is available?"
+
+## Input
+
+| Variable | Type | Description | Required |
+|----------|------|-------------|----------|
+| `workspace_path` | string | Path to speccrew workspace (e.g., `speccrew-workspace`) | **Yes** |
+
+## Output JSON
+
+```json
+{
+  "status": "full | lite | none",
+  "has_system_overview": false,
+  "has_features": false,
+  "has_entry_dirs": false,
+  "available_platforms": ["web-vue3", "backend-spring"],
+  "module_count": 0,
+  "features_files": ["path/to/features-web-vue3.json"],
+  "entry_dirs_files": ["path/to/entry-dirs-web-vue3.json"],
+  "system_overview_path": null,
+  "message": "Knowledge base status detected"
+}
+```
+
+**Status Definitions**:
+
+| Status | Condition |
+|--------|-----------|
+| `full` | has_system_overview = true AND has_features = true |
+| `lite` | has_features = true AND has_system_overview = false |
+| `none` | has_features = false AND has_system_overview = false |
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Step1[Step 1: Check system-overview.md]
+    Step1 --> Step2[Step 2: Scan for features files]
+    Step2 --> Step3[Step 3: Scan for entry-dirs files]
+    Step3 --> Step4[Step 4: Count modules and platforms]
+    Step4 --> Step5[Step 5: Determine status and return JSON]
+    Step5 --> End([End])
+```
+
+### Step 1: Check system-overview.md
+
+Check if the system overview file exists:
+
+1. Construct path: `{workspace_path}/knowledges/bizs/system-overview.md`
+2. Attempt to read the file
+3. Set `has_system_overview` = true if exists, false otherwise
+4. Set `system_overview_path` = path if exists, null otherwise
+
+**Output**: "Step 1 Status: ✅ COMPLETED - system-overview.md {exists|not found}"
+
+### Step 2: Scan for features files
+
+Scan the sync-state directory for feature inventory files:
+
+1. Construct path: `{workspace_path}/knowledges/base/sync-state/knowledge-bizs/`
+2. Glob pattern: `features-*.json`
+3. Collect all matching files into `features_files` array
+4. Set `has_features` = true if any files found
+
+**Output**: "Step 2 Status: ✅ COMPLETED - Found {count} features files"
+
+### Step 3: Scan for entry-dirs files
+
+Scan for entry directory configuration files:
+
+1. Use same sync-state path
+2. Glob pattern: `entry-dirs-*.json`
+3. Collect all matching files into `entry_dirs_files` array
+4. Set `has_entry_dirs` = true if any files found
+
+**Output**: "Step 3 Status: ✅ COMPLETED - Found {count} entry-dirs files"
+
+### Step 4: Count modules and platforms
+
+For each features file found:
+
+1. Read the JSON content
+2. Extract `platformId` and add to `available_platforms` array
+3. Sum up `modules` array length for `module_count`
+4. Extract `features` array length for feature count per platform
+
+**Output**: "Step 4 Status: ✅ COMPLETED - {platform_count} platforms, {module_count} modules"
+
+### Step 5: Determine status and return JSON
+
+Calculate the overall status:
+
+```
+IF has_system_overview AND has_features THEN
+    status = "full"
+ELSE IF has_features THEN
+    status = "lite"
+ELSE
+    status = "none"
+END IF
+```
+
+Return the complete JSON output.
+
+**Output**: "Step 5 Status: ✅ COMPLETED - Knowledge status: {status}"
+
+## Constraints
+
+1. **READ-ONLY**: This skill does not modify any files
+2. **Fast execution**: Use Glob for scanning, avoid deep file reads
+3. **Graceful handling**: Return empty arrays if directories don't exist
+4. **Path format**: All returned paths should be relative to workspace_path
+
+## Task Completion Report
+
+When the task is complete, report:
+
+```json
+{
+  "status": "success | failed",
+  "skill": "speccrew-pm-knowledge-detector",
+  "detection_result": {
+    "status": "full | lite | none",
+    "available_platforms": [...],
+    "module_count": 0
+  },
+  "message": "Knowledge base status detected successfully"
+}
+```
+
+## Checklist
+
+- [ ] Step 1: Checked system-overview.md existence
+- [ ] Step 2: Scanned for features-*.json files
+- [ ] Step 3: Scanned for entry-dirs-*.json files
+- [ ] Step 4: Counted platforms and modules
+- [ ] Step 5: Determined overall status and returned JSON

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

@@ -0,0 +1,276 @@
+---
+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.
+tools: Read, Write, Skill, Bash
+---
+
+# Module Initializer
+
+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.
+
+## Language Adaptation
+
+**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+
+- `language: "zh"` → Generate all content in 中文
+- `language: "en"` → Generate all content in English
+- Other languages → Use the specified language
+
+**All output content must be in the target language only.**
+
+## Trigger Scenarios
+
+- "Initialize module {name}"
+- "Deep analyze module {name}"
+- "Generate knowledge for module {name}"
+- "Start module analysis"
+
+## Input
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source_path` | string | Yes | 项目源码根路径 |
+| `module_name` | string | Yes | 模块名称 |
+| `platform_id` | string | Yes | 平台 ID (e.g., "web-vue3", "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) |
+
+## 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": []
+}
+```
+
+**Status 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 |
+
+## Workflow
+
+```mermaid
+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]
+    Step5 --> End([End])
+```
+
+### Step 1: Read and Filter Features
+
+**Step 1 Status: 🔄 IN PROGRESS**
+
+1. **Read features file**: Parse the `features_file` JSON
+2. **Filter by module**: Select features where `module == module_name` AND `analyzed == false`
+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"
+
+### Step 2: Select Analyzer by Platform Type
+
+**Step 2 Status: 🔄 IN PROGRESS**
+
+Based on `platform_type`, select the appropriate analyzer Skill:
+
+| platform_type | skill_name | Description |
+|---------------|------------|-------------|
+| web, mobile, desktop | `speccrew-knowledge-bizs-ui-analyze` | UI Feature Analysis |
+| backend | `speccrew-knowledge-bizs-api-analyze` | API Controller Analysis |
+
+**Output**: "Step 2 Status: ✅ COMPLETED - Selected analyzer: {skill_name}"
+
+### Step 3: Analyze Each Pending Feature
+
+**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
+
+Prepare input variables matching the analyzer Skill's Input Variables format:
+
+| 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") |
+
+#### Execution for Each Feature
+
+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
+
+**Output**: "Step 3 Status: ✅ COMPLETED - Analyzed {success} features, {failed} failed"
+
+### Step 4: Generate Module Summary
+
+**Step 4 Status: 🔄 IN PROGRESS**
+
+Invoke `speccrew-knowledge-module-summarize` Skill to generate/update the module overview document.
+
+**Input Parameters**:
+
+| Variable | Value |
+|----------|-------|
+| `module_name` | module_name |
+| `module_path` | `{output_path}/bizs/{platform_id}/{module_name}/` |
+| `language` | From input |
+
+**Output**: "Step 4 Status: ✅ COMPLETED - Module overview generated at {module_path}/{module_name}-overview.md"
+
+### Step 5: Return Result
+
+**Step 5 Status: 🔄 IN PROGRESS**
+
+Compile and return the final result:
+
+```json
+{
+  "status": "success | partial | failed",
+  "module_name": "...",
+  "platform_id": "...",
+  "features_analyzed": <count>,
+  "features_failed": <count>,
+  "output_dir": "...",
+  "overview_file": "...",
+  "errors": [...]
+}
+```
+
+**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}"
+
+## Constraints
+
+1. **Output path format**: Must match bizs-dispatch format: `{output_path}/bizs/{platform_id}/{module_name}/`
+
+2. **Use same analyzers as dispatch**: 
+   - Backend → `speccrew-knowledge-bizs-api-analyze`
+   - Web/Mobile/Desktop → `speccrew-knowledge-bizs-ui-analyze`
+
+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)
+
+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
+
+## 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 |
+
+## Reference: Analyzer Input Parameters
+
+### API Analyzer (speccrew-knowledge-bizs-api-analyze)
+
+| 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"` |
+| `module` | string | Business module name | `"system"` |
+| `analyzed` | boolean | Analysis status flag | `false` |
+| `platform_type` | string | Platform type | `"backend"` |
+| `platform_subtype` | string | Platform subtype | `"spring-boot"` |
+| `tech_stack` | array | Platform tech stack | `["java", "spring-boot"]` |
+| `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-admin-api.json"` |
+
+### UI Analyzer (speccrew-knowledge-bizs-ui-analyze)
+
+| 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"` |
+| `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
+
+When the task is complete, report:
+
+```json
+{
+  "status": "success | failed",
+  "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": []
+}
+```
+
+## Checklist
+
+- [ ] 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

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

@@ -0,0 +1,226 @@
+---
+name: speccrew-pm-module-matcher
+description: Match user requirement text against business knowledge base features to identify related modules. Reads features-*.json and performs semantic matching.
+tools: Read
+---
+
+# Module Matcher
+
+Match user requirement text against business knowledge base features to identify related modules. Performs semantic matching based on keywords, module names, and feature definitions.
+
+## Language Adaptation
+
+**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+
+- `language: "zh"` → Generate all content in 中文
+- `language: "en"` → Generate all content in English
+- Other languages → Use the specified language
+
+**All output content must be in the target language only.**
+
+## Trigger Scenarios
+
+- "Find modules for requirement X"
+- "Which modules handle user management?"
+- "Match requirement to knowledge base"
+- "Identify relevant modules"
+
+## Input
+
+| Variable | Type | Description | Required |
+|----------|------|-------------|----------|
+| `requirement_text` | string | User requirement text to match | **Yes** |
+| `features_files` | string[] | Array of paths to features-*.json files | **Yes** |
+| `language` | string | Target language for output | **Yes** |
+
+## Output JSON
+
+```json
+{
+  "matched_modules": [
+    {
+      "platform_id": "web-vue3",
+      "module_name": "system",
+      "platform_type": "web",
+      "confidence": "high | medium | low",
+      "matching_features": ["user-management", "role-management"],
+      "feature_count": 15,
+      "analyzed_count": 8,
+      "source_path": "src/views/system"
+    }
+  ],
+  "unmatched_keywords": ["workflow", "approval"],
+  "recommendation": "Suggested modules based on requirement analysis",
+  "total_platforms_scanned": 3,
+  "total_modules_scanned": 12,
+  "message": "Matching completed"
+}
+```
+
+**Confidence Levels**:
+
+| Level | Condition |
+|-------|-----------|
+| `high` | Direct keyword match with module name or feature fileName |
+| `medium` | Partial match or synonym match |
+| `low` | Related concept match only |
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Step1[Step 1: Parse requirement text]
+    Step1 --> Step2[Step 2: Read features files and build index]
+    Step2 --> Step3[Step 3: Perform semantic matching]
+    Step3 --> Step4[Step 4: Sort and generate recommendation]
+    Step4 --> End([End])
+```
+
+### Step 1: Parse Requirement Text
+
+Extract key entities and domain terms from the requirement:
+
+1. **Tokenize**: Split text into words/phrases
+2. **Extract entities**: Identify nouns, technical terms, business concepts
+3. **Normalize**: Convert to lowercase, handle Chinese/English mixed text
+4. **Build keyword list**: Create array of searchable terms
+
+**Chinese Text Handling**:
+- Use character-level matching for Chinese terms
+- Consider common abbreviations (e.g., "用户" matches "user")
+- Support both simplified and traditional characters
+
+**Output**: "Step 1 Status: ✅ COMPLETED - Extracted {keyword_count} keywords"
+
+### Step 2: Read Features Files and Build Index
+
+For each features file in the input array:
+
+1. **Read JSON**: Parse the features-*.json file
+2. **Extract platform info**: `platformId`, `platformType`
+3. **Build module index**: Group features by `module`
+4. **Build feature index**: Create lookup by `fileName`, `sourcePath`
+
+**Index Structure**:
+```
+{
+  "platform_id": {
+    "modules": {
+      "module_name": {
+        "features": [...],
+        "feature_count": N,
+        "analyzed_count": M
+      }
+    }
+  }
+}
+```
+
+**Error Handling**: Skip files that cannot be read or parsed, continue with others.
+
+**Output**: "Step 2 Status: ✅ COMPLETED - Built index from {file_count} files, {module_count} modules"
+
+### Step 3: Perform Semantic Matching
+
+Match keywords against the module-feature index:
+
+1. **Direct matching**:
+   - Keyword matches module name directly
+   - Keyword matches feature fileName
+   - Confidence = `high`
+
+2. **Partial matching**:
+   - Keyword is substring of module/feature name
+   - Module/feature name is substring of keyword
+   - Confidence = `medium`
+
+3. **Conceptual matching**:
+   - Keyword relates to known domain concepts
+   - Synonym matching (configurable)
+   - Confidence = `low`
+
+**Matching Algorithm**:
+```
+FOR each platform IN platforms:
+  FOR each module IN platform.modules:
+    score = 0
+    matching_features = []
+    
+    FOR each keyword IN keywords:
+      IF keyword matches module.name THEN
+        score += 3  // high confidence boost
+      END IF
+      
+      FOR each feature IN module.features:
+        IF keyword matches feature.fileName THEN
+          score += 1
+          matching_features.add(feature)
+        END IF
+      END FOR
+    END FOR
+    
+    IF score > 0 THEN
+      confidence = calculate_confidence(score, keyword_count)
+      matched_modules.add(module with confidence)
+    END IF
+  END FOR
+END FOR
+```
+
+**Output**: "Step 3 Status: ✅ COMPLETED - Found {match_count} matching modules"
+
+### Step 4: Sort and Generate Recommendation
+
+1. **Sort matched modules** by confidence (high → medium → low)
+2. **Generate recommendation text** based on top matches
+3. **Collect unmatched keywords** for user awareness
+4. **Return complete JSON result**
+
+**Recommendation Template**:
+- High confidence: "Module '{name}' is highly relevant for this requirement"
+- Medium confidence: "Module '{name}' may be relevant"
+- Low confidence: "Module '{name}' has partial relevance"
+
+**Output**: "Step 4 Status: ✅ COMPLETED - Generated recommendation"
+
+## Constraints
+
+1. **READ-ONLY**: This skill does not modify any files
+2. **Handle Chinese+English**: Support bilingual text matching
+3. **Skip unreadable files**: Continue processing even if some files fail
+4. **No external API**: Matching is done locally without LLM calls
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| File not found | Skip file, log warning |
+| Invalid JSON | Skip file, log error |
+| Empty features array | Continue with empty module list |
+| No keywords extracted | Return empty matches with warning |
+
+## Task Completion Report
+
+When the task is complete, report:
+
+```json
+{
+  "status": "success | partial | failed",
+  "skill": "speccrew-pm-module-matcher",
+  "matching_result": {
+    "matched_count": 3,
+    "high_confidence_count": 1,
+    "medium_confidence_count": 1,
+    "low_confidence_count": 1
+  },
+  "message": "Module matching completed"
+}
+```
+
+## Checklist
+
+- [ ] Step 1: Parsed requirement text and extracted keywords
+- [ ] Step 2: Read all features files and built index
+- [ ] Step 3: Performed semantic matching
+- [ ] Step 4: Sorted results and generated recommendation
+- [ ] Returned complete JSON output

package/package.json

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