speccrew 0.2.7 → 0.3.0

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

@@ -23,7 +23,20 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Input
 
-1. Feature spec document: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
+### Input Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `feature_id` | Optional | Feature 唯一标识符，如 `F-CRM-01`（向后兼容：不传则使用当前逻辑） |
+| `feature_name` | Optional | Feature 名称，如 `customer-list`（向后兼容：不传则使用当前逻辑） |
+
+### Input Files
+
+1. **Feature Spec 文档**：
+   - **新格式（推荐）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
+   - **旧格式（向后兼容）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
+   - 优先检查新格式，不存在则回退到旧格式
+
 2. API Contract template: `speccrew-fd-api-contract/templates/API-CONTRACT-TEMPLATE.md`
 3. System architecture (API specification part): Refer to project tech-stack-mappings.json for API naming conventions
 
@@ -53,9 +66,11 @@ Complete definition for each API:
 ### 4a Copy Template to Document Path
 
 1. **Read the template file**: `templates/API-CONTRACT-TEMPLATE.md`
-2. **Replace top-level placeholders** (feature name, date, etc.)
+2. **Replace top-level placeholders** (feature name, date, feature_id if provided, etc.)
 3. **Create the document** using `create_file`:
-   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+   - **新格式（当提供了 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md`
+     - 示例：`F-CRM-01-customer-list-api-contract.md`
+   - **旧格式（向后兼容，未提供 feature_id 时）**：`speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
    - Content: Template with top-level placeholders replaced
 4. **Verify**: Document has complete section structure ready for filling
 
@@ -80,8 +95,42 @@ For each API, locate its section anchor in the template and use `search_replace`
 
 ## Step 5: Joint Confirmation
 
-After both documents (Feature Spec + API Contract) are ready, request confirmation from user:
+After both documents (Feature Spec + API Contract) are ready, request user confirmation:
 
+**Conditional Confirmation Logic:**
+```
+IF feature_id is provided THEN
+  → Execute Feature-granular confirmation (情况 A)
+ELSE
+  → Execute Module-level confirmation (情况 B)
+```
+
+**情况 A：提供了 feature_id（Feature 粒度确认）**
+```
+Feature 设计阶段交付物已准备就绪：
+
+📋 Feature 信息：
+   - Feature ID: {feature_id}
+   - Feature 名称: {feature_name}
+
+📄 文档清单：
+   - Feature Spec: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md
+   - API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md
+
+请确认以下关键点：
+1. 当前 Feature 的技术方案是否可行？
+2. API 定义是否满足前端需求？
+3. 数据模型设计是否合理？
+
+⚠️ 确认后，API Contract 将成为前后端协作的唯一基准。
+   在设计/开发阶段只读引用，不允许修改。
+   如需变更，必须返回此阶段重新确认。
+
+✅ 当前仅确认单个 Feature 的交付物。
+   全局阶段状态（02_feature_design）将在所有 Feature 完成后由 Feature Designer Agent 统一更新。
+```
+
+**情况 B：未提供 feature_id（向后兼容，模块级确认）**
 ```
 Feature design phase deliverables are ready:
 - Feature Spec: speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md
@@ -103,20 +152,20 @@ After confirmation, you can start frontend and backend Designer Agents separatel
 
 After user confirms Joint Confirmation:
 
-### 6.1 Update Checkpoints File
+### 6a: Update Checkpoints File
 
-Write/Update `.checkpoints.json`:
+Update the `.checkpoints.json` file to record confirmation status.
+
+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": "..."
-      },
+
+**情况 A：提供了 feature_id（Feature 粒度）**
+```json
+{
+  "stage": "02_feature_design",
+  "feature_checkpoints": {
+    "{feature_id}": {
       "feature_spec_review": {
         "passed": true,
         "confirmed_at": "..."
@@ -124,43 +173,109 @@ Write/Update `.checkpoints.json`:
       "api_contract_joint": {
         "passed": true,
         "confirmed_at": "{current_timestamp}",
-        "description": "API contract joint confirmation passed"
+        "description": "API contract joint confirmation passed for {feature_id}"
       }
     }
+  },
+  "checkpoints": {
+    "function_decomposition": {
+      "passed": true,
+      "confirmed_at": "..."
+    }
   }
-  ```
+}
+```
+
+- 使用 `feature_checkpoints.{feature_id}` 作为 key 存储单个 Feature 的状态
+- 保留原有的 `checkpoints` 用于全局检查点
+- Log: "✅ Checkpoint (api_contract_joint) passed and recorded for Feature {feature_id}"
+
+**情况 B：未提供 feature_id（向后兼容，模块级）**
+```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
+### 6b: Update Workflow Progress
 
-Update `WORKFLOW-PROGRESS.json` to finalize the stage:
+Update `WORKFLOW-PROGRESS.json` to reflect current feature/module status.
 
 - 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"
-        ]
+
+**情况 A：提供了 feature_id（Feature 粒度）**
+```json
+{
+  "current_stage": "02_feature_design",
+  "stages": {
+    "02_feature_design": {
+      "status": "in_progress",
+      "features": {
+        "{feature_id}": {
+          "status": "confirmed",
+          "completed_at": "{current_timestamp}",
+          "confirmed_at": "{current_timestamp}",
+          "outputs": [
+            "02.feature-design/{feature-id}-{feature-name}-feature-spec.md",
+            "02.feature-design/{feature-id}-{feature-name}-api-contract.md"
+          ]
+        }
       }
     }
   }
-  ```
+}
+```
+
+- **重要**：单个 Feature 完成时，**不修改** `02_feature_design.status`（保持 `in_progress`）
+- **重要**：**不修改** `current_stage`（保持 `02_feature_design`）
+- 仅在 `stages.02_feature_design.features.{feature_id}` 中记录该 Feature 的完成状态
+- Log: "✅ Feature {feature_id} API Contract confirmed. Feature Designer Agent will update global stage status when all features are completed."
+
+**情况 B：未提供 feature_id（向后兼容，模块级）**
+```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."
 
+**关于全局状态管理的说明**：
+> Feature 粒度的 API Contract 完成后，全局阶段状态（`02_feature_design.status` 和 `current_stage`）**不由本 Skill 更新**。
+> 全局状态由 **Feature Designer Agent** 统一管理，当检测到所有 Feature 都完成时，统一更新为 `confirmed` 并推进到下一阶段。
+
 ### 6.3 Backward Compatibility
 
 If `WORKFLOW-PROGRESS.json` does not exist:
@@ -175,5 +290,5 @@ If `WORKFLOW-PROGRESS.json` does not exist:
 - [ ] Each API has complete request/response structure definition
 - [ ] URL naming conforms to backend architecture specifications
 - [ ] Error code list is complete
-- [ ] File has been written to correct path
-- [ ] Summary of both documents has been shown to user and confirmation requested
+- [ ] File has been written to correct path (with proper naming convention based on feature_id)
+- [ ] Summary of both documents has been shown to user and confirmation requested (including Feature ID if applicable)

package/.speccrew/skills/speccrew-fd-feature-design/SKILL.md

@@ -24,14 +24,36 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read PRD Input
 
+### 1.1 Input Parameters
+
+The skill receives the following parameters from the calling agent:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `feature_id` | No | Feature identifier (e.g., `F-CRM-01`). If not provided, processes entire PRD (backward compatibility) |
+| `feature_name` | No | Feature name in English (e.g., `customer-list`). Used for file naming |
+| `feature_type` | No | `Page+API` or `API-only`. `API-only` skips frontend design steps |
+| `iteration_id` | No | Current iteration identifier. Paths come from `prd_path`/`output_path`; `iteration_id` is used only for progress messages when available |
+| `prd_path` | Yes | Path to the Sub-PRD document |
+
+### 1.2 Read PRD
+
 Read in order:
 
-1. **Current iteration PRD**: `speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/[feature-name]-prd.md`
+1. **Current iteration PRD**: `{prd_path}` (typically `speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/[module-name]-prd.md`)
 2. **Feature spec template**: `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md`
 
-**[Master-Sub PRD structure]** If master PRD exists, also read all sub PRDs:
-- Master PRD: `[feature-name]-prd.md`
-- Sub PRDs: `[feature-name]-sub-[module1].md`, `[feature-name]-sub-[module2].md`, etc.
+### 1.3 Focus on Specific Feature (when feature_id provided)
+
+If `feature_id` is provided:
+- Locate the specific Feature in PRD Section 3.4 "Feature Breakdown"
+- Extract only the user stories and requirements related to this Feature
+- Ignore other Features in the same PRD
+- Use the Feature's scope to guide function breakdown
+
+### 1.4 Backward Compatibility (when feature_id not provided)
+
+If `feature_id` is NOT provided, process entire PRD using legacy mode. For Master-Sub PRD structure, read master PRD and all sub PRDs. See Reference Guides for detailed behavior.
 
 ## Step 2: Load System Knowledge
 
@@ -77,6 +99,25 @@ If cross-module relationships need analysis, use `speccrew-knowledge-graph-query
 
 Break down PRD functional requirements into implementable system functions.
 
+### 3.1 Feature-Based Decomposition (when feature_id provided)
+
+When processing a single Feature:
+
+1. **Extract Feature Scope**: From PRD Section 3.4, locate the specific Feature by `feature_id`
+2. **Identify Related User Stories**: Extract only user stories mapped to this Feature
+3. **Decompose into Functions**: Break down into 3-8 focused Functions (not 10-20)
+4. **Check feature_type**:
+   - If `feature_type = API-only`: Mark for backend-only design (skip frontend in Step 5)
+   - If `feature_type = Page+API`: Include both frontend and backend design
+
+### 3.2 Full PRD Decomposition (backward compatibility)
+
+When `feature_id` is NOT provided (legacy mode):
+- Decompose entire PRD into all required Functions
+- May result in 10-20 Functions for complex modules
+
+### 3.3 Function Analysis
+
 For each function, identify:
 
 | Aspect | Analysis Content |
@@ -132,14 +173,28 @@ After user confirms the function breakdown:
 
 ## Step 4: Determine Output Structure
 
-Based on PRD structure, determine feature spec output structure:
+### 4.1 Single Feature Output (when feature_id provided)
+
+When processing a single Feature:
+
+| Output | Description |
+|--------|-------------|
+| **Single File** | One Feature Spec document for this Feature only |
+| **File Naming** | `[feature-id]-[feature-name]-feature-spec.md` |
+| **Example** | `F-CRM-01-customer-list-feature-spec.md` |
+
+**No Master-Sub structure** for single Feature mode.
+
+### 4.2 Legacy Output (backward compatibility)
+
+When `feature_id` is NOT provided:
 
 | PRD Structure | Feature Spec Structure |
 |---------------|------------------------|
 | **Single PRD** | Single Feature Spec |
 | **Master-Sub PRD** | Master Feature Spec + Sub Feature Specs (one per module) |
 
-### Master Feature Spec Structure
+#### Master Feature Spec Structure (Legacy)
 
 ```
 02.feature-design/
@@ -164,6 +219,18 @@ Based on PRD structure, determine feature spec output structure:
 
 ## Step 5: Frontend Design (Per Function)
 
+### 5.0 Conditional Execution Based on feature_type
+
+**Execution Logic:**
+```
+IF feature_type = "Page+API" THEN
+  → Execute Step 5 (Full frontend design)
+IF feature_type = "API-only" THEN
+  → Skip Step 5 entirely (No frontend design needed)
+IF feature_type is NOT provided THEN
+  → Execute Step 5 (backward compatibility)
+```
+
 **Multi-Platform Rule**: If multiple frontend platforms are identified, repeat the frontend design (5.1 UI Prototype + 5.2 Interface Elements + 5.3 Interaction Flow) for EACH platform. Use platform-specific section headers:
 
 | Platforms | Section Structure |
@@ -173,6 +240,8 @@ Based on PRD structure, determine feature spec output structure:
 
 **Mobile-specific wireframe patterns:**
 
+> **Note**: These are ASCII wireframe design specifications, NOT actual template files in the `templates/` directory.
+
 ```
 Pattern M-A: Card List (replaces PC table list)
 +----------------------------------+
@@ -418,17 +487,15 @@ Frontend Components: {count} pages/components
 Backend Interfaces: {count} APIs
 Data Entities: {count} new, {count} modified
 
-[Master-Sub] Output Structure:
-- Master Feature Spec: {filename}
-- Sub Feature Specs: {list of filenames}
+Output File: {filename}
 ```
 
 **Ask user to confirm:**
-1. Is the frontend prototype appropriate for user needs?
+1. Is the frontend prototype appropriate for user needs? (if applicable)
 2. Is the backend logic flow correct and complete?
 3. Is the data model reasonable and extensible?
 4. Are all business rules and constraints captured?
-5. **[Master-Sub]** Is the module breakdown appropriate?
+5. **[Legacy Master-Sub]** Is the module breakdown appropriate?
 
 ### Checkpoint B Progress Update
 
@@ -466,6 +533,19 @@ After user confirms the complete feature spec:
 
 ### 10.1 Determine Output Paths
 
+#### Single Feature Mode (when feature_id provided)
+
+```
+speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md
+```
+
+**Naming Rules:**
+- `feature-id`: As provided in input (e.g., `F-CRM-01`)
+- `feature-name`: Converted to kebab-case (lowercase with hyphens)
+- **Example**: `F-CRM-01-customer-list-feature-spec.md`
+
+#### Legacy Mode (backward compatibility)
+
 **Single Feature Spec:**
 ```
 speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md
@@ -517,7 +597,7 @@ Fill sections sequentially using `search_replace` for each content block:
 | **Business Rules** | Permissions, validation, business logic rules |
 | **Cross-Module Interactions** | **[If applicable]** Interface contracts between modules |
 
-For Master-Sub specs, repeat Step 10.2a + 10.2b for each sub-spec document.
+For legacy Master-Sub specs (when feature_id not provided), repeat Step 10.2a + 10.2b for each sub-spec document.
 
 ### 10.3 Mermaid Diagram Requirements
 
@@ -631,6 +711,44 @@ After each worker completes:
 
 5. Log progress: "📊 Dispatch progress: {completed}/{total} completed, {failed} failed, {pending} pending"
 
+---
+
+# Reference Guides
+
+## Backward Compatibility Details (Legacy Mode)
+
+When `feature_id` is NOT provided, the skill operates in legacy mode:
+
+### Master-Sub PRD Structure
+
+If master PRD exists, also read all sub PRDs:
+- Master PRD: `[feature-name]-prd.md`
+- Sub PRDs: `[feature-name]-sub-[module1].md`, `[feature-name]-sub-[module2].md`, etc.
+
+### Output Structure (Legacy)
+
+**Single Feature Spec:**
+```
+speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md
+```
+
+**Master-Sub Feature Specs:**
+```
+02.feature-design/
+├── [feature-name]-feature-spec.md          # Master Feature Spec (overview + cross-module)
+├── [feature-name]-sub-[module1]-spec.md    # Sub Feature Spec: Module 1
+├── [feature-name]-sub-[module2]-spec.md    # Sub Feature Spec: Module 2
+```
+
+**Master Feature Spec MUST include:**
+- Overall feature overview and goals
+- Cross-module interaction diagram
+- Module list with scope boundaries
+- Cross-module interface contracts
+- Shared data structures
+
+---
+
 # Key Rules
 
 | Rule | Description |
@@ -645,22 +763,26 @@ After each worker completes:
 # Checklist
 
 - [ ] PRD has been read, all P0 requirements covered
-- [ ] **[Master-Sub]** All sub PRDs have been read
+- [ ] **[Single Feature Mode]** Feature ID and name parameters received
+- [ ] **[Single Feature Mode]** Only related Feature content extracted from PRD
+- [ ] **[Legacy Mode]** All sub PRDs have been read (if master-sub structure)
 - [ ] System overview loaded for context
 - [ ] Related module overviews loaded
 - [ ] **[Cross-module]** Knowledge graph queried for relationship analysis
 - [ ] Function breakdown completed with [EXISTING]/[MODIFIED]/[NEW] markers
+- [ ] **[Single Feature Mode]** 3-8 focused Functions defined
 - [ ] Checkpoint A passed: function breakdown confirmed with user
-- [ ] Output structure determined (single vs master-sub)
-- [ ] Frontend design includes ASCII wireframes and interaction flows
+- [ ] Output structure determined (single file for Feature mode)
+- [ ] **[API-only]** Frontend design step skipped correctly
+- [ ] **[Page+API]** Frontend design includes ASCII wireframes and interaction flows
 - [ ] **[Multi-platform]** Each frontend platform has separate wireframes and interaction flows
 - [ ] Backend design includes interface list and logic flows
 - [ ] Data model includes new entities and modifications to existing
 - [ ] Business rules and constraints documented
 - [ ] Checkpoint B passed: complete feature spec confirmed with user
-- [ ] **[Master-Sub]** Master spec includes cross-module overview and contracts
-- [ ] **[Master-Sub]** Each sub spec covers exactly one module
+- [ ] **[Legacy Master-Sub]** Master spec includes cross-module overview and contracts
+- [ ] **[Legacy Master-Sub]** Each sub spec covers exactly one module
 - [ ] All Mermaid diagrams follow mermaid-rule.md
 - [ ] No specific technology decisions included
-- [ ] Files written to correct paths
+- [ ] Files written to correct paths with proper naming (`{feature-id}-{feature-name}-feature-spec.md`)
 - [ ] API contract skill called after writing

package/.speccrew/skills/speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md

@@ -12,7 +12,10 @@
 
 | Item | Description |
 |------|-------------|
+| Feature ID | {Feature ID, e.g., F-CRM-01} |
 | Feature Name | {Feature Name} |
+| Feature Type | {Page+API / API-only} |
+| Source PRD | {Link to Sub-PRD document} |
 | Module | {Module Name} |
 | Core Function | {1-3 sentences describing core feature value} |
 | Target Users | {Describe target user groups} |
@@ -20,7 +23,7 @@
 
 ### 1.2 Feature Scope
 
-<!-- AI-NOTE: Check all items that this specification covers -->
+<!-- AI-NOTE: This specification covers a SINGLE Feature (business operation unit), not the entire module. Check all items that this specification covers. -->
 
 - [ ] {Function 1} - Frontend prototype + Interaction flow + Backend interface + Data definition
 - [ ] {Function 2} - Frontend prototype + Interaction flow + Backend interface + Data definition

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

@@ -30,9 +30,8 @@ Analyze one specific API controller from source code, extract all business featu
 | `{{platform_type}}` | string | Platform type | `"admin-api"`, `"app-api"` |
 | `{{platform_subtype}}` | string | Platform subtype | `"spring-boot"`, `"java"` |
 | `{{tech_stack}}` | array | Platform tech stack | `["java", "spring-boot", "mybatis-plus"]` |
-| `{{completed_dir}}` | string | Directory for completion marker files (`sync_state_path/completed`) | `"speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed"` |
-| `{{sourceFile}}` | string | Source features JSON file name | `"features-admin-api.json"` |
-| `{{language}}` | string | **REQUIRED** - Target language for generated content | `"zh"`, `"en"` |
+
+> **Note**: Additional parameters for completion markers (`completed_dir`, `sourceFile`, `language`) are defined in Step 7 and Language Adaptation section.
 
 ## Language Adaptation
 
@@ -129,8 +128,14 @@ graph TB
 **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 tech stack:**
    - Java/Spring Boot: Read `templates/FEATURE-DETAIL-TEMPLATE.md`
@@ -216,13 +221,8 @@ Each public API endpoint in the controller = one feature.
 - Document ALL public API endpoints with their HTTP methods and paths
 - For **internal service methods**: only record references, do not document as separate features
 - Document business flows for each API endpoint: request validation → business logic → data persistence → response
-- **Generate Mermaid flowcharts following `speccrew-workspace/docs/rules/mermaid-rule.md` guidelines:**
-  - Use `graph TB` or `graph LR` syntax (not `flowchart`)
-  - No parentheses `()` in node text (e.g., use `validate request` instead of `validate()`)
-  - No HTML tags like `<br/>`
-  - No `style` definitions
-  - No nested `subgraph`
-  - No special characters in node text
+- **Read Configuration**: Read `speccrew-workspace/docs/rules/mermaid-rule.md` for Mermaid diagram guidelines
+- **Generate Mermaid flowcharts** following the configuration (see [Reference Guides > Mermaid Guide](#mermaid-guide) for quick reference)
 - Use `{{language}}` for all extracted content naming
 
 **Example Code Analysis:**
@@ -846,12 +846,15 @@ Or in case of failure:
 
 **⚠️ MANDATORY - This step MUST be executed. The task is NOT complete until marker files are written.**
 
-分析完成后，将结果写入标记文件，供 dispatch 批量处理。
+Write analysis results to marker files for dispatch batch processing.
+
+**Input Parameters (from dispatch):**
+- `{{completed_dir}}` - **REQUIRED** - Marker files output directory (e.g., `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed`)
+- `{{sourceFile}}` - **REQUIRED** - Source features JSON file name (e.g., `features-admin-api.json`)
+- `{{language}}` - **REQUIRED** - Target language for content (see Language Adaptation section)
 
 **Prerequisites:**
 - Step 6 completed successfully
-- `{{completed_dir}}` - Marker files output directory (e.g., `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed`)
-- `{{sourceFile}}` - Source features JSON file name
 
 > **ASSUMPTION**: The `completed_dir` directory already exists (pre-created by dispatch Stage 2). If write fails, report error — do NOT attempt to create directories.
 
@@ -1103,6 +1106,17 @@ Before writing the graph.json file, verify:
 
 ## Reference Guides
 
+### Mermaid Guide
+
+When generating Mermaid diagrams, follow these compatibility guidelines from `speccrew-workspace/docs/rules/mermaid-rule.md`:
+
+- Use `graph TB` or `graph LR` syntax (not `flowchart`)
+- No parentheses `()` in node text
+- No HTML tags like `<br/>`
+- No `style` definitions
+- No nested `subgraph`
+- No special characters in node text
+
 ### Business Flow Diagram Guidelines
 
 When generating business flow diagrams in feature documents, follow these principles: