speccrew 0.6.68 → 0.7.0

package/.speccrew/skills/{speccrew-knowledge-techs-generate-quality-xml/SKILL.md → speccrew-knowledge-techs-generate-quality/workflow.agentflow.xml}

@@ -1,39 +1,3 @@
----
-name: speccrew-knowledge-techs-generate-quality-xml
-description: Quality assurance for generated tech documentation using XML workflow blocks. Performs cross-validation, consistency checks, completeness verification, and generates quality reports.
-tools: Read, Write, Glob, Grep, Bash
----
-
-# Tech Documentation Quality Assurance (XML Workflow)
-
-Perform comprehensive quality checks on generated technology documentation to ensure completeness, consistency, and accuracy using XML workflow blocks.
-
-## Role Definition
-
-You are a Technical Documentation Quality Assurance Specialist. Your role is to verify that generated tech documentation meets quality standards by performing:
-
-- **Completeness Verification**: Ensure all required documents and sections exist
-- **Cross-Validation**: Verify dependencies and references are consistent
-- **Consistency Checks**: Ensure naming conventions and style are uniform
-- **Source Traceability**: Verify all claims are properly sourced
-- **Mermaid Compatibility**: Ensure diagrams render correctly
-
-## Trigger Scenarios
-
-- "Verify tech documentation quality for {platform}"
-- "Run quality checks on generated docs"
-- "Validate platform tech docs"
-- "Check documentation completeness"
-
-## User
-
-Worker Agent (speccrew-task-worker)
-
----
-
-## XML Workflow Definition
-  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/xml-workflow-spec.md`
-```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <workflow id="techs-quality-check" status="pending" version="1.0" desc="Quality assurance for tech documentation">
   <!-- ============================================================
@@ -452,131 +416,3 @@ Worker Agent (speccrew-task-worker)
   </block>
 
 </workflow>
-```
-
----
-
-## Input Parameters
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| platform_dir | Yes | Path to platform's techs directory containing generated docs (e.g., `speccrew-workspace/knowledges/techs/{platform_id}/`) |
-| platform_id | Yes | Target platform identifier (e.g., "web-react", "backend-nestjs") |
-| platform_type | Yes | Platform type (web, mobile, backend, desktop) |
-| source_path | Yes | Original source code path for cross-validation |
-| analysis_report_path | No | Path to analysis.json for reference (default: `{platform_dir}/{platform_id}.analysis.json`) |
-
----
-
-## Output Files
-
-- Quality Report: `{platform_dir}/quality-report.json`
-- Completion Marker: `{platform_dir}/quality-done.json`
-- Console summary of check results
-
----
-
-## Quality Thresholds
-
-| Score | Status |
-|-------|--------|
-| 90-100 | EXCELLENT |
-| 80-89 | GOOD |
-| 70-79 | ACCEPTABLE |
-| 60-69 | NEEDS_IMPROVEMENT |
-| 0-59 | FAILED |
-
----
-
-## Constraints
-
-1. **Read-Only Source Access**: Only READ from source_path, never modify
-2. **Relative Paths Only**: All file references must use relative paths
-3. **JSON Output Only**: Quality report must be valid JSON
-4. **Complete All Steps**: Must complete all 8 steps even if early failures are found
-5. **Detailed Issue Reporting**: Include file paths and line numbers for issues when possible
-
----
-
-## Error Handling
-
-| Error Type | Action |
-|------------|--------|
-| Platform directory not found | Report error, terminate with failed status |
-| Required document missing | Record in completeness check, continue |
-| Analysis report missing | Skip cross-validation with source, continue |
-| Mermaid parsing error | Record in compatibility check, continue |
-
----
-
-## Task Completion Report
-
-Upon completion, return the following:
-
-```
-TASK COMPLETED: speccrew-knowledge-techs-generate-quality-xml
-
-## Input Parameters
-- platform_id: {platform_id}
-- platform_dir: {platform_dir}
-- source_path: {source_path}
-
-## Quality Summary
-- Total Checks: {total}
-- Passed: {passed}
-- Warnings: {warnings}
-- Failed: {failed}
-- Quality Score: {score}%
-
-## Status by Category
-- Completeness: {status}
-- Cross-Validation: {status}
-- Consistency: {status}
-- Source Traceability: {status}
-- Mermaid Compatibility: {status}
-
-## Output
-- Quality Report: {platform_dir}/quality-report.json
-
-## Recommendations
-{list of recommendations if any}
-```
-
----
-
-## Integration Notes
-
-This skill is designed to be invoked after `speccrew-knowledge-techs-generate` completes. The quality report can be used by:
-
-- `techs-dispatch` to determine if re-generation is needed
-- Development teams to identify documentation issues
-- CI/CD pipelines to enforce documentation quality gates
-
----
-
-## CONTINUOUS EXECUTION RULES
-
-This skill MUST execute all steps continuously without unnecessary interruptions.
-
-### FORBIDDEN Interruptions
-
-1. DO NOT ask user "Should I continue?" after completing a step
-2. DO NOT suggest "Let me split this into batches" or "Let's do this in parts"
-3. DO NOT pause to list what you plan to do next — just do it
-4. DO NOT ask for confirmation before generating output files
-5. DO NOT warn about "large number of files" — proceed with generation
-6. DO NOT offer "Should I proceed with the remaining items?"
-7. DO NOT present options like "Full execution / Sample execution / Pause"
-
-### When to Pause (ONLY these cases)
-
-1. Explicit `<event action="confirm">` blocks in the workflow
-2. Ambiguous requirements that genuinely need clarification
-3. Unrecoverable errors that prevent further progress
-4. Security-sensitive operations (e.g., deleting existing files)
-
-### Execution Behavior
-
-- When multiple checks need to be performed, execute ALL of them sequentially without asking
-- Continue execution even if individual checks fail — record failures and proceed
-- NEVER voluntarily stop mid-process to ask if user wants to continue

package/.speccrew/skills/speccrew-knowledge-techs-generate-ui-style/SKILL.md

@@ -1,24 +1,25 @@
 ---
 name: speccrew-knowledge-techs-generate-ui-style
-description: Generate UI style analysis documents for a specific frontend platform. Analyzes page types, components, layouts, and styling conventions from source code. Split from techs-generate for parallel execution with conventions worker. Only applicable to frontend platforms (web, mobile, desktop).
+description: Generate UI style analysis documents for a specific frontend platform using XML workflow blocks. Analyzes page types, components, layouts, and styling conventions from source code. Only applicable to frontend platforms (web, mobile, desktop).
 tools: Read, Write, Glob, Grep, Skill
 ---
 
-# Stage 2: Generate Platform UI Style Documents
+# Stage 2: Generate Platform UI Style Documents (XML Workflow)
 
-Generate comprehensive UI style documentation for a specific frontend platform by analyzing its source code structure, components, and styling patterns.
+Generate comprehensive UI style documentation for a specific frontend platform by analyzing its source code structure, components, and styling patterns using XML workflow blocks.
 
 ## Language Adaptation
 
-**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+**CRITICAL**: All generated documents must match the user's language. Detect the language from the user's input and generate content accordingly.
 
-- `language: "zh"` → Generate all content in 中文
-- `language: "en"` → Generate all content in English
-- Other languages → Use the specified language
+- User writes in 中文 → Generate Chinese documents, use `language: "zh"`
+- User writes in English → Generate English documents, use `language: "en"`
+- Other languages → Use the specified language code
 
 ## Prerequisite
 
 This skill ONLY applies to frontend platforms. The dispatcher MUST check platform_type before invoking:
+
 - `web` → Execute this skill
 - `mobile` → Execute this skill
 - `desktop` → Execute this skill
@@ -35,17 +36,17 @@ This skill ONLY applies to frontend platforms. The dispatcher MUST check platfor
 
 Worker Agent (speccrew-task-worker)
 
-## Input
+---
+
+## AgentFlow Definition
 
-- `platform_id`: Platform identifier (e.g., "web-react", "mobile-uniapp")
-- `platform_type`: Platform type (web, mobile, desktop)
-- `framework`: Primary framework (react, vue, angular, uniapp, flutter, etc.)
-- `source_path`: Platform source directory
-- `output_path`: Output directory (e.g., speccrew-workspace/knowledges/techs/{platform_id}/)
-- `language`: Target language ("zh", "en") - **REQUIRED**
-- `completed_dir`: (Optional) Directory for completion marker and analysis report
+<!-- @agentflow: workflow.agentflow.xml -->
+
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
+
+---
 
-## Output
+## Output Directory Structure
 
 ```
 {output_path}/
@@ -79,277 +80,6 @@ Worker Agent (speccrew-task-worker)
   - NOT created or written by this skill
   - May not exist if bizs pipeline has not been executed
 
-## Workflow
-
-```mermaid
-flowchart TD
-    Start --> Step0[Step 0: Read UI Style Templates]
-    Step0 --> Step1[Step 1: UI Style Analysis]
-    Step1 --> Step2[Step 2: Write Output Files]
-    Step2 --> Step3[Step 3: Generate Analysis Report]
-    Step3 --> Step4[Step 4: Report Results]
-    Step4 --> End
-```
-
-### Step 0: Read UI Style Templates
-
-Before processing, read all UI style template files to understand the required content structure:
-
-- **Read**: `../speccrew-knowledge-techs-generate/templates/COMPONENT-LIBRARY-TEMPLATE.md` - Component catalog structure
-- **Read**: `../speccrew-knowledge-techs-generate/templates/PAGE-LAYOUTS-TEMPLATE.md` - Layout patterns structure
-- **Read**: `../speccrew-knowledge-techs-generate/templates/PAGE-TYPE-SUMMARY-TEMPLATE.md` - Page type classification structure
-- **Read**: `../speccrew-knowledge-techs-generate/templates/COLOR-SYSTEM-TEMPLATE.md` - Color and typography system structure
-- **Purpose**: Understand template structure for fallback path copy+fill workflow
-
-### Step 1: UI Style Analysis
-
-**Directory Ownership**:
-- `ui-style/` — Fully managed by techs pipeline (this skill)
-  - Contains: ui-style-guide.md, styles/, page-types/, components/, layouts/
-  - Source: Framework-level design system analysis from source code
-- `ui-style-patterns/` — Managed by bizs pipeline (Stage 3.5: bizs-ui-style-extract)
-  - Contains: Business pattern aggregation from feature documents
-  - NOT created or written by this skill
-  - May not exist if bizs pipeline has not been executed
-
-**Primary Path (UI Analyzer Available and Succeeds)**:
-
-1. **CRITICAL**: Use the Skill tool to invoke `speccrew-knowledge-techs-ui-analyze` with these exact parameters:
-   ```
-   skill: "speccrew-knowledge-techs-ui-analyze"
-   args: "source_path={source_path};platform_id={platform_id};platform_type={platform_type};framework={framework};output_path={output_path}/ui-style/;language={language}"
-   ```
-
-2. **Wait for completion** and verify output files exist:
-   - `{output_path}/ui-style/ui-style-guide.md` ✓
-   - `{output_path}/ui-style/page-types/page-type-summary.md` ✓
-   - `{output_path}/ui-style/page-types/[type]-pages.md` (one per discovered type) ✓
-   - `{output_path}/ui-style/components/component-library.md` ✓
-   - `{output_path}/ui-style/components/common-components.md` ✓
-   - `{output_path}/ui-style/components/business-components.md` ✓
-   - `{output_path}/ui-style/layouts/page-layouts.md` ✓
-   - `{output_path}/ui-style/layouts/navigation-patterns.md` ✓
-   - `{output_path}/ui-style/styles/color-system.md` ✓
-   - `{output_path}/ui-style/styles/typography.md` ✓
-   - `{output_path}/ui-style/styles/spacing-system.md` ✓
-
-3. If all outputs verified → proceed to next step
-4. Record: `ui_analysis_level = "full"`
-
-**Secondary Path (UI Analyzer Fails or Partial Output)**:
-
-**MANDATORY: UI Style Fallback Path - Complete Directory Structure**
-
-When UI Style Analyzer fails or produces incomplete output, you MUST create ALL of the following directories and files. Skipping ANY item is FORBIDDEN.
-
-**Required Directory Structure (MANDATORY - ALL items must be created):**
-```
-ui-style/
-├── ui-style-guide.md              ← MANDATORY
-├── page-types/
-│   └── page-type-summary.md       ← MANDATORY
-├── components/
-│   └── component-library.md       ← MANDATORY
-├── layouts/
-│   └── page-layouts.md            ← MANDATORY
-└── styles/
-    └── color-system.md            ← MANDATORY
-```
-
-**Self-Verification Checklist (MUST complete before reporting success):**
-- [ ] ui-style/ui-style-guide.md exists and has content
-- [ ] ui-style/page-types/page-type-summary.md exists and has content
-- [ ] ui-style/components/component-library.md exists and has content
-- [ ] ui-style/layouts/page-layouts.md exists and has content
-- [ ] ui-style/styles/color-system.md exists and has content
-
-If ANY file in the checklist is missing, you MUST create it before proceeding to the next step. Do NOT report "completed" with missing files.
-
-**Execution Steps:**
-
-1. Create ui-style directory structure:
-   `{output_path}/ui-style/`, `{output_path}/ui-style/page-types/`, `{output_path}/ui-style/components/`, `{output_path}/ui-style/layouts/`, `{output_path}/ui-style/styles/`
-
-2. Generate minimal ui-style-guide.md by manually scanning source code:
-   - Design system: identify UI framework from dependencies (Material UI, Ant Design, Tailwind, etc.)
-   - Color system: scan for CSS variables, theme files, or color constants in `{source_path}/src/styles/` or `{source_path}/src/theme/`
-   - Typography: scan for font-family declarations
-   - Component library: list directories under `{source_path}/src/components/`
-   - Page types: list directories/files under `{source_path}/src/pages/` or `{source_path}/src/views/`
-
-3. Content structure for minimal ui-style-guide.md:
-   ```markdown
-   # UI Style Guide - {platform_id}
-   
-   > Note: Generated from manual source code inspection. Automated UI analysis was unavailable.
-   
-   ## Design System
-   - UI Framework: {detected from package.json}
-   - CSS Approach: {CSS Modules / Tailwind / styled-components / SCSS - detected from config}
-   
-   ## Component Library Overview
-   {list component directories found}
-   
-   ## Page Types Identified
-   {list page directories/files found}
-   
-   ## Styling Configuration
-   {extract from tailwind.config / theme file / CSS variables file}
-   ```
-
-4. **MANDATORY: UI Style Fallback - Copy Template + Fill Workflow**
-
-   For each ui-style sub-document, copy the template and use search_replace to fill:
-
-   **4.1 component-library.md**:
-   - Copy `templates/COMPONENT-LIBRARY-TEMPLATE.md` to `{output_path}/ui-style/components/component-library.md`
-   - Use search_replace to fill each AI-TAG section with data extracted from source code
-   - MUST include props tables for at least the top 5 most-used components
-   - Fill: COMPONENT_CATEGORIES, API_REFERENCE, COMPOSITION_PATTERNS, AGENT_GUIDE sections
-
-   **4.2 page-layouts.md**:
-   - Copy `templates/PAGE-LAYOUTS-TEMPLATE.md` to `{output_path}/ui-style/layouts/page-layouts.md`
-   - Fill layout types, slots, responsive behavior from source analysis
-   - Fill: LAYOUT_TYPES, LAYOUT_DETAILS, NAVIGATION sections
-
-   **4.3 page-type-summary.md**:
-   - Copy `templates/PAGE-TYPE-SUMMARY-TEMPLATE.md` to `{output_path}/ui-style/page-types/page-type-summary.md`
-   - Fill page classifications and routing conventions
-   - Fill: PAGE_TYPES, PAGE_TYPE_DETAILS, ROUTING sections
-
-   **4.4 color-system.md**:
-   - Copy `templates/COLOR-SYSTEM-TEMPLATE.md` to `{output_path}/ui-style/styles/color-system.md`
-   - Fill theme colors, functional colors, typography from CSS/SCSS variables
-   - Fill: THEME_COLORS, FUNCTIONAL_COLORS, SEMANTIC_TOKENS, TYPOGRAPHY, SPACING sections
-
-5. Record: `ui_analysis_level = "minimal"`
-
-**Tertiary Path (No UI Analysis Possible)**:
-
-If source code scanning also fails (e.g., non-standard structure):
-
-1. Create `{output_path}/ui-style/ui-style-guide.md` with references only:
-   ```markdown
-   # UI Style Guide - {platform_id}
-   
-   > Note: Automated and manual UI analysis were not possible for this platform.
-   > Manual inspection of source code is required.
-   
-   ## References
-   - Source components: {source_path}/src/components/ (if exists)
-   - Source pages: {source_path}/src/pages/ (if exists)
-   - Style files: {source_path}/src/styles/ (if exists)
-   - Package dependencies: {source_path}/package.json
-   ```
-
-2. Record: `ui_analysis_level = "reference_only"`
-
-**Note**: The conventions-design.md reference to ui-style is maintained by the conventions worker.
-
-### Step 2: Write Output Files
-
-Create output directory structure if not exists:
-
-1. **Create directories**:
-   - `{output_path}/ui-style/`
-   - `{output_path}/ui-style/page-types/`
-   - `{output_path}/ui-style/components/`
-   - `{output_path}/ui-style/layouts/`
-   - `{output_path}/ui-style/styles/`
-
-2. **Write all generated ui-style documents** to their respective directories.
-
-### Step 3: Generate Analysis Report
-
-**Output file**: `{completed_dir}/{platform_id}.analysis-ui-style.json`
-
-**Report Format**:
-
-```json
-{
-  "platform_id": "{platform_id}",
-  "platform_type": "{platform_type}",
-  "worker_type": "ui-style",
-  "analyzed_at": "{ISO 8601 timestamp}",
-  "ui_analysis_level": "full | minimal | reference_only",
-  "topics": {
-    "page_types": {
-      "status": "found | not_found | partial",
-      "count": N,
-      "files_analyzed": ["src/views/..."],
-      "notes": "..."
-    },
-    "components": {
-      "status": "found | not_found | partial",
-      "common_count": N,
-      "business_count": N,
-      "files_analyzed": ["src/components/..."],
-      "notes": "..."
-    },
-    "layouts": {
-      "status": "found | not_found | partial",
-      "count": N,
-      "files_analyzed": ["src/layouts/..."],
-      "notes": "..."
-    },
-    "styles": {
-      "status": "found | not_found | partial",
-      "files_analyzed": ["src/styles/..."],
-      "notes": "..."
-    }
-  },
-  "documents_generated": ["ui-style-guide.md", "page-types/page-type-summary.md", ...],
-  "source_dirs_scanned": ["src/views/", "src/components/", "src/styles/", "src/layouts/"],
-  "coverage_summary": {
-    "total_topics": 4,
-    "found": N,
-    "not_found": N,
-    "partial": N,
-    "coverage_percent": N
-  }
-}
-```
-
-**Rules**:
-- Every topic from the analysis MUST appear in the `topics` object
-- `files_analyzed` MUST list the actual file paths you read (relative to source_path)
-- `status` MUST be one of: `found`, `not_found`, `partial`
-- `coverage_percent` = (topics_found + topics_partial) / topics_total * 100, rounded to integer
-- `documents_generated` MUST list all .md files actually created
-- Use `create_file` to write this JSON file (this is the ONE exception where create_file is allowed — for JSON output files)
-
-### Step 4: Report Results
-
-**Completion marker file**: `{completed_dir}/{platform_id}.done-ui-style.json`
-
-**Format**:
-
-```json
-{
-  "platform_id": "{platform_id}",
-  "worker_type": "ui-style",
-  "status": "completed",
-  "ui_analysis_level": "full | minimal | reference_only",
-  "documents_generated": [...],
-  "analysis_file": "{platform_id}.analysis-ui-style.json",
-  "completed_at": "{ISO timestamp}"
-}
-```
-
-**Console output**:
-
-```
-Platform UI Style Documents Generated: {platform_id}
-- ui-style-guide.md: ✓ (analysis level: {ui_analysis_level})
-- page-types/page-type-summary.md: ✓
-- components/component-library.md: ✓
-- layouts/page-layouts.md: ✓
-- styles/color-system.md: ✓
-- Output Directory: {output_path}/ui-style/
-- Analysis Report: {completed_dir}/{platform_id}.analysis-ui-style.json
-- Completion Marker: {completed_dir}/{platform_id}.done-ui-style.json
-```
-
 ---
 
 ## Quality Requirements
@@ -359,18 +89,23 @@ Platform UI Style Documents Generated: {platform_id}
 - Analysis report MUST honestly reflect coverage level
 - All paths in documents MUST be relative (never absolute or file:// protocol)
 
+---
+
 ## Error Handling
 
-- If ui-analyze skill invocation fails → Execute Secondary Path (template fill)
-- If source code structure is non-standard and cannot be analyzed → Execute Tertiary Path (reference only)
-- Any path MUST output the done file and analysis file
-- Never report "completed" with missing mandatory files
+| Error Type | Action |
+|------------|--------|
+| Platform type is backend/api | Skip execution, return skipped status |
+| UI analyzer skill invocation fails | Execute Secondary Path (template fill) |
+| Source code structure is non-standard | Execute Tertiary Path (reference only) |
+| Template not found | Use default structure, log warning |
+| Any path MUST output the done file and analysis file | Never report "completed" with missing mandatory files |
 
 ---
 
 ## Task Completion Report
 
-Upon completion, output the following structured report:
+Upon completion, return the following structured report:
 
 ```json
 {
@@ -425,3 +160,33 @@ Upon completion, output the following structured report:
 - [ ] Analysis report generated: `{platform_id}.analysis-ui-style.json`
 - [ ] Completion marker generated: `{platform_id}.done-ui-style.json`
 - [ ] Console output reported with correct status
+
+---
+
+## CONTINUOUS EXECUTION RULES
+
+This skill MUST execute all steps continuously without unnecessary interruptions.
+
+### FORBIDDEN Interruptions
+
+1. DO NOT ask user "Should I continue?" after completing a step
+2. DO NOT suggest "Let me split this into batches" or "Let's do this in parts"
+3. DO NOT pause to list what you plan to do next — just do it
+4. DO NOT ask for confirmation before generating output files
+5. DO NOT warn about "large number of files" — proceed with generation
+6. DO NOT offer "Should I proceed with the remaining items?"
+7. DO NOT present options like "Full execution / Sample execution / Pause"
+
+### When to Pause (ONLY these cases)
+
+1. Explicit `<event action="confirm">` blocks in the workflow
+2. Ambiguous requirements that genuinely need clarification
+3. Unrecoverable errors that prevent further progress
+4. Security-sensitive operations (e.g., deleting existing files)
+
+### Execution Behavior
+
+- When multiple templates need filling, process ALL of them sequentially without asking
+- Use checkpoint files to track progress, enabling resumption if interrupted
+- If context window is approaching limit, save progress and inform user how to resume
+- NEVER voluntarily stop mid-process to ask if user wants to continue