speccrew 0.6.68 → 0.7.0

package/.speccrew/skills/speccrew-pm-module-initializer/workflow.agentflow.xml

@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="module-initializer-main" status="pending" version="1.0" desc="Generate analyze task plan for a single business module">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="source_path" required="true" type="string" desc="Project source code root path"/>
+    <field name="module_name" required="true" type="string" desc="Module name"/>
+    <field name="platform_id" required="true" type="string" desc="Platform ID (e.g., web-vue, admin-api)"/>
+    <field name="platform_type" required="true" type="string" desc="web / mobile / backend / desktop"/>
+    <field name="platform_subtype" required="false" type="string" desc="Platform subtype (e.g., vue, spring-boot)"/>
+    <field name="tech_stack" required="false" type="array" desc="Platform tech stack (e.g., [java, spring-boot])"/>
+    <field name="features_file" required="true" type="string" desc="Path to the platform's features-{platform}.json file"/>
+    <field name="output_path" required="true" type="string" desc="Knowledge base output root path"/>
+    <field name="completed_dir" required="true" type="string" desc="Marker file output directory for api-analyze .done.json markers"/>
+    <field name="sourceFile" required="true" type="string" desc="Features JSON filename (e.g., features-backend-system.json)"/>
+    <field name="language" required="true" type="string" desc="Output language (zh / en)"/>
+    <field name="workspace_path" required="true" type="string" desc="Workspace root path for constructing absolute paths"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="mandatory" desc="Path constraints">
+    <field name="text">Use the provided absolute paths directly. DO NOT construct or derive paths yourself.</field>
+    <field name="text">All paths must use forward slashes / as path separators (even on Windows)</field>
+  </block>
+
+  <block type="rule" id="R2" level="forbidden" desc="Execution constraints">
+    <field name="text">This skill generates task plan ONLY - do NOT execute analyzer skills</field>
+    <field name="text">Do NOT update features.json analyzed field</field>
+    <field name="text">All execution is handled by PM Agent based on task plan output</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Task Plan Generation" status="pending" desc="Generate task plan for module initialization">
+
+    <!-- Step 1: Read and filter features -->
+    <block type="task" id="B1" action="read-file" desc="Read features file and parse JSON">
+      <field name="path" value="${features_file}"/>
+      <field name="output" var="features_data"/>
+    </block>
+
+    <!-- Gateway: Validate features file -->
+    <block type="gateway" id="G1" mode="guard" desc="Verify features file exists and is valid"
+           test="${features_data} != null"
+           fail-action="stop">
+      <field name="message">Features file not found or invalid: ${features_file}</field>
+    </block>
+
+    <!-- Step 2: Filter features by module and pending status -->
+    <block type="task" id="B2" action="analyze" desc="Filter features by module and analyzed=false">
+      <field name="input" value="${features_data}"/>
+      <field name="filter">
+        - module == ${module_name}
+        - analyzed == false
+      </field>
+      <field name="output" var="pending_features"/>
+    </block>
+
+    <!-- Step 3: Select analyzer by platform type -->
+    <block type="task" id="B3" action="analyze" desc="Select analyzer skill based on platform_type">
+      <field name="input" value="${platform_type}"/>
+      <field name="logic">
+        IF platform_type IN [web, mobile, desktop] THEN analyzer_skill = "speccrew-knowledge-bizs-ui-analyze"
+        ELSE IF platform_type == backend THEN analyzer_skill = "speccrew-knowledge-bizs-api-analyze"
+      </field>
+      <field name="output" var="analyzer_skill"/>
+    </block>
+
+    <!-- Step 4: Build task list -->
+    <block type="loop" id="L1" over="${pending_features}" as="feature" desc="Build task list for each pending feature">
+      <block type="task" id="B4" action="analyze" desc="Build task object for feature">
+        <field name="input" value="${feature}"/>
+        <field name="build_task">
+          id: "ki-${platform_id}-${feature.module}-${feature.fileName}"
+          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}
+          status: "pending"
+        </field>
+        <field name="condition">IF platform_type == backend THEN include completed_dir and sourceFile</field>
+        <field name="output" var="task_entry"/>
+      </block>
+    </block>
+
+    <!-- Step 5: Build summarize parameters -->
+    <block type="task" id="B5" action="analyze" desc="Build summarize_params object">
+      <field name="build_object">
+        skill: "speccrew-knowledge-module-summarize"
+        module_name: ${module_name}
+        module_path: ${output_path}/bizs/${platform_id}/${module_name}
+        language: ${language}
+      </field>
+      <field name="output" var="summarize_params"/>
+    </block>
+
+    <!-- Step 6: Compile task plan JSON -->
+    <block type="task" id="B6" action="analyze" desc="Compile final task plan JSON">
+      <field name="compile">
+        module_name: ${module_name}
+        platform_id: ${platform_id}
+        analyzer_skill: ${analyzer_skill}
+        tasks: ${task_entries}
+        total_pending: ${task_entries.length}
+        summarize_params: ${summarize_params}
+      </field>
+      <field name="output" var="task_plan"/>
+    </block>
+
+    <!-- Checkpoint: Verify task plan generated -->
+    <block type="checkpoint" id="CP1" name="task-plan-generated" desc="Verify task plan is valid">
+      <field name="verify" value="${task_plan.module_name} != null AND ${task_plan.tasks} != null"/>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="module_name" from="${task_plan.module_name}" type="string" desc="Module being processed"/>
+    <field name="platform_id" from="${task_plan.platform_id}" type="string" desc="Platform identifier"/>
+    <field name="analyzer_skill" from="${task_plan.analyzer_skill}" type="string" desc="Selected analyzer skill name"/>
+    <field name="tasks" from="${task_plan.tasks}" type="array" desc="Array of pending features to analyze"/>
+    <field name="total_pending" from="${task_plan.total_pending}" type="number" desc="Count of pending features"/>
+    <field name="summarize_params" from="${task_plan.summarize_params}" type="object" desc="Parameters for module-summarize skill"/>
+    <field name="task_plan" from="${task_plan}" type="object" desc="Complete task plan JSON"/>
+  </block>
+
+</workflow>

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

@@ -65,123 +65,11 @@ Match user requirement text against business knowledge base features to identify
 | `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**
+## AgentFlow Definition
 
-**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"
+<!-- @agentflow: workflow.agentflow.xml -->
 
-**Output**: "Step 4 Status: ✅ COMPLETED - Generated recommendation"
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
 
 ## Constraints
 

package/.speccrew/skills/speccrew-pm-module-matcher/workflow.agentflow.xml

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="module-matcher-main" status="pending" version="1.0" desc="Match user requirement text against business knowledge base features">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="requirement_text" required="true" type="string" desc="User requirement text to match"/>
+    <field name="features_files" required="true" type="array" desc="Array of paths to features-*.json files"/>
+    <field name="language" required="true" type="string" desc="Target language for output"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="mandatory" desc="Execution constraints">
+    <field name="text">This skill is READ-ONLY - do not modify any files</field>
+    <field name="text">Handle Chinese+English mixed text matching</field>
+    <field name="text">Skip unreadable files - continue processing others</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Module Matching" status="pending" desc="Match requirement to knowledge base modules">
+
+    <!-- Step 1: Parse requirement text -->
+    <block type="task" id="B1" action="analyze" desc="Parse requirement and extract keywords">
+      <field name="input" value="${requirement_text}"/>
+      <field name="operations">
+        - Tokenize: Split text into words/phrases
+        - Extract entities: Identify nouns, technical terms, business concepts
+        - Normalize: Convert to lowercase, handle Chinese/English mixed text
+        - Build keyword list: Create array of searchable terms
+      </field>
+      <field name="chinese_handling">
+        - Use character-level matching for Chinese terms
+        - Consider common abbreviations (e.g., "用户" matches "user")
+        - Support both simplified and traditional characters
+      </field>
+      <field name="output" var="keywords"/>
+    </block>
+
+    <!-- Step 2: Read features files and build index -->
+    <block type="loop" id="L1" over="${features_files}" as="features_file" desc="Process each features file">
+      <block type="error-handler" id="EH1" desc="Handle file read errors gracefully">
+        <try>
+          <block type="task" id="B2" action="read-file" desc="Read features file">
+            <field name="path" value="${features_file}"/>
+            <field name="output" var="file_content"/>
+          </block>
+          <block type="task" id="B3" action="analyze" desc="Extract platform and module info">
+            <field name="input" value="${file_content}"/>
+            <field name="extract">
+              - platformId
+              - platformType
+              - modules (grouped by module name)
+              - features (with fileName, sourcePath)
+            </field>
+            <field name="output" var="platform_data"/>
+          </block>
+        </try>
+        <catch>
+          <block type="event" id="E1" action="log" level="warn" desc="Log file skip">
+            <field name="message">Skipping unreadable file: ${features_file}</field>
+          </block>
+        </catch>
+      </block>
+    </block>
+
+    <!-- Step 3: Perform semantic matching -->
+    <block type="task" id="B4" action="analyze" desc="Match keywords against module-feature index">
+      <field name="input">
+        keywords: ${keywords}
+        platform_data: ${platform_data}
+      </field>
+      <field name="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
+      </field>
+      <field name="confidence_levels">
+        - high: Direct keyword match with module name or feature fileName
+        - medium: Partial match or synonym match
+        - low: Related concept match only
+      </field>
+      <field name="output" var="matched_modules"/>
+    </block>
+
+    <!-- Step 4: Sort and generate recommendation -->
+    <block type="task" id="B5" action="analyze" desc="Sort results and generate recommendation">
+      <field name="input" value="${matched_modules}"/>
+      <field name="operations">
+        - Sort matched modules by confidence (high → medium → low)
+        - Generate recommendation text based on top matches
+        - Collect unmatched keywords for user awareness
+      </field>
+      <field name="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"
+      </field>
+      <field name="output" var="final_result"/>
+    </block>
+
+    <!-- Checkpoint: Verify matching complete -->
+    <block type="checkpoint" id="CP1" name="matching-complete" desc="Verify matching completed">
+      <field name="verify" value="${final_result.matched_modules} != null"/>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="matched_modules" from="${final_result.matched_modules}" type="array" desc="List of matched modules with confidence"/>
+    <field name="unmatched_keywords" from="${final_result.unmatched_keywords}" type="array" desc="Keywords that didn't match any module"/>
+    <field name="recommendation" from="${final_result.recommendation}" type="string" desc="Suggested modules based on requirement analysis"/>
+    <field name="total_platforms_scanned" from="${final_result.total_platforms_scanned}" type="number" desc="Number of platforms scanned"/>
+    <field name="total_modules_scanned" from="${final_result.total_modules_scanned}" type="number" desc="Number of modules scanned"/>
+    <field name="message" value="Matching completed" type="string" desc="Status message"/>
+  </block>
+
+</workflow>