speccrew 0.6.68 → 0.7.0

package/.speccrew/skills/speccrew-knowledge-bizs-ui-style-extract/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: speccrew-knowledge-bizs-ui-style-extract
-description: Extract and aggregate UI design patterns (page types, components, layouts) from analyzed bizs feature documents, outputting to techs ui-style-patterns directory.
+description: Extract and aggregate UI design patterns (page types, components, layouts) from analyzed bizs feature documents using XML workflow blocks, outputting to techs ui-style-patterns directory.
 tools: Read, Write
 ---
 
-# Bizs UI Style Extract
+# Bizs UI Style Extract (XML Workflow)
 
-Extract and aggregate **UI design patterns** from bizs pipeline analyzed feature documents. Through cross-module clustering analysis, identify common page types, component patterns, and layout patterns, then output them to the techs knowledge base `ui-style-patterns/` subdirectory.
+Extract and aggregate **UI design patterns** from bizs pipeline analyzed feature documents using XML workflow blocks. Through cross-module clustering analysis, identify common page types, component patterns, and layout patterns, then output them to the techs knowledge base `ui-style-patterns/` subdirectory.
 
 ## Language Adaptation
 
@@ -66,155 +66,270 @@ Extract and aggregate **UI design patterns** from bizs pipeline analyzed feature
 
 3. **MANDATORY: Template-first workflow** — Copy template MUST execute before filling sections for every pattern document.
 
-## Workflow Overview
-
-```mermaid
-graph TB
-    S1[Step 1: Load Features Manifest] --> S2[Step 2: Read Feature Documents]
-    S2 --> S3[Step 3: Read Module Overviews]
-    S3 --> S4[Step 4: Cross-Module Clustering]
-    S4 --> S5[Step 5: Generate Pattern Documents]
-    S5 --> S6[Step 6: Return Summary]
-```
-
----
-
-## Step 1: Load Features Manifest
-
-**Goal**: Read the features manifest to identify all completed features.
-
-**Input Validation**:
-- If `platform_type` is NOT `web`, `mobile`, or `desktop` → Skip this skill (backend platforms do not have UI patterns)
-- Verify `features_manifest_path` exists and is valid JSON
-- Verify `feature_docs_path` exists and is a directory
-- Create `output_path` directory if it does not exist
-
-**Action**:
-- Read `{features_manifest_path}` (e.g., `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-{platform}.json`)
-- Filter features where `status === "completed"`
-- Collect feature metadata: `featureId`, `module`, `documentPath`
-
-**Output**: List of completed features with their document paths.
-
----
-
-## Step 2: Read Feature Documents
-
-**Goal**: Extract UI-related information from all completed feature documents.
-
-**Action**:
-- For each completed feature, read the `.md` document from `documentPath`
-- Extract the following sections:
-  - **Interface Prototype**: ASCII wireframe diagrams
-  - **Page Elements Table**: Component list with types and responsibilities
-  - **Business Flow Description**: Interaction patterns
-
-**Extraction Focus**:
-| Section | What to Extract |
-|---------|-----------------|
-| Interface Prototype | ASCII wireframe structure, layout regions |
-| Page Elements Table | Component names, types, responsibilities, interactions |
-| Business Flow Description | User interaction sequences, navigation patterns |
-
----
-
-## Step 3: Read Module Overviews
-
-**Goal**: Gather module-level aggregated information for context.
-
-**Action**:
-- Read all `module-overview.md` files from `{module_overviews_path}`
-- Extract module-level summaries about:
-  - Common page structures
-  - Shared components
-  - Navigation patterns
-
-**Output**: Module-level context for pattern clustering.
-
----
-
-## Step 4: Cross-Module Clustering Analysis
-
-**Goal**: Identify recurring UI patterns across modules through clustering analysis.
-
-**Action**:
-- Analyze all extracted UI information from Steps 2-3
-- Cluster similar patterns into categories:
-  - **Page Types**: Pages with similar structure and purpose
-  - **Component Patterns**: Reusable component combinations
-  - **Layout Patterns**: Repeating structural layouts
-
-**Clustering Strategy**:
-- Adopt dynamic discovery strategy — Agent automatically identifies and categorizes pattern types based on actual analysis results
-- Templates only standardize output format, do not limit pattern types
-- Common patterns include but are not limited to:
-
-| Category | Common Patterns |
-|----------|-----------------|
-| Page Types | list-page, form-page, detail-page, tree-list-page, dashboard-page, wizard-page |
-| Component Patterns | search-filter-bar, data-table-pagination, modal-form, drawer-detail, tab-panel |
-| Layout Patterns | sidebar-content, topbar-sidebar-content, full-screen |
-
-**Pattern Recognition Criteria**:
-- **Frequency**: Pattern appears in 2+ features (stronger signal if across different modules)
-- **Similarity**: Structural similarity in ASCII wireframes
-- **Semantic alignment**: Similar business purpose and interaction flow
-
-> **Note**: Cross-module occurrence is a strong signal but not required. Patterns appearing in multiple features within a single module are also valid for extraction.
-
----
-
-## Step 5: Generate Pattern Documents
-
-**Goal**: Create pattern documents for each identified pattern using template-fill workflow.
-
-### 5.1 Template Selection
-
-| Pattern Category | Template File | Output Directory |
-|-----------------|---------------|------------------|
-| Page types | `templates/PAGE-TYPE-TEMPLATE.md` | `{output_path}/page-types/` |
-| Component patterns | `templates/COMPONENT-PATTERN-TEMPLATE.md` | `{output_path}/components/` |
-| Layout patterns | `templates/LAYOUT-PATTERN-TEMPLATE.md` | `{output_path}/layouts/` |
-
-**File Naming Convention**:
-- Use `kebab-case` for pattern names
-- Examples: `list-page.md`, `search-filter-bar.md`, `sidebar-content.md`
-
-### 5.2 For Each Pattern: Copy Template to Document Path
-
-For each identified pattern:
-1. **Select the appropriate template** based on pattern category
-2. **Replace top-level placeholders** (pattern name, category, etc.)
-3. **Create the document** using `create_file` at the corresponding output path
-4. **Verify**: Document has complete section structure ready for filling
-
-### 5.3 For Each Pattern: Fill Sections Using search_replace
-
-> ⚠️ **CRITICAL CONSTRAINTS:**
-> - **FORBIDDEN: `create_file` to rewrite the entire document**
-> - **MUST use `search_replace` to fill each section individually**
-> - **All section titles MUST be preserved**
-
-**Content Requirements**:
-1. **ASCII wireframes**: Must be generalized versions (not direct copies from specific features)
-2. **Instance references**: Must use relative paths to reference actual feature documents
-3. **Mermaid diagrams**: Must follow `speccrew-workspace/docs/rules/mermaid-rule.md` rules
-   - Use `graph TB/LR` syntax only
-   - No `<br/>` tags, no `style` definitions, no nested `subgraph`
-   - No `direction` keyword, no special symbols
-
----
-
-## Step 6: Return Summary
-
-**Goal**: Provide summary of generated pattern documents.
-
-**Action**:
-- Collect all generated file paths
-- Count patterns by category
-- Return summary object
-
----
+## AgentFlow Definition
+
+<!-- @agentflow: workflow.agentflow.xml -->
+
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="platform_id" required="true" type="string" desc="Platform identifier (e.g., web-vue, mobile-uniapp)"/>
+    <field name="platform_type" required="true" type="string" desc="Platform type (web, mobile, desktop)"/>
+    <field name="feature_docs_path" required="true" type="string" desc="Completed feature documents base path"/>
+    <field name="features_manifest_path" required="true" type="string" desc="Path to features-{platform}.json"/>
+    <field name="module_overviews_path" required="true" type="string" desc="Parent directory containing all module overview subdirectories"/>
+    <field name="output_path" required="true" type="string" desc="Output directory for pattern documents"/>
+    <field name="language" required="true" type="string" desc="User language code"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="forbidden" desc="Document generation constraints">
+    <field name="text">Using create_file to write pattern documents directly</field>
+    <field name="text">Full-file rewrite of pattern documents</field>
+  </block>
+
+  <block type="rule" id="R2" level="mandatory" desc="Document generation requirements">
+    <field name="text">Copy template MUST execute before filling sections for every pattern document</field>
+    <field name="text">All generated pattern documents must be in the specified language</field>
+  </block>
+
+  <!-- ============================================================
+       Global Continuous Execution Rules
+       ============================================================ -->
+  <block type="rule" id="GLOBAL-R1" level="forbidden" desc="Continuous execution constraints — NEVER violate">
+    <field name="text">DO NOT ask user "Should I continue?" or "How would you like to proceed?" during execution</field>
+    <field name="text">DO NOT offer options like "Full execution / Partial / Stop" — always execute ALL tasks to completion</field>
+    <field name="text">DO NOT suggest "Due to context window limits, let me pause" — complete current task, use checkpoint for resumption</field>
+    <field name="text">DO NOT estimate workload and suggest breaking it into phases — execute ALL items in sequence</field>
+    <field name="text">DO NOT warn about "large number of files" or "this may take a while" — proceed with generation</field>
+    <field name="text">Context window management: if approaching limit, save progress to checkpoint file and resume — do NOT ask user for guidance</field>
+  </block>
+
+  <!-- ============================================================
+       Gateway: Platform Type Check
+       ============================================================ -->
+  <block type="gateway" id="G1" mode="exclusive" desc="Check platform type for UI pattern extraction">
+    <branch test="${platform_type} NOT IN ['web', 'mobile', 'desktop']" name="Backend platform">
+      <block type="event" id="E1" action="log" level="info" desc="Log skip reason">
+        <field name="message">Skipping skill: backend platforms do not have UI patterns</field>
+      </block>
+      <block type="task" id="B1" action="analyze" desc="Return skip status">
+        <field name="status" value="skipped"/>
+        <field name="reason" value="Backend platform does not have UI patterns"/>
+        <field name="output" var="summary"/>
+      </block>
+    </branch>
+    <branch test="${platform_type} IN ['web', 'mobile', 'desktop']" name="UI platform">
+
+      <!-- ============================================================
+           Step 1: Load Features Manifest
+           ============================================================ -->
+      <sequence id="S1" name="Step 1: Load Features Manifest" status="pending" desc="Read features manifest to identify completed features">
+        <block type="task" id="B2" action="read-file" desc="Read features manifest file">
+          <field name="path" value="${features_manifest_path}"/>
+          <field name="output" var="featuresManifest"/>
+        </block>
+
+        <block type="task" id="B3" action="analyze" desc="Filter completed features">
+          <field name="input" value="${featuresManifest}"/>
+          <field name="filter" value="status === 'completed'"/>
+          <field name="collect" value="featureId, module, documentPath"/>
+          <field name="output" var="completed_features"/>
+        </block>
+      </sequence>
+
+      <!-- ============================================================
+           Gateway: Check Completed Features
+           ============================================================ -->
+      <block type="gateway" id="G2" mode="guard" desc="Check if completed features exist">
+        <branch test="${completed_features.length} > 0" name="Has completed features">
+
+          <!-- Step 1.5: Create Output Directory -->
+          <block type="task" id="B4" action="run-script" desc="Create output directory structure">
+            <field name="command">node -e "require('fs').mkdirSync('${output_path}/page-types', {recursive:true}); require('fs').mkdirSync('${output_path}/components', {recursive:true}); require('fs').mkdirSync('${output_path}/layouts', {recursive:true})"</field>
+          </block>
+
+          <!-- ============================================================
+               Step 2: Read Feature Documents
+               ============================================================ -->
+          <sequence id="S2" name="Step 2: Read Feature Documents" status="pending" desc="Extract UI information from feature documents">
+            <block type="task" id="B5" action="analyze" desc="Extract UI-related information from feature documents">
+              <field name="input" value="${completed_features}"/>
+              <field name="feature_docs_path" value="${feature_docs_path}"/>
+              <field name="extract_section" value="Interface Prototype"/>
+              <field name="extract_items" value="ASCII wireframe diagrams, layout regions"/>
+              <field name="extract_section_2" value="Page Elements Table"/>
+              <field name="extract_items_2" value="Component names, types, responsibilities, interactions"/>
+              <field name="extract_section_3" value="Business Flow Description"/>
+              <field name="extract_items_3" value="User interaction sequences, navigation patterns"/>
+              <field name="output" var="ui_extracted_data"/>
+            </block>
+          </sequence>
+
+          <!-- ============================================================
+               Step 3: Read Module Overviews
+               ============================================================ -->
+          <sequence id="S3" name="Step 3: Read Module Overviews" status="pending" desc="Gather module-level context">
+            <block type="task" id="B6" action="analyze" desc="Read module overview files for context">
+              <field name="glob_pattern" value="${module_overviews_path}/*/module-overview.md"/>
+              <field name="extract_items" value="Common page structures, Shared components, Navigation patterns"/>
+              <field name="output" var="module_context"/>
+            </block>
+          </sequence>
+
+          <!-- Checkpoint: Data Collection Complete -->
+          <block type="checkpoint" id="CP1" name="data-collection-complete" desc="Data collection complete">
+            <field name="file" value="${output_path}/.progress.json"/>
+            <field name="verify" value="${ui_extracted_data} != null AND ${module_context} != null"/>
+          </block>
+
+          <!-- ============================================================
+               Step 4: Cross-Module Clustering Analysis
+               ============================================================ -->
+          <sequence id="S4" name="Step 4: Cross-Module Clustering Analysis" status="pending" desc="Identify recurring UI patterns">
+            <block type="task" id="B7" action="analyze" desc="Perform cross-module clustering analysis">
+              <field name="input" value="${ui_extracted_data}"/>
+              <field name="module_context" value="${module_context}"/>
+              <field name="clustering_approach" value="Dynamic discovery - Agent automatically identifies and categorizes pattern types based on actual analysis results"/>
+              <field name="note" value="Templates only standardize output format, do not limit pattern types"/>
+              <field name="categories_page_types" value="Pages with similar structure and purpose (e.g., list-page, form-page, detail-page, tree-list-page, dashboard-page, wizard-page)"/>
+              <field name="categories_component_patterns" value="Reusable component combinations (e.g., search-filter-bar, data-table-pagination, modal-form, drawer-detail, tab-panel)"/>
+              <field name="categories_layout_patterns" value="Repeating structural layouts (e.g., sidebar-content, topbar-sidebar-content, full-screen)"/>
+              <field name="recognition_frequency" value="Pattern appears in 2+ features (stronger signal if across different modules)"/>
+              <field name="recognition_similarity" value="Structural similarity in ASCII wireframes"/>
+              <field name="recognition_semantic" value="Similar business purpose and interaction flow"/>
+              <field name="output" var="identified_patterns"/>
+            </block>
+          </sequence>
+
+          <!-- ============================================================
+               Gateway: Check Identified Patterns
+               ============================================================ -->
+          <block type="gateway" id="G3" mode="exclusive" desc="Check if patterns were identified">
+            <branch test="${identified_patterns.length} == 0" name="No patterns">
+              <block type="event" id="E2" action="log" level="warn" desc="Log no patterns">
+                <field name="message">No patterns identified from feature documents</field>
+              </block>
+              <block type="task" id="B8" action="analyze" desc="Return empty result">
+                <field name="status" value="completed"/>
+                <field name="platform_id" value="${platform_id}"/>
+                <field name="patterns_page_types" value='{"count": 0, "files": []}'/>
+                <field name="patterns_components" value='{"count": 0, "files": []}'/>
+                <field name="patterns_layouts" value='{"count": 0, "files": []}'/>
+                <field name="total_patterns" value="0"/>
+                <field name="output_path" value="${output_path}"/>
+                <field name="output" var="summary"/>
+              </block>
+            </branch>
+            <branch test="${identified_patterns.length} > 0" name="Has patterns">
+
+              <!-- ============================================================
+                   Step 5: Generate Pattern Documents
+                   ============================================================ -->
+              <block type="loop" id="L1" over="${identified_patterns}" as="pattern" desc="Generate pattern documents">
+
+                <!-- 5.1 Template Selection -->
+                <block type="gateway" id="G4" mode="exclusive" desc="Select template based on pattern category">
+                  <branch test="${pattern.category} == 'page-types'" name="Page type">
+                    <block type="task" id="B9" action="analyze" desc="Select page type template">
+                      <field name="template_path" value="./templates/PAGE-TYPE-TEMPLATE.md"/>
+                      <field name="output_directory" value="${output_path}/page-types/"/>
+                      <field name="output" var="selected_template"/>
+                    </block>
+                  </branch>
+                  <branch test="${pattern.category} == 'components'" name="Component pattern">
+                    <block type="task" id="B10" action="analyze" desc="Select component pattern template">
+                      <field name="template_path" value="./templates/COMPONENT-PATTERN-TEMPLATE.md"/>
+                      <field name="output_directory" value="${output_path}/components/"/>
+                      <field name="output" var="selected_template"/>
+                    </block>
+                  </branch>
+                  <branch test="${pattern.category} == 'layouts'" name="Layout pattern">
+                    <block type="task" id="B11" action="analyze" desc="Select layout pattern template">
+                      <field name="template_path" value="./templates/LAYOUT-PATTERN-TEMPLATE.md"/>
+                      <field name="output_directory" value="${output_path}/layouts/"/>
+                      <field name="output" var="selected_template"/>
+                    </block>
+                  </branch>
+                </block>
+
+                <!-- 5.2 Copy Template to Document Path -->
+                <block type="task" id="B12" action="run-script" desc="Copy template to output path">
+                  <field name="template" value="${selected_template}"/>
+                  <field name="filename_format" value="kebab-case (e.g., list-page.md, search-filter-bar.md, sidebar-content.md)"/>
+                  <field name="output_path" value="${selected_template.output_directory}/${pattern.name}.md"/>
+                  <field name="output" var="document_path"/>
+                </block>
+
+                <!-- 5.3 Fill Sections Using search_replace -->
+                <block type="task" id="B13" action="analyze" desc="Fill pattern document sections">
+                  <field name="document_path" value="${document_path}"/>
+                  <field name="pattern" value="${pattern}"/>
+                  <field name="language" value="${language}"/>
+                  <field name="constraint_forbidden" value="Using create_file to rewrite the entire document"/>
+                  <field name="constraint_mandatory" value="Use search_replace to fill each section individually"/>
+                  <field name="constraint_sections" value="All section titles MUST be preserved"/>
+                  <field name="content_ascii_wireframes" value="Must be generalized versions (not direct copies from specific features)"/>
+                  <field name="content_instance_references" value="Must use relative paths to reference actual feature documents"/>
+                  <field name="mermaid_rule" value="Follow speccrew-workspace/docs/rules/mermaid-rule.md rules"/>
+                  <field name="mermaid_syntax" value="Use graph TB/LR syntax only"/>
+                  <field name="mermaid_no_br" value="No br/ tags, no style definitions, no nested subgraph"/>
+                  <field name="mermaid_no_direction" value="No direction keyword, no special symbols"/>
+                  <field name="output" var="filled_document"/>
+                </block>
+
+                <!-- Checkpoint: Pattern Document Generated -->
+                <block type="checkpoint" id="CP2" name="pattern-document-generated" desc="Pattern document generated">
+                  <field name="file" value="${output_path}/.progress.json"/>
+                  <field name="verify" value="file_exists(${document_path}) AND document_has_all_sections(${document_path})"/>
+                </block>
+
+              </block>
+
+              <!-- Step 6: Return Summary -->
+              <block type="task" id="B14" action="analyze" desc="Generate summary of pattern documents">
+                <field name="collect_files" value="All generated file paths"/>
+                <field name="collect_counts" value="Pattern counts by category"/>
+                <field name="output" var="summary"/>
+              </block>
+
+            </branch>
+          </block>
+
+        </branch>
+        <branch test="${completed_features.length} == 0" name="No completed features">
+          <block type="event" id="E3" action="log" level="warn" desc="Log no features">
+            <field name="message">No completed features found - returning empty result</field>
+          </block>
+          <block type="task" id="B15" action="analyze" desc="Return empty summary">
+            <field name="status" value="completed"/>
+            <field name="platform_id" value="${platform_id}"/>
+            <field name="patterns_page_types" value='{"count": 0, "files": []}'/>
+            <field name="patterns_components" value='{"count": 0, "files": []}'/>
+            <field name="patterns_layouts" value='{"count": 0, "files": []}'/>
+            <field name="total_patterns" value="0"/>
+            <field name="output_path" value="${output_path}"/>
+            <field name="output" var="summary"/>
+          </block>
+        </branch>
+      </block>
+
+    </branch>
+  </block>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="final_summary" from="${summary}" type="object" desc="Summary of generated pattern documents with file list and counts"/>
+  </block>
+
+</workflow>
 
 ## Generation Rules
 
@@ -237,8 +352,6 @@ For each identified pattern:
    - Template section headers remain in English
    - Content text matches user language
 
----
-
 ## Error Handling
 
 | Scenario | Handling |
@@ -248,8 +361,6 @@ For each identified pattern:
 | Template not found | Use default structure, log warning |
 | Feature document missing | Skip feature, continue with others |
 
----
-
 ## Checklist
 
 - [ ] Step 1: Features manifest loaded, completed features identified