speccrew 0.5.5 → 0.5.7

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

@@ -24,6 +24,10 @@ This skill applies ISA-95 Stages 1-3 as an internal thinking framework for analy
 
 # Workflow
 
+**MANDATORY:**
+- **Business Perspective Only** — Feature Analysis is a PURE BUSINESS document. It describes WHAT the system does from a business/user perspective, NOT HOW it's technically implemented.
+- **Mermaid for all diagrams** — ALL business flows, interaction sequences, and cross-function flows MUST use Mermaid syntax (`flowchart TB`, `sequenceDiagram`). Plain text ASCII flowcharts are FORBIDDEN.
+
 ## Absolute Constraints
 
 > **Violation = task failure**
@@ -198,6 +202,16 @@ Write analysis results to `.feature-analysis.md`:
 - **Data Changes**: {description}
 - **System Relationship**: [EXISTING]/[MODIFIED]/[NEW] — {explanation}
 
+> **Content Guidelines for Function Details:**
+> 
+> | Aspect | ✅ ALLOWED (Business) | ❌ FORBIDDEN (Technical) |
+> |--------|----------------------|--------------------------|
+> | Frontend Changes | "New appointment list page with search/filter" | "AppointmentIndex.vue, ElDatePicker, v-hasPermi" |
+> | Backend Changes | "Create appointment management operations with validation" | "@PreAuthorize, AppointmentService.java, MapStruct" |
+> | Data Changes | "New appointment entity with status lifecycle" | "appointment_info table, customer_id BIGINT, SQL DDL" |
+> | System Relationship | "[NEW] Full new business module" | "yudao-module-appointment Maven submodule" |
+> | Diagrams | Mermaid flowchart/sequenceDiagram | ASCII text flowcharts |
+
 ## Name Discrepancy Notice (if applicable)
 - Parameter feature_name: {feature_name}
 - PRD actual feature name: {prd_name}
@@ -215,8 +229,16 @@ Write analysis results to `.feature-analysis.md`:
 
 | Rule | Description |
 |------|-------------|
-| **Analysis Only** | Do NOT design UI wireframes, API specs, or data models |
-| **Clear Markers** | Always use [EXISTING]/[MODIFIED]/[NEW] to indicate system relationship |
+| **Business Perspective Only** | Feature Analysis describes business capabilities and functional requirements. Every section must describe WHAT from user/business perspective |
+| **FORBIDDEN: File Paths** | Do NOT include any file paths, code paths, or directory structures (e.g., views/appointment/AppointmentIndex.vue, yudao-module-appointment/...) |
+| **FORBIDDEN: Framework Code** | Do NOT include code snippets in any language — no Java classes, SQL DDL/DML, Vue templates, TypeScript API code, HTML markup, annotations (@PreAuthorize, @OperateLog, @TableLogic, @TableName) |
+| **FORBIDDEN: Framework/Library Names** | Do NOT reference specific framework/library names as implementation details (MyBatis-Plus, MapStruct, Element Plus, wot-design-uni, ElDatePicker, wd-cell, BaseMapperX, etc.) |
+| **FORBIDDEN: Database Artifacts** | Do NOT include database table names (appointment_info), column names (customer_id, staff_id), SQL types (BIGINT, VARCHAR), indexes, or any SQL statements |
+| **FORBIDDEN: Technical Types** | Do NOT use programming language types (Long, String, Integer). Use business types: Text, Number, Date, Boolean, Enum, Identifier |
+| **FORBIDDEN: ASCII Diagrams** | Do NOT use plain text or ASCII art flowcharts. ALL diagrams MUST use Mermaid syntax |
+| **Mermaid Required** | Use `flowchart TB` for business process flows, `sequenceDiagram` for interaction flows. Reference mermaid-rule.md for syntax compliance |
+| Analysis Only | Do NOT design UI wireframes, API specs, or data models — that belongs to Feature Design phase |
+| System Markers | Always use [EXISTING]/[MODIFIED]/[NEW] to indicate system relationship |
 | **Checkpoint A Required** | User confirmation required before design phase (unless skipped) |
 | **Use Script for JSON** | Always use `update-progress.js` for checkpoint files |
 | **Output Contract** | `.feature-analysis.md` serves as interface for downstream design skills |
@@ -235,3 +257,5 @@ Write analysis results to `.feature-analysis.md`:
 - [ ] Checkpoint A passed: function breakdown confirmed with user (or skipped)
 - [ ] `.checkpoints.json` updated via script
 - [ ] `.feature-analysis.md` written to correct path
+- [ ] **CRITICAL — Business Content Only**: All sections use business-level descriptions. ZERO file paths, framework names, code snippets, SQL, database table/column names, component library names, or technical types
+- [ ] **CRITICAL — Mermaid Diagrams**: All process flows use Mermaid syntax (flowchart TB or sequenceDiagram). No ASCII text flowcharts

package/.speccrew/skills/speccrew-fd-feature-analyze/templates/FEATURE-ANALYSIS-TEMPLATE.md

@@ -0,0 +1,180 @@
+<!-- AI-NOTE: CRITICAL — Business Perspective Guidelines
+This Feature Analysis is a PURE BUSINESS document. It describes WHAT the system needs to do, NOT HOW it will be implemented.
+
+FORBIDDEN content (DO NOT include any of these):
+- ❌ File paths (src/views/..., yudao-module-xxx/...)
+- ❌ Framework/library names as implementation (MyBatis-Plus, MapStruct, Element Plus, wot-design-uni)
+- ❌ Code snippets in any language (Java, SQL, Vue, TypeScript)
+- ❌ Database table/column names (appointment_info, customer_id)
+- ❌ Technical types (BIGINT, VARCHAR, Long, String)
+- ❌ Component names (ElDatePicker, wd-cell, el-button)
+- ❌ Framework annotations (@PreAuthorize, @TableLogic, @OperateLog)
+- ❌ ASCII text flowcharts (use Mermaid instead)
+
+REQUIRED:
+- ✅ Business-level descriptions only
+- ✅ Mermaid diagrams for all flows (flowchart TB, sequenceDiagram)
+- ✅ [EXISTING]/[MODIFIED]/[NEW] system relationship markers
+-->
+
+# Feature Analysis: {feature-name}
+
+## Feature Information
+
+| Item | Value |
+|------|-------|
+| Feature ID | {feature_id} |
+| Feature Name | {feature_name} |
+| Feature Type | {Page+API / API / Page} |
+| Source PRD | {prd_relative_path} |
+| Iteration | {iteration_id} |
+| Analysis Date | {date} |
+
+---
+
+## System Context Summary
+
+<!-- AI-NOTE: Provide a business-level overview of how this feature fits into the system.
+Describe existing system capabilities that this feature can leverage.
+Use BUSINESS terms only — do NOT mention specific frameworks, libraries, or technical components.
+
+✅ CORRECT: "Leverages existing user authentication and role-based access control"
+❌ WRONG: "Uses Spring Security @PreAuthorize and yudao-module-system AuthController" -->
+
+### System Overview
+
+{Brief description of the system and how this feature relates to it}
+
+### Existing Reusable Capabilities
+
+| Capability | Relevance to This Feature |
+|------------|--------------------------|
+| {e.g., User Authentication} | {e.g., All operations require authenticated sessions} |
+| {e.g., Role-based Access} | {e.g., Different data visibility per role} |
+
+### Feature Dependencies
+
+| Dependent Feature | Dependency Type | Description |
+|-------------------|-----------------|-------------|
+| {e.g., F-CUST-001 Customer Management} | Data | {e.g., Appointment links to customer records} |
+
+### Business Data Flow
+
+<!-- AI-NOTE: Use Mermaid flowchart to show data flow. NO ASCII text diagrams. -->
+
+```mermaid
+flowchart TB
+    A["{Input Source}"] --> B["{This Feature}"]
+    B --> C["{Output/Downstream}"]
+    D["{Dependent Feature}"] --> B
+```
+
+---
+
+## Frontend Platforms
+
+| Platform ID | Type | Description |
+|-------------|------|-------------|
+| {platform_id} | {Web/Mobile} | {Brief platform description} |
+
+---
+
+## Function Breakdown (Total: {N} functions)
+
+<!-- AI-NOTE: List all functions identified from the PRD.
+Each function should be a distinct business capability, NOT a technical component.
+✅ CORRECT: "Appointment List with Search/Filter"
+❌ WRONG: "AppointmentController REST endpoints" -->
+
+| # | Function Name | Type | Related User Stories | System Relationship |
+|---|--------------|------|---------------------|---------------------|
+| F1 | {business function name} | {frontend/backend/both} | {user story references} | [NEW]/[EXISTING]/[MODIFIED] |
+
+---
+
+## Function Details
+
+<!-- AI-NOTE: Repeat this section for each function.
+ALL descriptions must be from BUSINESS perspective.
+FORBIDDEN: file paths, class names, component names, database tables, SQL, code snippets.
+Use Mermaid for any process flows. -->
+
+### F1: {Function Name}
+
+**Description**: {1-2 sentence business description of what this function does for the user}
+
+- **Frontend Changes ({platform_id})**:
+  <!-- AI-NOTE: Describe WHAT pages/screens/interactions are needed from a user perspective.
+  ✅ "New appointment list page with multi-criteria search, role-based data filtering, and status indicators"
+  ❌ "New AppointmentIndex.vue with ElDatePicker, v-hasPermi directive, el-button components" -->
+  - {[NEW/MODIFIED]} {Business description of the page/interaction}
+
+- **Backend Changes**:
+  <!-- AI-NOTE: Describe WHAT business operations are needed, not HOW they're implemented.
+  ✅ "Paginated query supporting customer name, date range, and status filters with role-based data isolation"
+  ❌ "GET /appointment/page endpoint with @PreAuthorize, using BaseMapperX" -->
+  - {[NEW/MODIFIED]} {Business description of the operation}
+
+- **Data Changes**:
+  <!-- AI-NOTE: Describe WHAT data entities are needed at a conceptual level.
+  ✅ "New Appointment entity with: ID, customer reference, staff reference, date/time, status lifecycle"
+  ❌ "New appointment_info table with customer_id BIGINT, staff_id BIGINT, CREATE TABLE..." -->
+  - {[NEW/MODIFIED]} {Business description of data entities and key attributes}
+
+- **System Relationship**: {[NEW]/[EXISTING]/[MODIFIED]} — {explanation of how this relates to existing system capabilities}
+
+**Business Flow**:
+
+```mermaid
+flowchart TB
+    Start(["{User action}"]) --> Step1["{Business step 1}"]
+    Step1 --> Decision{"{Business decision}"}
+    Decision -->|Yes| Step2["{Business step 2}"]
+    Decision -->|No| Error["{Error handling}"]
+    Step2 --> End(["{Completion}"])
+```
+
+---
+
+## Name Discrepancy Notice (if applicable)
+
+<!-- AI-NOTE: Only include this section if parameter feature_name differs from PRD feature name -->
+
+| Item | Value |
+|------|-------|
+| Parameter feature_name | {feature_name} |
+| PRD actual feature name | {prd_name} |
+| Discrepancy | {description} |
+| File naming follows | parameter value (as per Filename Lock Rule) |
+
+---
+
+## Summary Statistics
+
+| Item | Count |
+|------|-------|
+| Total Functions | {N} |
+| [NEW] Functions | {count} |
+| [MODIFIED] Functions | {count} |
+| [EXISTING] Reused Capabilities | {count} |
+| Frontend Platforms | {count} |
+
+---
+
+## Decomposition Status
+
+| Checkpoint | Status | Timestamp |
+|------------|--------|-----------|
+| Checkpoint A | {passed/pending} | {timestamp or null} |
+
+---
+
+## Checklist
+
+- [ ] PRD read and all requirements covered
+- [ ] System knowledge loaded
+- [ ] Function breakdown complete with [NEW]/[EXISTING]/[MODIFIED] markers
+- [ ] Function count within 3-8 range (Single Feature Mode)
+- [ ] **CRITICAL — Business content only**: Zero file paths, framework names, code snippets, SQL, database artifacts, component names
+- [ ] **CRITICAL — Mermaid diagrams**: All flows use Mermaid syntax, no ASCII flowcharts
+- [ ] Checkpoint A passed

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

@@ -36,6 +36,7 @@ ISA-95 Stages 4-6 as internal thinking framework:
 
 **MANDATORY:**
 - Template-first workflow — Step 5 (copy template) MUST precede Step 6 (fill content)
+- **Mermaid for all diagrams** — ALL interaction flows, processing logic flows, and cross-function sequences MUST use Mermaid syntax (`sequenceDiagram`, `flowchart TD`). Plain text ASCII flowcharts are FORBIDDEN for these sections. Reference: `speccrew-workspace/docs/rules/mermaid-rule.md`.
 
 **NOTE:** Design process is internal — no intermediate design-data files are produced.
 
@@ -170,6 +171,8 @@ Create ASCII wireframes showing layout, UI elements, navigation.
 
 Document: `User Action → Frontend Response → Backend API Call`
 
+**Output format: Mermaid `sequenceDiagram`** — Generate interaction flows as Mermaid sequence diagrams showing: User → Frontend → Backend API → Data Store. DO NOT use ASCII text charts.
+
 > **ISA-95 Stage 4 Thinking — Information Flows**
 > - Cross-module flows: Map data flows between feature and other modules
 > - Sequence coverage: Complete chain user→frontend→backend→database→external
@@ -184,6 +187,12 @@ Document: `User Action → Frontend Response → Backend API Call`
 
 ## Step 2: Backend Design
 
+> **CRITICAL CONSTRAINT**: Backend design in Feature Spec must remain at the BUSINESS API level:
+> - Describe API endpoints as business operations (e.g., "Create Shop" operation with business parameters)
+> - Describe business validation rules in plain language (e.g., "Shop name must be unique within tenant")
+> - Describe data entities as business concepts with business field types (Text, Number, Date, Enum)
+> - Do NOT include: Java class names, SQL statements, ORM mappings, framework annotations, Maven module paths
+
 ### 2.1 API/Interface List
 
 | Interface | Method | Description |
@@ -199,6 +208,8 @@ Document: `User Action → Frontend Response → Backend API Call`
 | Data Operations | What data to read/write |
 | Response | What data to return |
 
+**Output format: Mermaid `flowchart TD`** — Generate processing logic as Mermaid flowcharts showing: business validation → data operation → response. DO NOT use ASCII text charts.
+
 ### 2.3 Data Access Scheme
 
 | Operation | Data Target | Type |
@@ -327,6 +338,14 @@ Document: `User Action → Frontend Response → Backend API Call`
 
 5. **Data Model Completeness**: "Does the data model cover all fields and relationships needed?"
 
+6. **CRITICAL — Business Perspective Validation**: "Does the specification contain ONLY business concepts and rules? Verify there are NO:
+   - ❌ File paths or code directory structures
+   - ❌ Framework names or specific technologies (Java, MyBatis, Vue component names, etc.)
+   - ❌ Actual code snippets or SQL statements
+   - ❌ Component library names or framework-specific syntax
+   - ❌ Database table/column names or technical data types
+   If ANY of these are present, you MUST revise the affected sections to use pure business descriptions before proceeding."
+
 **WAIT for user confirmation before proceeding to document generation.**
 
 ### 4.3 Update Checkpoints
@@ -396,6 +415,13 @@ Log: "✅ Checkpoint B (feature_design_review) passed and recorded"
 | 5. API Contract Summary | Aggregated from Step 2.1 API List |
 | 6. Notes | Contextual notes from analysis |
 
+**CRITICAL — Diagram Format Rule:**
+- "交互流程" / "Interaction Flow" sections → MUST use Mermaid `sequenceDiagram`
+- "核心业务逻辑" / "Processing Logic" sections → MUST use Mermaid `flowchart TD`
+- "跨函数流程" / "Cross-Function Flow" sections → MUST use Mermaid `sequenceDiagram`
+- Plain text / ASCII flowcharts are FORBIDDEN in these sections
+- Reference: `speccrew-workspace/docs/rules/mermaid-rule.md` for syntax compliance
+
 ### Filling Rules
 
 - Use `search_replace` for each section individually
@@ -447,6 +473,13 @@ Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review pass
 | No Technology Decisions | Do NOT specify frameworks, databases, technologies |
 | Focus on WHAT not HOW | Describe what system does, not how it's implemented |
 | ASCII Wireframes Only | Use ASCII art for UI prototypes |
+| **FORBIDDEN: File Paths** | Do NOT include any file paths, code paths, or directory structures (e.g., src/views/..., yudao-module-base/..., pages/...) |
+| **FORBIDDEN: Framework Code** | Do NOT include actual code snippets in any language — no Java classes, SQL DDL/DML, Vue templates, TypeScript API code, HTML markup |
+| **FORBIDDEN: Framework Names as Implementation** | Do NOT reference specific framework/library names as implementation choices (MyBatis-Plus, Flyway, Element Plus component names like el-button, wot-design-uni widget names like wd-cell) |
+| **FORBIDDEN: Technical Types** | Do NOT use database column types (VARCHAR, BIGINT, INT), Java types (Long, String), or ORM annotations (@TableName, @TableId). Use business types: Text, Number, Date, Boolean, Enum |
+| **FORBIDDEN: Component Names** | Do NOT reference UI component library element names (ElDatePicker, ElMessageBox, wd-date-time-picker). Describe interaction behavior instead |
+| **FORBIDDEN: Database Artifacts** | Do NOT include table names, column names, index names, or any SQL statements. Use conceptual entity names and business field names |
+| **Business Perspective Priority** | Feature Spec is a BUSINESS document. Every section must describe WHAT from a user/business perspective, never HOW from a technical implementation perspective |
 | Mermaid Compatibility | Follow mermaid-rule.md guidelines |
 | Clear Markers | Use [EXISTING]/[MODIFIED]/[NEW] consistently |
 | Template-First | Copy template before filling content |
@@ -471,7 +504,10 @@ Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review pass
 - [ ] Output path determined
 - [ ] Template copied using `create_file`
 - [ ] All sections filled using `search_replace`
-- [ ] Mermaid diagrams verified for compliance
+- [ ] **[CRITICAL]** Interaction Flow uses Mermaid sequenceDiagram (NOT ASCII)
+- [ ] **[CRITICAL]** Processing Logic uses Mermaid flowchart TD (NOT ASCII)
+- [ ] All Mermaid diagrams follow mermaid-rule.md compliance rules
 - [ ] `.checkpoints.json` updated via script
 - [ ] No technology decisions included
 - [ ] No intermediate design-data artifact created
+- [ ] **CRITICAL — Business Content Only**: Verify ALL sections use business-level descriptions. Zero tolerance for: file paths, code snippets, SQL, framework names, component names, technical types

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

@@ -1,5 +1,45 @@
 # Feature Specification - [Feature Name]
 
+<!-- AI-NOTE: CRITICAL — Business Perspective Guidelines
+This Feature Spec is a PURE BUSINESS document describing WHAT the system does, NOT HOW it's implemented.
+
+## What to Include (Business Perspective)
+- ✅ User roles, business processes, functional requirements
+- ✅ Data meaning, business rules, constraints (conceptual level)
+- ✅ API functionality and parameter business meaning (no framework details)
+- ✅ Business validation rules, permission rules (business level)
+- ✅ Interaction flow business logic (What happens)
+- ✅ Conceptual data entities and their relationships
+
+## What to EXCLUDE (Technical Perspective) — FORBIDDEN
+- ❌ File paths or code paths (src/views/..., yudao-module-base/..., pages/base/...)
+- ❌ Framework-specific code (Vue directives, Java annotations, SQL statements)
+- ❌ Framework/library names as implementation choices (MyBatis-Plus, Flyway, wot-design-uni, Element Plus component names)
+- ❌ Programming language specific types (VARCHAR(50), BIGINT, Long, String)
+- ❌ Component library element names (el-button, wd-cell, ElDatePicker, etc.)
+- ❌ Error code numeric values or enum definitions
+- ❌ Database table names, column names, SQL DDL/DML
+- ❌ API layer implementation (request.get, @TableName, etc.)
+- ❌ Maven/Gradle module paths, package paths
+- ❌ Class names, method signatures, annotation names
+
+## Correct Approach Examples
+
+❌ WRONG (Technical):
+| Field | Type | Constraint |
+| shop_id | BIGINT NOT NULL | FK to system_shop |
+
+✅ CORRECT (Business):
+| Field | Business Type | Constraint | Meaning |
+| Shop ID | Identifier | Required, references Shop entity | Which shop this record belongs to |
+
+❌ WRONG (Technical):
+`src/views/base/shop/index.vue` with `<el-button v-hasPermi="['base:shop:create']">`
+
+✅ CORRECT (Business):
+Shop List Page — displays all shops with search/filter, includes "Add Shop" button (visible to Admin role only)
+-->
+
 > **Applicable Scenario**: System feature specification for a single feature or module
 > **Target Audience**: speccrew-feature-designer, speccrew-designer, speccrew-dev
 > **Source PRD**: [Link to PRD document]
@@ -23,7 +63,8 @@
 
 ### 1.2 Feature Scope
 
-<!-- AI-NOTE: This specification covers a SINGLE Feature (business operation unit), not the entire module. 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.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 - [ ] {Function 1} - Frontend prototype + Interaction flow + Backend interface + Data definition
 - [ ] {Function 2} - Frontend prototype + Interaction flow + Backend interface + Data definition
@@ -41,15 +82,18 @@
 
 ## 2. Function Details
 
-<!-- AI-NOTE: Repeat Section 2.N for each function in the feature. Each function should include: frontend prototype, interaction flow, backend interface, and data definition. -->
+<!-- AI-NOTE: Repeat Section 2.N for each function in the feature. Each function should include: frontend prototype, interaction flow, backend interface, and data definition.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 ### 2.1 Function: {Function Name}
 
 #### 2.1.1 Frontend Prototype
 
-<!-- AI-NOTE: If the project has multiple frontend platforms (e.g., web + mobile), create separate Frontend Prototype sub-sections for each platform. Use headers like "#### 2.1.1 Frontend Prototype - Web" and "#### 2.1.1b Frontend Prototype - Mobile". Each platform should have its own wireframes and element descriptions tailored to the platform's interaction patterns. -->
+<!-- AI-NOTE: If the project has multiple frontend platforms (e.g., web + mobile), create separate Frontend Prototype sub-sections for each platform. Use headers like "#### 2.1.1 Frontend Prototype - Web" and "#### 2.1.1b Frontend Prototype - Mobile". Each platform should have its own wireframes and element descriptions tailored to the platform's interaction patterns.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
-<!-- AI-NOTE: Use ASCII wireframes to show the UI layout. Choose the appropriate pattern below based on the interface type. -->
+<!-- AI-NOTE: Use ASCII wireframes to show the UI layout. Choose the appropriate pattern below based on the interface type.
+FORBIDDEN: Do NOT use framework-specific component names (el-button, wd-cell, etc.) or file paths in wireframes. -->
 
 **Pattern A: List Page**
 
@@ -195,7 +239,8 @@
 
 #### 2.1.2 Interaction Flow
 
-<!-- AI-NOTE: Use Mermaid sequenceDiagram to show the flow: User → Frontend → Backend API → Data Store. NO style definitions allowed. NO HTML tags. -->
+<!-- AI-NOTE: Use Mermaid sequenceDiagram to show the flow: User → Frontend → Backend API → Data Store. NO style definitions allowed. NO HTML tags. CRITICAL: This section MUST contain mermaid syntax. Plain text or ASCII flowcharts are FORBIDDEN.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 ```mermaid
 sequenceDiagram
@@ -241,6 +286,9 @@ sequenceDiagram
 
 #### 2.1.3 Backend Interface
 
+<!-- AI-NOTE: Describe API functionality from a business perspective. Focus on WHAT each API does, not HOW it's implemented.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
+
 **Interface List:**
 
 | Interface Name | Method | Path Pattern | Description | Caller |
@@ -250,7 +298,8 @@ sequenceDiagram
 
 **Processing Logic:**
 
-<!-- AI-NOTE: Use Mermaid flowchart TD to show the processing logic for each core interface. Show: business validation → data operation → response. NO style definitions allowed. -->
+<!-- AI-NOTE: Use Mermaid flowchart TD to show the processing logic for each core interface. Show: business validation → data operation → response. NO style definitions allowed. CRITICAL: This section MUST contain mermaid syntax. Plain text or ASCII flowcharts are FORBIDDEN.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 ```mermaid
 flowchart TD
@@ -283,12 +332,17 @@ flowchart TD
 
 #### 2.1.4 Data Definition
 
+<!-- AI-NOTE: ALL field definitions MUST use BUSINESS terms, not technical types.
+Example: NOT "VARCHAR(50) NOT NULL" → BUT "Text, required, max 50 characters"
+CRITICAL: Never include database table/column names, SQL types, or framework-specific annotations.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
+
 **Fields:**
 
-| Field Name | Field Type | Data Format | Constraint Rules | New/Existing | Remarks |
-|------------|------------|-------------|------------------|--------------|---------|
-| {Field Name} | String/Number/Boolean/Date/Enum | {e.g., length ≤32, phone format} | {Required/Optional, Unique, Default value} | NEW/EXISTING | {Additional notes} |
-| {Field Name} | {Type} | {Format} | {Constraints} | NEW/EXISTING | {Remarks} |
+| Field Name | Business Type | Constraint Rules | Business Meaning | New/Existing | Remarks |
+|------------|---------------|------------------|------------------|--------------|---------|
+| {Field Name} | Text/Number/Boolean/Date/Enum/Identifier | {e.g., Required, max 50 chars, unique} | {What this field means in business context} | NEW/EXISTING | {Additional notes} |
+| {Field Name} | {Business Type} | {Constraints} | {Business Meaning} | NEW/EXISTING | {Remarks} |
 
 **Data Source:**
 
@@ -328,7 +382,8 @@ flowchart TD
 
 ### 3.1 Shared Data Structures
 
-<!-- AI-NOTE: List data structures used across multiple functions -->
+<!-- AI-NOTE: List data structures used across multiple functions
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 | Structure Name | Used By Functions | Description |
 |----------------|-------------------|-------------|
@@ -337,7 +392,8 @@ flowchart TD
 
 ### 3.2 Cross-Function Flows
 
-<!-- AI-NOTE: Use Mermaid sequenceDiagram for flows that span multiple functions. NO style definitions. NO HTML tags. -->
+<!-- AI-NOTE: Use Mermaid sequenceDiagram for flows that span multiple functions. NO style definitions. NO HTML tags.
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 ```mermaid
 sequenceDiagram
@@ -372,7 +428,8 @@ sequenceDiagram
 
 ### 4.2 Business Logic Rules
 
-<!-- AI-NOTE: Numbered list of business rules -->
+<!-- AI-NOTE: Numbered list of business rules
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 1. **{Rule Name}**: {Detailed description of the rule}
 2. **{Rule Name}**: {Detailed description}
@@ -398,7 +455,8 @@ sequenceDiagram
 
 ### 5.2 Shared Response Format
 
-<!-- AI-NOTE: Standard response JSON structure used across all APIs in this feature -->
+<!-- AI-NOTE: Standard response JSON structure used across all APIs in this feature
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 **Success Response:**
 
@@ -436,21 +494,24 @@ sequenceDiagram
 
 ### 6.1 Pending Confirmations
 
-<!-- AI-NOTE: Checklist of items needing confirmation from stakeholders -->
+<!-- AI-NOTE: Checklist of items needing confirmation from stakeholders
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 - [ ] **{Item 1}**: {Description of what needs confirmation}
 - [ ] **{Item 2}**: {Description}
 
 ### 6.2 Assumptions & Dependencies
 
-<!-- AI-NOTE: List assumptions made and external dependencies -->
+<!-- AI-NOTE: List assumptions made and external dependencies
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 - **Assumption 1**: {Description of assumption}
 - **Dependency 1**: {External system or module this feature depends on}
 
 ### 6.3 Extension Notes
 
-<!-- AI-NOTE: Notes about future iterations or extensions -->
+<!-- AI-NOTE: Notes about future iterations or extensions
+FORBIDDEN: Do NOT include file paths, framework code, SQL statements, component library names, or any implementation-specific details in this section. -->
 
 - {Note about potential future enhancements}
 - {Note about scalability considerations}

package/docs/GETTING-STARTED.ar.md

@@ -91,28 +91,11 @@ flowchart LR
 
 ---
 
-## 3. الخطوة الصفرية: تشخيص المشروع وتهيئة قاعدة المعرفة
+## 3. تهيئة قاعدة المعرفة
 
 قبل بدء عملية الهندسة الرسمية، تحتاج إلى تهيئة قاعدة معرفة المشروع.
 
-### 3.1 تشخيص المشروع
-
-**مثال على المحادثة**:
-```
-@speccrew-team-leader تشخيص المشروع
-```
-
-**ما سيفعله الوكيل**:
-- مسح هيكل المشروع
-- اكتشاف المكدس التقني
-- تحديد الوحدات التجارية
-
-**المخرجات**:
-```
-speccrew-workspace/knowledges/base/diagnosis-reports/diagnosis-report-{date}.md
-```
-
-### 3.2 تهيئة قاعدة المعرفة التقنية
+### 3.1 تهيئة قاعدة المعرفة التقنية
 
 **مثال على المحادثة**:
 ```
@@ -134,7 +117,7 @@ speccrew-workspace/knowledges/techs/{platform-id}/
 └── INDEX.md               # ملف الفهرس
 ```
 
-### 3.3 تهيئة قاعدة المعرفة التجارية
+### 3.2 تهيئة قاعدة المعرفة التجارية
 
 **مثال على المحادثة**:
 ```
@@ -467,11 +450,26 @@ speccrew update
 
 > **ملاحظة**: يجب تنفيذ الخطوتين. تنفيذ `speccrew update` فقط لن يحدث أداة CLI نفسها؛ وتنفيذ `npm install` فقط لن يحدث الملفات في المشروع.
 
-### س5: كيفية عرض التكرارات التاريخية؟
+### س5: يظهر `speccrew update` إصدارًا جديدًا لكن بعد التثبيت لا يزال الإصدار القديم؟
+
+عادةً ما يكون بسبب ذاكرة التخزين المؤقت npm. الحل:
+
+```bash
+npm cache clean --force
+npm install -g speccrew@latest
+npm list -g speccrew
+```
+
+إذا لم يعمل، حدد رقم الإصدار:
+```bash
+npm install -g speccrew@0.5.6
+```
+
+### س6: كيفية عرض التكرارات التاريخية؟
 
 بعد الأرشفة، عرض في `speccrew-workspace/iteration-archives/`، منظم بتنسيق `{رقم}-{نوع}-{اسم}-{تاريخ}/`.
 
-### س6: هل تحتاج قاعدة المعرفة إلى تحديثات دورية؟
+### س7: هل تحتاج قاعدة المعرفة إلى تحديثات دورية؟
 
 مطلوب إعادة التهيئة في الحالات التالية:
 - تغييرات كبيرة في هيكل المشروع
@@ -486,7 +484,7 @@ speccrew update
 
 | المرحلة | الوكيل | محادثة البدء |
 |---------|--------|--------------|
-| التشخيص | Team Leader | `@speccrew-team-leader تشخيص المشروع` |
+
 | التهيئة | Team Leader | `@speccrew-team-leader تهيئة قاعدة المعرفة التقنية` |
 | تحليل المتطلبات | Product Manager | `@speccrew-product-manager لدي متطلب جديد: [الوصف]` |
 | تصميم الميزات | Feature Designer | `@speccrew-feature-designer بدء تصميم الميزات` |
@@ -520,7 +518,7 @@ speccrew update
 ## الخطوات التالية
 
 1. قم بتشغيل `speccrew init --ide qoder` لتهيئة مشروعك
-2. نفذ الخطوة الصفرية: تشخيص المشروع وتهيئة قاعدة المعرفة
+2. نفذ تهيئة قاعدة المعرفة
 3. تقدم عبر كل مرحلة باتباع سير العمل، واستمتع بتجربة التطوير المستندة إلى المواصفات!
 
 </div>