speccrew 0.3.3 → 0.3.5

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

@@ -172,15 +172,98 @@ After reading PRD documents, extract Feature Breakdown from each Sub-PRD:
    - `Type`: Either `Page+API` or `API-only`
    - `Dependencies`: List of prerequisite Feature IDs (if any)
 
-3. **Build Feature Registry**: Consolidate all features across Sub-PRDs into a unified list:
+3. **Build Feature Registry**: Consolidate all features across Sub-PRDs into a unified list.
+
+4. **Write Feature Registry to `.checkpoints.json`**:
+
+   Write or update the checkpoint file at:
    ```
-   Feature Registry Example:
-   ├── F-CRM-01: Customer List Management (Page+API) - from sub-prd-customer.md
-   ├── F-CRM-02: Customer Detail View (Page+API) - from sub-prd-customer.md, depends on F-CRM-01
-   └── F-CRM-03: Customer Search API (API-only) - from sub-prd-customer.md
+   speccrew-workspace/iterations/{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
+       }
+     }
+   }
    ```
 
-4. **Backward Compatibility Check**:
+   **Feature status values:**
+   - `pending`: Not started
+   - `in_progress`: Worker dispatched
+   - `completed`: Worker finished successfully
+   - `failed`: Worker failed (needs retry)
+   - `confirmed`: User confirmed the output
+
+   **After each worker completes**, update the corresponding feature's status:
+   - Feature Spec worker done → set `feature_spec_status` = `completed`
+   - API Contract worker done → set `api_contract_status` = `completed`
+
+5. **Present Feature Registry to user for confirmation**:
+
+   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 |
+   | ... | ... | ... | ... | ... | ... |
+
+   ⚠️ **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,
+   set confirmed_at via: node -e "console.log(new Date().toISOString())"
+   Then proceed to Phase 3.
+   ```
+
+6. **Backward Compatibility Check**:
    - If **Feature Breakdown exists**: Proceed with Feature-granular dispatch (new behavior)
    - If **Feature Breakdown missing**: Fall back to Sub-PRD-granular dispatch (legacy behavior)
    - Log the dispatch mode: "📋 Dispatch mode: Feature-granular" or "📋 Dispatch mode: Module-granular (legacy)"
@@ -203,9 +286,13 @@ When involving related business domains, read `speccrew-workspace/knowledges/biz
 - Technical architecture documents (handled by speccrew-system-designer)
 - Code conventions (handled by speccrew-system-designer/speccrew-dev)
 
-## Phase 3: Design
+## Phase 3: Design — Worker Dispatch
 
-After knowledge loading is complete, design feature specifications based on the dispatch mode:
+> ⚠️ **MANDATORY RULES FOR PHASE 3:**
+> 1. **DO NOT ask user which strategy to use** — the strategy is determined by Phase 2 extraction results, not user choice.
+> 2. **DO NOT invoke the Feature Design skill directly** when there are multiple Features. You MUST dispatch `speccrew-task-worker` agents.
+> 3. **Dispatch granularity is PER FEATURE, not per module.** Each Feature gets its own worker and its own output file.
+> 4. **DO NOT generate Feature Spec documents yourself.** Your role is to DISPATCH workers, not to write specs.
 
 ### 3.1 Dispatch Mode Decision
 
@@ -213,13 +300,13 @@ Based on Phase 2 Feature Breakdown extraction:
 
 | Condition | Dispatch Mode | Behavior |
 |-----------|---------------|----------|
-| Feature Breakdown found with multiple Features | Feature-granular | Each Feature gets its own worker/skill invocation |
-| Feature Breakdown found with single Feature | Direct skill | Invoke skill directly without worker |
-| No Feature Breakdown (legacy PRD) | Module-granular | Each Sub-PRD gets one worker (backward compatible) |
+| Feature Breakdown found with 2+ Features | Feature-granular (worker dispatch) | Each Feature gets its own worker |
+| Feature Breakdown found with 1 Feature | Direct skill invocation | Invoke skill directly (only case where this is allowed) |
+| No Feature Breakdown (legacy PRD) | Module-granular (worker dispatch) | Each Sub-PRD gets one worker (backward compatible) |
 
 ### 3.2 Feature-Granular Dispatch (New Behavior)
 
-When Feature Breakdown is present, dispatch by Feature:
+When Feature Breakdown is present and has 2+ Features:
 
 #### Single Feature (Direct Skill Invocation)
 If the entire iteration has only **one Feature** in the registry:
@@ -235,9 +322,11 @@ Invoke Skill directly with parameters:
   - `frontend_platforms`: List of frontend platforms from techs-manifest
 
 #### Multiple Features (Parallel Worker Dispatch)
-If the iteration has **multiple Features** in the registry:
+If the iteration has **2+ Features** in the registry:
+
+⚠️ **YOU MUST dispatch `speccrew-task-worker` agents. DO NOT invoke the skill yourself.**
 
-Invoke `speccrew-task-worker` agents in parallel, one per Feature:
+Invoke `speccrew-task-worker` agents in parallel, **one worker per Feature** (NOT per module):
 - Each worker receives:
   - `skill_path`: `speccrew-fd-feature-design/SKILL.md`
   - `context`:
@@ -256,6 +345,26 @@ Invoke `speccrew-task-worker` agents in parallel, one per Feature:
   - Worker 2: Feature F-CRM-02 → Feature Spec for Customer Detail
   - Worker N: Feature F-CRM-0N → Feature Spec for Feature N
 
+- **Batch dispatch for large feature counts**:
+  When total features > 6, dispatch in batches to avoid overload:
+  ```
+  Batch 1: Dispatch up to 6 workers (Features 1-6)
+  Wait for all workers in Batch 1 to complete
+  Update .checkpoints.json feature_spec_status for completed features
+  
+  Batch 2: Dispatch next 6 workers (Features 7-12)
+  Wait for all workers in Batch 2 to complete
+  Update .checkpoints.json feature_spec_status for completed features
+  
+  ... continue until all features are processed
+  ```
+  
+  **Between batches**: Report progress to user:
+  ```
+  📊 Batch 1 complete: 6/44 Feature Specs generated
+  Starting Batch 2...
+  ```
+
 - **Dependency handling**: Features with dependencies should note them, but all workers can execute simultaneously (each Feature Spec references its dependencies)
 
 - **Output file naming convention**:

package/package.json

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