speccrew 0.2.7 → 0.3.0

package/.speccrew/skills/speccrew-knowledge-techs-generate/SKILL.md

@@ -4,12 +4,9 @@ description: Stage 2 of technology knowledge initialization - Generate technolog
 tools: Read, Write, Glob, Grep, Skill
 ---
 
-> **⚠️ DEPRECATED**: This skill has been split into two specialized skills for parallel execution:
-> - **`speccrew-knowledge-techs-generate-conventions`** — Generates convention documents (INDEX, tech-stack, architecture, conventions-*)
-> - **`speccrew-knowledge-techs-generate-ui-style`** — Generates UI style documents (ui-style/ directory, frontend platforms only)
+> **⚠️ DEPRECATED**: This skill has been superseded by `speccrew-knowledge-techs-generate-conventions` and `speccrew-knowledge-techs-generate-ui-style`. Use those skills for new requests. This file is kept for backward compatibility only.
 >
 > **Do NOT invoke this skill directly.** Use the specialized skills via `speccrew-knowledge-techs-dispatch` Stage 2 dual-worker orchestration.
-> This file is retained as reference documentation only.
 
 # Stage 2: Generate Platform Technology Documents
 
@@ -50,66 +47,19 @@ Worker Agent (speccrew-task-worker)
 
 Generate the following documents in `{output_path}/`:
 
-```
-{output_path}/
-├── INDEX.md                    # Platform technology index (Required)
-├── tech-stack.md              # Technology stack details (Required)
-├── architecture.md            # Architecture conventions (Required)
-├── conventions-design.md      # Design conventions (Required)
-├── conventions-dev.md         # Development conventions (Required)
-├── conventions-unit-test.md        # Unit testing conventions (Required)
-├── conventions-system-test.md      # System testing conventions (Required)
-├── conventions-build.md       # Build & Deployment conventions (Required)
-├── conventions-data.md        # Data conventions (Optional)
-└── ui-style/                  # UI style analysis (Optional, frontend platforms only)
-    ├── ui-style-guide.md      # Main UI style guide
-    ├── page-types/            # Page type analysis
-    ├── components/            # Component analysis
-    ├── layouts/               # Layout patterns
-    └── styles/                # Styling conventions
-```
-
-### Platform Type to Document Mapping
-
-| Platform Type | Required Documents | Optional Documents | Generate conventions-data.md? |
-|---------------|-------------------|-------------------|------------------------------|
-| `backend` | All 8 docs | - | ✅ **必须生成** - 包含 ORM、数据建模、缓存策略 |
-| `web` | All 8 docs | conventions-data.md | ⚠️ **条件生成** - 仅当使用 ORM/数据层时（Prisma、TypeORM、Sequelize 等） |
-| `mobile` | All 8 docs | conventions-data.md | ❌ **默认不生成** - 根据实际技术栈判断 |
-| `desktop` | All 8 docs | conventions-data.md | ❌ **默认不生成** - 根据实际技术栈判断 |
-| `api` | All 8 docs | conventions-data.md | ⚠️ **条件生成** - 根据是否有数据层 |
-
-### Decision Logic for conventions-data.md
-
-**Step 1: Check Platform Type**
-- If `backend` → **Generate** (always)
-- If `web`/`mobile`/`desktop`/`api` → Proceed to Step 2
-
-**Step 2: Detect Data Layer (for non-backend platforms)**
+**Required Documents (All Platforms)**:
+- `INDEX.md` - Platform technology index
+- `tech-stack.md` - Technology stack details
+- `architecture.md` - Architecture conventions
+- `conventions-design.md` - Design conventions
+- `conventions-dev.md` - Development conventions
+- `conventions-unit-test.md` - Unit testing conventions
+- `conventions-system-test.md` - System testing conventions
+- `conventions-build.md` - Build & Deployment conventions
 
-Check configuration files for data layer indicators:
-
-| Indicator | Technology | Action |
-|-----------|------------|--------|
-| `prisma` in package.json dependencies | Prisma ORM | Generate conventions-data.md |
-| `typeorm` in package.json dependencies | TypeORM | Generate conventions-data.md |
-| `sequelize` in package.json dependencies | Sequelize | Generate conventions-data.md |
-| `mongoose` in package.json dependencies | Mongoose | Generate conventions-data.md |
-| `drizzle-orm` in package.json dependencies | Drizzle ORM | Generate conventions-data.md |
-| `firebase` / `@react-native-firebase` | Firebase | Generate conventions-data.md (lightweight) |
-| `sqlite` / `realm` / `@realm/react` | SQLite/Realm | Generate conventions-data.md (lightweight) |
-| `core-data` in iOS project | Core Data | Generate conventions-data.md |
-| `room` in Android project | Room Persistence | Generate conventions-data.md |
-| None detected | - | **Skip** conventions-data.md |
-
-**Step 3: Report Decision**
-```
-Platform: {platform_id}
-Type: {platform_type}
-Framework: {framework}
-Data Layer Detected: {yes/no/technology}
-Generate conventions-data.md: {yes/no}
-```
+**Optional Documents**:
+- `conventions-data.md` - Data conventions (backend required; other platforms: only if ORM/data layer detected)
+- `ui-style/` - UI style analysis (frontend platforms only)
 
 ## Workflow
 
@@ -445,6 +395,16 @@ Analysis completeness: {ui_style_analysis_level}
 
 **CRITICAL**: This step MUST follow the template fill workflow - copy template first, then fill sections.
 
+**Decision Logic for conventions-data.md**:
+
+IF `platform_type` == `backend`:
+  - Generate conventions-data.md (REQUIRED)
+ELSE IF `platform_type` IN [`web`, `mobile`, `desktop`, `api`]:
+  - Check package.json dependencies for data layer indicators:
+    - IF `prisma` / `typeorm` / `sequelize` / `mongoose` / `drizzle-orm` found → Generate conventions-data.md
+    - IF `firebase` / `sqlite` / `realm` found → Generate conventions-data.md (lightweight)
+    - ELSE → Skip conventions-data.md
+
 1. **For Each Document, Follow This Workflow**:
 
    **Step 5.1: Copy Template File**

package/.speccrew/skills/speccrew-knowledge-techs-index/SKILL.md

@@ -38,6 +38,14 @@ Worker Agent (speccrew-task-worker)
 
 - `{{output_path}}/INDEX.md` - Root technology knowledge index
 
+**INDEX.md Content Structure**:
+- Introduction (generation info, platform count)
+- Platform Overview (table with links to all platform docs)
+- Quick Reference (links organized by document type)
+- Agent-to-Platform Mapping (maps agents to their platform docs)
+- Document Guide (explains each document type)
+- Usage Guide (how to use the knowledge)
+
 ## Workflow
 
 ```mermaid
@@ -95,79 +103,35 @@ Read `techs-manifest.json` to get the list of all platforms:
 }
 ```
 
-### Step 2: Verify Platform Documents (Dynamic Detection)
+### Step 2: Verify Platform Documents
 
 **CRITICAL**: Do NOT assume all platforms have the same document set. Must dynamically detect which documents actually exist.
 
-For each platform in manifest, scan the platform directory to detect actual document existence:
+**Step 2a: Scan Platform Directories**
 
-```
-speccrew-workspace/knowledges/techs/{{platform_id}}/
-├── INDEX.md                    # Required - must exist
-├── tech-stack.md              # Required - must exist
-├── architecture.md            # Required - must exist
-├── conventions-design.md      # Required - must exist
-├── conventions-dev.md         # Required - must exist
-├── conventions-test.md        # Required - must exist
-├── conventions-build.md       # Required - must exist
-└── conventions-data.md        # Optional - check existence dynamically
-```
+For each platform in manifest:
+1. List all `.md` files in `{{techs_base_path}}/{{platform_id}}/`
+2. Build a document availability map for each platform
 
-**Dynamic Detection Logic:**
-
-1. **Scan Platform Directory**: List all `.md` files in `{{techs_base_path}}/{{platform_id}}/`
-2. **Build Document Availability Map**:
-   ```json
-   {
-     "platform_id": "mobile-uniapp",
-     "documents": {
-       "INDEX.md": true,
-       "tech-stack.md": true,
-       "architecture.md": true,
-       "conventions-design.md": true,
-       "conventions-dev.md": true,
-       "conventions-test.md": true,
-       "conventions-build.md": true,
-       "conventions-data.md": false  // Dynamically detected (optional)
-     }
-   }
-   ```
-3. **Validation**:
-   - If `INDEX.md` is missing → Note as error in report, skip this platform
-   - If any required document (except conventions-data.md) is missing → Note as warning
-   - Record actual document availability for dynamic link generation
-
-#### Document Verification Matrix
-
-For each platform directory, verify document existence with these strict rules:
-
-| Document | Required? | If Missing | Action |
-|----------|-----------|------------|--------|
-| INDEX.md | YES | ERROR | Skip entire platform from root INDEX. Log: "ERROR: Platform {platform_id} skipped - INDEX.md missing" |
-| tech-stack.md | YES | WARN | Include platform but mark document as "[Missing]" in links. Log warning |
-| architecture.md | YES | WARN | Include platform but mark as "[Missing]". Log warning |
-| conventions-design.md | YES | WARN | Include platform but mark as "[Missing]". Log warning |
-| conventions-dev.md | YES | WARN | Include platform but mark as "[Missing]". Log warning |
-| conventions-test.md | YES | WARN | Include platform but mark as "[Missing]". Log warning |
-| conventions-build.md | YES | WARN | Include platform but mark as "[Missing]". Log warning |
-| conventions-data.md | NO | OK | Do not warn. Do not include link. Silently skip |
-
-**Platform Eligibility Rules**:
-- INDEX.md missing → Platform SKIPPED entirely (not listed in root INDEX)
-- Any required doc missing (except INDEX.md) → Platform INCLUDED but marked INCOMPLETE
-- Only conventions-data.md missing → Platform is COMPLETE (it's optional)
-
-**Verification Summary** (generate at end of verification step):
-```
-Verification Report:
-- Total platforms in manifest: {N}
-- Complete platforms: {X} (all 7 required docs present)
-- Incomplete platforms: {Y} (missing some required docs) [WARN]
-  - {platform_id}: missing {doc1}, {doc2}
-- Skipped platforms: {Z} (no INDEX.md) [ERROR]
-  - {platform_id}: INDEX.md not found
-- Optional conventions-data.md present in: {W} platforms
-```
+**Step 2b: Verify Required Documents**
+
+Check each platform for required documents:
+| Document | Required? | If Missing |
+|----------|-----------|------------|
+| INDEX.md | YES | Skip entire platform from root INDEX |
+| tech-stack.md | YES | Mark as "[Missing]" in links |
+| architecture.md | YES | Mark as "[Missing]" in links |
+| conventions-design.md | YES | Mark as "[Missing]" in links |
+| conventions-dev.md | YES | Mark as "[Missing]" in links |
+| conventions-test.md | YES | Mark as "[Missing]" in links |
+| conventions-build.md | YES | Mark as "[Missing]" in links |
+| conventions-data.md | NO | Silently skip link |
+
+**Step 2c: Determine Platform Eligibility**
+
+- IF `INDEX.md` missing → Platform SKIPPED entirely
+- IF any required doc missing (except INDEX.md) → Platform INCLUDED but marked INCOMPLETE
+- IF only conventions-data.md missing → Platform is COMPLETE (it's optional)
 
 ### Step 3: Extract Platform Summaries
 

package/.speccrew/skills/speccrew-knowledge-techs-ui-analyze/SKILL.md

@@ -84,9 +84,11 @@ Generate the following documents in `{output_path}/`:
 
 3. **MANDATORY: Template-first workflow** — For every output document, the corresponding template MUST be copied to the target path first, then sections filled with `search_replace`. Skipping copy and writing content directly is FORBIDDEN.
 
-### Step 0: Read All Templates
+### Step 0: Pre-load Required Templates (Mandatory)
 
-Before analysis, read all template files to understand document structures and required content:
+**This step must complete before any workflow step begins.**
+
+Read all template files to understand document structures and required content:
 
 | Template File | Output Document | Purpose |
 |---------------|-----------------|---------|
@@ -106,6 +108,8 @@ Before analysis, read all template files to understand document structures and r
 
 **Key principle**: Extract information from source code according to each template's section requirements.
 
+**Error Handling**: IF any template file is missing THEN report error with template path and STOP workflow.
+
 ### Step 1: Discover Source Structure
 
 **Purpose**: Gather project metadata for `ui-style-guide.md` Section 1-2 (Project Overview, Platform Summary)

package/.speccrew/skills/speccrew-pm-requirement-analysis/SKILL.md

@@ -305,6 +305,7 @@ Before writing, determine the PRD structure based on requirement complexity:
 **Each Sub-PRD covers ONE module:**
 - Module-specific user stories and functional requirements
 - Module-internal process flows and use cases
+- **Feature Breakdown** (required): List all business operation units with Feature ID, Type, and dependencies
 - Module-specific acceptance criteria
 - Interface contracts with other modules (referencing Master PRD dependency matrix)
 
@@ -314,11 +315,40 @@ Fill in according to the template structure, requirements:
 - **Background & Goals**: Explain why we're doing this and what success looks like
 - **User Stories**: `As a [user role], I want [to do something], so that [I can achieve some goal]`
 - **Functional Requirements**: Group by priority (P0 Core / P1 Important / P2 Optional)
+- **Feature Breakdown**: Extract business operation units for downstream Feature Design (see Step 9.1)
 - **Non-functional Requirements**: Performance, security, compatibility, etc.
 - **Acceptance Criteria**: Quantifiable, verifiable definition of done
 - **Boundary Description**: Clearly define Not In Scope content
 - **Assumptions & Dependencies**: Prerequisites, external dependencies
 
+### Step 9.1: Extract Feature Breakdown
+
+For both simple and complex requirements, extract Feature Breakdown to guide downstream Feature Design:
+
+**Analysis Steps:**
+1. **Analyze user stories and functional requirements** for this module/feature
+2. **Identify business operation units** - each unit should represent:
+   - A complete business operation (e.g., "Customer List Management" includes search, filter, pagination, tag management)
+   - Can span 1-2 pages but remains business-cohesive
+   - Estimated implementation: no more than 15 code files (frontend + backend combined)
+3. **Classify Feature Type:**
+   - `Page+API`: Frontend page with corresponding backend APIs (for full-stack architecture)
+   - `API-only`: Group of related APIs (for backend-only features)
+4. **Assign Feature IDs**: Use format `F-{MODULE}-{NN}` (e.g., F-CRM-01, F-CRM-02)
+5. **Document dependencies**: Identify data or workflow dependencies between features
+
+**Granularity Guidelines:**
+| Good Feature Size | Too Large (Split Further) |
+|-------------------|--------------------------|
+| Single CRUD operation group | Complete module with 5+ CRUDs |
+| One list page with filters | Entire reporting subsystem |
+| One form with validation | Multi-step wizard with 10+ steps |
+| Single API endpoint group | All APIs for a domain |
+
+**Output:** Complete the Feature Breakdown table in Section 3.4 of the PRD template.
+
+**Note:** Even simple requirements (single-file PRD) should include Feature Breakdown, typically with 1-3 features.
+
 ### Marking Existing vs New Features
 
 When the requirement involves modifying existing system functions, clearly mark each item:
@@ -529,6 +559,8 @@ If WORKFLOW-PROGRESS.json does not exist (backward compatibility):
 - [ ] PRD structure (single vs master-sub) determined appropriately
 - [ ] **[Master-Sub]** Master PRD includes architecture overview, module list, dependency matrix, implementation phases
 - [ ] **[Master-Sub]** Each Sub-PRD covers exactly one module with interface contracts
+- [ ] **Feature Breakdown** extracted with appropriate granularity (each feature ≤ 15 code files)
+- [ ] **Feature Breakdown** includes Feature IDs, Types (Page+API / API-only), and dependencies
 - [ ] PRD completely filled according to template structure
 - [ ] User story granularity aligns with "single iteration completable" principle
 - [ ] Acceptance criteria are quantifiable and verifiable

package/.speccrew/skills/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md

@@ -103,7 +103,22 @@ graph TB
 | [Feature 1] | P0 | [Description] | [Acceptance Criteria] |
 | [Feature 2] | P1 | [Description] | [Acceptance Criteria] |
 
-### 3.2 Feature Details
+### 3.4 Feature Breakdown
+
+> List all business operation units in this module. Each feature represents a cohesive business operation (e.g., one frontend page with its backend APIs, or one API group for backend-only). This breakdown guides downstream Feature Design to generate per-feature specs.
+
+| Feature ID | Feature Name | Type | Pages/Endpoints | Description |
+|------------|-------------|------|-----------------|-------------|
+| F-{MODULE}-01 | {Feature name} | Page+API / API-only | {page count or endpoint count} | {Brief description} |
+| F-{MODULE}-02 | {Feature name} | Page+API / API-only | {page count or endpoint count} | {Brief description} |
+
+#### Feature Dependencies
+
+| Feature | Depends On | Dependency Type |
+|---------|-----------|----------------|
+| F-{MODULE}-02 | F-{MODULE}-01 | Data dependency |
+
+### 3.5 Feature Details
 
 #### Feature 1: [Feature Name]
 

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

@@ -24,10 +24,15 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Inputs
 
+**Input Parameters** (from agent context):
+- `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`. If provided, use new naming format.
+- `feature_name`: Feature name, e.g., `customer-list`.
+- `platform_id`: Target platform, e.g., `backend-spring`, `backend-nestjs`.
+
 Read in order:
 
-1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
-2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
+2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md`
 3. **Backend techs knowledge** (paths from agent context):
    - `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md`
    - `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md`
@@ -56,6 +61,8 @@ Use Glob/Grep to understand current backend codebase:
 
 Parse Feature Spec to identify all backend-relevant functions.
 
+> **Note**: With the new fine-grained Feature Spec format, each Feature Spec typically contains **3-8 functions** (previously 10-20). The extraction logic remains the same, but the scope is more focused.
+
 For each function, extract:
 
 | Aspect | Content |
@@ -91,7 +98,10 @@ Read the SD-BACKEND-TEMPLATE.md to understand document structure.
 2. **Replace top-level placeholders** with known variables:
    - Module name, feature name, platform ID, etc.
 3. **Create the document file** using `create_file`:
-   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
+   - **Target path pattern**:
+     - With `feature_id`: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{feature-id}-{feature-name}-design.md`
+       - Example: `03.system-design/backend-spring/F-CRM-01-customer-list-design.md`
+     - Without `feature_id` (backward compatibility): `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
    - Content: Template with top-level placeholders replaced
 4. **Verify**: Document should have complete section structure ready for filling
 
@@ -113,6 +123,22 @@ Fill each section with technology-specific implementation details.
 | **Transaction Boundaries** | Use actual framework transaction mechanism |
 | **Exception Handling** | Use actual exception classes and error codes |
 
+**How to Reference Techs Knowledge for Pseudo-code:**
+
+1. **Read relevant techs knowledge file for the platform**:
+   - Core syntax: `tech-stack.md` for framework version and key libraries
+   - ORM patterns: `conventions-data.md` for entity definitions and transaction management
+   - Design patterns: `conventions-design.md` for layer structure and naming conventions
+2. **Extract framework-specific syntax patterns**:
+   - Controller annotations/decorators
+   - Service injection patterns
+   - Repository/DAO method signatures
+   - Transaction management annotations
+3. **Apply patterns in pseudo-code**:
+   - Use exact annotation/decorator syntax from techs knowledge
+   - Follow naming conventions from conventions-design.md
+   - Apply ORM patterns from conventions-data.md
+
 **Pseudo-code Requirements:**
 - MUST use actual framework syntax from techs knowledge
 - Spring Boot: `@RestController`, `@PostMapping`, `@Valid`, `@Transactional`, etc.
@@ -153,7 +179,7 @@ Read INDEX-TEMPLATE.md to understand platform-level document structure.
 |---------|---------|
 | **Tech Stack Summary** | Extract from techs knowledge |
 | **Shared Design Decisions** | Middleware stack, data source config, base service classes, common utilities |
-| **Module List Table** | Links to each module design document |
+| **Module List Table** | Links to each module design document. Use `feature_id` as identifier if available (e.g., `F-CRM-01`), otherwise use module name. Example: `\| F-CRM-01 \| Customer List \| F-CRM-01-customer-list-design.md \| NEW \|` |
 | **Cross-Module Interaction Notes** | Shared services, event-driven patterns, dependencies |
 | **Database Schema Overview** | New tables, modified tables, entity relationships |
 
@@ -202,11 +228,11 @@ After completing all steps, output a structured completion report for the System
 - **Status**: SUCCESS
 - **Task ID**: {task_id from context}
 - **Platform**: {platform_id}
+- **Feature ID**: {feature_id}
 - **Feature**: {feature_name}
 - **Output Files**:
   - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{feature-id}-{feature-name}-design.md (or {module}-design.md if no feature_id)
 - **Summary**: Backend system design completed for {feature_name} on {platform_id} with {count} module designs
 ```
 
@@ -217,6 +243,7 @@ After completing all steps, output a structured completion report for the System
 - **Status**: FAILED
 - **Task ID**: {task_id from context}
 - **Platform**: {platform_id}
+- **Feature ID**: {feature_id}
 - **Feature**: {feature_name}
 - **Output Files**: []
 - **Error**: {description of what went wrong}

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

@@ -24,10 +24,15 @@ tools: Read, Write, Glob, Grep
 
 ## Step 1: Read Inputs
 
+**Input Parameters** (from agent context):
+- `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`. If provided, use new naming format.
+- `feature_name`: Feature name, e.g., `customer-list`.
+- `platform_id`: Target platform, e.g., `frontend-vue`, `frontend-react`.
+
 Read in order:
 
-1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
-2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
+2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/{feature-id}-{feature-name}-api-contract.md`
 3. **Frontend techs knowledge** (paths from agent context):
    - `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md`
    - `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md`
@@ -56,6 +61,8 @@ Document findings for reference in later steps.
 
 Parse Feature Spec to identify all functions (Section 2.N pattern).
 
+> **Note**: With the new fine-grained Feature Spec format, each Feature Spec typically contains **3-8 functions** (previously 10-20). The extraction logic remains the same, but the scope is more focused.
+
 For each function, extract:
 
 | Aspect | Content to Extract |
@@ -89,7 +96,10 @@ Read `SD-FRONTEND-TEMPLATE.md` for document structure.
 2. **Replace top-level placeholders** with known variables:
    - Module name, feature name, platform ID, etc.
 3. **Create the document file** using `create_file`:
-   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
+   - **Target path pattern**:
+     - With `feature_id`: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{feature-id}-{feature-name}-design.md`
+       - Example: `03.system-design/frontend-vue/F-CRM-01-customer-list-design.md`
+     - Without `feature_id` (backward compatibility): `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
    - Content: Template with top-level placeholders replaced
 4. **Verify**: Document should have complete section structure ready for filling
 
@@ -161,6 +171,15 @@ Read `INDEX-TEMPLATE.md` for document structure.
 
 Create table with links to each module design document.
 
+| Column | Content |
+|--------|---------|
+| **ID** | Use `feature_id` if available (e.g., `F-CRM-01`), otherwise use module name |
+| **Name** | Feature or module name |
+| **Document** | Link to design file (e.g., `F-CRM-01-customer-list-design.md`) |
+| **Status** | `[NEW]`, `[MODIFIED]`, or `[EXISTING]` |
+
+Example row with `feature_id`: `| F-CRM-01 | Customer List | F-CRM-01-customer-list-design.md | NEW |`
+
 ### 5.4 Verify Output
 
 Verify the completed INDEX.md:
@@ -207,11 +226,11 @@ After completing all steps, output a structured completion report for the System
 - **Status**: SUCCESS
 - **Task ID**: {task_id from context}
 - **Platform**: {platform_id}
+- **Feature ID**: {feature_id}
 - **Feature**: {feature_name}
 - **Output Files**:
   - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
+  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{feature-id}-{feature-name}-design.md (or {module}-design.md if no feature_id)
 - **Summary**: Frontend system design completed for {feature_name} on {platform_id} with {count} module designs
 ```
 
@@ -222,6 +241,7 @@ After completing all steps, output a structured completion report for the System
 - **Status**: FAILED
 - **Task ID**: {task_id from context}
 - **Platform**: {platform_id}
+- **Feature ID**: {feature_id}
 - **Feature**: {feature_name}
 - **Output Files**: []
 - **Error**: {description of what went wrong}

package/.speccrew/skills/speccrew-test-case-design/SKILL.md

@@ -98,6 +98,13 @@ speccrew-workspace/knowledges/techs/{platform_id}/conventions-system-test.md
 | Test Data Management | Fixtures, seeding, mock strategies |
 | API Contract Testing | Contract testing conventions if applicable |
 
+**Fallback Handling:**
+
+IF `conventions-system-test.md` not found:
+1. Use default analysis dimensions defined in Step 4
+2. Proceed without platform-specific testing conventions
+3. Log a note: "Testing conventions file not found, using default analysis dimensions"
+
 ## Step 4: Analyze Test Dimensions
 
 Systematically analyze test dimensions to ensure comprehensive coverage:
@@ -206,6 +213,16 @@ Each test case contains:
 | P2-Medium | Standard functionality, moderate impact | Edge cases, secondary flows |
 | P3-Low | Minor functionality, low impact | UI polish, rare edge cases |
 
+**Priority Mapping from Feature Spec to Test Cases:**
+
+| Feature Spec Priority | Test Case Priority | Mapping Rationale |
+|-----------------------|-------------------|------------------|
+| P0 (Critical) | P0 (Critical) | Core functionality must have critical test coverage |
+| P1 (Important) | P1 (High) | Important features need high-priority test validation |
+| P2 (Standard) | P2 (Medium) | Standard features receive medium-priority testing |
+| P3 (Minor) | P3 (Low) | Minor features receive low-priority testing |
+| Unspecified | P2 (Medium) | Default to medium priority if not specified |
+
 ## Step 6: Coverage Self-Check
 
 ### 6.1 Acceptance Criteria Coverage

package/.speccrew/skills/speccrew-test-code-gen/SKILL.md

@@ -50,7 +50,7 @@ Load platform testing conventions to understand the target test framework:
 speccrew-workspace/knowledges/techs/{platform_id}/conventions-system-test.md
 ```
 
-### 2.2 Secondary Convention Path (Fallback for Unit Testing)
+### 2.2 Unit Test Convention Path (Fallback)
 
 If `conventions-system-test.md` does not exist or for unit test specifics, read:
 
@@ -58,7 +58,7 @@ If `conventions-system-test.md` does not exist or for unit test specifics, read:
 speccrew-workspace/knowledges/techs/{platform_id}/conventions-unit-test.md
 ```
 
-### 2.3 Fallback Convention Path (Last Resort)
+### 2.3 Generic Convention Path (Last Resort)
 
 If neither conventions file exists, read `conventions-dev.md` and infer:
 
@@ -66,7 +66,7 @@ If neither conventions file exists, read `conventions-dev.md` and infer:
 |-----------------|-------------------|
 | conventions-dev.md | Extract framework from tech stack, infer unit test framework |
 
-### 2.3 Information to Extract
+### 2.4 Information to Extract
 
 | Item | Purpose |
 |------|---------|
@@ -109,6 +109,23 @@ For mocking strategy planning:
 
 Create a comprehensive test code generation plan:
 
+### 4.0 Determine File Grouping Strategy
+
+Before organizing test files, determine the grouping strategy:
+
+| Condition | Grouping Strategy |
+|-----------|-------------------|
+| Test cases share same module/component | Group into single test file |
+| Test cases are independent | One test file per test case |
+| Test cases span multiple modules | Create separate test files per module |
+
+**File Grouping Rules:**
+
+1. **IF test cases share same module/component THEN** group into single test file
+2. **IF test cases are independent THEN** one test file per test case
+3. **Maximum test cases per file:** 10 (split into multiple files if exceeded)
+4. **Naming convention:** `{module-name}.test.{ext}` or `{module-name}.spec.{ext}`
+
 ### 4.1 Test File Structure Planning
 
 Determine how test files are organized:

package/.speccrew/skills/speccrew-test-execute/SKILL.md

@@ -85,6 +85,12 @@ Determine if the system under test requires:
 
 **Checkpoint A**: If any environment check fails, report specific missing items and stop execution.
 
+✋ **STOP IF FAILED**: IF any pre-check fails THEN:
+1. Stop workflow immediately
+2. Report all failures to user
+3. Do NOT proceed to test execution
+4. Fix all environment issues before retry
+
 ## Step 3: Execute Tests
 
 ### 3.1 Determine Test Command
@@ -183,6 +189,8 @@ For each deviation, analyze:
 - **Skip Reason**: Why test could not execute
 - **Flaky Pattern**: Conditions causing intermittent failure
 
+> 📋 **Output Requirement**: These root cause analysis results MUST be included in Step 6 Report under the "Recommendations" section. Each root cause should map to its corresponding test case ID for traceability.
+
 ## Step 6: Generate Test Report
 
 ### 6.1 Read Template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {