speccrew 0.1.12 → 0.2.1

package/.speccrew/agents/speccrew-test-manager.md

@@ -15,6 +15,76 @@ Your core task is: coordinate three-phase testing workflow (test case design →
 
 # Workflow
 
+## Phase 0: Workflow Progress Management
+
+### Step 0.1: Stage Gate — Verify Upstream Completion
+
+**Read `WORKFLOW-PROGRESS.json`** from workspace root:
+```
+speccrew-workspace/WORKFLOW-PROGRESS.json
+```
+
+**Validation Rules:**
+- Verify `stages.04_development.status == "confirmed"`
+- If not confirmed → **STOP** with message: "Development stage has not been confirmed. Please complete and confirm the development stage before starting system test."
+
+**Update Current Stage:**
+- Set `stages.05_system_test.status` to `"in_progress"`
+- Record `stages.05_system_test.started_at` with current timestamp
+- Write updated `WORKFLOW-PROGRESS.json`
+
+### Step 0.2: Check Resume State (断点续传)
+
+**Read Checkpoint File** (if exists):
+```
+speccrew-workspace/iterations/{number}-{type}-{name}/05.system-test/.checkpoints.json
+```
+
+**Resume Decision Matrix:**
+
+| Checkpoint State | Action |
+|-----------------|--------|
+| `test_case_coverage.passed == true` | Skip Phase 3 (test-case-design), proceed to Phase 4 (test-code-gen) |
+| `test_code_review.passed == true` | Skip Phase 3+4, proceed to Phase 5 (test-execution) |
+| `test_execution_report.passed == true` | Stage complete — ask user if they want to redo |
+| File does not exist | Proceed normally from Phase 1 |
+
+**User Confirmation for Resume:**
+- Display detected resume point to user
+- Ask: "Resume from [phase]? Or restart from beginning?"
+- Proceed based on user choice
+
+### Step 0.3: Check Dispatch Resume (多平台断点续传)
+
+**Read Dispatch Progress** (if exists):
+```
+speccrew-workspace/iterations/{number}-{type}-{name}/05.system-test/DISPATCH-PROGRESS.json
+```
+
+**Parse Task Status by Phase:**
+- Group tasks by `phase` field (test_case_design, test_code_gen, test_execution)
+- For each phase, identify:
+  - `completed` tasks — skip
+  - `failed` tasks — retry
+  - `pending` tasks — execute
+
+**Display Progress Summary:**
+```
+Dispatch Resume Status:
+├── test_case_design: {completed}/{total} completed, {failed} failed, {pending} pending
+├── test_code_gen: {completed}/{total} completed, {failed} failed, {pending} pending
+└── test_execution: {completed}/{total} completed, {failed} failed, {pending} pending
+```
+
+### Step 0.4: Backward Compatibility
+
+If `WORKFLOW-PROGRESS.json` does not exist:
+- Proceed with existing workflow (Phase 1 onwards)
+- Skip all progress tracking steps
+- Maintain full compatibility with legacy projects
+
+---
+
 ## Phase 1: Preparation
 
 When user requests to start testing:
@@ -109,6 +179,37 @@ Invoke Skill directly with parameters:
 
 > **IMPORTANT**: Use the **Skill tool** (not the Agent tool) to invoke each test skill.
 
+> **DISPATCH-PROGRESS Strategy**: Append mode — each test phase appends its tasks to the existing DISPATCH-PROGRESS.json with a distinct `phase` field. Previous phase records are preserved for full traceability.
+
+**Initialize Dispatch Progress File:**
+
+Before dispatching, create or update `DISPATCH-PROGRESS.json`:
+```json
+{
+  "stage": "05_system_test",
+  "phase": "test_case_design",
+  "total": {platform_count},
+  "completed": 0,
+  "failed": 0,
+  "pending": {platform_count},
+  "tasks": [
+    {
+      "id": "test-case-{platform_id}",
+      "platform": "{platform_id}",
+      "phase": "test_case_design",
+      "skill": "speccrew-test-case-design",
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "output": null,
+      "error": null
+    }
+  ]
+}
+```
+
+**Dispatch Workers:**
+
 Use the **Skill tool** to invoke `speccrew-test-case-design` for each platform in parallel:
 - Each worker receives:
   - `skill_name`: `speccrew-test-case-design`
@@ -118,11 +219,19 @@ Use the **Skill tool** to invoke `speccrew-test-case-design` for each platform i
     - `api_contract_path`: Path to the API contract document (if exists)
     - `platform_id`: Platform identifier
     - `output_path`: Path for the platform-specific test cases document
+    - `task_id`: `test-case-{platform_id}` (for progress tracking)
 - Parallel execution pattern:
   - Worker 1: Master Feature Spec + Platform 1 Design → Platform 1 Test Cases
   - Worker 2: Master Feature Spec + Platform 2 Design → Platform 2 Test Cases
   - Worker N: Master Feature Spec + Platform N Design → Platform N Test Cases
 
+**Update Progress on Completion:**
+
+For each completed worker, parse Task Completion Report and update `DISPATCH-PROGRESS.json`:
+- On SUCCESS: Set `status` to `"completed"`, record `completed_at`, set `output`
+- On FAILED: Set `status` to `"failed"`, record `error`, set `recovery_hint` if available
+- Recalculate `completed`, `failed`, `pending` counts
+
 ### 3.4 Checkpoint A: Test Case Review
 
 After test case design completes for all platforms:
@@ -141,6 +250,22 @@ After test case design completes for all platforms:
 - Wait for user to confirm test case coverage is adequate
 - Only proceed to code generation phase after user confirmation
 
+**Write Checkpoint File:**
+
+Create or update `.checkpoints.json`:
+```json
+{
+  "stage": "05_system_test",
+  "checkpoints": {
+    "test_case_coverage": {
+      "passed": true,
+      "confirmed_at": "{ISO8601_timestamp}",
+      "description": "Test case coverage review (Checkpoint A)"
+    }
+  }
+}
+```
+
 **Output Path:**
 - `speccrew-workspace/iterations/{number}-{type}-{name}/05.system-test/cases/{platform_id}/[feature]-test-cases.md`
 
@@ -165,12 +290,51 @@ Invoke Skill directly:
 
 ### 4.3 Multi-Platform Parallel Execution
 
+> **DISPATCH-PROGRESS Strategy**: Append mode — each test phase appends its tasks to the existing DISPATCH-PROGRESS.json with a distinct `phase` field. Previous phase records are preserved for full traceability.
+
+**Initialize Dispatch Progress File:**
+
+Update `DISPATCH-PROGRESS.json` with new phase:
+```json
+{
+  "stage": "05_system_test",
+  "phase": "test_code_gen",
+  "total": {platform_count},
+  "completed": 0,
+  "failed": 0,
+  "pending": {platform_count},
+  "tasks": [
+    {
+      "id": "test-code-{platform_id}",
+      "platform": "{platform_id}",
+      "phase": "test_code_gen",
+      "skill": "speccrew-test-code-gen",
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "output": null,
+      "error": null
+    }
+  ]
+}
+```
+
+**Dispatch Workers:**
+
 Use the **Skill tool** to invoke `speccrew-test-code-gen` for each platform in parallel:
   - `context`:
     - `test_cases_path`: Path to the platform-specific test cases document
     - `system_design_path`: Path to the platform system design document
     - `platform_id`: Platform identifier
     - `output_dir`: Directory for generated test code and plan
+    - `task_id`: `test-code-{platform_id}` (for progress tracking)
+
+**Update Progress on Completion:**
+
+For each completed worker, parse Task Completion Report and update `DISPATCH-PROGRESS.json`:
+- On SUCCESS: Set `status` to `"completed"`, record `completed_at`, set `output`
+- On FAILED: Set `status` to `"failed"`, record `error`
+- Recalculate `completed`, `failed`, `pending` counts
 
 ### 4.4 Checkpoint B: Code Review
 
@@ -190,6 +354,27 @@ After test code generation completes for all platforms:
 - Wait for user to confirm test code is acceptable
 - Only proceed to execution phase after user confirmation
 
+**Update Checkpoint File:**
+
+Update `.checkpoints.json`:
+```json
+{
+  "stage": "05_system_test",
+  "checkpoints": {
+    "test_case_coverage": {
+      "passed": true,
+      "confirmed_at": "{timestamp}",
+      "description": "Test case coverage review (Checkpoint A)"
+    },
+    "test_code_review": {
+      "passed": true,
+      "confirmed_at": "{ISO8601_timestamp}",
+      "description": "Test code generation review (Checkpoint B)"
+    }
+  }
+}
+```
+
 **Output:**
 - Test code: Written to project source test directories
 - Test code plan: `speccrew-workspace/iterations/{number}-{type}-{name}/05.system-test/code/{platform_id}/[feature]-test-code-plan.md`
@@ -214,11 +399,50 @@ Invoke Skill directly:
 
 ### 5.3 Multi-Platform Parallel Execution
 
+> **DISPATCH-PROGRESS Strategy**: Append mode — each test phase appends its tasks to the existing DISPATCH-PROGRESS.json with a distinct `phase` field. Previous phase records are preserved for full traceability.
+
+**Initialize Dispatch Progress File:**
+
+Update `DISPATCH-PROGRESS.json` with new phase:
+```json
+{
+  "stage": "05_system_test",
+  "phase": "test_execution",
+  "total": {platform_count},
+  "completed": 0,
+  "failed": 0,
+  "pending": {platform_count},
+  "tasks": [
+    {
+      "id": "test-exec-{platform_id}",
+      "platform": "{platform_id}",
+      "phase": "test_execution",
+      "skill": "speccrew-test-execute",
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "output": null,
+      "error": null
+    }
+  ]
+}
+```
+
+**Dispatch Workers:**
+
 Use the **Skill tool** to invoke `speccrew-test-execute` for each platform in parallel:
   - `context`:
     - `test_code_path`: Path to the platform test code directory
     - `platform_id`: Platform identifier
     - `output_dir`: Directory for reports
+    - `task_id`: `test-exec-{platform_id}` (for progress tracking)
+
+**Update Progress on Completion:**
+
+For each completed worker, parse Task Completion Report and update `DISPATCH-PROGRESS.json`:
+- On SUCCESS: Set `status` to `"completed"`, record `completed_at`, set `output`
+- On FAILED: Set `status` to `"failed"`, record `error`
+- Recalculate `completed`, `failed`, `pending` counts
 
 ### 5.4 Deviation Detection
 
@@ -277,6 +501,60 @@ Provide clear recommendation:
 - Confirm to proceed to delivery phase, or
 - Return to development phase for bug fixes
 
+### 6.5 Finalize Progress Files
+
+**Update Checkpoint File:**
+
+Update `.checkpoints.json`:
+```json
+{
+  "stage": "05_system_test",
+  "checkpoints": {
+    "test_case_coverage": {
+      "passed": true,
+      "confirmed_at": "{timestamp}",
+      "description": "Test case coverage review (Checkpoint A)"
+    },
+    "test_code_review": {
+      "passed": true,
+      "confirmed_at": "{timestamp}",
+      "description": "Test code generation review (Checkpoint B)"
+    },
+    "test_execution_report": {
+      "passed": true,
+      "confirmed_at": "{ISO8601_timestamp}",
+      "description": "Test execution final report"
+    }
+  }
+}
+```
+
+**Update Workflow Progress:**
+
+Update `WORKFLOW-PROGRESS.json`:
+```json
+{
+  "iteration": "{iteration_name}",
+  "current_stage": "05_system_test",
+  "stages": {
+    "05_system_test": {
+      "status": "confirmed",
+      "started_at": "{timestamp}",
+      "completed_at": "{timestamp}",
+      "confirmed_at": "{ISO8601_timestamp}",
+      "outputs": [
+        "05.system-test/cases/",
+        "05.system-test/code/",
+        "05.system-test/reports/",
+        "05.system-test/bugs/"
+      ]
+    }
+  }
+}
+```
+
+> **Note**: `current_stage` does not advance — 05_system_test is the final stage of the pipeline.
+
 # Deliverables
 
 | Deliverable | Path | Notes |

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

@@ -193,6 +193,50 @@ Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development
 Ready for testing phase.
 ```
 
+## Task Completion Report
+
+At the end of Step 8 (or if the skill fails at any point), output a structured Task Completion Report:
+
+### Success Report
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**:
+  - {file_path_1}
+  - {file_path_2}
+  - ...
+- **Summary**: Backend module {module_name} implemented with {X} tasks completed
+```
+
+### Failure Report
+
+If the skill fails at any step:
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**: {list of partially generated files, or "None"}
+- **Summary**: {one-line description of what was attempted}
+- **Error**: {detailed error description}
+- **Error Category**: {DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED}
+- **Partial Outputs**: {list of files that were generated before failure, or "None"}
+- **Recovery Hint**: {suggestion for how to resolve and retry}
+```
+
+**Error Category Definitions**:
+- `DEPENDENCY_MISSING`: Required runtime/dependency not available
+- `BUILD_FAILURE`: Compilation error, maven/gradle build failure
+- `VALIDATION_ERROR`: Checkstyle, test failure, or validation error
+- `RUNTIME_ERROR`: Service startup failure, runtime exception
+- `BLOCKED`: Blocked by external dependency or unresolved design issue
+
 # Key Rules
 
 | Rule | Description |

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

@@ -246,6 +246,50 @@ Technical Debt Items: {count}
 Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md
 ```
 
+## Task Completion Report
+
+At the end of Step 8 (or if the skill fails at any point), output a structured Task Completion Report:
+
+### Success Report
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**:
+  - {file_path_1}
+  - {file_path_2}
+  - ...
+- **Summary**: Desktop module {module_name} implemented with {X} tasks completed
+```
+
+### Failure Report
+
+If the skill fails at any step:
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**: {list of partially generated files, or "None"}
+- **Summary**: {one-line description of what was attempted}
+- **Error**: {detailed error description}
+- **Error Category**: {DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED}
+- **Partial Outputs**: {list of files that were generated before failure, or "None"}
+- **Recovery Hint**: {suggestion for how to resolve and retry}
+```
+
+**Error Category Definitions**:
+- `DEPENDENCY_MISSING`: Required Node.js/npm or Rust dependency not available
+- `BUILD_FAILURE`: Electron/Tauri build error, native compilation failure
+- `VALIDATION_ERROR`: ESLint, TypeScript type check, Rust clippy, or test failure
+- `RUNTIME_ERROR`: App crash on launch, runtime exception, IPC communication failure
+- `BLOCKED`: Blocked by external dependency, native module issue, or unresolved design issue
+
 **Ask user to confirm:**
 1. Are all IPC channels working correctly?
 2. Is context isolation properly configured?

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

@@ -212,6 +212,50 @@ Tech Debt: {count}
 Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md
 ```
 
+## Task Completion Report
+
+At the end of Step 6 (or if the skill fails at any point), output a structured Task Completion Report:
+
+### Success Report
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**:
+  - {file_path_1}
+  - {file_path_2}
+  - ...
+- **Summary**: Frontend module {module_name} implemented with {X} tasks completed
+```
+
+### Failure Report
+
+If the skill fails at any step:
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**: {list of partially generated files, or "None"}
+- **Summary**: {one-line description of what was attempted}
+- **Error**: {detailed error description}
+- **Error Category**: {DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED}
+- **Partial Outputs**: {list of files that were generated before failure, or "None"}
+- **Recovery Hint**: {suggestion for how to resolve and retry}
+```
+
+**Error Category Definitions**:
+- `DEPENDENCY_MISSING`: Required Node.js/npm dependency not available
+- `BUILD_FAILURE`: Vite/Webpack build error, compilation failure
+- `VALIDATION_ERROR`: ESLint, TypeScript type check, or test failure
+- `RUNTIME_ERROR`: Runtime exception in browser/dev server
+- `BLOCKED`: Blocked by external dependency or unresolved design issue
+
 # Key Rules
 
 | Rule | Description |

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

@@ -200,6 +200,50 @@ Mobile Development Complete:
 Ready for QA Agent acceptance testing.
 ```
 
+## Task Completion Report
+
+At the end of Step 8 (or if the skill fails at any point), output a structured Task Completion Report:
+
+### Success Report
+
+```
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**:
+  - {file_path_1}
+  - {file_path_2}
+  - ...
+- **Summary**: Mobile module {module_name} implemented with {X} tasks completed
+```
+
+### Failure Report
+
+If the skill fails at any step:
+
+```
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: {task_id from dispatch context}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**: {list of partially generated files, or "None"}
+- **Summary**: {one-line description of what was attempted}
+- **Error**: {detailed error description}
+- **Error Category**: {DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED}
+- **Partial Outputs**: {list of files that were generated before failure, or "None"}
+- **Recovery Hint**: {suggestion for how to resolve and retry}
+```
+
+**Error Category Definitions**:
+- `DEPENDENCY_MISSING`: Required Flutter/Dart or npm dependency not available
+- `BUILD_FAILURE`: Flutter build error, Gradle/Xcode compilation failure
+- `VALIDATION_ERROR`: Static analysis error (`flutter analyze`), test failure
+- `RUNTIME_ERROR`: App crash on simulator/emulator, runtime exception
+- `BLOCKED`: Blocked by external dependency, native module issue, or unresolved design issue
+
 # Key Rules
 
 | Rule | Description |

package/.speccrew/skills/speccrew-fd-api-contract/SKILL.md

@@ -99,6 +99,76 @@ Please confirm the following key points:
 After confirmation, you can start frontend and backend Designer Agents separately.
 ```
 
+## Step 6: Update Progress Files
+
+After user confirms Joint Confirmation:
+
+### 6.1 Update Checkpoints File
+
+Write/Update `.checkpoints.json`:
+
+- Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/.checkpoints.json`
+- Content:
+  ```json
+  {
+    "stage": "02_feature_design",
+    "checkpoints": {
+      "function_decomposition": {
+        "passed": true,
+        "confirmed_at": "..."
+      },
+      "feature_spec_review": {
+        "passed": true,
+        "confirmed_at": "..."
+      },
+      "api_contract_joint": {
+        "passed": true,
+        "confirmed_at": "{current_timestamp}",
+        "description": "API contract joint confirmation passed"
+      }
+    }
+  }
+  ```
+
+- Preserve existing checkpoint statuses when updating
+- Log: "✅ Checkpoint (api_contract_joint) passed and recorded"
+
+### 6.2 Update Workflow Progress
+
+Update `WORKFLOW-PROGRESS.json` to finalize the stage:
+
+- Path: `speccrew-workspace/iterations/{iteration-id}/WORKFLOW-PROGRESS.json`
+- Update:
+  ```json
+  {
+    "current_stage": "03_system_design",
+    "stages": {
+      "02_feature_design": {
+        "status": "confirmed",
+        "completed_at": "{current_timestamp}",
+        "confirmed_at": "{current_timestamp}",
+        "outputs": [
+          "02.feature-design/[feature-name]-feature-spec.md",
+          "02.feature-design/[feature-name]-api-contract.md"
+        ]
+      }
+    }
+  }
+  ```
+
+- Set `02_feature_design.status` to `confirmed`
+- Set `current_stage` to `03_system_design`
+- Record all output file paths
+- Log: "✅ Stage 02_feature_design confirmed. Ready for System Design phase."
+
+### 6.3 Backward Compatibility
+
+If `WORKFLOW-PROGRESS.json` does not exist:
+- Log: "⚠️ No workflow progress file found. Skipping workflow update."
+- Still update `.checkpoints.json` if the directory exists
+
+---
+
 # Checklist
 
 - [ ] All APIs mentioned in feature spec have defined contracts