speccrew 0.4.4 → 0.5.0

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
 

package/.speccrew/skills/speccrew-fd-api-contract/SKILL.md

@@ -21,6 +21,12 @@ tools: Read, Write, Glob, Grep
 
 3. **MANDATORY: Template-first workflow** — Step 4a (copy template) MUST execute before Step 4b (fill sections). Skipping Step 4a and writing content directly is FORBIDDEN.
 
+4. **ABORT CONDITIONS** — If any of the following occur, STOP immediately and report to user:
+   - Feature Spec document (`feature_spec_path`) does not exist or is empty → STOP
+   - API Contract template file does not exist → STOP
+   - `node ... update-progress.js` script execution fails → **HARD STOP**: Do NOT manually create or edit JSON progress files. Report the script error and wait for user resolution.
+   - User rejects Joint Confirmation → STOP, ask user for specific revision requirements
+
 ## Step 1: Read Input
 
 ### Input Parameters
@@ -152,6 +158,8 @@ After confirmation, you can start frontend and backend Designer Agents separatel
 
 After user confirms Joint Confirmation:
 
+> **SCRIPT ENFORCEMENT RULE**: All `.checkpoints.json` and `WORKFLOW-PROGRESS.json` updates MUST be performed via `node speccrew-workspace/scripts/update-progress.js` commands. Manually creating or editing these JSON files is FORBIDDEN. If the script fails, STOP and report the error — do NOT attempt manual JSON construction.
+
 ### 6a: Update Checkpoints File
 
 Update the `.checkpoints.json` file to record confirmation status.
@@ -272,6 +280,8 @@ Update `WORKFLOW-PROGRESS.json` to reflect current feature/module status.
 - Record all output file paths
 - Log: "✅ Stage 02_feature_design confirmed. Ready for System Design phase."
 
+> **Note**: On Windows PowerShell, do not use backslash (`\`) for line continuation. Write the entire command on a single line.
+
 **关于全局状态管理的说明**：
 > Feature 粒度的 API Contract 完成后，全局阶段状态（`02_feature_design.status` 和 `current_stage`）**不由本 Skill 更新**。
 > 全局状态由 **Feature Designer Agent** 统一管理，当检测到所有 Feature 都完成时，统一更新为 `confirmed` 并推进到下一阶段。

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

@@ -0,0 +1,224 @@
+---
+name: speccrew-fd-feature-analyze
+description: Feature Analysis SOP. Reads PRD documents and system knowledge to produce function decomposition with system relationship markers. Outputs .feature-analysis.md as interface contract for downstream design skills. Use when Feature Designer needs to analyze and decompose PRD requirements before design phase.
+tools: Read, Write, Glob, Grep
+---
+
+# Methodology Foundation
+
+This skill applies ISA-95 Stages 1-3 as an internal thinking framework for analysis:
+
+| ISA-95 Stage | Analysis Purpose |
+|--------------|------------------|
+| Stage 1: Domain Description | Understand business context, scope boundaries, glossary |
+| Stage 2: Information Flows | Identify data sources, destinations, and cross-module exchanges |
+| Stage 3: Categories of Information | Classify data entities and establish information hierarchy |
+
+> ⚠️ **No separate modeling documents.** The methodology guides thinking quality, not document quantity.
+
+# Trigger Scenarios
+
+- PRD has been confirmed, user requests to start feature analysis
+- Feature Designer Agent needs to decompose PRD into functions before design
+- User asks "Analyze this feature" or "Break down this requirement"
+
+# Workflow
+
+## Absolute Constraints
+
+> **Violation = task failure**
+
+1. **FORBIDDEN: Script execution failure** — If `update-progress.js` fails, HARD STOP and report error
+2. **FORBIDDEN: Hand-written `.checkpoints.json`** — ALWAYS use `update-progress.js` script
+3. **FORBIDDEN: Skip Checkpoint A** — User confirmation required before proceeding to design phase (unless `skip_checkpoint=true`)
+
+## Step 1: Read PRD Input
+
+### 1.1 Input Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `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 (e.g., `customer-list`) |
+| `feature_type` | No | `Page+API` or `API-only` |
+| `iteration_id` | No | Current iteration identifier |
+| `frontend_platforms` | No | List of frontend platforms (auto-discover if not provided) |
+| `skip_checkpoint` | No | Boolean, default `false`. Skip Checkpoint A if `true` |
+
+### 1.2 Read PRD
+
+Read the PRD document at `{prd_path}` (typically `speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/[module-name]-prd.md`)
+
+### 1.3 Focus on Specific Feature (when feature_id provided)
+
+If `feature_id` is provided:
+- Locate the specific Feature in PRD Section 3.4 "Feature Breakdown"
+- Extract only the user stories and requirements related to this Feature
+- Ignore other Features in the same PRD
+
+### 1.4 Backward Compatibility (when feature_id not provided)
+
+If `feature_id` is NOT provided, process entire PRD using legacy mode.
+
+## Step 2: Load System Knowledge
+
+### 2.1 Read System Overview
+
+Read: `speccrew-workspace/knowledges/bizs/system-overview.md`
+
+### 2.2 Load Related Module Overviews
+
+Based on PRD content, identify related modules and read:
+```
+speccrew-workspace/knowledges/bizs/{module-name}/{module-name}-overview.md
+```
+
+### 2.2b Discover Frontend Platforms
+
+Read `speccrew-workspace/knowledges/techs/techs-manifest.json` to identify frontend platforms:
+
+| Platform Type | Examples |
+|---------------|----------|
+| `web-*` | web-vue, web-react |
+| `mobile-*` | mobile-uniapp, mobile-flutter |
+
+- If `frontend_platforms` parameter provided, use that list
+- Otherwise, read techs-manifest.json directly
+
+### 2.3 Query Knowledge Graph (Optional)
+
+If cross-module relationships need analysis, use `speccrew-knowledge-graph-query` skill.
+
+## Step 3: Function Breakdown
+
+Break down PRD functional requirements into implementable system functions.
+
+### 3.1 Feature-Based Decomposition (when feature_id provided)
+
+When processing a single Feature:
+
+1. **Extract Feature Scope**: From PRD Section 3.4, locate the specific Feature by `feature_id`
+2. **Identify Related User Stories**: Extract only user stories mapped to this Feature
+3. **Decompose into Functions**: Break down into 3-8 focused Functions
+4. **Check feature_type**: Mark `API-only` for backend-only design
+
+### 3.2 Full PRD Decomposition (backward compatibility)
+
+When `feature_id` is NOT provided (legacy mode):
+- Decompose entire PRD into all required Functions
+- May result in 10-20 Functions for complex modules
+
+### 3.3 Function Analysis
+
+For each function, identify:
+
+| Aspect | Analysis Content |
+|--------|------------------|
+| **Frontend Changes** | New pages, components, or modifications to existing UI |
+| **Backend Changes** | New interfaces or modifications to existing logic |
+| **Data Changes** | New data structures or modifications to existing data |
+| **System Relationship** | How this relates to existing system capabilities |
+
+### Mark Relationship to Existing System
+
+| Marker | Meaning | Example |
+|--------|---------|---------|
+| `[EXISTING]` | Reuse current system capability | `[EXISTING] User authentication system` |
+| `[MODIFIED]` | Enhance/change existing feature | `[MODIFIED] Add validation to user profile form` |
+| `[NEW]` | Create brand new functionality | `[NEW] Order management module` |
+
+### Checkpoint A: Present Function Breakdown for Confirmation
+
+**Conditional Execution:** If `skip_checkpoint=true`, skip user confirmation and proceed to Step 4.
+
+If `skip_checkpoint=false` (default):
+1. Present function breakdown with [EXISTING]/[MODIFIED]/[NEW] markers to user
+2. Ask: "Does this function breakdown align with your understanding of the requirements?"
+3. **HARD STOP** — Wait for user confirmation before proceeding
+
+### Checkpoint A Progress Update
+
+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 \
+  --checkpoint function_decomposition \
+  --passed true
+```
+
+Log: "✅ Checkpoint A (function_decomposition) passed and recorded"
+
+## Step 4: Write Output Contract
+
+Write analysis results to `.feature-analysis.md`:
+
+### Output Path
+
+| Mode | Output Path |
+|------|-------------|
+| With feature_id | `{prd_parent}/02.feature-design/{feature-id}-{feature-name}.feature-analysis.md` |
+| Legacy mode | `{prd_parent}/02.feature-design/.feature-analysis.md` |
+
+### Output Structure
+
+```markdown
+# Feature Analysis: {feature-name}
+
+## Feature Information
+- Feature ID: {feature_id}
+- Feature Name: {feature_name}
+- Feature Type: {feature_type}
+- Source PRD: {prd_path}
+
+## System Context Summary
+[System knowledge and module overviews summary]
+
+## Frontend Platforms
+[List from techs-manifest.json]
+
+## Function Breakdown (Total: {N} functions)
+
+| # | Function Name | Type | Related User Stories | System Relationship |
+|---|--------------|------|---------------------|---------------------|
+| 1 | {name} | {frontend/backend/both} | {story refs} | [EXISTING]/[MODIFIED]/[NEW] |
+
+## Function Details
+### F1: {function-name}
+- **Frontend Changes**: {description or N/A}
+- **Backend Changes**: {description}
+- **Data Changes**: {description}
+- **System Relationship**: [EXISTING]/[MODIFIED]/[NEW] — {explanation}
+
+## Decomposition Status
+- Checkpoint A: {passed/pending}
+- Confirmed at: {timestamp or null}
+```
+
+---
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **Analysis Only** | Do NOT design UI wireframes, API specs, or data models |
+| **Clear Markers** | Always use [EXISTING]/[MODIFIED]/[NEW] to indicate system relationship |
+| **Checkpoint A Required** | User confirmation required before design phase (unless skipped) |
+| **Use Script for JSON** | Always use `update-progress.js` for checkpoint files |
+| **Output Contract** | `.feature-analysis.md` serves as interface for downstream design skills |
+
+# Checklist
+
+- [ ] PRD has been read, all P0 requirements covered
+- [ ] **[Single Feature Mode]** Feature ID and name parameters received
+- [ ] **[Single Feature Mode]** Only related Feature content extracted from PRD
+- [ ] **[Legacy Mode]** All sub PRDs have been read (if master-sub structure)
+- [ ] System overview loaded for context
+- [ ] Related module overviews loaded
+- [ ] **[Cross-module]** Knowledge graph queried for relationship analysis
+- [ ] Function breakdown completed with [EXISTING]/[MODIFIED]/[NEW] markers
+- [ ] **[Single Feature Mode]** 3-8 focused Functions defined
+- [ ] Checkpoint A passed: function breakdown confirmed with user (or skipped)
+- [ ] `.checkpoints.json` updated via script
+- [ ] `.feature-analysis.md` written to correct path