speccrew 0.5.13 → 0.5.16

package/.speccrew/skills/speccrew-knowledge-techs-dispatch/SKILL.md

@@ -52,6 +52,27 @@ Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized pl
 - Root index: `speccrew-workspace/knowledges/techs/INDEX.md`
 - Status files: `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/stage{N}-status.json`
 
+# Quick Reference — Execution Flow
+
+```
+Stage 1: Platform Detection
+  └─ Read techs-manifest.json → Identify platforms & tech stacks
+        ↓
+Stage 2: Tech Doc Generation (PARALLEL)
+  └─ Dispatch techs-generate workers per platform
+  └─ After each generate worker completes → dispatch quality check worker
+  └─ Monitor completion markers
+        ↓
+Stage 2.5: Completion Verification
+  └─ Step A: Scan completion markers
+  └─ Step B: Verify output integrity
+  └─ Step C: Update dispatch progress
+        ↓
+Stage 3: Root Index Generation
+  └─ Generate techs/README.md root index
+  └─ Cross-platform consistency check
+```
+
 ## Workflow Overview
 
 ```mermaid
@@ -86,6 +107,13 @@ See [Platform Status Tracking Fields](#platform-status-tracking-fields) for stat
 
 ---
 
+> **⚠️ MANDATORY RULES FOR PARALLEL EXECUTION (Stage 2)**:
+> 1. ALL platform workers MUST be dispatched in PARALLEL — sequential execution is FORBIDDEN
+> 2. Each platform worker runs independently via techs-generate Skill
+> 3. Monitor completion via marker files in each platform directory
+> 4. Failed workers can be retried independently
+> 5. Do NOT proceed to Stage 2.5 until ALL workers have completed or failed
+
 ## Stage 2: Generate Platform Documents (Parallel)
 
 **Goal**: Generate technology documentation for each platform in parallel.
@@ -155,6 +183,38 @@ IF platform.platform_type IN ["web", "mobile", "desktop"]:
 - WAIT_ALL workers complete
 - Both workers run in PARALLEL for the same platform
 
+**Step 2e: Launch Quality Check Workers — PARALLEL per Completed Generate Worker**
+
+After each `speccrew-knowledge-techs-generate` worker completes (writes `.done-conventions.json` marker), immediately dispatch the corresponding quality check worker:
+
+| Generate Worker | Quality Worker | Input |
+|-----------------|----------------|-------|
+| `speccrew-knowledge-techs-generate-conventions` | `speccrew-knowledge-techs-generate-quality` | `output_path` from generate output |
+| `speccrew-knowledge-techs-generate-ui-style` | `speccrew-knowledge-techs-generate-quality` | `output_path` from generate output |
+
+**Quality Worker Task Prompt Format**:
+
+```json
+{
+  "skill_name": "speccrew-knowledge-techs-generate-quality",
+  "context": {
+    "platform_dir": "<platform_output_path>",
+    "platform_id": "<platform.platform_id>",
+    "platform_type": "<platform.platform_type>",
+    "source_path": "<platform.source_path>"
+  }
+}
+```
+
+**Execution sequence**:
+1. Scan `completed_dir` for new `.done-conventions.json` and `.done-ui-style.json` files
+2. For each completed generate worker, prepare corresponding quality worker task
+3. Launch ALL quality workers for the current batch in PARALLEL
+4. Wait for ALL quality workers to complete
+5. Each quality worker writes `.quality-done.json` marker to `completed_dir`
+
+> **Stage 2 Completion Condition**: ALL generate workers AND ALL quality check workers completed (`.done-*.json` and `.quality-done.json` markers present) before proceeding to Stage 2.5
+
 ### Worker Completion Marker (MANDATORY)
 
 Each Worker MUST create a completion marker file after generating documents. See [Worker Completion Marker Format](#worker-completion-marker-format) for details.
@@ -211,45 +271,50 @@ speccrew-workspace/knowledges/techs/{platform_id}/
 - `total_platforms`, `completed`, `failed` counts
 - Per-platform: `documents_generated` list
 
-**Step 2e: Scan Completion Markers**
+**Step 2f: Scan Completion Markers**
 
 For each platform in the manifest:
 1. Check for `{platform_id}.done-conventions.json` (REQUIRED for all platforms)
 2. If platform_type IN ["web", "mobile", "desktop"], also check for `{platform_id}.done-ui-style.json`
-3. A platform is "fully completed" only when ALL expected done files are present
-4. If any expected done file is missing → mark platform as `failed` (Worker crashed without creating marker)
+3. Check for `{platform_id}.quality-done.json` (REQUIRED — quality check completion marker)
+4. A platform is "fully completed" only when ALL expected done files AND quality markers are present
+5. If any expected done file is missing → mark platform as `failed` (Worker crashed without creating marker)
 
-**Step 2f: Verify Document Output**
+**Step 2g: Verify Document Output**
 
 For each platform:
 - **Conventions**: Check that INDEX.md, tech-stack.md, architecture.md, conventions-*.md exist
 - **UI-Style** (frontend platforms only): Check that ui-style/ directory and required files exist
+- **Quality Report**: Check that `{platform_dir}/quality-report.json` exists (generated by quality worker)
 - If any required document is missing → downgrade status accordingly
 
-**Step 2g: Read Coverage Reports**
+**Step 2h: Read Coverage and Quality Reports**
 
 For each platform:
 1. Read `{platform_id}.analysis-conventions.json`
 2. If frontend platform, also read `{platform_id}.analysis-ui-style.json`
-3. Merge coverage data from both reports for manifest update
+3. Read `{platform_dir}/quality-report.json` for quality metrics
+4. Merge coverage and quality data from all reports for manifest update
 
-**Step 2h: Update Manifest Status**
+**Step 2i: Update Manifest Status**
 
 Update `techs-manifest.json` for each platform:
 - Set `status` based on worker results:
-  - `"completed"` — ALL workers succeeded
-  - `"partial"` — conventions succeeded but ui-style failed (frontend only)
-  - `"failed"` — conventions worker failed
+  - `"completed"` — ALL workers succeeded (including quality check)
+  - `"partial"` — conventions succeeded but ui-style or quality failed (frontend only)
+  - `"failed"` — conventions worker or quality check failed
 - Set `completedAt` to current timestamp
 - Set `workers.conventions.status` from done-conventions.json
 - Set `workers.ui_style.status` from done-ui-style.json (or `"skipped"` for backend platforms)
+- Set `workers.quality.status` from quality-done.json
 - Set `analysisLevel` based on:
-  - `"full"` if coverage_percent >= 60 and all required docs exist
-  - `"minimal"` if coverage_percent < 60 or some optional docs missing
-  - `"reference_only"` if critical docs missing or Worker failed
+  - `"full"` if coverage_percent >= 60 and all required docs exist and quality passed
+  - `"minimal"` if coverage_percent < 60 or some optional docs missing or quality warnings
+  - `"reference_only"` if critical docs missing or Worker failed or quality failed
 - Set `topicsCoverage` from analysis-conventions.json coverage_percent
+- Set `qualityScore` from quality.json if available
 
-**Step 2i: Handle Failures**
+**Step 2j: Handle Failures**
 
 For platforms with conventions worker `status: "failed"`:
 - Mark platform as `failed`
@@ -262,6 +327,11 @@ For frontend platforms with ui-style worker `status: "failed"` but conventions s
 - Conventions docs are still usable
 - Log a warning that UI-style analysis failed
 
+For platforms with quality worker `status: "failed"` but generate succeeded:
+- Mark platform as `partial` (docs generated but quality issues)
+- Log a warning with quality failure details
+- Include quality report in manifest for review
+
 ---
 
 ## Stage 2.5: Quality Synchronization
@@ -269,9 +339,58 @@ For frontend platforms with ui-style worker `status: "failed"` but conventions s
 **Trigger**: After ALL Stage 2 Workers have completed (all platforms processed)
 **Purpose**: Verify cross-platform consistency and document completeness before indexing
 
-**Steps**:
+**Three-Step Process**:
+
+### Step A: Scan Completion Markers
+
+Scan the completion marker files in `{completed_dir}/` for each platform:
+
+1. List all `.done-*.json` files in the sync-status directory
+2. For each platform in manifest:
+   - Check `{platform_id}.done-conventions.json` exists (REQUIRED for ALL platforms)
+   - IF `platform_type` IN ["web", "mobile", "desktop"]: check `{platform_id}.done-ui-style.json`
+3. Categorize platforms:
+   - **completed**: All expected done files present with `status: "completed"`
+   - **failed**: Missing done file OR `status: "failed"` in done file
+   - **partial**: Conventions succeeded but ui-style failed (frontend only)
+
+**Output**: `platforms_completed[]`, `platforms_failed[]`, `platforms_partial[]` lists
+
+### Step B: Verify Output Integrity
 
-#### Step 1: Collect Worker Results
+For each platform in `platforms_completed` and `platforms_partial`:
+
+1. Verify required document files exist in `knowledges/techs/{platform_id}/`:
+   - `INDEX.md`, `tech-stack.md`, `architecture.md`
+   - `conventions-design.md`, `conventions-dev.md`
+   - `conventions-unit-test.md`, `conventions-system-test.md`, `conventions-build.md`
+2. For frontend platforms, verify `ui-style/ui-style-guide.md` exists
+3. Check each document is non-empty (>= 20 lines minimum)
+4. Record verification results: `documents_present[]`, `documents_missing[]`
+
+**Output**: Per-platform integrity status with document check results
+
+### Step C: Update Dispatch Progress
+
+Update the dispatch progress status:
+
+1. Generate `stage2-status.json` with verification results (see format below)
+2. For failed platforms:
+   - Set `error_category` based on failure type:
+     - `marker_missing`: Done file not created
+     - `output_incomplete`: Required documents missing
+     - `worker_crash`: Worker process terminated unexpectedly
+3. Decision point:
+   - IF ALL platforms failed → ABORT pipeline, report error
+   - IF ANY platform succeeded → CONTINUE to Stage 3 with successful platforms
+
+**Output**: `stage2-status.json` ready, pipeline ready for Stage 3
+
+---
+
+### Detailed Verification Steps
+
+#### Document Existence Check
 For each platform, verify the following required documents exist:
 - INDEX.md
 - tech-stack.md
@@ -283,7 +402,7 @@ For each platform, verify the following required documents exist:
 - conventions-build.md
 - conventions-data.md (optional - only for backend or platforms with detected data layer)
 
-#### Step 2: Document Completeness Check
+#### Document Completeness Check
 For each platform directory at `speccrew-workspace/knowledges/techs/{platform_id}/`:
 1. List all .md files present
 2. Check against required document list
@@ -329,10 +448,10 @@ SEVERITY: warning (does not block pipeline, but recorded in quality report)
 
 #### Check 5: Topic Coverage Verification
 
-Read `{completed_dir}/{platform_id}.analysis.json` (if it exists):
-1. Extract `coverage_summary.coverage_percent`
-2. If `coverage_percent` < 60 → flag as `coverage_warning`
-3. Extract list of topics with `status: "not_found"` → record as `topics_missing`
+Read `{completed_dir}/{platform_id}.analysis-conventions.json` and `{completed_dir}/{platform_id}.analysis-ui-style.json` (if they exist):
+1. Merge `coverage_summary.coverage_percent` from both reports
+2. If combined `coverage_percent` < 60 → flag as `coverage_warning`
+3. Extract list of topics with `status: "not_found"` from both reports → record as `topics_missing`
 4. If `coverage_percent` < 30 → flag as `coverage_critical` (pipeline should warn but continue)
 
 ```
@@ -487,6 +606,23 @@ Write to `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/stage2-s
 3. **Platform-Specific Document Recommendations**:
    - Adjust "Agent 重点文档" recommendations based on actual available documents
 
+### Cross-Platform Consistency Check
+
+```pseudocode
+FOR EACH platform_pair IN combinations(platforms, 2):
+  shared_deps = intersection(platform_a.dependencies, platform_b.dependencies)
+  FOR EACH dep IN shared_deps:
+    IF platform_a.dep_version != platform_b.dep_version:
+      WARN "Version mismatch: {dep} — {platform_a}: {v1}, {platform_b}: {v2}"
+  
+  shared_conventions = intersection(platform_a.conventions, platform_b.conventions)
+  FOR EACH convention IN shared_conventions:
+    IF platform_a.convention_rule != platform_b.convention_rule:
+      WARN "Convention conflict: {convention}"
+
+THRESHOLD: warnings > 5 → flag for manual review
+```
+
 **Output**:
 - `speccrew-workspace/knowledges/techs/INDEX.md` (complete with platform index and Agent mapping, dynamically generated)
 
@@ -679,3 +815,31 @@ pending → processing → completed
                     → partial (conventions OK, ui-style failed)
                     → failed
 ```
+
+---
+
+## Task Completion Report
+
+Upon completing all stages, output the following structured report:
+
+```json
+{
+  "status": "success | partial | failed",
+  "skill": "speccrew-knowledge-techs-dispatch",
+  "stages_completed": ["stage_1", "stage_2", "stage_2_5", "stage_3"],
+  "stages_failed": [],
+  "output_summary": {
+    "platforms_processed": ["frontend", "backend"],
+    "docs_generated_per_platform": {"frontend": 5, "backend": 4},
+    "root_index_generated": true,
+    "cross_platform_check_passed": true
+  },
+  "output_files": [
+    "knowledges/techs/{platform}/README.md",
+    "knowledges/techs/{platform}/conventions.md",
+    "knowledges/techs/README.md"
+  ],
+  "errors": [],
+  "next_steps": ["Review generated tech documentation"]
+}
+```