speccrew 0.2.7 → 0.3.1

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

@@ -23,7 +23,17 @@ tools: Read, Write, Glob, Grep
 
 3. **MANDATORY: Template-first workflow** — Copy template MUST execute before filling sections. Skipping copy and writing content directly is FORBIDDEN.
 
-## Step 1: Requirements Clarification (Progressive Multi-Round)
+## Step 1: Requirements Clarification (MANDATORY)
+
+⚠️ **MANDATORY: This step CANNOT be skipped.**
+
+```
+IF user provided a complete requirement document:
+  → Perform at least 1 confirmation round (verify understanding, scope, priorities)
+  → Generate clarification summary
+IF user provided incomplete input:
+  → Perform full progressive clarification (Round 1 → Round 2 → optional Round 3)
+```
 
 Use progressive questioning to clarify requirements. Do NOT ask all questions at once.
 
@@ -66,7 +76,53 @@ Sufficient to proceed when ALL of:
 - [ ] Relationship to existing system is understood
 
 If ANY is unclear → ask follow-up questions targeting the gap
-If ALL are clear → proceed to Step 2
+If ALL are clear → proceed to Step 1 Output
+```
+
+### Step 1 Output: Generate Clarification Summary
+
+After Sufficiency Check passes, generate a clarification summary file:
+
+```
+Path: speccrew-workspace/iterations/{iteration}/01.product-requirement/.clarification-summary.md
+```
+
+**Content template:**
+```markdown
+# Clarification Summary
+
+## Input Type
+- [ ] Complete requirement document provided
+- [ ] Incomplete input (progressive clarification performed)
+
+## Clarification Rounds
+- Round 1 (Core Understanding): [Summary of Q&A]
+- Round 2 (Scope & Boundaries): [Summary of Q&A]
+- Round 3 (Detail & Acceptance): [If applicable, Summary of Q&A]
+
+## Sufficiency Check Status
+- [x] Business problem is clearly understood
+- [x] Target users and core scenarios identified
+- [x] Scope boundaries (in/out) are defined
+- [x] Relationship to existing system is understood
+
+## Key Decisions
+- [Record any key decisions made during clarification]
+
+## Proceed Gate
+✅ All checks passed. Ready for Step 2.
+```
+
+### Proceed Gate to Step 2
+
+**Before proceeding to Step 2, verify BOTH conditions:**
+
+```
+□ All Sufficiency Check items marked as ✅
+□ .clarification-summary.md file exists and is complete
+
+IF both conditions met → Proceed to Step 2
+IF any condition fails → STOP and complete the missing items
 ```
 
 **Principles:**
@@ -274,6 +330,16 @@ If there are gaps or unclear points, ask the user to confirm before proceeding.
 
 Before writing, determine the PRD structure based on requirement complexity:
 
+### Structure Decision (MANDATORY IF/THEN)
+
+```
+IF modules_count >= 2 OR cross_module_dependencies exist:
+  → MANDATORY: Use Master-Sub Structure
+  → Record: sub_prd_count = len(module_list)
+ELSE:
+  → Use Single PRD Structure
+```
+
 ### Simple Requirements (Single Document)
 - Single feature with clear boundaries
 - Minimal dependencies on existing modules
@@ -305,6 +371,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 +381,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:
@@ -390,47 +486,135 @@ If the iteration directory does not exist, refer to the `000-sample` directory s
 
 ## Step 12: Write Files Using Template-Fill Workflow
 
-### 12a Copy Template to Document Path
+⚠️ **CRITICAL: For Master-Sub structure, you MUST generate ALL Sub-PRD files.**
+- **DO NOT put all module content into the Master PRD.**
+- **Each Sub-PRD is a SEPARATE file containing ONLY that module's requirements.**
+
+---
+
+### Step 12a: Generate Master PRD
 
-For each document to write (PRD, and optionally Sub-PRDs):
+**For BOTH Single and Master-Sub structures:**
 
-1. **Read the template**: `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
-2. **Replace top-level placeholders** (feature name, iteration, date)
-3. **Create the document** using `create_file` at the path determined in Step 11
-4. **Verify**: Document has complete section structure
+1. **Copy template to document path:**
+   - Read `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
+   - Replace top-level placeholders (feature name, iteration, date)
+   - Create document using `create_file` at: `{iteration}/01.product-requirement/{feature-name}-prd.md`
 
-### 12b Fill Each Section Using search_replace
+2. **Fill Master-only content using `search_replace`:**
+   - Section 1: Overall background, goals, success metrics
+   - Section 2: System architecture overview (Mermaid graph TB)
+   - Section 3: Module list with scope boundaries (from Step 6.1)
+   - Section 4: Cross-module dependency matrix (from Step 6.2)
+   - Section 5: Implementation phases and ordering (from Step 6.3)
+   - Section 6: Shared entities and data contracts
+   - Section 7: Global non-functional requirements
 
-Fill each section with content prepared in Step 9, using `search_replace` per section.
+3. **DO NOT include module-specific content in Master:**
+   - No module-specific user stories
+   - No module-specific functional requirements
+   - No module-specific Feature Breakdown tables
 
 > ⚠️ **CRITICAL CONSTRAINTS:**
 > - **FORBIDDEN: `create_file` to rewrite the entire document**
 > - **MUST use `search_replace` to fill each section individually**
 > - **All section titles MUST be preserved**
 
-For Master-Sub structure, repeat 12a + 12b for each Sub-PRD document.
+---
+
+### Step 12b: Generate Sub-PRDs (LOOP - MANDATORY for Master-Sub)
+
+**IF Step 8 determined Master-Sub structure, execute this loop:**
+
+```
+FOR each module in module_list from Step 6.1:
+  
+  12b.1: Copy template to sub_prd_path
+    sub_prd_name = "{feature-name}-sub-{module-key}.md"
+    sub_prd_path = "{iteration}/01.product-requirement/{sub_prd_name}"
+    
+    Action:
+    1. Read templates/PRD-TEMPLATE.md
+    2. Replace top-level placeholders
+    3. Create document using create_file at sub_prd_path
+
+  12b.2: Fill module-specific content using search_replace:
+    - Section 1: Module-specific background and context
+    - Section 2: Module-specific user stories
+    - Section 3: Module-specific functional requirements
+    - Section 3.4: Module-specific Feature Breakdown (REQUIRED)
+    - Section 5: Module-specific acceptance criteria
+    - Add: Interface Contracts (from Master dependency matrix)
+
+  12b.3: Verify file exists and is non-empty
+    - Read sub_prd_path to confirm file was created
+    - Verify file size > 1KB (not empty placeholder)
+
+NEXT module
+
+⚠️ STOP condition: All modules in module_list have been processed.
+```
+
+**Example loop execution:**
+```
+Iteration 1: Process module "inventory"
+  → Create: inventory-management-sub-inventory.md
+  → Fill: inventory-specific content
+  → Verify: file exists and has content
+
+Iteration 2: Process module "order"
+  → Create: inventory-management-sub-order.md
+  → Fill: order-specific content
+  → Verify: file exists and has content
+
+... continue until all modules processed
+```
+
+---
+
+### Step 12c: Verification Checklist (MANDATORY)
+
+**After all PRD files are generated, verify:**
+
+```
+□ Master PRD exists at {iteration}/01.product-requirement/{feature-name}-prd.md
+□ Master PRD file size > 2KB (not empty placeholder)
+
+[For Master-Sub structure ONLY:]
+  □ All {sub_prd_count} Sub-PRD files exist
+  □ Each Sub-PRD file size > 3KB (not empty placeholder)
+  □ Master PRD Section index links match actual Sub-PRD files
+  □ No broken file references
+  □ Each Sub-PRD contains module-specific Feature Breakdown
+
+IF any check fails → STOP and report error, fix before proceeding
+IF all checks pass → Proceed to Step 12d
+```
+
+---
 
-### 12c Request Confirmation
+### Step 12d: Request Confirmation
 
-After writing files, show summary and request user confirmation:
+After verification passes, show summary and request user confirmation:
 
-### Simple PRD Output
+**Simple PRD Output:**
 ```
 PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
 ```
 
-### Complex PRD Output (with modeling)
+**Complex PRD Output (with modeling):**
 ```
 Business Modeling generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-bizs-modeling.md
 PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
 ```
 
-### Master-Sub PRD Output
+**Master-Sub PRD Output:**
 ```
 Master PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
-Sub-PRDs generated:
+Sub-PRDs generated ({sub_prd_count} files):
   - [feature-name]-sub-[module1].md
   - [feature-name]-sub-[module2].md
+  - ...
 ```
 
 Please confirm the following key points:
@@ -529,6 +713,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}