speccrew 0.2.7 → 0.3.0

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

@@ -55,12 +55,48 @@ Orchestrate **bizs knowledge base generation** with a 5-stage pipeline: Feature
 
 ## Workflow Overview
 
+**Execution Pseudocode:**
+
+```
+INPUT: source_path, language, sync_mode, max_concurrent_workers
+
+STAGE 0: Platform Detection
+  FOR each detected platform:
+    Identify platform_type, platform_subtype, tech_stack
+  Present platform list for user confirmation
+
+STAGE 1: Feature Inventory
+  Stage 1a: Entry Directory Recognition → Generate entry-dirs-{platform}.json
+  Stage 1b: Feature Inventory → Generate features-{platform}.json
+  Stage 1c (incremental only): Merge features with existing state
+
+STAGE 2: Feature Analysis (REPEAT until all features processed)
+  Step 0: Ensure completed_dir exists
+  Step 1: Get next batch of pending features
+  Step 2: Launch parallel Workers (API or UI analysis)
+  Step 3: Process batch results, update features.json, write graph
+
+STAGE 3: Module Summarize (parallel per module)
+  FOR each module:
+    Launch Worker with module-summarize skill
+
+STAGE 3.5: UI Style Pattern Extract (parallel per frontend platform)
+  FOR each frontend platform:
+    Launch Worker with ui-style-extract skill
+
+STAGE 4: System Summary
+  Launch Worker with system-summarize skill
+
+OUTPUT: system-overview.md, graph data, module overviews
+```
+
+**Stage Sequence:**
+
 ```mermaid
 flowchart TB
-    S0[Pre-processing: Platform Root Detection] --> S0a[Stage 0: Platform Detection]
-    S0a --> S1a[Stage 1a: Entry Directory Recognition]
+    S0[Stage 0: Platform Detection] --> S1a[Stage 1a: Entry Directory Recognition]
     S1a --> S1b[Stage 1b: Feature Inventory]
-    S1b --> S1c[Stage 1c: Feature Merge - Incremental]
+    S1b --> S1c[Stage 1c: Feature Merge]
     S1c --> S2[Stage 2: Feature Analysis + Graph Write]
     S2 --> S3[Stage 3: Module Summarize]
     S3 --> S3_5[Stage 3.5: UI Style Pattern Extract]
@@ -330,6 +366,17 @@ After generating the entry-dirs JSON:
 
 > **Script execution rule**: All script calls in Stage 2 are executed **directly by the dispatch agent** via `run_in_terminal`. Only the analysis tasks are delegated to Worker Agents.
 
+**Skill Routing Table (by platformType):**
+
+| platformType | skill_name | Description |
+|--------------|------------|-------------|
+| `web` | `speccrew-knowledge-bizs-ui-analyze` | Web frontend (Vue/React/Angular) |
+| `mobile` | `speccrew-knowledge-bizs-ui-analyze` | Mobile apps (Flutter/React Native/UniApp) |
+| `desktop` | `speccrew-knowledge-bizs-ui-analyze` | Desktop apps (Electron/WPF) |
+| `backend` | `speccrew-knowledge-bizs-api-analyze` | Backend APIs (Java/Python/Node.js) |
+
+> **CRITICAL**: Use this routing table to select the correct skill for each feature in Step 2.
+
 #### Execution Flow
 
 Repeat the following 3 steps until all features are processed:
@@ -366,9 +413,7 @@ node -e "require('fs').mkdirSync('{completed_dir}', {recursive: true}); console.
 ⚠️ **CRITICAL**: You MUST launch ALL features in the current batch SIMULTANEOUSLY as parallel Worker Tasks. **FORBIDDEN**: sequential launch (start one Worker, wait, then start next).
 
 For each feature in the `batch` array, prepare a Worker Task:
-- **Skill routing** by `platformType`:
-    - `"web"`, `"mobile"`, `"desktop"` → `skill_name: speccrew-knowledge-bizs-ui-analyze`
-    - `"backend"` → `skill_name: speccrew-knowledge-bizs-api-analyze`
+- **Select skill** using the routing table at Stage 2 start
 - **Worker parameters**: Pass all feature fields plus `language`, `completed_dir`, `sourceFile`, `skill_path`
 - **Behavior constraint**: Worker MUST NOT create any temporary scripts. If execution fails, STOP and report error.
 

package/.speccrew/skills/speccrew-knowledge-bizs-ui-analyze/SKILL.md

@@ -55,20 +55,6 @@ Analyze one specific UI feature from source code, extract business functionality
 
 ## Output
 
-## 🚫 ABSOLUTE PROHIBITIONS (ZERO TOLERANCE)
-
-> **These rules apply to ALL steps. Violation = task failure.**
-
-1. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write the analysis document (`{{documentPath}}`). Documents MUST be created by copying the template (Step 5a) then filling sections with `search_replace` (Step 5b). `create_file` produces truncated output on large files.
-
-2. **FORBIDDEN: File deletion** — NEVER use `Remove-Item`, `del`, `rm`, `fs.unlinkSync`, or any delete command on generated files. If a file is malformed, fix it with `search_replace`.
-
-3. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire document content in a single operation. Always use targeted `search_replace` on specific sections.
-
-4. **MANDATORY: Template-first workflow** — Step 5a (copy template) MUST execute before Step 5b (fill sections). Skipping Step 5a and writing content directly is FORBIDDEN.
-
-## Output (Files)
-
 **Generated Files (MANDATORY - Task is NOT complete until all files are written):**
 1. `{{documentPath}}` - Feature documentation file
 2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
@@ -94,6 +80,12 @@ The return value is used by dispatch to update the feature status in `features-{
 
 ## Workflow
 
+> **⚠️ CRITICAL CONSTRAINTS (apply to ALL steps):**
+> 1. **FORBIDDEN: `create_file` for documents** — Documents MUST be created by copying template (Step 5a) then filling with `search_replace` (Step 5b)
+> 2. **FORBIDDEN: File deletion** — If a file is malformed, fix it with `search_replace`
+> 3. **FORBIDDEN: Full-file rewrite** — Always use targeted `search_replace` on specific sections
+> 4. **MANDATORY: Template-first workflow** — Step 5a MUST execute before Step 5b
+
 ```mermaid
 graph TB
     Start([Start]) --> Step1[Step 1 Read Analysis Template]
@@ -109,13 +101,19 @@ graph TB
 
 ---
 
-### Step 1: Read Analysis Template
+### Step 1: Read Analysis Template (Required before workflow starts)
 
 **Step 1 Status: 🔄 IN PROGRESS**
 
 1. **Check Analysis Status:**
-   - If `{{analyzed}}` is `true`, output "Step 1 Status: ⏭️ SKIPPED (already analyzed)" and skip to Step 6 with status="skipped"
-   - If `{{analyzed}}` is `false`, proceed
+   ```
+   IF {{analyzed}} == true THEN
+       Output "Step 1 Status: ⏭️ SKIPPED (already analyzed)"
+       Skip to Step 6 with status="skipped"
+   ELSE
+       Proceed to next step
+   END IF
+   ```
 
 2. **Read the appropriate template based on platform type:**
    
@@ -290,13 +288,13 @@ Each user interaction or page initialization in the feature file = one business
 - **MUST analyze API call sequences**: identify serial vs parallel calls, try/catch/finally timing, race conditions
 - **MUST document boundary scenarios**: empty data, error branches, state reset, concurrent operations
 - For APIs and shared methods in flowcharts: show name, type, and main function only (no deep analysis)
-- **Generate Mermaid flowcharts following `speccrew-workspace/docs/rules/mermaid-rule.md` guidelines:**
+- **Read Configuration**: Read `speccrew-workspace/docs/rules/mermaid-rule.md` for Mermaid diagram guidelines
+- **Generate Mermaid flowcharts** following the configuration:
   - Use `graph TB` or `graph LR` syntax (not `flowchart`)
-  - No parentheses `()` in node text (e.g., use `open method` instead of `open()`)
+  - No parentheses `()` in node text
   - No HTML tags like `<br/>`
   - No `style` definitions
   - No nested `subgraph`
-  - No special characters in node text
 - Use `{{language}}` for all extracted content naming
 
 4. **Build Graph Data** (per feature file):

package/.speccrew/skills/speccrew-knowledge-module-summarize/SKILL.md

@@ -35,6 +35,8 @@ Read all {{feature_name}}.md files of a specific module, extract and summarize i
 ## Output
 
 - `{{module_path}}/{{module_name}}-overview.md` - Complete module overview (overwritten)
+  - Example: `speccrew-workspace/knowledges/bizs/backend-ai/chat/chat-overview.md`
+  - Example: `speccrew-workspace/knowledges/bizs/web-vue/order/order-overview.md`
 
 ## Workflow
 
@@ -49,16 +51,6 @@ flowchart TD
     Step6 --> End([End])
 ```
 
-### Absolute Constraints
-
-> **These rules apply to ALL steps. Violation = task failure.**
-
-1. **FORBIDDEN: `create_file` for overview document** — NEVER use `create_file` to write the module overview document. If the initial skeleton exists, use `search_replace` to fill sections. If no skeleton exists, copy the template first then fill with `search_replace`.
-
-2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire document content in a single operation. Always use targeted `search_replace` on specific sections.
-
-3. **MANDATORY: Template-first workflow** — Template (or existing skeleton) MUST be in place before filling sections. Writing content without a template base is FORBIDDEN.
-
 ### Step 1: Read Prerequisites
 
 Before processing, read all required files:
@@ -134,6 +126,11 @@ Collect all business rules from feature details:
 
 ### Step 5: Generate Complete MODULE-OVERVIEW.md
 
+**⚠️ CRITICAL CONSTRAINTS (apply to this step):**
+> 1. **FORBIDDEN: `create_file` for overview document** — If skeleton exists, use `search_replace`; if not, copy template first then fill with `search_replace`
+> 2. **FORBIDDEN: Full-file rewrite** — Always use targeted `search_replace` on specific sections
+> 3. **MANDATORY: Template-first workflow** — Template (or existing skeleton) MUST be in place before filling sections
+
 **IMPORTANT**: ALL generated content (entity descriptions, business rules, flow descriptions, section headers, and narrative text) MUST be written in the language specified by the `language` parameter. Only code identifiers, file paths, and technical terms (class names, API endpoints) remain in their original language.
 
 1. **Read Configuration**:

package/.speccrew/skills/speccrew-knowledge-system-summarize/SKILL.md

@@ -37,19 +37,11 @@ Worker Agent (speccrew-task-worker)
 ## Output
 
 - `{{output_path}}/system-overview.md` - Complete system overview
+  - Example (single platform): `speccrew-workspace/knowledges/bizs/system-overview.md`
+  - Example (multi-platform): `speccrew-workspace/knowledges/bizs/system-overview.md` (aggregates all platforms)
 
 ## Workflow
 
-### Absolute Constraints
-
-> **These rules apply to ALL steps. Violation = task failure.**
-
-1. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write the system overview document. It MUST be created by copying the template (Step 7a) then filling sections with `search_replace` (Step 7b). `create_file` produces truncated output on large files.
-
-2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire document content in a single operation. Always use targeted `search_replace` on specific sections.
-
-3. **MANDATORY: Template-first workflow** — Step 7a (copy template) MUST execute before Step 7b (fill sections). Skipping Step 7a and writing content directly is FORBIDDEN.
-
 ### Prerequisites
 
 Before starting, verify:
@@ -216,32 +208,36 @@ Create flow-module mapping matrix:
 
 ### Step 7: Generate system-overview.md
 
+**⚠️ CRITICAL CONSTRAINTS (apply to Step 7a and 7b):**
+> 1. **FORBIDDEN: `create_file` for documents** — Document MUST be created by copying template (Step 7a) then filling with `search_replace` (Step 7b)
+> 2. **FORBIDDEN: Full-file rewrite** — Always use targeted `search_replace` on specific sections
+> 3. **MANDATORY: Template-first workflow** — Step 7a MUST execute before Step 7b
+
+**Step 7a: Prepare Document**
+
 1. **Read Configuration**:
    - Read `speccrew-workspace/docs/configs/tech-stack-mappings.json` → system tech stacks and display names
    - Read `speccrew-workspace/docs/rules/mermaid-rule.md` → Mermaid diagram guidelines
 
-2. **Determine Technology Stack**:
+2. **Invoke** `speccrew-get-timestamp` using Skill tool:
+   - Parameters: none (uses default format `YYYY-MM-DD-HHmmss`)
+   - Returns: timestamp string (e.g., `2026-03-17-132645`)
+   - Use the returned timestamp as generation timestamp in document
+
+3. **Determine Technology Stack**:
    - Extract platform types from discovered module paths
    - Map platform_type to display name via tech-stack-mappings.json
    - Example: `web-vue` → `Vue 3 + TypeScript`; `backend-java` → `Java 17 + Spring Boot`
 
-3. **Get Timestamp**:
-   - **CRITICAL**: Use the Skill tool to invoke `speccrew-get-timestamp` (no parameters needed, uses default format `YYYY-MM-DD-HHmmss`, returns timestamp string e.g. `2026-03-17-132645`)
-   - Use the returned timestamp as generation timestamp in document
-
-4. **Copy template to document path (Step 7a)**:
+4. **Copy template to document path**:
    - Read template: `templates/SYSTEM-OVERVIEW-TEMPLATE.md` (already loaded in Step 0)
    - Replace top-level placeholders (system name, generation timestamp, tech stack info)
-   - Create document using `create_file` at: `output_path/system-overview.md`
+   - Create document using `create_file` at: `{{output_path}}/system-overview.md`
    - Verify: Document has complete section structure ready for filling
 
-5. **Fill each section using search_replace (Step 7b)**:
+**Step 7b: Fill Each Section Using search_replace**
 
-> ⚠️ **CRITICAL CONSTRAINTS:**
-> - **FORBIDDEN: `create_file` to rewrite the entire document** — it destroys template structure
-> - **MUST use `search_replace` to fill each section individually**
-> - **All section titles MUST be preserved**
-> - If a section has no applicable content, keep the section title and replace placeholder with "N/A"
+> ⚠️ **CRITICAL**: Use `search_replace` to fill each section individually. If a section has no applicable content, keep the section title and replace placeholder with "N/A"
 
 **Fill via `search_replace`:**
 

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

@@ -66,7 +66,10 @@ flowchart TB
 
 **Goal**: Scan source code and identify all technology platforms.
 
-**Action**:
+**Step 1a: Read Configuration**
+- Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized platform mapping rules
+
+**Step 1b: Invoke Worker**
 - Invoke 1 Worker Agent (`speccrew-task-worker.md`) with skill `speccrew-knowledge-techs-init/SKILL.md`
 - Task: Analyze project structure, detect technology platforms
 - Parameters to pass to skill:
@@ -79,55 +82,7 @@ flowchart TB
 
 See [templates/techs-manifest-EXAMPLE.json](templates/techs-manifest-EXAMPLE.json) for complete example.
 
-### Platform Status Tracking Fields
-
-Each platform entry in techs-manifest.json includes status tracking fields for monitoring the analysis pipeline progress:
-
-| Field | Type | Values | Description |
-|-------|------|--------|-------------|
-| `status` | string | `pending` / `processing` / `completed` / `partial` / `failed` | Current analysis status |
-| `startedAt` | string \| null | ISO 8601 timestamp | When the Worker started analyzing this platform |
-| `completedAt` | string \| null | ISO 8601 timestamp | When the Worker finished analyzing this platform |
-| `analysisLevel` | string \| null | `full` / `minimal` / `reference_only` | Depth of analysis achieved |
-| `topicsCoverage` | number \| null | 0-100 | Percentage of domain topics covered (from analysis.json) |
-| `workers` | object | See below | Per-worker status tracking |
-
-**Workers Object Structure:**
-```json
-{
-  "platform_id": "web-vue",
-  "status": "completed",
-  "workers": {
-    "conventions": {
-      "status": "completed",
-      "skill": "speccrew-knowledge-techs-generate-conventions",
-      "done_file": "web-vue.done-conventions.json"
-    },
-    "ui_style": {
-      "status": "completed",
-      "skill": "speccrew-knowledge-techs-generate-ui-style",
-      "done_file": "web-vue.done-ui-style.json"
-    }
-  }
-}
-```
-
-For backend platforms, `ui_style.status` is set to `"skipped"`.
-
-**Status Lifecycle:**
-```
-pending → processing → completed
-                    → partial (conventions OK, ui-style failed)
-                    → failed
-```
-
-**Stage 1 (techs-init)**: All platforms initialized with `status: "pending"`, other tracking fields set to `null`.
-
-**Stage 2 (techs-generate)**: 
-- Before launching Workers: Set `status: "processing"`, `startedAt: "{now}"`, set both workers status to `"processing"`
-- After all Workers complete successfully: Set `status: "completed"`, `completedAt: "{now}"`, populate `analysisLevel` and `topicsCoverage` from Worker output
-- After conventions Worker fails: Set `status: "failed"`, `completedAt: "{now}"`
-- After ui-style Worker fails (but conventions succeeded): Set `status: "partial"`, `completedAt: "{now}"`
+See [Platform Status Tracking Fields](#platform-status-tracking-fields) for status field definitions.
 
 ---
 
@@ -157,102 +112,57 @@ When launching each platform Worker, the Workers will output:
 - `{completed_dir}/{platform_id}.analysis-conventions.json` — conventions coverage report
 - `{completed_dir}/{platform_id}.analysis-ui-style.json` — ui-style coverage report (frontend only)
 
-**Parallel Execution Logic**:
-
-```
-# Ensure completed_dir exists before launching Workers
-completed_dir = "speccrew-workspace/knowledges/techs/.sync-status/"
-CREATE_DIRECTORY IF NOT EXISTS completed_dir
-
-FOR each platform IN manifest.platforms:
-  # Update manifest before launching Workers
-  SET platform.status = "processing"
-  SET platform.startedAt = "{current_timestamp}"
-  SET platform.workers.conventions.status = "processing"
-  IF platform.platform_type IN ["web", "mobile", "desktop"]:
-    SET platform.workers.ui_style.status = "processing"
-  WRITE manifest to techs-manifest.json
-  
-  # Worker 1: Conventions (ALL platforms)
-  INVOKE speccrew-task-worker WITH:
-    - skill_path: "speccrew-knowledge-techs-generate-conventions/SKILL.md"
-    - context:
-        platform_id: platform.platform_id
-        platform_type: platform.platform_type
-        framework: platform.framework
-        source_path: platform.source_path
-        config_files: platform.config_files
-        convention_files: platform.convention_files
-        output_path: "speccrew-workspace/knowledges/techs/{platform.platform_id}/"
-        completed_dir: completed_dir
-        language: language
-  
-  # Worker 2: UI-Style (frontend platforms ONLY)
-  IF platform.platform_type IN ["web", "mobile", "desktop"]:
-    INVOKE speccrew-task-worker WITH:
-      - skill_path: "speccrew-knowledge-techs-generate-ui-style/SKILL.md"
-      - context:
-          platform_id: platform.platform_id
-          platform_type: platform.platform_type
-          framework: platform.framework
-          source_path: platform.source_path
-          output_path: "speccrew-workspace/knowledges/techs/{platform.platform_id}/"
-          completed_dir: completed_dir
-          language: language
-  
-  # Both workers run in PARALLEL for the same platform
-    
-WAIT_ALL workers complete
-```
+**Step 2a: Prepare Environment and Update Manifest**
+
+1. Ensure completed_dir exists: `speccrew-workspace/knowledges/techs/.sync-status/`
+2. For each platform in manifest:
+   - SET `platform.status = "processing"`
+   - SET `platform.startedAt = "{current_timestamp}"`
+   - SET `platform.workers.conventions.status = "processing"`
+   - IF platform.platform_type IN ["web", "mobile", "desktop"]: SET `platform.workers.ui_style.status = "processing"`
+   - WRITE manifest to techs-manifest.json
+
+**Step 2b: Launch Conventions Worker (ALL Platforms)**
+
+For each platform, invoke `speccrew-task-worker` with:
+- skill_path: `speccrew-knowledge-techs-generate-conventions/SKILL.md`
+- context:
+  - platform_id: platform.platform_id
+  - platform_type: platform.platform_type
+  - framework: platform.framework
+  - source_path: platform.source_path
+  - config_files: platform.config_files
+  - convention_files: platform.convention_files
+  - output_path: `speccrew-workspace/knowledges/techs/{platform.platform_id}/`
+  - completed_dir: completed_dir
+  - language: language
+
+**Step 2c: Launch UI-Style Worker (Frontend Platforms ONLY)**
+
+IF platform.platform_type IN ["web", "mobile", "desktop"]:
+1. Invoke `speccrew-task-worker` with:
+   - skill_path: `speccrew-knowledge-techs-generate-ui-style/SKILL.md`
+   - context:
+     - platform_id: platform.platform_id
+     - platform_type: platform.platform_type
+     - framework: platform.framework
+     - source_path: platform.source_path
+     - output_path: `speccrew-workspace/knowledges/techs/{platform.platform_id}/`
+     - completed_dir: completed_dir
+     - language: language
+
+**Step 2d: Wait for All Workers**
+- WAIT_ALL workers complete
+- Both workers run in PARALLEL for the same platform
 
 ### Worker Completion Marker (MANDATORY)
 
-After generating all documents and the analysis report, each Worker MUST create a completion marker file:
-
-#### Conventions Worker Done File
-
-**File**: `{completed_dir}/{platform_id}.done-conventions.json`
-
-**Format**:
-```json
-{
-  "platform_id": "web-vue",
-  "worker_type": "conventions",
-  "status": "completed",
-  "documents_generated": [
-    "INDEX.md", "tech-stack.md", "architecture.md",
-    "conventions-dev.md", "conventions-design.md",
-    "conventions-unit-test.md", "conventions-build.md"
-  ],
-  "analysis_file": "web-vue.analysis-conventions.json",
-  "completed_at": "2024-01-15T10:45:00Z"
-}
-```
+Each Worker MUST create a completion marker file after generating documents. See [Worker Completion Marker Format](#worker-completion-marker-format) for details.
 
-#### UI-Style Worker Done File
+- Conventions Worker: `{completed_dir}/{platform_id}.done-conventions.json`
+- UI-Style Worker: `{completed_dir}/{platform_id}.done-ui-style.json` (frontend only)
 
-**File**: `{completed_dir}/{platform_id}.done-ui-style.json`
-
-**Format**:
-```json
-{
-  "platform_id": "web-vue",
-  "worker_type": "ui-style",
-  "status": "completed",
-  "ui_analysis_level": "full",
-  "documents_generated": [
-    "ui-style/ui-style-guide.md"
-  ],
-  "analysis_file": "web-vue.analysis-ui-style.json",
-  "completed_at": "2024-01-15T10:45:00Z"
-}
-```
-
-**Status values**:
-- `completed` — All required documents generated successfully
-- `failed` — Critical failure, required documents not generated
-
-If a Worker encounters a fatal error, it should still attempt to create the done file with `status: "failed"` and include error details in an `"error"` field.
+**Status values**: `completed` | `failed`
 
 **Output per Platform**:
 ```
@@ -301,14 +211,7 @@ speccrew-workspace/knowledges/techs/{platform_id}/
 - `total_platforms`, `completed`, `failed` counts
 - Per-platform: `documents_generated` list
 
----
-
-## Stage 2 Post-Processing: Validate Worker Output
-
-**Trigger**: After ALL platform Workers have completed (or timed out)
-**Purpose**: Validate Worker output via completion markers and update manifest status
-
-**Step 2a: Scan Completion Markers**
+**Step 2e: Scan Completion Markers**
 
 For each platform in the manifest:
 1. Check for `{platform_id}.done-conventions.json` (REQUIRED for all platforms)
@@ -316,21 +219,21 @@ For each platform in the manifest:
 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)
 
-**Step 2b: Verify Document Output**
+**Step 2f: 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
 - If any required document is missing → downgrade status accordingly
 
-**Step 2c: Read Coverage Reports**
+**Step 2g: Read Coverage 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
 
-**Step 2d: Update Manifest Status**
+**Step 2h: Update Manifest Status**
 
 Update `techs-manifest.json` for each platform:
 - Set `status` based on worker results:
@@ -346,7 +249,7 @@ Update `techs-manifest.json` for each platform:
   - `"reference_only"` if critical docs missing or Worker failed
 - Set `topicsCoverage` from analysis-conventions.json coverage_percent
 
-**Step 2e: Handle Failures**
+**Step 2i: Handle Failures**
 
 For platforms with conventions worker `status: "failed"`:
 - Mark platform as `failed`
@@ -681,3 +584,98 @@ After all 3 stages complete, return a summary object to the caller:
   }
 }
 ```
+
+---
+
+## Reference Guides
+
+### Worker Completion Marker Format
+
+Each Worker MUST create a completion marker file after generating documents.
+
+#### Conventions Worker Done File
+
+**File**: `{completed_dir}/{platform_id}.done-conventions.json`
+
+**Format**:
+```json
+{
+  "platform_id": "web-vue",
+  "worker_type": "conventions",
+  "status": "completed",
+  "documents_generated": [
+    "INDEX.md", "tech-stack.md", "architecture.md",
+    "conventions-dev.md", "conventions-design.md",
+    "conventions-unit-test.md", "conventions-build.md"
+  ],
+  "analysis_file": "web-vue.analysis-conventions.json",
+  "completed_at": "2024-01-15T10:45:00Z"
+}
+```
+
+#### UI-Style Worker Done File
+
+**File**: `{completed_dir}/{platform_id}.done-ui-style.json`
+
+**Format**:
+```json
+{
+  "platform_id": "web-vue",
+  "worker_type": "ui-style",
+  "status": "completed",
+  "ui_analysis_level": "full",
+  "documents_generated": [
+    "ui-style/ui-style-guide.md"
+  ],
+  "analysis_file": "web-vue.analysis-ui-style.json",
+  "completed_at": "2024-01-15T10:45:00Z"
+}
+```
+
+**Status values**:
+- `completed` — All required documents generated successfully
+- `failed` — Critical failure, required documents not generated
+
+If a Worker encounters a fatal error, it should still attempt to create the done file with `status: "failed"` and include error details in an `"error"` field.
+
+### Platform Status Tracking Fields
+
+Each platform entry in techs-manifest.json includes status tracking fields for monitoring the analysis pipeline progress:
+
+| Field | Type | Values | Description |
+|-------|------|--------|-------------|
+| `status` | string | `pending` / `processing` / `completed` / `partial` / `failed` | Current analysis status |
+| `startedAt` | string \| null | ISO 8601 timestamp | When the Worker started analyzing this platform |
+| `completedAt` | string \| null | ISO 8601 timestamp | When the Worker finished analyzing this platform |
+| `analysisLevel` | string \| null | `full` / `minimal` / `reference_only` | Depth of analysis achieved |
+| `topicsCoverage` | number \| null | 0-100 | Percentage of domain topics covered (from analysis.json) |
+| `workers` | object | See below | Per-worker status tracking |
+
+**Workers Object Structure:**
+```json
+{
+  "platform_id": "web-vue",
+  "status": "completed",
+  "workers": {
+    "conventions": {
+      "status": "completed",
+      "skill": "speccrew-knowledge-techs-generate-conventions",
+      "done_file": "web-vue.done-conventions.json"
+    },
+    "ui_style": {
+      "status": "completed",
+      "skill": "speccrew-knowledge-techs-generate-ui-style",
+      "done_file": "web-vue.done-ui-style.json"
+    }
+  }
+}
+```
+
+For backend platforms, `ui_style.status` is set to `"skipped"`.
+
+**Status Lifecycle:**
+```
+pending → processing → completed
+                    → partial (conventions OK, ui-style failed)
+                    → failed
+```