speccrew 0.5.1 → 0.5.3

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

@@ -26,22 +26,18 @@ Phase 2: Knowledge Loading
   └── Read PRDs → Discover platforms → Extract Features
   └── Write .checkpoints.json → HARD STOP (user confirms Feature Registry)
         ↓
-Phase 3: Feature Design — Three-Stage Pipeline
+Phase 3: Feature Design — Two-Stage Pipeline
   └── 3a: Analyze (fd-feature-analyze)
   │     └── 1 Feature? → Direct skill invocation
   │     └── 2+ Features? → Batch dispatch workers (6/batch)
   │     └── Output: .feature-analysis.md per Feature
-  └── 3b: Design (fd-feature-design)
-  │     └── 1 Feature? → Direct skill invocation
-  │     └── 2+ Features? → Batch dispatch workers (6/batch)
-  │     └── Output: .feature-design-data.md per Feature
+  └── 3b: Design & Generate (fd-feature-design)
+  │     └── 1 Feature? → Direct skill invocation (with Checkpoint B)
+  │     └── 2+ Features? → Batch dispatch workers (6/batch, skip_checkpoint=true)
+  │     └── Output: {feature-id}-{feature-name}-feature-spec.md per Feature
   └── 3c: Confirm (HARD STOP for multi-Feature)
-  │     └── 1 Feature? → Checkpoint B handled inside generate skill
-  │     └── 2+ Features? → Agent presents batch summary → HARD STOP
-  └── 3d: Generate (fd-feature-generate)
-        └── 1 Feature? → Direct skill invocation (with Checkpoint B)
-        └── 2+ Features? → Batch dispatch workers (skip_checkpoint=true)
-        └── Output: {feature-id}-{feature-name}-feature-spec.md
+        └── 1 Feature? → Checkpoint B handled inside design skill
+        └── 2+ Features? → Agent presents batch summary → HARD STOP
         ↓
 Phase 4: API Contract Generation
   └── Dispatch API Contract workers (same batch pattern)
@@ -57,9 +53,8 @@ Phase 4: API Contract Generation
 | Phase 0 | STAGE GATE | PRD must be confirmed before starting. If not → STOP |
 | Phase 2 | HARD STOP | Feature Registry must be confirmed by user before Phase 3 |
 | Phase 3a | SKILL-ONLY | Analyze workers MUST use speccrew-fd-feature-analyze skill. Agent MUST NOT perform function decomposition itself |
-| Phase 3b | SKILL-ONLY | Design workers MUST use speccrew-fd-feature-design skill. Agent MUST NOT design features itself |
-| Phase 3c | HARD STOP (multi) | For 2+ Features: Agent MUST present batch summary and wait for user confirmation before generating |
-| Phase 3d | SKILL-ONLY | Generate workers MUST use speccrew-fd-feature-generate skill. Agent MUST NOT write Feature Spec documents itself |
+| Phase 3b | SKILL-ONLY | Design & Generate workers MUST use speccrew-fd-feature-design skill. Agent MUST NOT design features or write Feature Spec documents itself |
+| Phase 3c | HARD STOP (multi) | For 2+ Features: Agent MUST present batch summary and wait for user confirmation after Feature Specs are generated |
 | Phase 4 | SKILL-ONLY | API Contract workers MUST use speccrew-fd-api-contract skill |
 | Phase 4 | HARD STOP | Joint Confirmation must be confirmed by user before finalizing |
 | ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT attempt to generate content manually as fallback |
@@ -71,7 +66,7 @@ Phase 4: API Contract Generation
 
 1. **Skill Invocation Failure**: Any skill call returns error → STOP. Do NOT generate content manually.
 2. **Script Execution Failure**: `node ... update-progress.js` fails → STOP. Do NOT manually create/edit JSON files.
-3. **Missing Intermediate Artifacts**: `.feature-analysis.md` missing before Phase 3b, or `.feature-design-data.md` missing before Phase 3d → STOP.
+3. **Missing Intermediate Artifacts**: `.feature-analysis.md` missing before Phase 3b → STOP.
 4. **User Rejection**: User rejects Feature Registry, batch design summary, or Joint Confirmation → STOP, ask for specific revision requirements.
 5. **Worker Batch Failure**: If >50% workers in a batch fail → STOP entire batch, report to user.
 
@@ -324,15 +319,15 @@ 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: Feature Design — Three-Stage Pipeline
+## Phase 3: Feature Design — Two-Stage Pipeline
 
 > ⚠️ **MANDATORY RULES FOR PHASE 3:**
 > 1. **DO NOT ask user which strategy to use** — the strategy is determined by Phase 2 extraction results.
 > 2. **DO NOT invoke skills 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 per phase.
 > 4. **DO NOT generate Feature Spec documents yourself.** Your role is to DISPATCH workers.
-> 5. **Phase 3a → 3b → 3c → 3d is STRICTLY SERIAL.** Each phase must complete before the next begins.
-> 6. **Intermediate artifacts are MANDATORY.** .feature-analysis.md must exist before Phase 3b. .feature-design-data.md must exist before Phase 3d.
+> 5. **Phase 3a → 3b → 3c is STRICTLY SERIAL.** Each phase must complete before the next begins.
+> 6. **Intermediate artifacts are MANDATORY.** .feature-analysis.md must exist before Phase 3b.
 
 ---
 
@@ -360,9 +355,9 @@ If only **1 Feature** in registry:
 
 If **2+ Features** in registry:
 
-1. **Initialize/Update DISPATCH-PROGRESS.json**:
+1. **Initialize DISPATCH-PROGRESS.json**:
    ```bash
-   node speccrew-workspace/scripts/update-progress.js init-dispatch --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_analyze --tasks "F-CRM-01,F-CRM-02,F-CRM-03"
+   node speccrew-workspace/scripts/update-progress.js init --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_analyze --tasks "[{\"id\":\"F-CRM-01\"},{\"id\":\"F-CRM-02\"},{\"id\":\"F-CRM-03\"}]"
    ```
 
 2. **Dispatch Workers** (batch of 6):
@@ -388,9 +383,9 @@ If **2+ Features** in registry:
 
 ---
 
-### Phase 3b: Design — Feature Specification
+### Phase 3b: Design & Generate — Feature Spec Production
 
-**Purpose**: Transform function decomposition into complete feature specifications.
+**Purpose**: Transform function decomposition into complete Feature Spec documents in a single pass (design + document generation).
 
 **Prerequisite**: All Phase 3a outputs exist (`.feature-analysis.md` for each Feature)
 
@@ -398,6 +393,8 @@ If **2+ Features** in registry:
 
 #### Single Feature (Direct Invocation)
 
+If only **1 Feature** in registry:
+
 - Skill path: `speccrew-fd-feature-design/SKILL.md`
 - Parameters:
   - `feature_analysis_path`: Path to `.feature-analysis.md` from Phase 3a
@@ -406,12 +403,14 @@ If **2+ Features** in registry:
   - `feature_name`: Feature name
   - `feature_type`: `Page+API` or `API-only`
   - `frontend_platforms`: Platform list
+  - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
+- Checkpoint B handled inside skill (user confirmation before writing)
 
 #### Multiple Features (Worker Dispatch)
 
-1. **Update DISPATCH-PROGRESS.json**:
+1. **Initialize DISPATCH-PROGRESS.json for Design & Generate stage**:
    ```bash
-   node speccrew-workspace/scripts/update-progress.js update-stage --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_design
+   node speccrew-workspace/scripts/update-progress.js init --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_spec --tasks "[{\"id\":\"F-CRM-01\"},{\"id\":\"F-CRM-02\"},{\"id\":\"F-CRM-03\"}]"
    ```
 
 2. **Dispatch Workers** (batch of 6):
@@ -424,22 +423,27 @@ If **2+ Features** in registry:
        - `feature_name`: Feature name
        - `feature_type`: `Page+API` or `API-only`
        - `frontend_platforms`: Platform list
+       - `output_path`: Path for final spec
+       - `skip_checkpoint`: `true` (batch mode — Checkpoint B deferred to Phase 3c)
+
+3. **Wait for batch completion**, update progress per worker
 
-3. **Wait for batch completion**, update progress
+4. **Update `.checkpoints.json`** for each completed Feature:
+   - Set `feature_spec_status` = `completed`
 
-**Output**: One `.feature-design-data.md` per Feature
+**Output**: One `{feature-id}-{feature-name}-feature-spec.md` per Feature
 
 ---
 
-### Phase 3c: Confirm — Batch Design Review (Multi-Feature Only)
+### Phase 3c: Confirm — Batch Spec Review (Multi-Feature Only)
 
 **Condition**: Execute ONLY when 2+ Features exist
 
-**Purpose**: Present batch design summary and obtain user confirmation before final generation.
+**Purpose**: Present batch Feature Spec summary and obtain user confirmation before proceeding to API Contract generation.
 
-1. **Read all `.feature-design-data.md` files**
+1. **Read all `feature-spec.md` files** generated in Phase 3b
 
-2. **Build Batch Design Summary**:
+2. **Build Batch Spec Summary**:
 
    | Feature ID | Feature Name | Functions | Frontend Components | APIs | Data Entities |
    |------------|--------------|-----------|---------------------|------|---------------|
@@ -449,7 +453,7 @@ If **2+ Features** in registry:
 
 3. **Present to User**:
    ```
-   📋 Batch Design Summary
+   📋 Batch Feature Spec Summary
    
    Total Features: {N}
    ├── Functions Designed: {total}
@@ -459,77 +463,27 @@ If **2+ Features** in registry:
    
    [Summary table above]
    
-   ⚠️ HARD STOP — Please review all designs before proceeding to document generation.
+   ⚠️ HARD STOP — Please review all Feature Specs before proceeding to API Contract generation.
    ```
 
 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` for all Features:
+   - If user confirms → Update `.checkpoints.json`:
      ```bash
-     node speccrew-workspace/scripts/update-progress.js write-checkpoint --file speccrew-workspace/iterations/{iteration}/02.feature-design/.checkpoints.json --checkpoint feature_spec_review --passed true
+     node speccrew-workspace/scripts/update-progress.js write-checkpoint --file speccrew-workspace/iterations/{iteration}/02.feature-design/.checkpoints.json --stage 02_feature_design --checkpoint feature_spec_review --passed true
      ```
 
 ---
 
-### Phase 3d: Generate — Document Assembly
-
-**Purpose**: Assemble final Feature Spec documents from design data.
-
-**Prerequisite**: 
-- Single Feature: Phase 3b complete
-- Multi-Feature: Phase 3c confirmation passed
-
-**Skill**: `speccrew-fd-feature-generate/SKILL.md`
-
-#### Single Feature (Direct Invocation)
-
-- Skill path: `speccrew-fd-feature-generate/SKILL.md`
-- Parameters:
-  - `feature_analysis_path`: Path to `.feature-analysis.md`
-  - `feature_design_data_path`: Path to `.feature-design-data.md`
-  - `feature_id`: Feature ID
-  - `feature_name`: Feature name
-  - `feature_type`: `Page+API` or `API-only`
-  - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md`
-- Checkpoint B handled inside skill (user confirmation before writing)
-
-#### Multiple Features (Worker Dispatch)
-
-1. **Update DISPATCH-PROGRESS.json**:
-   ```bash
-   node speccrew-workspace/scripts/update-progress.js update-stage --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_generate
-   ```
-
-2. **Dispatch Workers** (batch of 6):
-   - Each worker receives:
-     - `skill_path`: `speccrew-fd-feature-generate/SKILL.md`
-     - `context`:
-       - `feature_analysis_path`: Path to `.feature-analysis.md`
-       - `feature_design_data_path`: Path to `.feature-design-data.md`
-       - `feature_id`: Feature ID
-       - `feature_name`: Feature name
-       - `feature_type`: `Page+API` or `API-only`
-       - `output_path`: Path for final spec
-       - `skip_checkpoint`: `true` (Checkpoint B already done in Phase 3c)
-
-3. **Wait for batch completion**
-
-4. **Update `.checkpoints.json`** for each completed Feature:
-   - Set `feature_spec_status` = `completed`
-
-**Output**: One `{feature-id}-{feature-name}-feature-spec.md` per Feature
-
----
-
 ### Phase 3 Error Handling
 
-When any worker (analyze/design/generate) reports failure:
+When any worker (analyze/design) reports failure:
 
-1. **Identify Phase**: Record which phase failed (3a/3b/3d) and which skill
+1. **Identify Phase**: Record which phase failed (3a/3b) and which skill
 
 2. **Update status**: Set the failed feature's status in `.checkpoints.json`:
    ```bash
-   node speccrew-workspace/scripts/update-progress.js update-task --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --task {feature_id} --status failed --error "[{phase}] {error_message}"
+   node speccrew-workspace/scripts/update-progress.js update-task --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --task-id {feature_id} --status failed --error "[{phase}] {error_message}"
    ```
 
 3. **Continue batch**: Do NOT stop entire batch for single failure. Complete remaining workers.

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

@@ -144,6 +144,7 @@ After user confirms (or if skipped):
 ```bash
 node speccrew-workspace/scripts/update-progress.js write-checkpoint \
   --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+  --stage 02_feature_design \
   --checkpoint function_decomposition \
   --passed true
 ```

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

@@ -1,7 +1,7 @@
 ---
 name: speccrew-fd-feature-design
-description: Feature Design SOP. Transforms function decomposition into complete feature specifications including frontend prototypes, backend interface logic, and data model design. Reads .feature-analysis.md as input and outputs .feature-design-data.md as interface contract for downstream generate skill. Does not involve specific technology implementation details.
-tools: Read, Write, Glob, Grep
+description: Feature Design & Spec Generation SOP. Reads .feature-analysis.md and PRD documents, performs frontend/backend/data design, and generates complete Feature Spec document using template-first workflow. Combines design thinking with document generation in a single pass, without producing any intermediate design-data artifacts. Use when Feature Designer needs to produce Feature Spec from completed analysis.
+tools: Read, Write, Glob, Grep, search_replace
 ---
 
 # Methodology Foundation
@@ -20,45 +20,55 @@ ISA-95 Stages 4-6 as internal thinking framework:
 
 - Function decomposition completed (`.feature-analysis.md` exists)
 - Checkpoint A passed (function breakdown confirmed)
-- User requests feature specifications design
+- Feature Spec document generation needed
 
 # Workflow
 
 ## Absolute Constraints
 
-**ABORT CONDITIONS:** `.feature-analysis.md` does not exist OR Checkpoint A not passed → HARD STOP
+**ABORT CONDITIONS:**
+- `.feature-analysis.md` missing OR Checkpoint A not passed → HARD STOP
+- Template file missing → HARD STOP
 
-**FORBIDDEN:** `create_file` for final feature-spec documents (use template + search_replace in generate skill)
+**FORBIDDEN:**
+- `create_file` for final documents in section-fill phase — use template + search_replace
+- Full-file rewrite — use targeted search_replace per section
 
-## Step 0: Precondition Check
-
-**MANDATORY:** Verify `.feature-analysis.md` exists.
-
-**IF missing → ABORT:** `ERROR: .feature-analysis.md not found. Run speccrew-fd-feature-analysis first.`
-
-**Actions:**
-1. Read `.feature-analysis.md`
-2. Verify Checkpoint A: `function_decomposition.passed == true`
-3. IF not passed → STOP
-4. Extract: feature_id, feature_name, feature_type, functions[], platforms[]
+**MANDATORY:**
+- Template-first workflow — Step 5 (copy template) MUST precede Step 6 (fill content)
 
-## Step 1: Determine Output Structure
+**NOTE:** Design process is internal — no intermediate design-data files are produced.
 
-### 1.1 Single Feature Output (when feature_id provided)
+## Step 0: Precondition Check
 
-| Output | File Naming | Example |
-|--------|-------------|---------|
-| Single File | `{feature-id}-{feature-name}.feature-design-data.md` | `F-CRM-01-customer-list.feature-design-data.md` |
+### Step 0 Input Parameters
 
-### 1.2 Legacy Output (backward compatibility)
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `feature_analysis_path` | Yes | Path to `.feature-analysis.md` |
+| `prd_path` | Yes | Path to the Sub-PRD document |
+| `feature_id` | No | Feature identifier (e.g., `F-CRM-01`) |
+| `feature_name` | No | Feature name in English |
+| `feature_type` | No | `Page+API` or `API-only` |
+| `frontend_platforms` | No | List of frontend platforms |
+| `output_path` | No | Custom output path for Feature Spec (auto-generated if not provided) |
+| `skip_checkpoint` | No | Boolean, default `false`. Skip Checkpoint B if `true` (batch mode) |
 
-When `feature_id` is NOT provided: Single PRD → Single file; Master-Sub PRD → Master + Sub files
+### Step 0 Actions
 
-**Master Design Data MUST include:** overall overview, cross-module diagram, module boundaries, interface contracts, shared data structures.
+1. Read `.feature-analysis.md` at `feature_analysis_path`
+2. Verify Checkpoint A: `function_decomposition.passed == true`
+3. IF not passed → ABORT: `ERROR: Checkpoint A not passed. Run speccrew-fd-feature-analysis first.`
+4. Extract key data:
+   - `feature_id`: From analysis file or parameter
+   - `feature_name`: From analysis file or parameter
+   - `feature_type`: From analysis file or parameter (`Page+API` or `API-only`)
+   - `functions[]`: Function breakdown list
+   - `platforms[]`: Frontend platforms list
 
-## Step 2: Frontend Design (Per Function)
+## Step 1: Frontend Design
 
-### 2.0 Conditional Execution
+### 1.0 Conditional Execution
 
 `feature_type = "Page+API"` → Execute design; `feature_type = "API-only"` → Skip; Not provided → Execute (backward compatibility)
 
@@ -118,7 +128,7 @@ Pattern M-C: Action Sheet
 +----------------------------------+
 ```
 
-### 2.1 UI Prototype
+### 1.1 UI Prototype
 
 Create ASCII wireframes showing layout, UI elements, navigation.
 
@@ -139,13 +149,13 @@ Create ASCII wireframes showing layout, UI elements, navigation.
 +--------------------------------------------------+
 ```
 
-### 2.2 Interface Element Descriptions
+### 1.2 Interface Element Descriptions
 
 | Element | Type | Behavior |
 |---------|------|----------|
 | {name} | {component type} | {behavior description} |
 
-### 2.3 Interaction Flow
+### 1.3 Interaction Flow
 
 Document: `User Action → Frontend Response → Backend API Call`
 
@@ -155,21 +165,21 @@ Document: `User Action → Frontend Response → Backend API Call`
 > - Interface identification: Every data exchange point = potential API endpoint
 > - Exception flows: Document alternative paths, not just happy path
 
-### 2.4 Backend API Mapping
+### 1.4 Backend API Mapping
 
 | Frontend Action | Backend API | Purpose |
 |-----------------|-------------|---------|
 | {action} | {API endpoint} | {data exchanged} |
 
-## Step 3: Backend Design (Per Function)
+## Step 2: Backend Design
 
-### 3.1 API/Interface List
+### 2.1 API/Interface List
 
 | Interface | Method | Description |
 |-----------|--------|-------------|
 | {name} | {GET/POST/PUT/DELETE} | {purpose} |
 
-### 3.2 Processing Logic Flow
+### 2.2 Processing Logic Flow
 
 | Stage | Description |
 |-------|-------------|
@@ -178,22 +188,22 @@ Document: `User Action → Frontend Response → Backend API Call`
 | Data Operations | What data to read/write |
 | Response | What data to return |
 
-### 3.3 Data Access Scheme
+### 2.3 Data Access Scheme
 
 | Operation | Data Target | Type |
 |-----------|-------------|------|
 | Read | {data} | [EXISTING]/[NEW] |
 | Write | {data} | [EXISTING]/[NEW] |
 
-### 3.4 Cross-Module Interactions
+### 2.4 Cross-Module Interactions
 
 | This Module | Interacts With | Interface | Data Exchanged |
 |-------------|----------------|-----------|----------------|
 | {module} | {other module} | {API/Event} | {what data} |
 
-## Step 4: Data Model Design
+## Step 3: Data Model & Business Rules
 
-### 4.1 New Data Structures
+### 3.1 New Data Structures
 
 | Field | Type | Constraints | Description |
 |-------|------|-------------|-------------|
@@ -205,13 +215,13 @@ Document: `User Action → Frontend Response → Backend API Call`
 > - Semantic consistency: Align with domain glossary
 > - Relationships: Identify core relationships (1:1, 1:N, N:N)
 
-### 4.2 Modifications to Existing Data Structures
+### 3.2 Modifications to Existing Data Structures
 
 | Entity | Change Type | Details | Impact |
 |--------|-------------|---------|--------|
 | {entity} | Add/Modify/Remove field | {description} | {affected areas} |
 
-### 4.3 Data Relationships
+### 3.3 Data Relationships
 
 **New Relationships:** `EntityA --1:N--> EntityB`
 
@@ -219,13 +229,13 @@ Document: `User Action → Frontend Response → Backend API Call`
 |------------|-----------------|--------------|
 | {new} | {existing} | {1:1 / 1:N / N:M} |
 
-### 4.4 Data Source Descriptions
+### 3.4 Data Source Descriptions
 
 | Data | Source | Update Frequency |
 |------|--------|------------------|
 | {item} | {internal/external/user} | {real-time/periodic/on-demand} |
 
-## Step 5: Business Rules and Constraints
+### 3.5 Permission Rules
 
 > **ISA-95 Stage 6 Thinking — Information Descriptions**
 > - Validation: Field-level, cross-field, business logic rules
@@ -233,74 +243,184 @@ Document: `User Action → Frontend Response → Backend API Call`
 > - Permissions: Data access rules mapping to API authorization
 > - Traceability: Every rule traces back to PRD requirement
 
-### 5.1 Permission Rules
-
 | Function | Required Permission | Scope |
 |----------|---------------------|-------|
 | {function} | {permission} | {global/module/resource-specific} |
 
-### 5.2 Business Logic Rules
+### 3.6 Business Logic Rules
 
 | Rule ID | Description | Trigger | Action |
 |---------|-------------|---------|--------|
 | BR-{number} | {description} | {when applies} | {what happens} |
 
-### 5.3 Validation Rules
+### 3.7 Validation Rules
 
 | Field | Frontend Validation | Backend Validation |
 |-------|---------------------|---------------------|
 | {field} | {client rules} | {server rules} |
 
-## Step 6: Write Output Contract
-
-Write to `{feature-id}-{feature-name}.feature-design-data.md`:
-
-```markdown
-# Feature Design Data: {feature-name}
-
-## Output Structure
-- Mode: {single-feature/legacy-master-sub}
-- Output path: {planned path}
-
-## Frontend Design
-### Platforms: {list}
-### UI Prototypes
-[Per-platform ASCII wireframes]
-### Interface Elements
-[Element tables]
-### Interaction Flows
-[Mermaid diagrams + descriptions]
-### Backend API Mapping
-[Action → API mapping tables]
-
-## Backend Design
-### API/Interface List
-[Interface tables]
-### Processing Logic
-[Logic flows]
-### Data Access Scheme
-[Operation tables]
-### Cross-Module Interactions
-[Cross-module tables]
-
-## Data Model
-### New Data Structures
-[Entity field tables]
-### Modified Data Structures
-[Modification tables]
-### Data Relationships
-[Relationship diagrams]
-### Data Sources
-[Source tables]
-
-## Business Rules
-### Permission Rules
-[Permission tables]
-### Business Logic Rules
-[Rule tables with BR-{number} IDs]
-### Validation Rules
-[Validation tables]
+## Step 4: Checkpoint B — User Confirmation
+
+**Conditional Execution:** Skip if `skip_checkpoint=true`
+
+### 4.1 Present Design Summary
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║           FEATURE DESIGN SUMMARY - CHECKPOINT B              ║
+╠══════════════════════════════════════════════════════════════╣
+║ Feature: {feature_name} ({feature_id})                       ║
+╠══════════════════════════════════════════════════════════════╣
+║ FUNCTIONS DESIGNED                                           ║
+║ Total: {N} functions                                         ║
+║                                                              ║
+║ Function Breakdown:                                          ║
+║ • {Function 1} - [EXISTING/MODIFIED/NEW]                     ║
+║ • {Function 2} - [EXISTING/MODIFIED/NEW]                     ║
+║ • {Function 3} - [EXISTING/MODIFIED/NEW]                     ║
+╠══════════════════════════════════════════════════════════════╣
+║ SYSTEM RELATIONSHIP SUMMARY                                  ║
+║ • [EXISTING]: {count} - Reuse existing capabilities          ║
+║ • [MODIFIED]: {count} - Enhance existing features            ║
+║ • [NEW]: {count} - Create new functionality                  ║
+╠══════════════════════════════════════════════════════════════╣
+║ FRONTEND COMPONENTS                                          ║
+║ • Platforms: {platform list}                                 ║
+║ • UI Patterns: {list of wireframe patterns used}             ║
+║ • Total Functions with UI: {count}                           ║
+╠══════════════════════════════════════════════════════════════╣
+║ BACKEND INTERFACES                                           ║
+║ • Total APIs: {count}                                        ║
+║ • New APIs: {count}                                          ║
+║ • Modified APIs: {count}                                     ║
+║ • Cross-Module Interactions: {count}                         ║
+╠══════════════════════════════════════════════════════════════╣
+║ DATA ENTITIES                                                ║
+║ • New Entities: {count}                                      ║
+║ • Modified Entities: {count}                                 ║
+║ • Business Rules: {count}                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### 4.2 HARD STOP — 5 Confirmation Questions
+
+**STOP — DO NOT PROCEED until user confirms:**
+
+1. **Function Coverage**: "Does this design cover all functions from the analysis? Are any functions missing?"
+
+2. **System Relationship Markers**: "Are the [EXISTING]/[MODIFIED]/[NEW] markers accurate for each component?"
+
+3. **UI/UX Approach**: "Do the ASCII wireframes and interaction flows match your expectations?"
+
+4. **Backend Interface Scope**: "Are the API endpoints and cross-module interactions correctly identified?"
+
+5. **Data Model Completeness**: "Does the data model cover all fields and relationships needed?"
+
+**WAIT for user confirmation before proceeding to document generation.**
+
+### 4.3 Update Checkpoints
+
+After user confirms (or if skipped):
+
+```bash
+node speccrew-workspace/scripts/update-progress.js write-checkpoint \
+  --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+  --stage 02_feature_design \
+  --checkpoint feature_design_review \
+  --passed true
+```
+
+Log: "✅ Checkpoint B (feature_design_review) passed and recorded"
+
+## Step 5: Determine Output Path & Copy Template
+
+### 5.1 Determine Output Path
+
+**Single Feature Mode** (when `feature_id` provided):
+```
+{iteration_path}/02.feature-design/{feature_id}-{feature_name}-feature-spec.md
+```
+
+**Legacy Single Mode** (backward compatibility):
 ```
+{iteration_path}/02.feature-design/[feature-name]-feature-spec.md
+```
+
+**Legacy Master-Sub Mode** (backward compatibility):
+- Master Spec: `{iteration_path}/02.feature-design/[master-name]-feature-spec.md`
+- Sub Specs: `{iteration_path}/02.feature-design/[sub-name]-feature-spec.md` (one per sub-feature)
+
+### 5.2 Copy Template
+
+1. Read template: `templates/FEATURE-SPEC-TEMPLATE.md` (relative path from skill directory)
+2. Replace top-level placeholders:
+   - `[Feature Name]` → actual feature name
+   - `{Feature ID}` → actual feature ID
+   - `{Feature Name}` → actual feature name
+   - `{Page+API / API-only}` → actual feature type
+   - `{Link to Sub-PRD document}` → `prd_path` value
+3. Create document using `create_file` with template content
+4. Verify section structure exists (Sections 1-6 with proper numbering)
+
+## Step 6: Fill Sections Using search_replace
+
+### Section Mapping Table
+
+| Template Section | Data Source |
+|------------------|-------------|
+| 1. Overview (Basic Information, Feature Scope) | `.feature-analysis.md` Feature Information + summary |
+| 1.3 Relationship to Existing System | `.feature-analysis.md` System Relationships |
+| 2. Function Details | Step 1 Frontend Design + Step 2 Backend Design results (internal) |
+| 2.1.x Frontend Prototype | Step 1.1 UI Prototype results |
+| 2.1.x Interaction Flow | Step 1.3 Interaction Flow results |
+| 2.1.x Backend Interface | Step 2.1-2.3 Backend Design results |
+| 2.1.x Data Definition | Step 3.1-3.4 Data Model results |
+| 3. Cross-Function Concerns | Step 2.4 Cross-Module results |
+| 4. Business Rules & Constraints | Step 3.5-3.7 Business Rules results |
+| 5. API Contract Summary | Aggregated from Step 2.1 API List |
+| 6. Notes | Contextual notes from analysis |
+
+### Filling Rules
+
+- Use `search_replace` for each section individually
+- Preserve all section titles and numbering
+- No applicable content → "N/A"
+- Multi-platform: Create separate sub-sections per platform
+
+### Legacy Master-Sub Mode
+
+If processing Master-Sub structure:
+- Repeat Step 5+6 for each sub-spec
+- Master spec contains: Overview, Cross-module diagram, shared data structures
+- Sub specs contain: Per-feature detailed design
+
+## Step 7: Mermaid Diagram Compliance
+
+Verify all Mermaid diagrams follow compliance rules:
+
+1. **NO style definitions** — No `classDef`, `style`, or CSS-like syntax
+2. **NO HTML tags** — No `<br/>`, `<b>`, or other HTML in labels
+3. **Use standard syntax only:**
+   - `sequenceDiagram` for interaction flows
+   - `flowchart TD` for processing logic
+   - Plain text labels with standard characters
+4. **Reference:** `speccrew-workspace/docs/rules/mermaid-rule.md`
+
+**Validation:** Before finalizing, scan all Mermaid blocks for non-compliant syntax.
+
+## Step 8: Update Checkpoints
+
+Set final checkpoint status:
+
+```bash
+node speccrew-workspace/scripts/update-progress.js write-checkpoint \
+  --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+  --stage 02_feature_design \
+  --checkpoint feature_spec_review \
+  --passed true
+```
+
+Log: "✅ Feature Spec generation completed. Checkpoint feature_spec_review passed."
 
 ---
 
@@ -312,19 +432,30 @@ Write to `{feature-id}-{feature-name}.feature-design-data.md`:
 | Focus on WHAT not HOW | Describe what system does, not how it's implemented |
 | ASCII Wireframes Only | Use ASCII art for UI prototypes |
 | Mermaid Compatibility | Follow mermaid-rule.md guidelines |
-| Clear Markers | Use [EXISTING]/[MODIFIED]/[NEW] markers |
+| Clear Markers | Use [EXISTING]/[MODIFIED]/[NEW] consistently |
+| Template-First | Copy template before filling content |
+| search_replace Only | Never use create_file for section updates after template copy |
+| Checkpoint B | Get user confirmation before writing files (unless skipped) |
+| No Intermediate Files | Design process is internal — do NOT output any intermediate design-data artifacts |
 
 # Checklist
 
-- [ ] `.feature-analysis.md` verified
-- [ ] Checkpoint A passed
-- [ ] Output structure determined
+- [ ] `.feature-analysis.md` verified and exists
+- [ ] Checkpoint A passed (`function_decomposition.passed == true`)
+- [ ] All input parameters resolved (feature_id, feature_name, feature_type)
+- [ ] Template file `templates/FEATURE-SPEC-TEMPLATE.md` exists
 - [ ] **[API-only]** Frontend design skipped
-- [ ] **[Page+API]** ASCII wireframes and flows included
-- [ ] **[Multi-platform]** Per-platform designs
+- [ ] **[Page+API]** ASCII wireframes created for all platforms
+- [ ] **[Multi-platform]** Per-platform designs completed
 - [ ] Backend interfaces and logic documented
-- [ ] Data model with entities and modifications
-- [ ] Business rules documented
+- [ ] Data model with entities and modifications documented
+- [ ] Business rules (permissions, logic, validation) documented
 - [ ] ISA-95 Stage 4/5/6 thinking applied
-- [ ] `.feature-design-data.md` created
+- [ ] Checkpoint B passed: design summary confirmed with user (or skipped)
+- [ ] Output path determined
+- [ ] Template copied using `create_file`
+- [ ] All sections filled using `search_replace`
+- [ ] Mermaid diagrams verified for compliance
+- [ ] `.checkpoints.json` updated via script
 - [ ] No technology decisions included
+- [ ] No intermediate design-data artifact created

package/package.json

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

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

@@ -1,243 +0,0 @@
----
-name: speccrew-fd-feature-generate
-description: Feature Spec Generation SOP. Reads .feature-analysis.md and .feature-design-data.md interface contracts, assembles complete Feature Spec document using template-first workflow. Handles Checkpoint B user confirmation before writing files. Use when Feature Designer needs to generate final Feature Spec document from completed design data.
-tools: Read, Write, Glob, Grep
----
-
-# Skill Overview
-
-Generates final Feature Spec document from completed design data. Reads intermediate artifacts and assembles complete specification using template-first workflow.
-
-## Trigger Scenarios
-
-- Feature design data ready (`.feature-design-data.md` exists)
-- Feature analysis complete (`.feature-analysis.md` exists)
-- Final Feature Spec document generation needed
-
----
-
-# Workflow
-
-## Absolute Constraints
-
-> **Violation = task failure**
-
-### ABORT CONDITIONS
-- `.feature-analysis.md` missing → **HARD STOP**
-- `.feature-design-data.md` missing → **HARD STOP**
-- Template file missing → **HARD STOP**
-- **NEVER skip preconditions verification**
-
-### FORBIDDEN
-- `create_file` for final documents — use template + `search_replace`
-- Full-file rewrite — use targeted `search_replace` per section
-
-### MANDATORY
-- **Template-first workflow** — Step 4 (copy template) MUST precede Step 5 (fill content)
-
----
-
-## Step 1: Read Input & Verify Preconditions
-
-### 1.1 Input Parameters
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `feature_analysis_path` | Yes | Path to `.feature-analysis.md` |
-| `feature_design_data_path` | Yes | Path to `.feature-design-data.md` |
-| `feature_id` | No | Feature identifier (e.g., F-CRM-01) |
-| `feature_name` | No | Feature name |
-| `feature_type` | No | Page+API or API-only |
-| `output_path` | No | Custom output path (auto-generated if not provided) |
-| `skip_checkpoint` | No | Boolean. If true, skip Checkpoint B (batch mode) |
-
-### 1.2 Verify Input Files
-
-**IF either file missing → ABORT:**
-```
-❌ ERROR: Prerequisite files not found.
-   Missing: [filename]
-   
-   This skill requires completed feature analysis and design.
-   Please run speccrew-fd-feature-analyze and speccrew-fd-feature-design first.
-```
-
-### 1.3 Read Files
-
-1. Read `.feature-analysis.md` — extract: Function Breakdown, [EXISTING]/[MODIFIED]/[NEW] counts
-2. Read `.feature-design-data.md` — extract: Frontend Design, Backend Design, Data Model, Business Rules
-3. Read Feature Spec template: `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md`
-
----
-
-## Step 2: Build Design Summary
-
-Extract statistics from intermediate artifacts:
-
-| Metric | Source |
-|--------|--------|
-| Functions Designed | `.feature-analysis.md` Function Breakdown section |
-| [EXISTING] / [MODIFIED] / [NEW] counts | Function markers in analysis |
-| Frontend Components | `.feature-design-data.md` Frontend Design (0 if API-only) |
-| Backend Interfaces | `.feature-design-data.md` Backend Design API count |
-| Data Entities | `.feature-design-data.md` Data Model (new/modified) |
-
----
-
-## Step 3: Checkpoint B — User Confirmation
-
-> **Skip this step if `skip_checkpoint=true`**
-
-### 3.1 Present Summary
-
-```
-Feature Design Summary for: {feature-name}
-
-Functions Designed: {count}
-├── [EXISTING] {count} functions reuse existing capabilities
-├── [MODIFIED] {count} functions enhance existing features
-└── [NEW] {count} functions are brand new
-
-Frontend Components: {count} pages/components
-Backend Interfaces: {count} APIs
-Data Entities: {count} new, {count} modified
-
-Output File: {filename}
-```
-
-### 3.2 Confirm 5 Questions
-
-**HARD STOP** — Wait for user confirmation on:
-
-1. Is the frontend prototype appropriate? (if applicable)
-2. Is the backend logic flow correct and complete?
-3. Is the data model reasonable and extensible?
-4. Are all business rules captured?
-5. [Legacy Master-Sub] Is the module breakdown appropriate?
-
-### 3.3 Update Checkpoint
-
-Update `.checkpoints.json`:
-```json
-{
-  "feature_spec_review": {
-    "passed": true,
-    "confirmed_at": "{timestamp}",
-    "description": "Feature specification confirmed"
-  }
-}
-```
-
----
-
-## Step 4: Determine Output Path & Copy Template
-
-### 4.1 Determine Output Path
-
-| Mode | Path Pattern |
-|------|--------------|
-| Single Feature | `{iteration}/02.feature-design/{feature-id}-{feature-name}-feature-spec.md` |
-| Legacy Single | `{iteration}/02.feature-design/[feature-name]-feature-spec.md` |
-| Legacy Master-Sub | Multiple files (master + sub-specs) |
-
-### 4.2 Copy Template
-
-1. Read template: `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md`
-2. Replace top-level placeholders: `{Feature Name}`, `{Feature ID}`, etc.
-3. **Create document** using `create_file` with template content
-4. Verify complete section structure exists
-
----
-
-## Step 5: Fill Sections Using search_replace
-
-Map data sources to template sections:
-
-| Template Section | Data Source |
-|------------------|-------------|
-| Feature Overview | `.feature-analysis.md` Feature Information + summary |
-| Function Breakdown | `.feature-analysis.md` Function Breakdown |
-| Frontend Design | `.feature-design-data.md` Frontend Design |
-| Backend Design | `.feature-design-data.md` Backend Design |
-| Data Model | `.feature-design-data.md` Data Model |
-| Business Rules | `.feature-design-data.md` Business Rules |
-| Cross-Module Interactions | `.feature-design-data.md` Cross-Module (if applicable) |
-
-**Rules:**
-- Use `search_replace` for each section individually
-- Preserve all section titles and numbering
-- No applicable content → replace placeholder with "N/A"
-- Legacy Master-Sub: repeat Step 4+5 for each sub-spec
-
----
-
-## Step 6: Mermaid Diagram Compliance
-
-Verify all Mermaid diagrams follow compatibility rules:
-
-- Use only basic node definitions: `A[text content]`
-- No HTML tags (e.g., `<br/>`)
-- No nested subgraphs
-- No `direction` keyword
-- No `style` definitions
-- Standard `graph TB/LR` or `sequenceDiagram` syntax only
-
-Reference: `speccrew-workspace/docs/rules/mermaid-rule.md`
-
----
-
-## Step 7: Update Checkpoints
-
-Update `.checkpoints.json`:
-- Set `feature_spec_review.passed = true`
-- Set `confirmed_at` timestamp
-- Preserve existing checkpoint states
-
----
-
-# Reference Guides
-
-## Legacy Mode Backward Compatibility
-
-When `feature_id` is NOT provided:
-
-**Single Feature Spec:**
-```
-02.feature-design/[feature-name]-feature-spec.md
-```
-
-**Master-Sub Feature Specs:**
-```
-02.feature-design/
-├── [feature-name]-feature-spec.md          # Master (overview + cross-module)
-├── [feature-name]-sub-[module1]-spec.md    # Sub: Module 1
-└── [feature-name]-sub-[module2]-spec.md    # Sub: Module 2
-```
-
-Master spec MUST include: overall overview, cross-module diagram, module list, interface contracts.
-
----
-
-# Key Rules
-
-| Rule | Description |
-|------|-------------|
-| **Template-First** | Copy template before filling content |
-| **search_replace Only** | Never use `create_file` for section updates |
-| **Checkpoint B** | Get user confirmation before writing files |
-| **Mermaid Compliance** | Follow mermaid-rule.md guidelines |
-| **Clear Markers** | Use [EXISTING]/[MODIFIED]/[NEW] consistently |
-
----
-
-# Output Checklist
-
-- [ ] Both input files verified and read
-- [ ] Design summary built with statistics
-- [ ] Checkpoint B passed (or skipped via flag)
-- [ ] Output path determined
-- [ ] Template copied using `create_file`
-- [ ] All sections filled using `search_replace`
-- [ ] Mermaid diagrams verified compliant
-- [ ] `.checkpoints.json` updated
-- [ ] [Legacy Master-Sub] All sub-specs generated