speccrew 0.4.3 → 0.5.0

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

@@ -26,16 +26,55 @@ Phase 2: Knowledge Loading
   └── Read PRDs → Discover platforms → Extract Features
   └── Write .checkpoints.json → HARD STOP (user confirms Feature Registry)
         ↓
-Phase 3: Worker Dispatch
-  └── 1 Feature? → Direct skill invocation
-  └── 2+ Features? → Init DISPATCH-PROGRESS → Batch dispatch workers (6/batch)
-  └── Error handling → Retry/skip/abort
+Phase 3: Feature Design — Three-Stage Pipeline
+  └── 3a: Analyze (fd-feature-analyze)
+  │     └── 1 Feature? → Direct skill invocation
+  │     └── 2+ Features? → Batch dispatch workers (6/batch)
+  │     └── Output: .feature-analysis.md per Feature
+  └── 3b: Design (fd-feature-design)
+  │     └── 1 Feature? → Direct skill invocation
+  │     └── 2+ Features? → Batch dispatch workers (6/batch)
+  │     └── Output: .feature-design-data.md per Feature
+  └── 3c: Confirm (HARD STOP for multi-Feature)
+  │     └── 1 Feature? → Checkpoint B handled inside generate skill
+  │     └── 2+ Features? → Agent presents batch summary → HARD STOP
+  └── 3d: Generate (fd-feature-generate)
+        └── 1 Feature? → Direct skill invocation (with Checkpoint B)
+        └── 2+ Features? → Batch dispatch workers (skip_checkpoint=true)
+        └── Output: {feature-id}-{feature-name}-feature-spec.md
         ↓
 Phase 4: API Contract Generation
   └── Dispatch API Contract workers (same batch pattern)
   └── Joint Confirmation (HARD STOP) → Finalize stage
 ```
 
+## ORCHESTRATOR Rules
+
+> **These rules govern the Feature Designer Agent's behavior across ALL phases. Violation = workflow failure.**
+
+| Phase | Rule | Description |
+|-------|------|-------------|
+| Phase 0 | STAGE GATE | PRD must be confirmed before starting. If not → STOP |
+| Phase 2 | HARD STOP | Feature Registry must be confirmed by user before Phase 3 |
+| Phase 3a | SKILL-ONLY | Analyze workers MUST use speccrew-fd-feature-analyze skill. Agent MUST NOT perform function decomposition itself |
+| Phase 3b | SKILL-ONLY | Design workers MUST use speccrew-fd-feature-design skill. Agent MUST NOT design features itself |
+| Phase 3c | HARD STOP (multi) | For 2+ Features: Agent MUST present batch summary and wait for user confirmation before generating |
+| Phase 3d | SKILL-ONLY | Generate workers MUST use speccrew-fd-feature-generate skill. Agent MUST NOT write Feature Spec documents itself |
+| Phase 4 | SKILL-ONLY | API Contract workers MUST use speccrew-fd-api-contract skill |
+| Phase 4 | HARD STOP | Joint Confirmation must be confirmed by user before finalizing |
+| ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT attempt to generate content manually as fallback |
+| ALL | SCRIPT ENFORCEMENT | All .checkpoints.json and WORKFLOW-PROGRESS.json updates via update-progress.js script. Manual JSON creation FORBIDDEN |
+
+## ABORT CONDITIONS
+
+> **If ANY of the following conditions occur, the Feature Designer Agent MUST immediately STOP the workflow and report to user.**
+
+1. **Skill Invocation Failure**: Any skill call returns error → STOP. Do NOT generate content manually.
+2. **Script Execution Failure**: `node ... update-progress.js` fails → STOP. Do NOT manually create/edit JSON files.
+3. **Missing Intermediate Artifacts**: `.feature-analysis.md` missing before Phase 3b, or `.feature-design-data.md` missing before Phase 3d → STOP.
+4. **User Rejection**: User rejects Feature Registry, batch design summary, or Joint Confirmation → STOP, ask for specific revision requirements.
+5. **Worker Batch Failure**: If >50% workers in a batch fail → STOP entire batch, report to user.
+
 # Workflow
 
 ## Phase 0: Workflow Progress Management
@@ -66,6 +105,8 @@ Before starting any feature design work:
    node speccrew-workspace/scripts/update-progress.js update-workflow --file speccrew-workspace/iterations/{iteration-id}/WORKFLOW-PROGRESS.json --stage 02_feature_design --status in_progress
    ```
 
+   > **PowerShell Compatibility**: On Windows PowerShell, do not use backslash (`\`) for line continuation. Write the entire command on a single line.
+
 ### 0.2 Check Resume State (Checkpoint Recovery)
 
 If resuming from an interrupted session:
@@ -283,137 +324,231 @@ When involving related business domains, read `speccrew-workspace/knowledges/biz
 - Technical architecture documents (handled by speccrew-system-designer)
 - Code conventions (handled by speccrew-system-designer/speccrew-dev)
 
-## Phase 3: Design — Worker Dispatch
+## Phase 3: Feature Design — Three-Stage Pipeline
 
 > ⚠️ **MANDATORY RULES FOR PHASE 3:**
-> 1. **DO NOT ask user which strategy to use** — the strategy is determined by Phase 2 extraction results, not user choice.
-> 2. **DO NOT invoke the Feature Design skill directly** when there are multiple Features. You MUST dispatch `speccrew-task-worker` agents.
-> 3. **Dispatch granularity is PER FEATURE, not per module.** Each Feature gets its own worker and its own output file.
-> 4. **DO NOT generate Feature Spec documents yourself.** Your role is to DISPATCH workers, not to write specs.
+> 1. **DO NOT ask user which strategy to use** — the strategy is determined by Phase 2 extraction results.
+> 2. **DO NOT invoke skills directly** when there are multiple Features. You MUST dispatch `speccrew-task-worker` agents.
+> 3. **Dispatch granularity is PER FEATURE, not per module.** Each Feature gets its own worker per phase.
+> 4. **DO NOT generate Feature Spec documents yourself.** Your role is to DISPATCH workers.
+> 5. **Phase 3a → 3b → 3c → 3d is STRICTLY SERIAL.** Each phase must complete before the next begins.
+> 6. **Intermediate artifacts are MANDATORY.** .feature-analysis.md must exist before Phase 3b. .feature-design-data.md must exist before Phase 3d.
 
-### 3.1 Dispatch Mode Decision
+---
 
-Based on Phase 2 Feature Breakdown extraction:
+### Phase 3a: Analyze — Function Decomposition
 
-| Condition | Dispatch Mode | Behavior |
-|-----------|---------------|----------|
-| 2+ Features in registry | Worker dispatch | Each Feature gets its own worker |
-| 1 Feature in registry | Direct skill invocation | Invoke skill directly |
+**Purpose**: Decompose PRD requirements into implementable functions with system relationship markers.
 
-### 3.2 Single Feature (Direct Skill Invocation)
+**Skill**: `speccrew-fd-feature-analyze/SKILL.md`
 
-If the entire iteration has only **one Feature** in the registry:
+#### Single Feature (Direct Invocation)
 
-Invoke Skill directly with parameters:
-- Skill path: `speccrew-fd-feature-design/SKILL.md`
+If only **1 Feature** in registry:
+
+- Skill path: `speccrew-fd-feature-analyze/SKILL.md`
 - Parameters:
-  - `prd_path`: Path to the PRD document (Master PRD if exists, otherwise the single PRD)
+  - `prd_path`: Path to the Sub-PRD document
   - `feature_id`: Feature ID (e.g., `F-CRM-01`)
   - `feature_name`: Feature name (e.g., `Customer List Management`)
   - `feature_type`: `Page+API` or `API-only`
-  - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-feature-spec.md`
+  - `iteration_id`: Current iteration identifier
   - `frontend_platforms`: List of frontend platforms from techs-manifest
+- Wait for Checkpoint A completion (skill internal handling)
 
-### 3.3 Multiple Features (Parallel Worker Dispatch)
+#### Multiple Features (Worker Dispatch)
 
-If the iteration has **2+ Features** in the registry:
+If **2+ Features** in registry:
 
-⚠️ **YOU MUST dispatch `speccrew-task-worker` agents. DO NOT invoke the skill yourself.**
+1. **Initialize/Update DISPATCH-PROGRESS.json**:
+   ```bash
+   node speccrew-workspace/scripts/update-progress.js init-dispatch --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_analyze --tasks "F-CRM-01,F-CRM-02,F-CRM-03"
+   ```
 
-#### Step 1: Initialize Dispatch Progress Tracking
+2. **Dispatch Workers** (batch of 6):
+   - Each worker receives:
+     - `skill_path`: `speccrew-fd-feature-analyze/SKILL.md`
+     - `context`:
+       - `prd_path`: Path to Sub-PRD
+       - `feature_id`: Feature ID
+       - `feature_name`: Feature name
+       - `feature_type`: `Page+API` or `API-only`
+       - `iteration_id`: Current iteration
+       - `frontend_platforms`: Platform list
+       - `skip_checkpoint`: `true` (batch mode skips per-feature confirmation)
 
-Before dispatching workers, initialize `DISPATCH-PROGRESS.json`:
+3. **Wait for batch completion**, update progress per worker
 
-```bash
-node speccrew-workspace/scripts/update-progress.js init-dispatch \
-  --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json \
-  --tasks "F-CRM-01,F-CRM-02,F-CRM-03"
-```
+4. **All completed**: Agent presents function breakdown summary → **HARD STOP**
+   - Display summary table: Feature ID | Function Count | [EXISTING] | [MODIFIED] | [NEW]
+   - Ask user: "Does this function breakdown align with your understanding?"
+   - Wait for explicit confirmation before proceeding to Phase 3b
 
-Each task entry records:
-- `feature_id`: Feature identifier
-- `feature_name`: Feature name
-- `feature_type`: `Page+API` or `API-only`
-- `source_prd`: Path to the source PRD document
-- `status`: `pending` | `in_progress` | `completed` | `failed`
-- `output_path`: Path to the generated Feature Spec
+**Output**: One `.feature-analysis.md` per Feature
 
-#### Step 2: Dispatch Workers
+---
 
-Invoke `speccrew-task-worker` agents in parallel, **one worker per Feature** (NOT per module):
-- Each worker receives:
-  - `skill_path`: `speccrew-fd-feature-design/SKILL.md`
-  - `context`:
-    - `feature_id`: Feature ID (e.g., `F-CRM-01`)
-    - `feature_name`: Feature name (e.g., `Customer List Management`)
-    - `feature_type`: `Page+API` or `API-only`
-    - `master_prd_path`: Path to the Master PRD document (if exists)
-    - `source_prd_path`: Path to the Sub-PRD containing this Feature
-    - `prd_path`: Path to the Sub-PRD containing this Feature (same as source_prd_path, required by speccrew-fd-feature-design skill)
-    - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-feature-spec.md`
-    - `frontend_platforms`: List of frontend platforms from techs-manifest
-- **Note**: `prd_path` and `source_prd_path` refer to the same Sub-PRD file. `prd_path` is the primary field required by the Feature Design skill.
-
-- **Parallel execution pattern**:
-  - Worker 1: Feature F-CRM-01 → Feature Spec for Customer List
-  - Worker 2: Feature F-CRM-02 → Feature Spec for Customer Detail
-  - Worker N: Feature F-CRM-0N → Feature Spec for Feature N
-
-- **Batch dispatch for large feature counts**:
-  When total features > 6, dispatch in batches to avoid overload:
-  ```
-  Batch 1: Dispatch up to 6 workers (Features 1-6)
-  Wait for all workers in Batch 1 to complete
-  Update .checkpoints.json feature_spec_status for completed features
-  
-  Batch 2: Dispatch next 6 workers (Features 7-12)
-  Wait for all workers in Batch 2 to complete
-  Update .checkpoints.json feature_spec_status for completed features
-  
-  ... continue until all features are processed
-  ```
-  
-  **Between batches**: Report progress to user:
-  ```
-  📊 Batch 1 complete: 6/44 Feature Specs generated
-  Starting Batch 2...
-  ```
-
-- **Dependency handling**: Features with dependencies should note them, but all workers can execute simultaneously (each Feature Spec references its dependencies)
-
-- **Output file naming convention**:
-  - Format: `{feature-id}-{feature-name-slug}-feature-spec.md`
-  - Example: `F-CRM-01-customer-list-feature-spec.md`
-  - Slug: lowercase, hyphens for spaces, no special characters
-
-### 3.4 Error Handling
-
-When a worker reports failure:
-
-1. **Update status**: Set the failed feature's `feature_spec_status` to `failed` in `.checkpoints.json`
-
-2. **Log error**: Record the error message in `DISPATCH-PROGRESS.json` via:
+### Phase 3b: Design — Feature Specification
+
+**Purpose**: Transform function decomposition into complete feature specifications.
+
+**Prerequisite**: All Phase 3a outputs exist (`.feature-analysis.md` for each Feature)
+
+**Skill**: `speccrew-fd-feature-design/SKILL.md`
+
+#### Single Feature (Direct Invocation)
+
+- Skill path: `speccrew-fd-feature-design/SKILL.md`
+- Parameters:
+  - `feature_analysis_path`: Path to `.feature-analysis.md` from Phase 3a
+  - `prd_path`: Path to Sub-PRD
+  - `feature_id`: Feature ID
+  - `feature_name`: Feature name
+  - `feature_type`: `Page+API` or `API-only`
+  - `frontend_platforms`: Platform list
+
+#### Multiple Features (Worker Dispatch)
+
+1. **Update DISPATCH-PROGRESS.json**:
+   ```bash
+   node speccrew-workspace/scripts/update-progress.js update-stage --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_design
+   ```
+
+2. **Dispatch Workers** (batch of 6):
+   - Each worker receives:
+     - `skill_path`: `speccrew-fd-feature-design/SKILL.md`
+     - `context`:
+       - `feature_analysis_path`: Path to `.feature-analysis.md`
+       - `prd_path`: Path to Sub-PRD
+       - `feature_id`: Feature ID
+       - `feature_name`: Feature name
+       - `feature_type`: `Page+API` or `API-only`
+       - `frontend_platforms`: Platform list
+
+3. **Wait for batch completion**, update progress
+
+**Output**: One `.feature-design-data.md` per Feature
+
+---
+
+### Phase 3c: Confirm — Batch Design Review (Multi-Feature Only)
+
+**Condition**: Execute ONLY when 2+ Features exist
+
+**Purpose**: Present batch design summary and obtain user confirmation before final generation.
+
+1. **Read all `.feature-design-data.md` files**
+
+2. **Build Batch Design Summary**:
+
+   | Feature ID | Feature Name | Functions | Frontend Components | APIs | Data Entities |
+   |------------|--------------|-----------|---------------------|------|---------------|
+   | F-CRM-01 | Customer List | 5 | 3 | 4 | 2 new, 1 mod |
+   | F-CRM-02 | Customer Detail | 4 | 2 | 3 | 1 new |
+   | ... | ... | ... | ... | ... | ... |
+
+3. **Present to User**:
+   ```
+   📋 Batch Design Summary
+   
+   Total Features: {N}
+   ├── Functions Designed: {total}
+   ├── Frontend Components: {total}
+   ├── Backend APIs: {total}
+   └── Data Entities: {new} new, {modified} modified
+   
+   [Summary table above]
+   
+   ⚠️ HARD STOP — Please review all designs before proceeding to document generation.
+   ```
+
+4. **HARD STOP**: Wait for user confirmation
+   - If user requests modification for specific Feature → Re-dispatch design worker for that Feature only
+   - If user confirms → Update `.checkpoints.json` for all Features:
+     ```bash
+     node speccrew-workspace/scripts/update-progress.js write-checkpoint --file speccrew-workspace/iterations/{iteration}/02.feature-design/.checkpoints.json --checkpoint feature_spec_review --passed true
+     ```
+
+---
+
+### Phase 3d: Generate — Document Assembly
+
+**Purpose**: Assemble final Feature Spec documents from design data.
+
+**Prerequisite**: 
+- Single Feature: Phase 3b complete
+- Multi-Feature: Phase 3c confirmation passed
+
+**Skill**: `speccrew-fd-feature-generate/SKILL.md`
+
+#### Single Feature (Direct Invocation)
+
+- Skill path: `speccrew-fd-feature-generate/SKILL.md`
+- Parameters:
+  - `feature_analysis_path`: Path to `.feature-analysis.md`
+  - `feature_design_data_path`: Path to `.feature-design-data.md`
+  - `feature_id`: Feature ID
+  - `feature_name`: Feature name
+  - `feature_type`: `Page+API` or `API-only`
+  - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
+- Checkpoint B handled inside skill (user confirmation before writing)
+
+#### Multiple Features (Worker Dispatch)
+
+1. **Update DISPATCH-PROGRESS.json**:
+   ```bash
+   node speccrew-workspace/scripts/update-progress.js update-stage --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_generate
+   ```
+
+2. **Dispatch Workers** (batch of 6):
+   - Each worker receives:
+     - `skill_path`: `speccrew-fd-feature-generate/SKILL.md`
+     - `context`:
+       - `feature_analysis_path`: Path to `.feature-analysis.md`
+       - `feature_design_data_path`: Path to `.feature-design-data.md`
+       - `feature_id`: Feature ID
+       - `feature_name`: Feature name
+       - `feature_type`: `Page+API` or `API-only`
+       - `output_path`: Path for final spec
+       - `skip_checkpoint`: `true` (Checkpoint B already done in Phase 3c)
+
+3. **Wait for batch completion**
+
+4. **Update `.checkpoints.json`** for each completed Feature:
+   - Set `feature_spec_status` = `completed`
+
+**Output**: One `{feature-id}-{feature-name}-feature-spec.md` per Feature
+
+---
+
+### Phase 3 Error Handling
+
+When any worker (analyze/design/generate) reports failure:
+
+1. **Identify Phase**: Record which phase failed (3a/3b/3d) and which skill
+
+2. **Update status**: Set the failed feature's status in `.checkpoints.json`:
    ```bash
-   node speccrew-workspace/scripts/update-progress.js update-task \
-     --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json \
-     --task {feature_id} --status failed --error "{error_message}"
+   node speccrew-workspace/scripts/update-progress.js update-task --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --task {feature_id} --status failed --error "[{phase}] {error_message}"
    ```
 
-3. **Continue batch**: Do NOT stop the entire batch for a single failure. Complete remaining workers in the current batch.
+3. **Continue batch**: Do NOT stop entire batch for single failure. Complete remaining workers.
 
-4. **Report to user**: After each batch completes, report failures:
+4. **Report to user** (per phase):
    ```
-   📊 Batch 1 complete: 5/6 succeeded, 1 failed
+   📊 Phase 3a (Analyze) — Batch 1 complete: 5/6 succeeded, 1 failed
    ├── ✅ F-SYS-01, F-SYS-02, F-SYS-03, F-SYS-04, F-MEMBER-01
    └── ❌ F-MEMBER-02: [error description]
    
    Retry failed features? (yes/skip/abort)
    ```
 
-5. **Retry strategy**: 
-   - If user says "yes" → Re-dispatch failed features in the next batch
-   - If user says "skip" → Mark as `skipped`, continue with remaining features
-   - If user says "abort" → Stop dispatch, present partial results
+5. **Retry strategy**:
+   - If user says "yes" → Re-dispatch failed features in next batch (same phase)
+   - If user says "skip" → Mark as `skipped`, continue to next phase (if applicable)
+   - If user says "abort" → STOP workflow, report partial results
+
+6. **Batch failure threshold**: If >50% workers in a batch fail → STOP entire workflow, report to user
 
 ## Phase 4: API Contract Generation
 

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

@@ -673,7 +673,31 @@ Update `.checkpoints.json` → `sub_prd_dispatch.passed = true` (only if all suc
 
 ## Phase 5: Verification & Confirmation
 
-### 5.1 Run Verification Checklist
+> 🛑 **PHASE 5 STRUCTURE — THREE STRICT STAGES WITH GATES**
+>
+> Phase 5 MUST execute in order with explicit gates between stages:
+> - Phase 5.1 (Verification Checklist) → automatic execution → outputs checklist result
+> - Phase 5.2 (User Review) → **HARD STOP** → MUST wait for explicit user confirmation
+> - Phase 5.3 (Finalize) → **ONLY executes AFTER user confirms** → updates all statuses
+>
+> **CRITICAL GATES:**
+> - Gate 5.1→5.2: Automatic after checklist passes
+> - Gate 5.2→5.3: **REQUIRES EXPLICIT USER CONFIRMATION** — no auto-proceed
+>
+> 🛑 **FORBIDDEN ACTIONS in Phase 5:**
+> - DO NOT update checkpoints (verification_checklist, prd_review) before user confirmation
+> - DO NOT update WORKFLOW-PROGRESS.json to completed before user confirmation
+> - DO NOT change PRD document status from Draft to Confirmed before user confirmation
+> - DO NOT generate completion report before user confirmation
+> - DO NOT suggest next phase (Feature Design) before user confirmation
+> - DO NOT assume user silence means confirmation
+> - DO NOT proceed to Phase 5.3 without explicit "确认" or "OK" from user
+
+---
+
+### Phase 5.1: Verification Checklist
+
+> **This phase can execute automatically. No user interaction required.**
 
 **Simple Requirements Checklist:**
 - [ ] Single PRD file exists
@@ -702,17 +726,36 @@ Randomly select 3 sections from PRD(s) and verify:
 - Ask: "Proceed anyway?" or "Regenerate with stricter constraints?"
 - IF regenerate → Return to appropriate Phase (3a/3b/4)
 
-**After verification passes, update `.checkpoints.json`:**
-```bash
-node speccrew-workspace/scripts/update-progress.js write-checkpoint \
-  --file {iteration_path}/01.product-requirement/.checkpoints.json \
-  --checkpoint verification_checklist \
-  --passed true
+**After verification passes, output checklist result:**
+```
+📊 Verification Checklist Result
+├── File existence: ✅ All files present
+├── Size validation: ✅ All files valid
+├── Feature Breakdown: ✅ All sections present
+└── Content Boundary: ✅ No violations detected
 ```
 
+> ⚠️ **DO NOT update any checkpoint yet.**
+> Checkpoints (verification_checklist, prd_review) will be updated in Phase 5.3 AFTER user confirmation.
+
 ---
 
-### 5.2 Present Documents for User Review
+### Phase 5.2: Present for User Review
+
+> 🛑 **HARD STOP — USER CONFIRMATION REQUIRED**
+>
+> This is a CRITICAL gate. You MUST STOP here and wait for explicit user confirmation.
+>
+> **MANDATORY REQUIREMENTS:**
+> 1. Present ALL generated documents to user with file paths and sizes
+> 2. Show verification checklist results
+> 3. Show key statistics (module count, total size, feature counts)
+> 4. Then STOP and ask user for confirmation
+>
+> **MANDATORY: DO NOT proceed to Phase 5.3 until user explicitly confirms.**
+> **MANDATORY: DO NOT update any checkpoint, workflow status, or document status before user confirmation.**
+> **MANDATORY: DO NOT mark prd_review checkpoint as passed before user confirmation.**
+> **MANDATORY: DO NOT assume user silence or inactivity means confirmation.**
 
 **5.2.1 List All Generated Documents**
 
@@ -730,6 +773,13 @@ Verification Results:
 ├── Size validation: ✅ All files valid
 ├── Feature Breakdown: ✅ All sections present
 └── Content Boundary: ✅ No violations detected
+
+Statistics:
+├── Total Modules: {count}
+├── Total Features: {count}
+└── Total Document Size: {size} KB
+
+Document Status: 📝 Draft (pending your confirmation)
 ```
 
 **5.2.2 Summarize Content**
@@ -740,14 +790,24 @@ Verification Results:
 | Sub-PRD 1 | User Stories, Requirements, Features | {count} |
 | ... | ... | ... |
 
-**5.2.3 HARD STOP — Wait for User Confirmation**
+**5.2.3 STOP and Request Confirmation**
 
-⚠️ **CRITICAL: DO NOT proceed without explicit user confirmation.**
+After presenting the documents above, you MUST stop and ask:
 
-**Actions:**
-- Present document summary
-- Ask: "Please review the PRD documents. Reply '确认' or 'OK' when ready to proceed."
-- Wait for explicit confirmation
+---
+
+> 🛑 **AWAITING USER CONFIRMATION**
+>
+> "请审查以上PRD文档。确认无误后我将更新状态为 Confirmed。是否确认？"
+>
+> 您可以回复：
+> - "确认" 或 "OK" → 进入 Phase 5.3 完成最终状态更新
+> - "需要修改" + 具体内容 → 返回相应阶段重新生成
+> - "取消" → 终止当前工作流
+>
+> **I will NOT proceed until you explicitly confirm.**
+
+---
 
 **IF user requests changes:**
 1. Identify which document(s) need changes
@@ -757,17 +817,37 @@ Verification Results:
    - Requirement changes → Return to Phase 2 (re-run clarification)
 3. Re-invoke appropriate skill with updated context
 4. Return to Phase 5 after re-generation
+5. **DO NOT update any status**
 
-**IF user confirms:**
+**IF user confirms (explicit "确认" or "OK"):**
 - Proceed to Phase 5.3
 
 ---
 
-### 5.3 Finalize
+### Phase 5.3: Finalize
+
+> ⚠️ **PREREQUISITE: Phase 5.3 can ONLY execute AFTER user has explicitly confirmed in Phase 5.2.**
+>
+> IF user has NOT confirmed → DO NOT execute any step below.
+> IF you are unsure whether user confirmed → DO NOT execute any step below.
+>
+> **Verification before proceeding:**
+> - Did user explicitly say "确认" or "OK" in Phase 5.2?
+> - If NO → Return to Phase 5.2 and wait for confirmation
+> - If YES → Proceed with the steps below
 
 **5.3.1 Update Checkpoints**
 
+Now update all checkpoints (user has confirmed):
+
 ```bash
+# Update verification_checklist checkpoint
+node speccrew-workspace/scripts/update-progress.js write-checkpoint \
+  --file {iteration_path}/01.product-requirement/.checkpoints.json \
+  --checkpoint verification_checklist \
+  --passed true
+
+# Update prd_review checkpoint
 node speccrew-workspace/scripts/update-progress.js write-checkpoint \
   --file {iteration_path}/01.product-requirement/.checkpoints.json \
   --checkpoint prd_review \

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

@@ -21,6 +21,12 @@ tools: Read, Write, Glob, Grep
 
 3. **MANDATORY: Template-first workflow** — Step 4a (copy template) MUST execute before Step 4b (fill sections). Skipping Step 4a and writing content directly is FORBIDDEN.
 
+4. **ABORT CONDITIONS** — If any of the following occur, STOP immediately and report to user:
+   - Feature Spec document (`feature_spec_path`) does not exist or is empty → STOP
+   - API Contract template file does not exist → STOP
+   - `node ... update-progress.js` script execution fails → **HARD STOP**: Do NOT manually create or edit JSON progress files. Report the script error and wait for user resolution.
+   - User rejects Joint Confirmation → STOP, ask user for specific revision requirements
+
 ## Step 1: Read Input
 
 ### Input Parameters
@@ -152,6 +158,8 @@ After confirmation, you can start frontend and backend Designer Agents separatel
 
 After user confirms Joint Confirmation:
 
+> **SCRIPT ENFORCEMENT RULE**: All `.checkpoints.json` and `WORKFLOW-PROGRESS.json` updates MUST be performed via `node speccrew-workspace/scripts/update-progress.js` commands. Manually creating or editing these JSON files is FORBIDDEN. If the script fails, STOP and report the error — do NOT attempt manual JSON construction.
+
 ### 6a: Update Checkpoints File
 
 Update the `.checkpoints.json` file to record confirmation status.
@@ -272,6 +280,8 @@ Update `WORKFLOW-PROGRESS.json` to reflect current feature/module status.
 - Record all output file paths
 - Log: "✅ Stage 02_feature_design confirmed. Ready for System Design phase."
 
+> **Note**: On Windows PowerShell, do not use backslash (`\`) for line continuation. Write the entire command on a single line.
+
 **关于全局状态管理的说明**：
 > Feature 粒度的 API Contract 完成后，全局阶段状态（`02_feature_design.status` 和 `current_stage`）**不由本 Skill 更新**。
 > 全局状态由 **Feature Designer Agent** 统一管理，当检测到所有 Feature 都完成时，统一更新为 `confirmed` 并推进到下一阶段。