speccrew 0.1.12 → 0.2.1

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

@@ -71,8 +71,8 @@ Analyze one specific UI feature from source code, extract business functionality
 
 **Generated Files (MANDATORY - Task is NOT complete until all files are written):**
 1. `{{documentPath}}` - Feature documentation file
-2. `{{completed_dir}}/{{fileName}}.done.json` - Completion status marker
-3. `{{completed_dir}}/{{fileName}}.graph.json` - Graph data marker
+2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
+3. `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json` - Graph data marker
 
 **Return Value (JSON format):**
 ```json
@@ -808,7 +808,7 @@ After analysis is complete, write the results to marker files for dispatch to pr
 > **ASSUMPTION**: The `completed_dir` directory already exists (pre-created by dispatch Stage 2). If write fails, report error — do NOT attempt to create directories.
 
 ### Pre-write Checklist (VERIFY before writing each file):
-- [ ] Filename follows `{fileName}` pattern (file name only)
+- [ ] Filename follows `{module}-{subpath}-{fileName}` pattern (see naming convention below)
 - [ ] File content is valid JSON (not empty)
 - [ ] All required fields are present and non-empty
 - [ ] File is written with UTF-8 encoding
@@ -829,30 +829,57 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
 **✅ CORRECT Format - MUST USE:**
 ```
-{completed_dir}/{fileName}.done.json     ← Completion status marker (JSON format)
-{completed_dir}/{fileName}.graph.json    ← Graph data marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.done.json     ← Completion status marker (JSON format)
+{completed_dir}/{module}-{subpath}-{fileName}.graph.json    ← Graph data marker (JSON format)
 ```
 
+**Naming Rule Explanation:**
+
+The marker filename MUST follow the composite naming pattern `{module}-{subpath}-{fileName}` to prevent conflicts between same-named source files.
+
+**How to Extract Each Component from `{{sourcePath}}`:**
+
+1. **module**: Use `{{module}}` input variable directly (e.g., `system`, `trade`, `bpm`)
+
+2. **subpath**: Extract the middle path between the platform source root and the file name:
+   - Remove the top-level directory prefix (e.g., `yudao-ui/yudao-ui-admin-vue3/src/views/`)
+   - Remove the file name at the end
+   - Replace path separators (`/`) with hyphens (`-`)
+   - If the file is at the module root directory, subpath will be empty → omit from filename
+
+3. **fileName**: Use `{{fileName}}` input variable (file name WITHOUT extension)
+
 **Examples:**
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.done.json`
-- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.graph.json`
+
+| sourcePath | module | subpath | fileName | Marker Filename |
+|------------|--------|---------|----------|-----------------|
+| `yudao-ui/yudao-ui-admin-vue3/src/views/system/notify/message/index.vue` | `system` | `notify-message` | `index` | `system-notify-message-index.done.json` |
+| `yudao-ui/yudao-ui-admin-vue3/src/views/system/user/index.vue` | `system` | `user` | `index` | `system-user-index.done.json` |
+| `yudao-ui/yudao-ui-admin-vue3/src/views/bpm/process-instance/index.vue` | `bpm` | `process-instance` | `index` | `bpm-process-instance-index.done.json` |
+
+**Special Case - Empty subpath:**
+- If the file is directly in the module root directory (no subpath), use format: `{module}-{fileName}.done.json`
+- Example: `yudao-ui/yudao-ui-admin-vue3/src/views/system/index.vue` → `system-index.done.json`
+
+**Full Path Examples:**
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
+- `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-user-index.graph.json`
 
 **❌ WRONG Format - NEVER USE:**
 ```
-{fileName}.completed.json    ← WRONG extension
-{fileName}.done              ← WRONG extension (missing .json)
-{fileName}.done.txt          ← WRONG extension
-{fileName}_done.json         ← WRONG separator and extension
-{fileName}-completed.json    ← WRONG separator and extension
+{fileName}.done.json              ← WRONG: missing module and subpath (causes conflicts)
+{fileName}.graph.json             ← WRONG: missing module and subpath (causes conflicts)
+{module}-{fileName}.done.json     ← WRONG: missing subpath (may still conflict)
+{fileName}.completed.json         ← WRONG extension
+{fileName}.done                   ← WRONG extension (missing .json)
+{fileName}_done.json              ← WRONG separator and extension
 ```
 
 **❌ WRONG Filename Examples - NEVER USE:**
+- `index.done.json` - WRONG: missing module and subpath (conflicts with other `index.vue` files)
+- `system-index.done.json` - WRONG: missing subpath (if file is in `system/notify/message/`)
 - `index.completed.json` - WRONG: uses `.completed.json` instead of `.done.json`
-- `index.done` - WRONG: uses `.done` instead of `.done.json`
-- `index.done.txt` - WRONG: uses `.done.txt` instead of `.done.json`
 - `index_done.json` - WRONG: uses underscore and wrong extension
-- `dict-index.done.json` - WRONG: has module prefix
-- `system-index.done.json` - WRONG: has module prefix
 
 ---
 
@@ -942,9 +969,9 @@ After analysis is complete, write the results to marker files for dispatch to pr
    > {"fileName": "index", "status": "success", ...}
    > ```
 
-   Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.done.json`:
+   Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json`:
    
-   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.done.json`
+   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.done.json`
 
    **Complete JSON Template (ALL fields required):**
    ```json
@@ -981,12 +1008,13 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
    > **⚠️ CRITICAL**: The `documentPath` field is MANDATORY. It MUST match the `{{documentPath}}` variable from Step 5a. This is used to verify the document was created successfully.
 
-   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.done.json`, where `fileName` is the feature file name (e.g., `index`, `UserForm`, `AiKnowledgeDocumentCreateListReqVO`).
-   - ✅ CORRECT: `index.done.json` (using file name directly)
-   - ✅ CORRECT: `UserForm.done.json` (using file name directly)
+   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.done.json` to prevent conflicts between same-named files.
+   - ✅ CORRECT: `system-notify-message-index.done.json` (full composite naming)
+   - ✅ CORRECT: `system-user-index.done.json` (full composite naming)
+   - ✅ CORRECT: `bpm-index.done.json` (when subpath is empty, file at module root)
+   - ❌ WRONG: `index.done.json` (missing module and subpath - will conflict)
    - ❌ WRONG: `index.done` (missing .json extension)
-   - ❌ WRONG: `dict-index.done.json` (using old featureId format)
-   - ❌ WRONG: `system-index.done.json` (using module prefix)
+   - ❌ WRONG: `system-index.done.json` (missing subpath when file is in nested directory)
 
    ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -994,9 +1022,9 @@ After analysis is complete, write the results to marker files for dispatch to pr
 
    > **⚠️ CRITICAL FORMAT REQUIREMENT**: The `.graph.json` file MUST be valid JSON and **MUST include the root-level `module` field**. Do NOT rely on scripts to infer the module from `.done` file - the `module` field MUST be explicitly present at the root level of `.graph.json`.
 
-   Use the Write tool to create file at `{{completed_dir}}/{{fileName}}.graph.json`:
+   Use the Write tool to create file at `{{completed_dir}}/{module}-{subpath}-{fileName}.graph.json`:
    
-   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/index.graph.json`
+   **Full path example:** `d:/dev/speccrew/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed/system-notify-message-index.graph.json`
 
    ```json
    {
@@ -1031,11 +1059,13 @@ After analysis is complete, write the results to marker files for dispatch to pr
    > - Do NOT assume scripts will fall back to reading from `.done` file
    > - Missing `module` field will cause the graph merge pipeline to reject this file
 
-   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{fileName}.graph.json`, where `fileName` is the feature file name (e.g., `index`, `UserForm`, `AiKnowledgeDocumentCreateListReqVO`).
-   - ✅ CORRECT: `index.graph.json` (using file name directly)
-   - ✅ CORRECT: `UserForm.graph.json` (using file name directly)
+   ⚠️ **CRITICAL NAMING RULE:** Filename MUST be `{module}-{subpath}-{fileName}.graph.json` to prevent conflicts between same-named files.
+   - ✅ CORRECT: `system-notify-message-index.graph.json` (full composite naming)
+   - ✅ CORRECT: `system-user-index.graph.json` (full composite naming)
+   - ✅ CORRECT: `bpm-index.graph.json` (when subpath is empty, file at module root)
+   - ❌ WRONG: `index.graph.json` (missing module and subpath - will conflict)
    - ❌ WRONG: `dict-index.graph.json` (using old featureId format)
-   - ❌ WRONG: `system-index.graph.json` (using module prefix)
+   - ❌ WRONG: `system-index.graph.json` (missing subpath when file is in nested directory)
 
    ⚠️ **CRITICAL:** The file MUST contain valid JSON content. Empty files or files with only whitespace will cause processing failures.
 
@@ -1047,7 +1077,7 @@ After analysis is complete, write the results to marker files for dispatch to pr
    - [ ] Each `calls` edge has proper metadata with trigger information
    - [ ] No API import is left without a corresponding edge
 
-**Output:** "Step 7 Status: ✅ COMPLETED - Marker files written ({{completed_dir}}/{{fileName}}.done, .graph.json)"
+**Output:** "Step 7 Status: ✅ COMPLETED - Marker files written ({{completed_dir}}/{module}-{subpath}-{fileName}.done.json, .graph.json)"
 
 **On Failure:** "Step 7 Status: ⚠️ PARTIAL - Marker file write failed, but analysis completed"
 

package/.speccrew/skills/speccrew-pm-requirement-analysis/SKILL.md

@@ -442,6 +442,69 @@ Please confirm the following key points:
 
 After confirmation, you can start the Solution Agent for solution planning.
 
+## Step 13: Write Progress Files
+
+After user confirms the PRD, write progress tracking files:
+
+### 13a Write Checkpoint File
+
+Write or update the checkpoint file at:
+```
+speccrew-workspace/iterations/{iteration}/01.product-requirement/.checkpoints.json
+```
+
+Content:
+```json
+{
+  "stage": "01_prd",
+  "checkpoints": {
+    "prd_review": {
+      "passed": true,
+      "confirmed_at": "<current-ISO-timestamp>",
+      "description": "PRD review and confirmation"
+    }
+  }
+}
+```
+
+### 13b Update Workflow Progress
+
+Read and update the WORKFLOW-PROGRESS.json file:
+
+1. **Read**: `speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json`
+2. **Update the following fields**:
+   - `current_stage` = "02_feature_design"
+   - `01_prd.status` = "confirmed"
+   - `01_prd.completed_at` = `<current-ISO-timestamp>`
+   - `01_prd.confirmed_at` = `<current-ISO-timestamp>`
+   - `01_prd.outputs` = `["01.product-requirement/{feature-name}-prd.md"]`
+
+**Example updated stage entry**:
+```json
+{
+  "01_prd": {
+    "status": "confirmed",
+    "started_at": "2026-04-08T10:00:00Z",
+    "completed_at": "2026-04-08T11:30:00Z",
+    "confirmed_at": "2026-04-08T11:35:00Z",
+    "outputs": [
+      "01.product-requirement/user-management-prd.md"
+    ]
+  }
+}
+```
+
+### 13c Handle Missing Progress File
+
+If WORKFLOW-PROGRESS.json does not exist (backward compatibility):
+- Create the file with initial structure
+- Set `01_prd` to confirmed state directly
+- Other stages remain as `pending`
+
+**Status Flow**: `pending` → `in_progress` → `completed` → `confirmed`
+
+---
+
 # Knowledge Loading Strategy
 
 1. **First**: Read `system-overview.md` for system context
@@ -473,3 +536,5 @@ After confirmation, you can start the Solution Agent for solution planning.
 - [ ] **[If modifying existing features]** All changes marked with [EXISTING]/[MODIFIED]/[NEW]
 - [ ] Files written to correct paths
 - [ ] Summary shown to user and confirmation requested
+- [ ] **[After confirmation]** Checkpoint file written to `01.product-requirement/.checkpoints.json`
+- [ ] **[After confirmation]** WORKFLOW-PROGRESS.json updated with confirmed status and outputs

package/.speccrew/skills/speccrew-sd-backend/SKILL.md

@@ -191,6 +191,44 @@ Files Generated:
 - {list all file paths}
 ```
 
+## Step 7: Task Completion Report
+
+After completing all steps, output a structured completion report for the System Designer Agent to parse and update DISPATCH-PROGRESS.json:
+
+### On Success
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**:
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+- **Summary**: Backend system design completed for {feature_name} on {platform_id} with {count} module designs
+```
+
+### On Failure
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**: []
+- **Error**: {description of what went wrong}
+- **Error Category**: DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED
+- **Recovery Hint**: {suggestion for how to resolve or retry}
+```
+
+**Error Categories:**
+- `DEPENDENCY_MISSING`: Required input file or knowledge document not found
+- `VALIDATION_ERROR`: Input validation failed (e.g., invalid Feature Spec format)
+- `BLOCKED`: Blocked by external dependency or prerequisite not met
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-sd-desktop/SKILL.md

@@ -208,6 +208,44 @@ Concerns/Trade-offs:
 4. Are all API calls from API Contract covered?
 5. Is the native integration approach suitable?
 
+## Step 7: Task Completion Report
+
+After completing all steps, output a structured completion report for the System Designer Agent to parse and update DISPATCH-PROGRESS.json:
+
+### On Success
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**:
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+- **Summary**: Desktop system design completed for {feature_name} on {platform_id} with {count} module designs
+```
+
+### On Failure
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**: []
+- **Error**: {description of what went wrong}
+- **Error Category**: DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED
+- **Recovery Hint**: {suggestion for how to resolve or retry}
+```
+
+**Error Categories:**
+- `DEPENDENCY_MISSING`: Required input file or knowledge document not found
+- `VALIDATION_ERROR`: Input validation failed (e.g., invalid Feature Spec format)
+- `BLOCKED`: Blocked by external dependency or prerequisite not met
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-sd-frontend/SKILL.md

@@ -196,6 +196,44 @@ Concerns/Trade-offs:
 3. Do the pseudo-code patterns match project conventions?
 4. Are all API calls from API Contract covered?
 
+## Step 7: Task Completion Report
+
+After completing all steps, output a structured completion report for the System Designer Agent to parse and update DISPATCH-PROGRESS.json:
+
+### On Success
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**:
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+- **Summary**: Frontend system design completed for {feature_name} on {platform_id} with {count} module designs
+```
+
+### On Failure
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**: []
+- **Error**: {description of what went wrong}
+- **Error Category**: DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED
+- **Recovery Hint**: {suggestion for how to resolve or retry}
+```
+
+**Error Categories:**
+- `DEPENDENCY_MISSING`: Required input file or knowledge document not found
+- `VALIDATION_ERROR`: Input validation failed (e.g., invalid Feature Spec format)
+- `BLOCKED`: Blocked by external dependency or prerequisite not met
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-sd-mobile/SKILL.md

@@ -204,6 +204,44 @@ Concerns/Trade-offs:
 4. Are all API calls from API Contract covered?
 5. Are platform-specific features (permissions, native integration) properly handled?
 
+## Step 7: Task Completion Report
+
+After completing all steps, output a structured completion report for the System Designer Agent to parse and update DISPATCH-PROGRESS.json:
+
+### On Success
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**:
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+- **Summary**: Mobile system design completed for {feature_name} on {platform_id} with {count} module designs
+```
+
+### On Failure
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from context}
+- **Platform**: {platform_id}
+- **Feature**: {feature_name}
+- **Output Files**: []
+- **Error**: {description of what went wrong}
+- **Error Category**: DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED
+- **Recovery Hint**: {suggestion for how to resolve or retry}
+```
+
+**Error Categories:**
+- `DEPENDENCY_MISSING`: Required input file or knowledge document not found
+- `VALIDATION_ERROR`: Input validation failed (e.g., invalid Feature Spec format)
+- `BLOCKED`: Blocked by external dependency or prerequisite not met
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-test-case-design/SKILL.md

@@ -302,3 +302,36 @@ Fill each section with test case data using `search_replace`.
 - [ ] Preconditions are clearly stated for each test case
 - [ ] Steps are detailed enough for execution without ambiguity
 - [ ] Document written to correct output path
+
+---
+
+# Task Completion Report
+
+Upon completion (success or failure), output the following report format:
+
+## Success Report
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: <from dispatch context, e.g., "test-case-web-vue">
+- **Platform**: <platform_id, e.g., "web-vue">
+- **Phase**: test_case_design
+- **Output Files**:
+  - `speccrew-workspace/iterations/{iteration}/05.system-test/cases/{platform_id}/[feature]-test-cases.md`
+- **Summary**: Test case design completed with {count} test cases covering {dimensions} dimensions
+```
+
+## Failure Report
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: <from dispatch context>
+- **Platform**: <platform_id>
+- **Phase**: test_case_design
+- **Output Files**: None
+- **Summary**: Test case design failed during {step}
+- **Error**: <detailed error description>
+- **Error Category**: DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED
+- **Partial Outputs**: <list of partially generated files or "None">
+- **Recovery Hint**: <suggestion for recovery, e.g., "Check feature spec document exists at specified path">
+```

package/.speccrew/skills/speccrew-test-code-gen/SKILL.md

@@ -344,3 +344,37 @@ Fill each section with code plan data from Step 4.
 - [ ] Shared fixtures and helpers are extracted properly
 - [ ] Arrange-Act-Assert structure maintained in tests
 - [ ] Code plan document written to correct path
+
+---
+
+# Task Completion Report
+
+Upon completion (success or failure), output the following report format:
+
+## Success Report
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: <from dispatch context, e.g., "test-code-web-vue">
+- **Platform**: <platform_id, e.g., "web-vue">
+- **Phase**: test_code_gen
+- **Output Files**:
+  - `speccrew-workspace/iterations/{iteration}/05.system-test/code/{platform_id}/[feature]-test-code-plan.md`
+  - <list of generated test source files>
+- **Summary**: Test code generation completed with {file_count} files covering {case_count} test cases
+```
+
+## Failure Report
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: <from dispatch context>
+- **Platform**: <platform_id>
+- **Phase**: test_code_gen
+- **Output Files**: <list of partial outputs or "None">
+- **Summary**: Test code generation failed during {step}
+- **Error**: <detailed error description>
+- **Error Category**: DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED
+- **Partial Outputs**: <list of partially generated files or "None">
+- **Recovery Hint**: <suggestion for recovery, e.g., "Verify test case document format is valid">
+```

package/.speccrew/skills/speccrew-test-execute/SKILL.md

@@ -291,3 +291,37 @@ Each bug report must include:
 - [ ] Bug severity is classified (Critical/High/Medium/Low)
 - [ ] All bug reports written to correct output path
 - [ ] Test report written to correct output path
+
+---
+
+# Task Completion Report
+
+Upon completion (success or failure), output the following report format:
+
+## Success Report
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: <from dispatch context, e.g., "test-exec-web-vue">
+- **Platform**: <platform_id, e.g., "web-vue">
+- **Phase**: test_execution
+- **Output Files**:
+  - `speccrew-workspace/iterations/{iteration}/05.system-test/reports/[feature]-test-report.md`
+  - `speccrew-workspace/iterations/{iteration}/05.system-test/bugs/[feature]-bug-{seq}.md` (if any failures)
+- **Summary**: Test execution completed with {passed}/{total} passed, {failed} failed, {skipped} skipped
+```
+
+## Failure Report
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: <from dispatch context>
+- **Platform**: <platform_id>
+- **Phase**: test_execution
+- **Output Files**: <list of partial outputs or "None">
+- **Summary**: Test execution failed during {step}
+- **Error**: <detailed error description>
+- **Error Category**: DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED
+- **Partial Outputs**: <list of partially generated files or "None">
+- **Recovery Hint**: <suggestion for recovery, e.g., "Check test dependencies are installed and test configuration is valid">
+```

package/README.ar.md

@@ -41,6 +41,58 @@ SpecCrew هو إطار عمل مدمج لفريق تطوير افتراضي با
 
 ---
 
+## ✨ الميزات الرئيسية
+
+### 🏭 فريق البرمجيات الافتراضي
+توليد بنقرة واحدة **7 أدوار وكيل احترافية** + **30+ سير عمل للمهارات**، بناء فريق برمجيات افتراضي كامل:
+- **Team Leader** - الجدولة العالمية وإدارة التكرارات
+- **Product Manager** - تحليل المتطلبات وإخراج PRD
+- **Feature Designer** - تصميم الميزات + عقود API
+- **System Designer** - تصميم الأنظمة Frontend/Backend/Mobile/Desktop
+- **System Developer** - التطوير المتوازي متعدد المنصات
+- **Test Manager** - تنسيق الاختبار في ثلاث مراحل
+- **Task Worker** - تنفيذ المهام الفرعية المتوازية
+
+### 📐 نمذجة ISA-95 ذات المراحل الست
+استنادًا إلى منهجية النمذجة الدولية **ISA-95**، توحيد تحويل متطلبات الأعمال إلى أنظمة البرمجيات:
+```
+Domain Descriptions → Functions in Domains → Functions of Interest
+     ↓                       ↓                      ↓
+Information Flows → Categories of Information → Information Descriptions
+```
+- كل مرحلة تتوافق مع مخططات UML محددة (حالات الاستخدام، التسلسل، الفئات)
+- متطلبات الأعمال "تُصقل خطوة بخطوة"، بدون فقدان المعلومات
+- المخرجات قابلة للاستخدام مباشرة في التطوير
+
+### 📚 نظام قاعدة المعرفة
+بنية قاعدة معرفية من ثلاثة مستويات تضمن عمل الذكاء الاصطناعي دائمًا استنادًا إلى "مصدر الحقيقة الوحيد":
+
+| المستوى | الدليل | المحتوى | الغرض |
+|---------|--------|---------|--------|
+| L1 معرفة النظام | `knowledge/techs/` | مجموعة التقنيات، البنية، الاتفاقيات | الذكاء الاصطناعي يفهم الحدود التقنية للمشروع |
+| L2 معرفة الأعمال | `knowledge/bizs/` | وظائف الوحدات، تدفقات الأعمال، الكيانات | الذكاء الاصطناعي يفهم منطق الأعمال |
+| L3 منتجات التكرار | `iterations/iXXX/` | PRD، وثائق التصميم، تقارير الاختبار | سلسلة التتبع الكاملة للمتطلبات الحالية |
+
+### 🔄 خط أنابيب المعرفة ذي الأربع مراحل
+**بنية توليد المعرفة الآلية**، توليد تلقائي لوثائق الأعمال/التقنية من الكود المصدري:
+```
+المرحلة 1: مسح الكود المصدري → توليد قائمة الوحدات
+المرحلة 2: التحليل المتوازي → استخراج الميزات (عاملين متعددين متوازيًا)
+المرحلة 3: التلخيص المتوازي → إكمال نظرة عامة على الوحدات (عاملين متعددين متوازيًا)
+المرحلة 4: تجميع النظام → توليد بانوراما النظام
+```
+- يدعم **المزامنة الكاملة** و**المزامنة التزايدي** (استنادًا إلى Git diff)
+- شخص واحد يحسن، الفريق يشارك
+
+### 🔧 Harness إطار التنفيذ العملي
+**إطار تنفيذ موحد**، يضمن تحويل مستندات التصميم بدقة إلى تعليمات تطوير قابلة للتنفيذ:
+- **مبدأ دليل العمليات**: Skill هو SOP، خطوات واضحة ومتتالية ومكتملة ذاتياً
+- **عقد المدخلات والمخرجات**: تعريف واضح للواجهات، تنفيذ صارم مثل الكود الزائف
+- **بنية الإفصاح التدريجي**: تحميل الطبقات للمعلومات، تجنب التحميل الزائد للسياق
+- **تفويض الوكلاء الفرعيين**: المهام المعقدة تُقسم تلقائياً، التنفيذ المتوازي يضمن الجودة
+
+---
+
 ## 8 مشاكل أساسية تم حلها
 
 ### 1. الذكاء الاصطناعي يتجاهل توثيق المشروع الحالي (فجوة المعرفة)
@@ -189,7 +241,7 @@ speccrew init --ide claude
 
 بعد التهيئة، سيتم إنشاء ما يلي في مشروعك:
 - `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 تعريفات أدوار Agent
-- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 38 سير عمل Skill
+- `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 30+ سير عمل Skill
 - `speccrew-workspace/` — مساحة العمل (أدلة التكرار، قاعدة المعرفة، قوالب المستندات)
 - `.speccrewrc` — ملف تكوين SpecCrew
 
@@ -213,7 +265,22 @@ speccrew update --ide claude
 
 > تتطلب مخرجات كل مرحلة تأكيداً بشرياً قبل الانتقال إلى المرحلة التالية.
 
-### 4. أوامر CLI الأخرى
+### 4. تحديث SpecCrew
+
+عندما يتم إصدار نسخة جديدة من SpecCrew، يتطلب الأمر خطوتين لإكمال التحديث:
+
+```bash
+# Step 1: 更新全局 CLI 工具到最新版本
+npm install -g speccrew@latest
+
+# Step 2: 同步项目中的 Agents 和 Skills 到最新版本
+cd /path/to/your-project
+speccrew update
+```
+
+> **ملاحظة**: يقوم الأمر `npm install -g speccrew@latest` بتحديث أداة CLI نفسها، بينما يقوم الأمر `speccrew update` بتحديث ملفات تعريف Agent و Skill في المشروع. يجب تنفيذ الخطوتين لإكمال التحديث الكامل.
+
+### 5. أوامر CLI الأخرى
 
 ```bash
 speccrew list       # عرض قائمة agents و skills المثبتة
@@ -239,7 +306,7 @@ your-project/
 │   │   ├── speccrew-system-developer.md  # مطور النظام: التطوير المتوازي حسب المنصة
 │   │   ├── speccrew-test-manager.md      # مدير الاختبار: تنسيق الاختبار ثلاثي المراحل
 │   │   └── speccrew-task-worker.md       # عامل المهام: تنفيذ المهام الفرعية المتوازية
-│   └── skills/                      # 38 مهارة (مجمعة حسب الوظيفة)
+│   └── skills/                      # 30+ مهارة (مجمعة حسب الوظيفة)
 │       ├── speccrew-pm-*/                # إدارة المنتج (تحليل المتطلبات، التقييم)
 │       ├── speccrew-fd-*/                # تصميم الميزات (Feature Design، عقد API)
 │       ├── speccrew-sd-*/                # تصميم النظام (واجهة/خلفية/محمول/سطح مكتب)