speccrew 0.1.12 → 0.2.1

package/.speccrew/agents/speccrew-feature-designer.md

@@ -15,6 +15,94 @@ Your core task is to **bridge requirements and implementation**: based on the us
 
 # Workflow
 
+## Phase 0: Workflow Progress Management
+
+> **Stage Gate & Resume Checkpoint System** — Ensures proper flow between pipeline stages and supports resuming from interruptions.
+
+### 0.1 Stage Gate — Verify Upstream Completion
+
+Before starting any feature design work:
+
+1. **Read `WORKFLOW-PROGRESS.json`** from:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/WORKFLOW-PROGRESS.json`
+   - If the file does not exist → Skip to Phase 1 (backward compatibility mode)
+
+2. **Verify PRD Stage Status**:
+   - Check: `stages.01_prd.status == "confirmed"`
+   - If **NOT confirmed**:
+     - **STOP** — Do not proceed
+     - Report to user: "❌ **PRD stage has not been confirmed.** Please complete PRD confirmation first using the Product Manager agent. Current status: `{status}`"
+   - If **confirmed**:
+     - Read `stages.01_prd.outputs` to get PRD file paths
+     - Proceed to Step 0.2
+
+3. **Update Stage Status**:
+   - Set `stages.02_feature_design.status = "in_progress"`
+   - Set `stages.02_feature_design.started_at = "{current_timestamp}"`
+   - Write the updated `WORKFLOW-PROGRESS.json`
+
+### 0.2 Check Resume State (Checkpoint Recovery)
+
+If resuming from an interrupted session:
+
+1. **Read `.checkpoints.json`** from:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/.checkpoints.json`
+   - If the file does not exist → Start from Phase 1 (no previous progress)
+
+2. **Evaluate Checkpoint Status**:
+
+| Checkpoint | If Passed | Resume Point |
+|------------|-----------|--------------|
+| `function_decomposition.passed == true` | Skip Checkpoint A | Start from Step 3 (Frontend Design) |
+| `feature_spec_review.passed == true` | Skip Checkpoint A & B | Start from Phase 4 (API Contract) |
+| `api_contract_joint.passed == true` | All checkpoints complete | Ask user: "Feature Design phase already completed. Do you want to redo?" |
+
+3. **Display Resume Summary**:
+   ```
+   📋 Resume Status:
+   ├── function_decomposition: ✅ Passed
+   ├── feature_spec_review: ✅ Passed
+   └── api_contract_joint: ⏳ Pending
+   
+   Resuming from: API Contract Generation phase
+   ```
+
+4. **User Confirmation**: Show resume point and ask "Continue from this checkpoint?"
+
+### 0.3 Check Dispatch Resume (Multi-Platform Recovery)
+
+If the feature involves multiple frontend platforms:
+
+1. **Read `DISPATCH-PROGRESS.json`** from:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/02.feature-design/DISPATCH-PROGRESS.json`
+   - If the file does not exist → No dispatch in progress, proceed normally
+
+2. **List Platform Task Status**:
+   ```
+   📊 Dispatch Status:
+   ├── fd-web-vue: ✅ Completed
+   ├── fd-mobile-uniapp: ⏳ Pending
+   └── fd-web-react: ❌ Failed (error message)
+   
+   Total: 3 | Completed: 1 | Failed: 1 | Pending: 1
+   ```
+
+3. **Resume Strategy**:
+   - Skip tasks with `status == "completed"`
+   - Re-execute tasks with `status == "failed"`
+   - Execute tasks with `status == "pending"`
+
+4. **User Confirmation**: Ask "Resume dispatch for pending/failed platforms?"
+
+### 0.4 Backward Compatibility
+
+If `WORKFLOW-PROGRESS.json` does not exist:
+- Log: "⚠️ No workflow progress file found. Running in legacy mode."
+- Proceed with Phase 1 normally without stage gate checks
+- This ensures compatibility with projects started before the workflow system was introduced
+
+---
+
 ## Phase 1: Preparation
 
 When user requests to start feature design:
@@ -125,6 +213,38 @@ After both Feature Spec and API Contract documents are ready, present summary to
 - Request user confirmation before proceeding to system design phase
 - After confirmation, API Contract becomes the read-only baseline for downstream stages
 
+### 4.4 Finalize Stage (Update Workflow Progress)
+
+After user confirms Joint Confirmation:
+
+1. **Update `WORKFLOW-PROGRESS.json`**:
+   ```json
+   {
+     "current_stage": "03_system_design",
+     "stages": {
+       "02_feature_design": {
+         "status": "confirmed",
+         "completed_at": "{timestamp}",
+         "confirmed_at": "{timestamp}",
+         "outputs": [
+           "02.feature-design/[feature-name]-feature-spec.md",
+           "02.feature-design/[feature-name]-api-contract.md"
+         ]
+       }
+     }
+   }
+   ```
+
+2. **Write Updated Progress File**:
+   - Path: `speccrew-workspace/iterations/{iteration-id}/WORKFLOW-PROGRESS.json`
+   - Set `current_stage` to `03_system_design` (ready for next stage)
+   - Set `02_feature_design.status` to `confirmed`
+   - Record all output file paths in `outputs` array
+
+3. **Confirm Transition**:
+   - Notify user: "✅ Feature Design phase completed and confirmed. Ready to start System Design phase."
+   - The next agent (speccrew-system-designer) will verify this confirmation via its Stage Gate
+
 # Deliverables
 
 | Deliverable | Path | Notes |

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

@@ -36,6 +36,60 @@ When involving related domains:
 - `speccrew-workspace/knowledge/domain/glossary/` → Business terminology glossary
 - `speccrew-workspace/knowledge/domain/qa/` → Common problem solutions
 
+# Workflow Progress Management
+
+## Phase 0.1: Load Workflow Progress
+
+Before starting work, check the workflow progress state:
+
+1. **Find Active Iteration**: Use Glob to search for `speccrew-workspace/iterations/*/WORKFLOW-PROGRESS.json`
+2. **If WORKFLOW-PROGRESS.json exists**:
+   - Read the file to get current stage and status
+   - If `current_stage` is not `01_prd`, this iteration may already be in progress at a later stage
+   - If `01_prd.status` is `confirmed`, check resume state (Step 0.2)
+3. **If WORKFLOW-PROGRESS.json does not exist**:
+   - Create initial WORKFLOW-PROGRESS.json in the iteration directory:
+     ```json
+     {
+       "iteration": "{iteration-name}",
+       "current_stage": "01_prd",
+       "stages": {
+         "01_prd": {
+           "status": "in_progress",
+           "started_at": "<current-timestamp>",
+           "completed_at": null,
+           "confirmed_at": null,
+           "outputs": []
+         },
+         "02_feature_design": { "status": "pending" },
+         "03_system_design": { "status": "pending" },
+         "04_development": { "status": "pending" },
+         "05_system_test": { "status": "pending" }
+       }
+     }
+     ```
+
+## Phase 0.2: Check Resume State
+
+If `01_prd.status` is `confirmed` or `completed`, check for checkpoint file:
+
+1. **Read checkpoint file**: `speccrew-workspace/iterations/{iteration}/01.product-requirement/.checkpoints.json`
+2. **If `prd_review.passed == true`**:
+   - PRD has been completed and confirmed previously
+   - Ask user to choose:
+     - **(a) View existing PRD and continue to next stage**: Show PRD content, prepare to transition to `02_feature_design`
+     - **(b) Regenerate PRD (overwrite)**: Reset `01_prd.status` to `in_progress`, proceed with normal workflow
+3. **If checkpoint does not exist or `passed == false`**:
+   - Proceed with normal PRD generation workflow
+
+## Phase 0.3: Backward Compatibility
+
+If WORKFLOW-PROGRESS.json does not exist (legacy iterations or new workspace):
+- Execute the original workflow without progress tracking
+- Progress files will be created when PRD is confirmed
+
+---
+
 # Workflow
 
 Invoke Skill: Find `speccrew-pm-requirement-analysis/SKILL.md` in the skills directory

package/.speccrew/agents/speccrew-system-designer.md

@@ -15,9 +15,52 @@ Your core task is: based on the Feature Spec (WHAT to build), design HOW to buil
 
 # Workflow
 
+## Phase 0: Workflow Progress Management
+
+### Step 0.1: Stage Gate — Verify Upstream Completion
+
+Before starting system design, verify that Feature Design stage is confirmed:
+
+1. **Read WORKFLOW-PROGRESS.json** from `speccrew-workspace/iterations/{current}/WORKFLOW-PROGRESS.json`
+2. **Validate upstream stage**: Check `stages.02_feature_design.status == "confirmed"`
+3. **If not confirmed**: STOP — "Feature Design stage has not been confirmed. Please complete Feature Design confirmation first."
+4. **If confirmed**: 
+   - Read `02_feature_design.outputs` to get Feature Spec and API Contract paths
+   - Update `03_system_design.status` to `in_progress`, record `started_at` timestamp
+
+### Step 0.2: Check Resume State (断点续传)
+
+Check if there's existing progress to resume:
+
+1. **Read .checkpoints.json** from `speccrew-workspace/iterations/{current}/03.system-design/.checkpoints.json` (if exists)
+2. **Determine resume point** based on passed checkpoints:
+   - `framework_evaluation.passed == true` → Skip Phase 3 (Framework Evaluation)
+   - `design_overview.passed == true` → Skip Phase 4 (DESIGN-OVERVIEW.md generation)
+   - `joint_confirmation.passed == true` → Entire stage completed, ask user if they want to redo
+3. **Present resume summary** to user if resuming from checkpoint
+
+### Step 0.3: Check Dispatch Resume (Feature×Platform Matrix)
+
+Check dispatch progress for parallel task execution:
+
+1. **Read DISPATCH-PROGRESS.json** from `speccrew-workspace/iterations/{current}/03.system-design/DISPATCH-PROGRESS.json` (if exists)
+2. **List task statuses**:
+   - `completed`: Skip these tasks
+   - `failed`: Retry these tasks
+   - `pending`: Execute these tasks
+3. **Show resume summary** to user with counts: total/completed/failed/pending
+
+### Step 0.4: Backward Compatibility
+
+If WORKFLOW-PROGRESS.json does not exist:
+- Continue with existing logic (Phase 1 onwards)
+- Do not fail if progress files are missing
+
+---
+
 ## Phase 1: Preparation
 
-When user requests to start system design:
+When user requests to start system design (and Phase 0 gates are passed):
 
 ### 1.1 Identify Feature Spec and API Contract Documents
 
@@ -128,18 +171,55 @@ Based on platform types in techs-manifest:
 - `desktop-*` → dispatch `speccrew-sd-desktop`
 - `backend-*` → dispatch `speccrew-sd-backend`
 
-### 5.2 Single Feature Spec + Single Platform
-
-When there is only one Feature Spec and one platform, call skill directly with parameters:
-- Skill path: determined by platform type mapping (see 5.1)
-- Pass context:
-  - `platform_id`: Platform identifier from techs-manifest
-  - `feature_spec_path`: Path to Feature Spec document
-  - `api_contract_path`: Path to API Contract document
-  - `techs_paths`: Relevant techs knowledge paths
-  - `framework_decisions`: Framework decisions from Phase 3
-
-### 5.3 Parallel Execution (Feature × Platform)
+### 5.2 Initialize DISPATCH-PROGRESS.json
+
+Before dispatching, create or update dispatch tracking:
+
+1. **Create task entries** for each Feature × Platform combination:
+   ```json
+   {
+     "stage": "03_system_design",
+     "total": 6,
+     "completed": 0,
+     "failed": 0,
+     "pending": 6,
+     "tasks": [
+       {
+         "id": "sd-{platform_id}-{feature_name}",
+         "platform": "{platform_id}",
+         "feature": "{feature_name}",
+         "skill": "speccrew-sd-{type}",
+         "status": "pending",
+         "started_at": null,
+         "completed_at": null,
+         "output": null,
+         "error": null
+       }
+     ]
+   }
+   ```
+2. **Check existing progress** (from Step 0.3) — skip `completed` tasks
+3. **Update status** to `in_progress` for tasks being dispatched
+
+### 5.3 Single Feature Spec + Single Platform
+
+When there is only one Feature Spec and one platform:
+
+1. Update task status to `in_progress` with `started_at` timestamp
+2. Call skill directly with parameters:
+   - Skill path: determined by platform type mapping (see 5.1)
+   - Pass context:
+     - `task_id`: Task identifier for progress tracking
+     - `platform_id`: Platform identifier from techs-manifest
+     - `feature_spec_path`: Path to Feature Spec document
+     - `api_contract_path`: Path to API Contract document
+     - `techs_paths`: Relevant techs knowledge paths
+     - `framework_decisions`: Framework decisions from Phase 3
+3. **Parse Task Completion Report** from skill output:
+   - If `Status: SUCCESS` → Update task to `completed`, record `output` path
+   - If `Status: FAILED` → Update task to `failed`, record `error` details
+
+### 5.4 Parallel Execution (Feature × Platform)
 
 > **IMPORTANT**: Use the **Skill tool** (not the Agent tool) to invoke each design skill.
 
@@ -155,6 +235,7 @@ When multiple Feature Specs and/or multiple platforms exist, create a matrix of
 Each worker receives:
 - `skill_name`: Per-platform design skill based on platform type (see 5.1)
 - `context`:
+  - `task_id`: Unique task identifier (e.g., `sd-web-vue-feature-a`)
   - `platform_id`: Platform identifier from techs-manifest
   - `feature_spec_path`: Path to ONE Feature Spec document (not all)
   - `api_contract_path`: API Contract document path
@@ -162,6 +243,8 @@ Each worker receives:
   - `framework_decisions`: Framework decisions from Phase 3
   - `output_base_path`: Path to `03.system-design/` directory
 
+**Before dispatch**: Update each task status to `in_progress` with `started_at` timestamp.
+
 **Parallel execution example** (2 features × 3 platforms = 6 skill invocations):
 - Skill 1: speccrew-sd-frontend for Feature A on web-vue → 03.system-design/web-vue/
 - Skill 2: speccrew-sd-backend for Feature A on backend-spring → 03.system-design/backend-spring/
@@ -171,6 +254,27 @@ Each worker receives:
 - Skill 6: speccrew-sd-mobile for Feature B on mobile-uniapp → 03.system-design/mobile-uniapp/
 
 All skills execute simultaneously to maximize efficiency.
+
+### 5.5 Update DISPATCH-PROGRESS.json
+
+After each skill completes, parse its **Task Completion Report** and update:
+
+```json
+{
+  "tasks": [
+    {
+      "id": "sd-web-vue-feature-a",
+      "status": "completed",
+      "completed_at": "2026-01-15T10:30:00Z",
+      "output": "03.system-design/web-vue/feature-a-design.md"
+    }
+  ],
+  "completed": 4,
+  "failed": 1,
+  "pending": 1
+}
+```
+
 Wait for all skills to complete before proceeding to Phase 6.
 
 ## Phase 6: Joint Confirmation
@@ -181,7 +285,39 @@ After all platform designs are complete:
 2. List all design documents with paths
 3. Highlight cross-platform integration points
 4. Request user confirmation
-5. After confirmation, designs become baseline for Dev phase
+
+### 6.1 Update Checkpoints on Confirmation
+
+After user confirms:
+
+1. **Write .checkpoints.json**:
+   ```json
+   {
+     "stage": "03_system_design",
+     "checkpoints": {
+       "framework_evaluation": { "passed": true, "confirmed_at": "..." },
+       "design_overview": { "passed": true, "confirmed_at": "..." },
+       "joint_confirmation": { "passed": true, "confirmed_at": "..." }
+     }
+   }
+   ```
+
+2. **Update WORKFLOW-PROGRESS.json**:
+   ```json
+   {
+     "current_stage": "04_development",
+     "stages": {
+       "03_system_design": {
+         "status": "confirmed",
+         "completed_at": "...",
+         "confirmed_at": "...",
+         "outputs": ["DESIGN-OVERVIEW.md", "platform-indexes", "module-designs"]
+       }
+     }
+   }
+   ```
+
+3. **Designs become baseline** for Dev phase
 
 # Deliverables