speccrew 0.6.25 → 0.6.26

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

@@ -261,93 +261,63 @@ Check if feature specification documents already exist in the current iteration:
 - If feature specification documents already exist → Ask user whether to overwrite or create a new version
 - If no feature specification documents exist → Proceed directly to design phase
 
-## Phase 2: Knowledge Loading
+## Phase 2: Feature Registry Initialization
 
-After user confirmation, load knowledge in the following order:
+> 🛑 **ORCHESTRATOR RULES — Phase 2**
+> - ❌ DO NOT read PRD files directly — dispatch Worker
+> - ❌ DO NOT parse Feature Breakdown tables yourself
+> - ❌ DO NOT read techs-manifest.json directly
+> - ❌ DO NOT build Feature Registry manually
+> - ✅ ONLY dispatch Worker with `speccrew-fd-feature-registry-init` skill
+> - ✅ ONLY read `.feature-registry.json` after Worker completes
+> - ✅ ONLY present summary and collect user confirmation
 
-### Must Read
-Read all confirmed PRD documents specified by the user. PRD documents contain:
-- Feature background and goals
-- User stories and scenarios
-- Functional requirements description
-- Business process flows
-- Acceptance criteria
+### Step 1: Confirm PRD Path
 
-### Discover Frontend Platforms
+Confirm the PRD directory path with user. The PRD directory should contain:
+- Master PRD (`*-master-prd.md`)
+- Sub-PRD files (`*-sub-*.md`)
 
-Read `{workspace_path}/knowledges/techs/techs-manifest.json` to identify all frontend platforms:
-- Look for platform entries with type starting with `web-` or `mobile-`
-- If multiple frontend platforms exist (e.g., web-vue + mobile-uniapp), frontend design MUST cover each platform separately
-- If only one frontend platform exists, design for that single platform
-- Store discovered platform list for use in Phase 3 worker dispatch
+Default path: `{iteration_path}/01.product-requirement`
 
-### Extract Feature Breakdown (Section 3.4)
+### Step 2: Dispatch Feature Registry Worker
 
-After reading PRD documents, extract Feature Breakdown from each Sub-PRD:
+Dispatch a Worker to execute `speccrew-fd-feature-registry-init` skill:
 
-1. **Locate Section 3.4**: In each Sub-PRD, find the "Feature Breakdown" table under Section 3.4
+```
+Worker dispatch parameters:
+- skill: speccrew-fd-feature-registry-init
+- prd_dir: {iteration_path}/01.product-requirement
+- workspace_path: {workspace_path}
+- language: {language}
+```
+
+Worker will:
+- Read all PRD files and techs-manifest.json
+- Extract Feature Breakdown from each Sub-PRD Section 3.4
+- Generate `.feature-registry.json`
+- Return summary statistics
 
-2. **Parse Feature Table**: Extract the following columns for each Feature:
+### Step 3: Verify Feature Registry
+
+After Worker completes:
+1. Read `{prd_dir}/.feature-registry.json` — verify it exists and contains valid data
+2. Extract the following for each Feature:
    - `Feature ID`: Unique identifier (e.g., `F-CRM-01`, `F-CRM-02`)
    - `Feature Name`: Descriptive name (e.g., `Customer List Management`)
    - `Type`: Either `Page+API` or `API-only`
-   - `Module`: Module identifier the feature belongs to (e.g., `M1-System`, `M2-Member`). Derive from the Sub-PRD's module classification.
-   - `Source PRD`: The Sub-PRD filename this feature was extracted from (e.g., `crm-system-sub-member.md`)
+   - `Module`: Module identifier the feature belongs to
+   - `Source PRD`: The Sub-PRD filename this feature was extracted from
    - `Dependencies`: List of prerequisite Feature IDs (if any)
 
-3. **Build Feature Registry**: Consolidate all features across Sub-PRDs into a unified list.
-
-4. **Write Feature Registry to `.checkpoints.json`**:
+3. **Write Feature Registry to `.checkpoints.json`**:
 
-   Write or update the checkpoint file at:
-   ```
-   {iterations_dir}/{iteration}/02.feature-design/.checkpoints.json
-   ```
-
-   Structure — each feature has individual status fields for full checklist tracking:
-   ```json
-   {
-     "stage": "02_feature_design",
-     "checkpoints": {
-       "function_decomposition": {
-         "passed": false,
-         "confirmed_at": null,
-         "description": "Feature Registry extraction and confirmation",
-         "total_features": 42,
-         "total_modules": 13,
-         "features": [
-           {
-             "feature_id": "F-SYS-01",
-             "feature_name": "Account Login",
-             "type": "Page+API",
-             "module": "M1-System",
-             "source_prd": "crm-system-sub-system.md",
-             "dependencies": [],
-             "feature_spec_status": "pending",
-             "api_contract_status": "pending"
-           },
-           {
-             "feature_id": "F-MEMBER-01",
-             "feature_name": "Customer Info Management",
-             "type": "Page+API",
-             "module": "M2-Member",
-             "source_prd": "crm-system-sub-member.md",
-             "dependencies": ["F-SYS-01"],
-             "feature_spec_status": "pending",
-             "api_contract_status": "pending"
-           }
-         ]
-       },
-       "feature_spec_review": {
-         "passed": false,
-         "confirmed_at": null
-       },
-       "api_contract_joint": {
-         "passed": false,
-         "confirmed_at": null
-       }
-     }
-   }
+   ```bash
+   node {update_progress_script} write-checkpoint \
+     --file {iterations_dir}/{iteration}/02.feature-design/.checkpoints.json \
+     --stage 02_feature_design \
+     --checkpoint function_decomposition \
+     --data '{"features": [...], "total_features": N, "total_modules": M}'
    ```
 
    **Feature status values:**
@@ -361,38 +331,31 @@ After reading PRD documents, extract Feature Breakdown from each Sub-PRD:
    - Feature Spec worker done → set `feature_spec_status` = `completed`
    - API Contract worker done → set `api_contract_status` = `completed`
 
-### 2.5a Feature Name Normalization
-
-Before presenting the Feature Registry to user:
-
-1. **Extract exact names** from PRD Section 3.4 table — use the name column value verbatim
-2. **Store as-is** in `.checkpoints.json` `feature_name` field — no translation, no slug conversion
-3. **Validate uniqueness**: Ensure no two Features share the same `feature_name`
-4. **Language rule**: `feature_name` MUST preserve the PRD's original language (Chinese names stay Chinese)
+### Step 4: HARD STOP — User Confirmation
 
-5. **Present Feature Registry to user for confirmation**:
+Present the Feature Registry to user and wait for confirmation before proceeding:
 
-   Display the full feature table:
+Display the full feature table:
 
-   | # | Feature ID | Feature Name | Type | Module | Dependencies |
-   |---|-----------|-------------|------|--------|--------------|
-   | 1 | F-SYS-01 | Account Login | Page+API | M1-System | - |
-   | 2 | F-MEMBER-01 | Customer Info | Page+API | M2-Member | F-SYS-01 |
-   | ... | ... | ... | ... | ... | ... |
+| # | Feature ID | Feature Name | Type | Module | Dependencies |
+|---|-----------|-------------|------|--------|--------------|
+| 1 | F-SYS-01 | Account Login | Page+API | M1-System | - |
+| 2 | F-MEMBER-01 | Customer Info | Page+API | M2-Member | F-SYS-01 |
+| ... | ... | ... | ... | ... | ... |
 
-   ⚠️ **HARD STOP — WAIT FOR USER CONFIRMATION**
+⚠️ **HARD STOP — WAIT FOR USER CONFIRMATION**
 
-   ```
-   DO NOT dispatch Feature Spec workers until user explicitly confirms the Feature Registry.
-   Ask user:
-   - Is the feature decomposition granularity appropriate?
-   - Are Feature IDs, Types, and dependencies correct?
-   - Any features to add, remove, or merge?
-
-   IF user requests changes → update .checkpoints.json, then re-present.
-   ONLY after user confirms → update function_decomposition.passed = true.
-   Then proceed to Phase 3.
-   ```
+```
+DO NOT dispatch Feature Spec workers until user explicitly confirms the Feature Registry.
+Ask user:
+- Is the feature decomposition granularity appropriate?
+- Are Feature IDs, Types, and dependencies correct?
+- Any features to add, remove, or merge?
+
+IF user requests changes → update .checkpoints.json, then re-present.
+ONLY after user confirms → update function_decomposition.passed = true.
+Then proceed to Phase 3.
+```
 
 ### Read on Demand
 When involving related business domains, read `{workspace_path}/knowledges/bizs/system-overview.md` first, then follow the links within it to navigate to:
@@ -551,41 +514,59 @@ If only **1 Feature** in registry:
 
 ### Phase 3c: Confirm — Batch Spec Review (Multi-Feature Only)
 
+> 🛑 **ORCHESTRATOR RULES — Phase 3c**
+> - ❌ DO NOT read feature-spec.md files for summary aggregation
+> - ❌ DO NOT count functions/components/APIs by parsing Spec documents
+> - ✅ ONLY read DISPATCH-PROGRESS.json for summary data
+> - ✅ Summary metadata is written by each Worker via update-progress.js
+
 **Condition**: Execute ONLY when 2+ Features exist
 
 **Purpose**: Present batch Feature Spec summary and obtain user confirmation before proceeding to API Contract generation.
 
-1. **Read all `feature-spec.md` files** generated in Phase 3b
+#### Step 1: Read Progress Summary
 
-2. **Build Batch Spec Summary**:
+Read DISPATCH-PROGRESS.json to get completion status and metadata for all features:
 
-   | Feature ID | Feature Name | Functions | Frontend Components | APIs | Data Entities |
-   |------------|--------------|-----------|---------------------|------|---------------|
-   | F-CRM-01 | Customer List | 5 | 3 | 4 | 2 new, 1 mod |
-   | F-CRM-02 | Customer Detail | 4 | 2 | 3 | 1 new |
-   | ... | ... | ... | ... | ... | ... |
+```bash
+node {workspace_path}/scripts/update-progress.js read --file {dispatch_progress_path} --overview
+```
 
-3. **Present to User**:
-   ```
-   📋 Batch Feature Spec Summary
-   
-   Total Features: {N}
-   ├── Functions Designed: {total}
-   ├── Frontend Components: {total}
-   ├── Backend APIs: {total}
-   └── Data Entities: {new} new, {modified} modified
-   
-   [Summary table above]
-   
-   ⚠️ HARD STOP — Please review all Feature Specs before proceeding to API Contract generation.
-   ```
+The progress file contains each task's status and metadata (function_count, component_count, api_count, entity_count) updated by Workers upon completion.
+
+#### Step 2: Build Summary from Progress Data
+
+From the progress data, build the batch summary table:
+
+| Feature ID | Feature Name | Functions | Frontend Components | APIs | Data Entities | Status |
+|---|---|---|---|---|---|---|
+
+> 🛑 **DO NOT read individual feature-spec.md files to build this summary.**
+> All summary data comes from DISPATCH-PROGRESS.json metadata fields.
+
+#### Step 3: Present Summary to User
+
+```
+📋 Batch Feature Spec Summary
+
+Total Features: {N}
+├── Functions Designed: {total}
+├── Frontend Components: {total}
+├── Backend APIs: {total}
+└── Data Entities: {new} new, {modified} modified
+
+[Summary table above]
+
+⚠️ HARD STOP — Please review all Feature Specs before proceeding to API Contract generation.
+```
+
+#### Step 4: HARD STOP — Wait for User Confirmation
 
-4. **HARD STOP**: Wait for user confirmation
-   - If user requests modification for specific Feature → Re-dispatch design worker for that Feature only
-   - If user confirms → Update `.checkpoints.json`:
-     ```bash
-     node {update_progress_script} write-checkpoint --file {iterations_dir}/{iteration}/02.feature-design/.checkpoints.json --stage 02_feature_design --checkpoint feature_spec_review --passed true
-     ```
+- If user requests modification for specific Feature → Re-dispatch design worker for that Feature only
+- If user confirms → Update `.checkpoints.json`:
+  ```bash
+  node {update_progress_script} write-checkpoint --file {iterations_dir}/{iteration}/02.feature-design/.checkpoints.json --stage 02_feature_design --checkpoint feature_spec_review --passed true
+  ```
 
 ---
 

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

@@ -510,6 +510,26 @@ node speccrew-workspace/scripts/update-progress.js write-checkpoint \
 
 Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review passed."
 
+## Step 9: Update Progress with Metadata
+
+After generating the Feature Spec document, update the task in DISPATCH-PROGRESS.json with summary metadata:
+
+```bash
+node {workspace_path}/scripts/update-progress.js update-task \
+  --file {dispatch_progress_path} \
+  --task-id {feature_task_id} \
+  --status completed \
+  --metadata '{"function_count": X, "component_count": Y, "api_count": Z, "entity_count": W}'
+```
+
+Where:
+- `function_count`: Number of functions defined in the Feature Spec
+- `component_count`: Number of frontend components identified
+- `api_count`: Number of API endpoints defined
+- `entity_count`: Number of data entities defined
+
+⚠️ This step is MANDATORY — the FD Agent relies on this metadata for batch summary in Phase 3c.
+
 ---
 
 # Key Rules
@@ -555,6 +575,7 @@ Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review pass
 - [ ] **[CRITICAL]** Processing Logic uses Mermaid flowchart TD (NOT ASCII)
 - [ ] All Mermaid diagrams follow mermaid-rule.md compliance rules
 - [ ] `.checkpoints.json` updated via script
+- [ ] **CRITICAL**: DISPATCH-PROGRESS.json updated with metadata (function_count, component_count, api_count, entity_count)
 - [ ] 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-registry-init/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: speccrew-fd-feature-registry-init
+description: Extract Feature Breakdown from Master PRD and Sub-PRD files to generate Feature Registry. Scans PRD directory, parses Feature Breakdown tables from all Sub-PRDs, and outputs .feature-registry.json with module-grouped features and summary statistics.
+tools: Read, Write, Glob
+---
+
+# Feature Registry Initialization
+
+Extract Feature Breakdown from Master PRD and Sub-PRD files to generate a centralized Feature Registry. This Skill discovers all PRD files, parses Feature Breakdown tables, and produces a structured registry with summary statistics.
+
+## Trigger Scenarios
+
+- "Initialize feature registry from PRDs"
+- "Extract features from all Sub-PRDs"
+- "Build feature registry for the project"
+- "Generate feature breakdown summary"
+
+## Input Parameters
+
+| Parameter | Type | Description | Required |
+|-----------|------|-------------|----------|
+| `prd_dir` | string | Path to PRD documents directory (contains Master PRD and all Sub-PRDs) | **Yes** |
+| `workspace_path` | string | Workspace root path for reading techs-manifest.json | **Yes** |
+| `language` | string | Target language for output content | **Yes** |
+
+## Output
+
+- **JSON File**: `{prd_dir}/.feature-registry.json` - Structured feature registry
+- **Summary**: Markdown table with module statistics and feature distribution
+
+---
+
+## Workflow
+
+### Step 0: Read Template / Validate Inputs
+
+1. **Validate prd_dir exists**
+   - Check if `{prd_dir}` directory exists
+   - If not found, report error and stop
+
+2. **Validate Sub-PRD files exist**
+   - Scan for files matching `*-sub-*.md` pattern in `{prd_dir}`
+   - If no Sub-PRD files found, report error and stop
+
+3. **Output**: "Step 0 Status: ✅ COMPLETED - Found {sub_prd_count} Sub-PRD files"
+
+### Step 1: Discover PRD Files
+
+1. **Scan PRD Directory**
+   - Find **Master PRD**: files matching `*-master-prd.md`
+   - Find **Sub-PRDs**: files matching `*-sub-*.md`
+   - Record file paths and names
+
+2. **Discover Frontend Platforms**
+   - Read `{workspace_path}/knowledges/techs/techs-manifest.json`
+   - Extract platform list from the manifest
+   - Platforms typically include: `web-vue`, `mobile-uniapp`, etc.
+
+3. **Output**: 
+   - "Step 1 Status: ✅ COMPLETED - Found 1 Master PRD, {count} Sub-PRDs"
+   - "Frontend Platforms: {platform_list}"
+
+### Step 2: Extract Feature Breakdown from Each Sub-PRD
+
+For each Sub-PRD file:
+
+1. **Read Sub-PRD Content**
+   - Parse the markdown file
+
+2. **Locate Section 3.4 "Feature Breakdown"**
+   - Find the section header (may be in different languages based on `language`)
+   - Common patterns: "3.4 Feature Breakdown", "3.4 功能分解", etc.
+
+3. **Parse Feature Table**
+   - Extract table rows containing feature information
+   - For each feature, extract:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `feature_id` | Feature identifier | F-SYS-01, F-CRM-05 |
+| `feature_name` | Human-readable feature name | User Management, Order List |
+| `type` | Feature type | User Interaction / Backend Process |
+| `priority` | Priority level | P0 / P1 / P2 |
+| `sub_features` | List of sub-feature IDs | ["M1-F01-01", "M1-F01-02"] |
+| `description` | Brief description | Manage system users and permissions |
+| `source_prd` | Source file name | litemes-sub-system-management.md |
+| `module_key` | Module identifier | system-management |
+
+4. **Extract Module Information**
+   - Derive `module_id` from PRD (e.g., M1, M2)
+   - Derive `module_name` from PRD header or content
+   - Map to `module_key` (kebab-case identifier)
+
+5. **Output**: "Step 2 Status: ✅ COMPLETED - Extracted {feature_count} features from {prd_name}"
+
+### Step 3: Build Feature Registry
+
+1. **Merge All Features**
+   - Combine features from all Sub-PRDs into a single collection
+   - Group features by module
+
+2. **Calculate Summary Statistics**
+
+| Statistic | Calculation |
+|-----------|-------------|
+| `total_modules` | Count of unique modules |
+| `total_features` | Total count of all features |
+| `by_priority` | Count by priority (P0, P1, P2) |
+| `by_type` | Count by type (User Interaction, Backend Process) |
+| `frontend_platforms` | List from techs-manifest.json |
+
+3. **Organize Registry Structure**
+   - Group features under their respective modules
+   - Sort modules by module_id (M1, M2, M3...)
+   - Sort features by feature_id within each module
+
+4. **Output**: "Step 3 Status: ✅ COMPLETED - Registry contains {total_features} features across {total_modules} modules"
+
+### Step 4: Write Output Files
+
+1. **Write `.feature-registry.json`**
+
+Output path: `{prd_dir}/.feature-registry.json`
+
+Structure:
+```json
+{
+  "created_at": "2026-01-15T10:30:00Z",
+  "summary": {
+    "total_modules": 8,
+    "total_features": 42,
+    "by_priority": {
+      "P0": 35,
+      "P1": 5,
+      "P2": 2
+    },
+    "by_type": {
+      "User Interaction": 30,
+      "Backend Process": 12
+    },
+    "frontend_platforms": ["web-vue", "mobile-uniapp"]
+  },
+  "modules": [
+    {
+      "module_id": "M1",
+      "module_name": "System Management",
+      "module_key": "system-management",
+      "source_prd": "litemes-sub-system-management.md",
+      "features": [
+        {
+          "feature_id": "F-SYS-01",
+          "feature_name": "User Management",
+          "type": "User Interaction",
+          "priority": "P0",
+          "sub_features": ["M1-F01-01", "M1-F01-02"],
+          "description": "Manage system users and permissions"
+        }
+      ]
+    }
+  ]
+}
+```
+
+2. **Output**: "Step 4 Status: ✅ COMPLETED - Written .feature-registry.json"
+
+### Step 5: Output Summary
+
+Generate and output a Markdown summary table for Agent display:
+
+```markdown
+## Feature Registry Summary
+
+| Module | Features | P0 | P1 | P2 | Types |
+|--------|----------|----|----|----|-------|
+| M1 System Management | 4 | 4 | 0 | 0 | UI: 4, Backend: 0 |
+| M2 User Center | 6 | 5 | 1 | 0 | UI: 5, Backend: 1 |
+| ... | ... | ... | ... | ... | ... |
+| **Total** | **42** | **35** | **5** | **2** | **UI: 30, Backend: 12** |
+
+**Frontend Platforms:** web-vue, mobile-uniapp
+
+**Registry File:** `{prd_dir}/.feature-registry.json`
+```
+
+**Output**: "Step 5 Status: ✅ COMPLETED - Summary generated"
+
+---
+
+## Task Completion Report
+
+When the task is complete, report:
+
+```json
+{
+  "status": "success",
+  "skill": "speccrew-fd-feature-registry-init",
+  "result": {
+    "registry_file": "{prd_dir}/.feature-registry.json",
+    "total_modules": 8,
+    "total_features": 42,
+    "by_priority": {
+      "P0": 35,
+      "P1": 5,
+      "P2": 2
+    },
+    "by_type": {
+      "User Interaction": 30,
+      "Backend Process": 12
+    }
+  },
+  "message": "Feature registry initialized successfully"
+}
+```
+
+---
+
+## Constraints
+
+1. **READ-ONLY on PRDs**: Do not modify any PRD files
+2. **JSON Output**: Registry must be valid JSON
+3. **Feature ID Uniqueness**: Each feature_id should be unique across all modules
+4. **Module Grouping**: Features must be grouped by their source module
+5. **Priority Validation**: Only accept P0, P1, P2 as valid priority values
+6. **Type Validation**: Only accept "User Interaction" or "Backend Process" as valid types
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| prd_dir not found | Report error, stop execution |
+| No Sub-PRD files found | Report error, stop execution |
+| Master PRD not found | Log warning, continue with Sub-PRDs only |
+| techs-manifest.json not found | Use empty platform list, log warning |
+| Feature table not found in Sub-PRD | Skip that PRD, log warning |
+| Invalid feature data | Skip invalid row, log warning |
+| Duplicate feature_id | Keep first occurrence, log warning |
+
+## Checklist
+
+- [ ] Step 0: Validated prd_dir exists
+- [ ] Step 0: Found at least one Sub-PRD file
+- [ ] Step 1: Discovered Master PRD and all Sub-PRDs
+- [ ] Step 1: Read techs-manifest.json for frontend platforms
+- [ ] Step 2: All Sub-PRD files scanned
+- [ ] Step 2: Feature Breakdown tables parsed from each Sub-PRD
+- [ ] Step 3: Features merged and grouped by module
+- [ ] Step 3: Summary statistics calculated (total, by_priority, by_type)
+- [ ] Step 4: `.feature-registry.json` written to correct path
+- [ ] Step 5: Summary table generated and output

package/package.json

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