speccrew 0.4.4 → 0.5.1

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

@@ -26,16 +26,55 @@ Phase 2: Knowledge Loading
   └── Read PRDs → Discover platforms → Extract Features
   └── Write .checkpoints.json → HARD STOP (user confirms Feature Registry)
         ↓
-Phase 3: Worker Dispatch
-  └── 1 Feature? → Direct skill invocation
-  └── 2+ Features? → Init DISPATCH-PROGRESS → Batch dispatch workers (6/batch)
-  └── Error handling → Retry/skip/abort
+Phase 3: Feature Design — Three-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
+  └── 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
         ↓
 Phase 4: API Contract Generation
   └── Dispatch API Contract workers (same batch pattern)
   └── Joint Confirmation (HARD STOP) → Finalize stage
 ```
 
+## ORCHESTRATOR Rules
+
+> **These rules govern the Feature Designer Agent's behavior across ALL phases. Violation = workflow failure.**
+
+| Phase | Rule | Description |
+|-------|------|-------------|
+| 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 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 |
+| ALL | SCRIPT ENFORCEMENT | All .checkpoints.json and WORKFLOW-PROGRESS.json updates via update-progress.js script. Manual JSON creation FORBIDDEN |
+
+## ABORT CONDITIONS
+
+> **If ANY of the following conditions occur, the Feature Designer Agent MUST immediately STOP the workflow and report to user.**
+
+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.
+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.
+
 # Workflow
 
 ## Phase 0: Workflow Progress Management
@@ -66,6 +105,8 @@ Before starting any feature design work:
    node speccrew-workspace/scripts/update-progress.js update-workflow --file speccrew-workspace/iterations/{iteration-id}/WORKFLOW-PROGRESS.json --stage 02_feature_design --status in_progress
    ```
 
+   > **PowerShell Compatibility**: On Windows PowerShell, do not use backslash (`\`) for line continuation. Write the entire command on a single line.
+
 ### 0.2 Check Resume State (Checkpoint Recovery)
 
 If resuming from an interrupted session:
@@ -283,137 +324,231 @@ 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 — Worker Dispatch
+## Phase 3: Feature Design — Three-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, 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.
+> 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.
 
-### 3.1 Dispatch Mode Decision
+---
 
-Based on Phase 2 Feature Breakdown extraction:
+### Phase 3a: Analyze — Function Decomposition
 
-| Condition | Dispatch Mode | Behavior |
-|-----------|---------------|----------|
-| 2+ Features in registry | Worker dispatch | Each Feature gets its own worker |
-| 1 Feature in registry | Direct skill invocation | Invoke skill directly |
+**Purpose**: Decompose PRD requirements into implementable functions with system relationship markers.
 
-### 3.2 Single Feature (Direct Skill Invocation)
+**Skill**: `speccrew-fd-feature-analyze/SKILL.md`
 
-If the entire iteration has only **one Feature** in the registry:
+#### Single Feature (Direct Invocation)
 
-Invoke Skill directly with parameters:
-- Skill path: `speccrew-fd-feature-design/SKILL.md`
+If only **1 Feature** in registry:
+
+- Skill path: `speccrew-fd-feature-analyze/SKILL.md`
 - Parameters:
-  - `prd_path`: Path to the PRD document (Master PRD if exists, otherwise the single PRD)
+  - `prd_path`: Path to the Sub-PRD document
   - `feature_id`: Feature ID (e.g., `F-CRM-01`)
   - `feature_name`: Feature name (e.g., `Customer List Management`)
   - `feature_type`: `Page+API` or `API-only`
-  - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-feature-spec.md`
+  - `iteration_id`: Current iteration identifier
   - `frontend_platforms`: List of frontend platforms from techs-manifest
+- Wait for Checkpoint A completion (skill internal handling)
 
-### 3.3 Multiple Features (Parallel Worker Dispatch)
+#### Multiple Features (Worker Dispatch)
 
-If the iteration has **2+ Features** in the registry:
+If **2+ Features** in registry:
 
-⚠️ **YOU MUST dispatch `speccrew-task-worker` agents. DO NOT invoke the skill yourself.**
+1. **Initialize/Update 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"
+   ```
 
-#### Step 1: Initialize Dispatch Progress Tracking
+2. **Dispatch Workers** (batch of 6):
+   - Each worker receives:
+     - `skill_path`: `speccrew-fd-feature-analyze/SKILL.md`
+     - `context`:
+       - `prd_path`: Path to Sub-PRD
+       - `feature_id`: Feature ID
+       - `feature_name`: Feature name
+       - `feature_type`: `Page+API` or `API-only`
+       - `iteration_id`: Current iteration
+       - `frontend_platforms`: Platform list
+       - `skip_checkpoint`: `true` (batch mode skips per-feature confirmation)
 
-Before dispatching workers, initialize `DISPATCH-PROGRESS.json`:
+3. **Wait for batch completion**, update progress per worker
 
-```bash
-node speccrew-workspace/scripts/update-progress.js init-dispatch \
-  --file speccrew-workspace/iterations/{iteration}/02.feature-design/DISPATCH-PROGRESS.json \
-  --tasks "F-CRM-01,F-CRM-02,F-CRM-03"
-```
+4. **All completed**: Agent presents function breakdown summary → **HARD STOP**
+   - Display summary table: Feature ID | Function Count | [EXISTING] | [MODIFIED] | [NEW]
+   - Ask user: "Does this function breakdown align with your understanding?"
+   - Wait for explicit confirmation before proceeding to Phase 3b
 
-Each task entry records:
-- `feature_id`: Feature identifier
-- `feature_name`: Feature name
-- `feature_type`: `Page+API` or `API-only`
-- `source_prd`: Path to the source PRD document
-- `status`: `pending` | `in_progress` | `completed` | `failed`
-- `output_path`: Path to the generated Feature Spec
+**Output**: One `.feature-analysis.md` per Feature
 
-#### Step 2: Dispatch Workers
+---
 
-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`:
-    - `feature_id`: Feature ID (e.g., `F-CRM-01`)
-    - `feature_name`: Feature name (e.g., `Customer List Management`)
-    - `feature_type`: `Page+API` or `API-only`
-    - `master_prd_path`: Path to the Master PRD document (if exists)
-    - `source_prd_path`: Path to the Sub-PRD containing this Feature
-    - `prd_path`: Path to the Sub-PRD containing this Feature (same as source_prd_path, required by speccrew-fd-feature-design skill)
-    - `output_path`: `speccrew-workspace/iterations/{iteration}/02.feature-design/{feature_id}-{feature-name-slug}-feature-spec.md`
-    - `frontend_platforms`: List of frontend platforms from techs-manifest
-- **Note**: `prd_path` and `source_prd_path` refer to the same Sub-PRD file. `prd_path` is the primary field required by the Feature Design skill.
-
-- **Parallel execution pattern**:
-  - Worker 1: Feature F-CRM-01 → Feature Spec for Customer List
-  - 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**:
-  - Format: `{feature-id}-{feature-name-slug}-feature-spec.md`
-  - Example: `F-CRM-01-customer-list-feature-spec.md`
-  - Slug: lowercase, hyphens for spaces, no special characters
-
-### 3.4 Error Handling
-
-When a worker reports failure:
-
-1. **Update status**: Set the failed feature's `feature_spec_status` to `failed` in `.checkpoints.json`
-
-2. **Log error**: Record the error message in `DISPATCH-PROGRESS.json` via:
+### Phase 3b: Design — Feature Specification
+
+**Purpose**: Transform function decomposition into complete feature specifications.
+
+**Prerequisite**: All Phase 3a outputs exist (`.feature-analysis.md` for each Feature)
+
+**Skill**: `speccrew-fd-feature-design/SKILL.md`
+
+#### Single Feature (Direct Invocation)
+
+- Skill path: `speccrew-fd-feature-design/SKILL.md`
+- Parameters:
+  - `feature_analysis_path`: Path to `.feature-analysis.md` from Phase 3a
+  - `prd_path`: Path to Sub-PRD
+  - `feature_id`: Feature ID
+  - `feature_name`: Feature name
+  - `feature_type`: `Page+API` or `API-only`
+  - `frontend_platforms`: Platform list
+
+#### 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_design
+   ```
+
+2. **Dispatch Workers** (batch of 6):
+   - Each worker receives:
+     - `skill_path`: `speccrew-fd-feature-design/SKILL.md`
+     - `context`:
+       - `feature_analysis_path`: Path to `.feature-analysis.md`
+       - `prd_path`: Path to Sub-PRD
+       - `feature_id`: Feature ID
+       - `feature_name`: Feature name
+       - `feature_type`: `Page+API` or `API-only`
+       - `frontend_platforms`: Platform list
+
+3. **Wait for batch completion**, update progress
+
+**Output**: One `.feature-design-data.md` per Feature
+
+---
+
+### Phase 3c: Confirm — Batch Design Review (Multi-Feature Only)
+
+**Condition**: Execute ONLY when 2+ Features exist
+
+**Purpose**: Present batch design summary and obtain user confirmation before final generation.
+
+1. **Read all `.feature-design-data.md` files**
+
+2. **Build Batch Design Summary**:
+
+   | 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 |
+   | ... | ... | ... | ... | ... | ... |
+
+3. **Present to User**:
+   ```
+   📋 Batch Design 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 designs before proceeding to document 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:
+     ```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
+     ```
+
+---
+
+### 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:
+
+1. **Identify Phase**: Record which phase failed (3a/3b/3d) 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 "{error_message}"
+   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}"
    ```
 
-3. **Continue batch**: Do NOT stop the entire batch for a single failure. Complete remaining workers in the current batch.
+3. **Continue batch**: Do NOT stop entire batch for single failure. Complete remaining workers.
 
-4. **Report to user**: After each batch completes, report failures:
+4. **Report to user** (per phase):
    ```
-   📊 Batch 1 complete: 5/6 succeeded, 1 failed
+   📊 Phase 3a (Analyze) — Batch 1 complete: 5/6 succeeded, 1 failed
    ├── ✅ F-SYS-01, F-SYS-02, F-SYS-03, F-SYS-04, F-MEMBER-01
    └── ❌ F-MEMBER-02: [error description]
    
    Retry failed features? (yes/skip/abort)
    ```
 
-5. **Retry strategy**: 
-   - If user says "yes" → Re-dispatch failed features in the next batch
-   - If user says "skip" → Mark as `skipped`, continue with remaining features
-   - If user says "abort" → Stop dispatch, present partial results
+5. **Retry strategy**:
+   - If user says "yes" → Re-dispatch failed features in next batch (same phase)
+   - If user says "skip" → Mark as `skipped`, continue to next phase (if applicable)
+   - If user says "abort" → STOP workflow, report partial results
+
+6. **Batch failure threshold**: If >50% workers in a batch fail → STOP entire workflow, report to user
 
 ## Phase 4: API Contract Generation