speccrew 0.3.1 → 0.3.2

package/.speccrew/agents/speccrew-product-manager.md

@@ -175,12 +175,114 @@ Pass the following context to the Skill:
 - Pre-skill assessment results (clarification_status, expected_complexity, etc.)
 - Clarification Q&A records (if any)
 
+---
+
+## Phase 3: Sub-PRD Worker Dispatch (Master-Sub Structure Only)
+
+**IF the Skill output includes a Sub-PRD Dispatch Plan (from Step 12c), execute this phase.**
+**IF Single PRD structure, skip to Phase 4.**
+
+After the Skill generates the Master PRD and outputs the dispatch plan, the PM Agent takes over to generate Sub-PRDs in parallel using worker agents.
+
+### 3.1 Read Dispatch Plan
+
+From the Skill's Step 12c output, collect:
+- `feature_name`: System-level feature name
+- `template_path`: Path to PRD-TEMPLATE.md
+- `master_prd_path`: Path to the generated Master PRD
+- `output_dir`: Directory for Sub-PRD files (same as Master PRD directory)
+- Module list with context for each module:
+  - `module_name`, `module_key`, `module_scope`, `module_entities`
+  - `module_user_stories`, `module_requirements`, `module_features`
+  - `module_dependencies`
+
+### 3.2 Dispatch Workers
+
+Invoke `speccrew-task-worker` agents in parallel, one per module:
+
+Each worker receives:
+- `skill_path`: `speccrew-pm-sub-prd-generate/SKILL.md`
+- `context`:
+  - `module_name`: Module name (e.g., "Customer Management")
+  - `module_key`: Module identifier for file naming (e.g., "customer")
+  - `module_scope`: What this module covers
+  - `module_entities`: Core business entities
+  - `module_user_stories`: Module-specific user stories
+  - `module_requirements`: Module-specific functional requirements (P0/P1/P2)
+  - `module_features`: Feature Breakdown entries for this module
+  - `module_dependencies`: Dependencies on other modules
+  - `master_prd_path`: Path to the Master PRD
+  - `feature_name`: System-level feature name
+  - `template_path`: Path to PRD-TEMPLATE.md
+  - `output_path`: `{output_dir}/{feature_name}-sub-{module_key}.md`
+
+**Parallel execution pattern:**
+```
+Worker 1: Module "customer"     → crm-system-sub-customer.md
+Worker 2: Module "contact"      → crm-system-sub-contact.md
+Worker 3: Module "opportunity"  → crm-system-sub-opportunity.md
+...
+Worker N: Module "{module-N}"   → crm-system-sub-{module-N}.md
+```
+
+**All workers execute simultaneously.** Wait for all workers to complete before proceeding.
+
+### 3.3 Collect Results
+
+After all workers complete:
+
+1. **Check worker results**: Verify each worker reported success
+2. **List generated files**:
+   ```
+   📊 Sub-PRD Generation Results:
+   ├── Worker 1: {module-1} → ✅ Generated ({file_size})
+   ├── Worker 2: {module-2} → ✅ Generated ({file_size})
+   ├── Worker N: {module-N} → ✅ Generated ({file_size})
+   │
+   Total: N workers | Completed: X | Failed: Y
+   ```
+
+3. **Handle failures**: If any worker failed:
+   - Report which modules failed and why
+   - Re-dispatch failed modules (retry once)
+   - If retry fails, report to user for manual intervention
+
+---
+
+## Phase 4: Verification & Confirmation
+
+### 4.1 Execute Verification Checklist
+
+Return to the Skill's Step 12d for verification:
+- Verify Master PRD exists and size > 2KB
+- Verify all Sub-PRD files exist and each size > 3KB
+- Verify Master PRD Sub-PRD Index matches actual files
+- Verify each Sub-PRD contains Feature Breakdown (Section 3.4)
+
+### 4.2 Request User Confirmation
+
+Execute Skill's Step 12e to present summary and request user review.
+
+### 4.3 Finalize PRD Stage (After User Confirmation)
+
+After user confirms the PRD documents are correct:
+
+1. Execute Skill's Step 13 to write progress files (update WORKFLOW-PROGRESS.json, set `01_prd.status` = `confirmed`)
+2. Update all PRD document status lines from `📝 Draft` to `✅ Confirmed` with confirmation date using `search_replace`
+3. Output completion message:
+   ```
+   ✅ PRD documents have been confirmed. PRD stage is complete.
+   When you are ready to proceed with Feature Design, please start a new conversation and invoke the Feature Designer Agent.
+   ```
+4. **END** — Do not proceed further. Do not invoke or suggest transitioning to the next stage agent.
+
 # Deliverables
 
 | Deliverable | Path | Notes |
 |-------------|------|-------|
 | PRD Document | `speccrew-workspace/iterations/{number}-{type}-{name}/01.prd/[feature-name]-prd.md` | Based on template from `speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md` |
 | Business Modeling (complex) | `speccrew-workspace/iterations/{number}-{type}-{name}/01.prd/[feature-name]-bizs-modeling.md` | ISA-95 six-stage modeling, only for complex requirements |
+| Sub-PRD Documents (complex) | `speccrew-workspace/iterations/{number}-{type}-{name}/01.prd/[feature-name]-sub-[module].md` | One per module, generated by worker dispatch |
 
 # Constraints
 
@@ -193,13 +295,15 @@ Pass the following context to the Skill:
 **Must do:**
 - Read business module list to confirm boundaries between requirements and existing features
 - Use templates from `speccrew-pm-requirement-analysis/templates/`
-- Explicitly prompt user for confirmation after PRD completion, only transition to speccrew-planner after confirmation
+- Explicitly prompt user for review and confirmation after PRD completion
 - Execute Pre-Skill Requirement Assessment before invoking the Skill
 - Pass clarification context and complexity assessment to the Skill
+- For complex requirements (2+ modules), dispatch Sub-PRD generation to parallel workers using `speccrew-pm-sub-prd-generate/SKILL.md`
 
 **Must not do:**
 - Do not make technical solution decisions (that's speccrew-planner's responsibility)
 - Do not skip manual confirmation to directly start the next stage
 - Do not assume business rules on your own; clarify unclear requirements with the user
 - Do not skip the clarification process, even when user provides detailed documents
+- Do not automatically transition to or invoke the next stage agent (Feature Designer). The user will start the next stage in a new conversation window.
 

package/.speccrew/skills/speccrew-pm-requirement-analysis/SKILL.md

@@ -484,147 +484,158 @@ speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/
 
 If the iteration directory does not exist, refer to the `000-sample` directory structure to create it.
 
-## Step 12: Write Files Using Template-Fill Workflow
+## Step 12: Write PRD Files
 
-⚠️ **CRITICAL: For Master-Sub structure, you MUST generate ALL Sub-PRD files.**
-- **DO NOT put all module content into the Master PRD.**
-- **Each Sub-PRD is a SEPARATE file containing ONLY that module's requirements.**
+### Step 12a: Plan File List (MANDATORY FIRST STEP)
 
----
+Before writing any file, create a complete list of ALL files to generate:
+
+**For Single PRD Structure:**
+
+| # | File | Path |
+|---|------|------|
+| 1 | PRD | {iteration}/01.prd/{feature-name}-prd.md |
+
+**For Master-Sub Structure (present this table to user):**
 
-### Step 12a: Generate Master PRD
+| # | File Type | Module | Path |
+|---|-----------|--------|------|
+| 1 | Master PRD | (system overview) | {iteration}/01.prd/{feature-name}-prd.md |
+| 2 | Sub-PRD | {module-1-name} | {iteration}/01.prd/{feature-name}-sub-{module-1-key}.md |
+| 3 | Sub-PRD | {module-2-name} | {iteration}/01.prd/{feature-name}-sub-{module-2-key}.md |
+| ... | ... | ... | ... |
+| N+1 | Sub-PRD | {module-N-name} | {iteration}/01.prd/{feature-name}-sub-{module-N-key}.md |
 
-**For BOTH Single and Master-Sub structures:**
+Total files: 1 (Master) + N (Sub-PRDs) = N+1 files.
 
-1. **Copy template to document path:**
-   - Read `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
-   - Replace top-level placeholders (feature name, iteration, date)
-   - Create document using `create_file` at: `{iteration}/01.product-requirement/{feature-name}-prd.md`
+⚠️ **Present this file list to user for confirmation before proceeding.**
 
-2. **Fill Master-only content using `search_replace`:**
-   - Section 1: Overall background, goals, success metrics
-   - Section 2: System architecture overview (Mermaid graph TB)
-   - Section 3: Module list with scope boundaries (from Step 6.1)
-   - Section 4: Cross-module dependency matrix (from Step 6.2)
-   - Section 5: Implementation phases and ordering (from Step 6.3)
-   - Section 6: Shared entities and data contracts
-   - Section 7: Global non-functional requirements
+---
 
-3. **DO NOT include module-specific content in Master:**
-   - No module-specific user stories
-   - No module-specific functional requirements
-   - No module-specific Feature Breakdown tables
+### Step 12b: Generate Master PRD
+
+1. Read `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
+2. Create document using `create_file` at: `{iteration}/01.prd/{feature-name}-prd.md`
+
+3. Fill content using `search_replace` per section:
+
+**For Single PRD Structure** — fill ALL sections with full detail:
+   - Section 1 (Background & Goals): Full background, goals
+   - Section 2 (User Stories): All user stories with scenarios
+   - Section 3 (Functional Requirements): All requirements including Feature Breakdown (3.4)
+   - Section 4 (Non-functional Requirements): Performance, security, etc.
+   - Section 5 (Acceptance Criteria): All criteria
+   - Section 6 (Boundary Description): In/out scope
+   - Section 7 (Assumptions & Dependencies)
+
+**For Master-Sub Structure** — fill ONLY system-level overview content:
+   - Section 1 (Background & Goals): System-wide background and goals
+   - Section 2 (User Stories): **HIGH-LEVEL system user stories ONLY** (e.g., "As a store manager, I want a CRM system to manage customer relationships"). DO NOT include module-specific user stories.
+   - Section 3 (Functional Requirements):
+     - 3.1 Use Case Diagram: System-level use case diagram showing all modules
+     - 3.2 Business Process Flow: Cross-module process flow overview
+     - 3.3 Feature List: Module-level feature summary table (NOT detailed features)
+     - 3.4 Feature Breakdown: Write "See individual Sub-PRDs for module-specific Feature Breakdown"
+     - 3.5 Feature Details: Write "See individual Sub-PRDs for module-specific Feature Details"
+   - Section 4 (Non-functional Requirements): System-wide NFRs only
+   - Section 5 (Acceptance Criteria): System-wide acceptance criteria only
+   - Section 6 (Boundary Description): System-wide scope boundaries
+   - Section 7 (Assumptions & Dependencies): System-wide dependencies
+   - **APPEND after Section 7** using `search_replace` on the PRD Status line:
+     - **Section 8: Module Overview** — Module list table (from Step 6.1), Cross-module dependency matrix (from Step 6.2), Implementation phases (from Step 6.3)
+     - **Section 9: Sub-PRD Index** — List all Sub-PRD file paths with module names
 
 > ⚠️ **CRITICAL CONSTRAINTS:**
 > - **FORBIDDEN: `create_file` to rewrite the entire document**
 > - **MUST use `search_replace` to fill each section individually**
-> - **All section titles MUST be preserved**
+> - **For Master-Sub: DO NOT include module-specific user stories, requirements, or Feature Breakdowns in the Master PRD**
 
 ---
 
-### Step 12b: Generate Sub-PRDs (LOOP - MANDATORY for Master-Sub)
+### Step 12c: Sub-PRD Dispatch Plan (MANDATORY for Master-Sub)
 
-**IF Step 8 determined Master-Sub structure, execute this loop:**
+**IF Step 8 determined Master-Sub structure:**
 
-```
-FOR each module in module_list from Step 6.1:
-  
-  12b.1: Copy template to sub_prd_path
-    sub_prd_name = "{feature-name}-sub-{module-key}.md"
-    sub_prd_path = "{iteration}/01.product-requirement/{sub_prd_name}"
-    
-    Action:
-    1. Read templates/PRD-TEMPLATE.md
-    2. Replace top-level placeholders
-    3. Create document using create_file at sub_prd_path
+⚠️ **IMPORTANT: Sub-PRD generation is handled by the PM Agent through parallel worker dispatch.**
+**DO NOT generate Sub-PRD files sequentially in this skill.**
 
-  12b.2: Fill module-specific content using search_replace:
-    - Section 1: Module-specific background and context
-    - Section 2: Module-specific user stories
-    - Section 3: Module-specific functional requirements
-    - Section 3.4: Module-specific Feature Breakdown (REQUIRED)
-    - Section 5: Module-specific acceptance criteria
-    - Add: Interface Contracts (from Master dependency matrix)
+Prepare and output the dispatch plan for the PM Agent:
 
-  12b.3: Verify file exists and is non-empty
-    - Read sub_prd_path to confirm file was created
-    - Verify file size > 1KB (not empty placeholder)
+**Sub-PRD Dispatch Plan:**
 
-NEXT module
+For each module from Step 6.1, prepare worker context:
 
-⚠️ STOP condition: All modules in module_list have been processed.
-```
+| # | Module | module_key | Sub-PRD Path | Feature Count |
+|---|--------|-----------|--------------|---------------|
+| 1 | {module-1-name} | {module-1-key} | {feature-name}-sub-{module-1-key}.md | {count} |
+| 2 | {module-2-name} | {module-2-key} | {feature-name}-sub-{module-2-key}.md | {count} |
+| ... | ... | ... | ... | ... |
 
-**Example loop execution:**
-```
-Iteration 1: Process module "inventory"
-  → Create: inventory-management-sub-inventory.md
-  → Fill: inventory-specific content
-  → Verify: file exists and has content
+For each module, collect and output the following context data:
+- `module_name`: Module name
+- `module_key`: Module identifier (for file naming)
+- `module_scope`: What this module covers (from Step 6.1)
+- `module_entities`: Core entities (from Step 6.1)
+- `module_user_stories`: User stories specific to this module (from Steps 1-5 analysis)
+- `module_requirements`: Functional requirements for this module (P0/P1/P2)
+- `module_features`: Feature Breakdown entries for this module (from Step 9.1 analysis)
+- `module_dependencies`: Dependencies on other modules (from Step 6.2)
 
-Iteration 2: Process module "order"
-  → Create: inventory-management-sub-order.md
-  → Fill: order-specific content
-  → Verify: file exists and has content
+After outputting the dispatch plan:
 
-... continue until all modules processed
 ```
+→ RETURN to PM Agent for parallel worker dispatch.
+→ PM Agent will invoke speccrew-task-worker for each module.
+→ Each worker uses speccrew-pm-sub-prd-generate/SKILL.md to generate one Sub-PRD.
+```
+
+**IF Single PRD Structure:** Skip this step (no Sub-PRDs needed).
 
 ---
 
-### Step 12c: Verification Checklist (MANDATORY)
+### Step 12d: Verification Checklist (Execute after all Sub-PRDs are generated)
 
-**After all PRD files are generated, verify:**
+**After PM Agent confirms all workers have completed, verify:**
 
-```
-□ Master PRD exists at {iteration}/01.product-requirement/{feature-name}-prd.md
-□ Master PRD file size > 2KB (not empty placeholder)
+- [ ] Master PRD exists and file size > 2KB
+- [ ] [Master-Sub] All {sub_prd_count} Sub-PRD files exist
+- [ ] [Master-Sub] Each Sub-PRD file size > 3KB
+- [ ] [Master-Sub] Master PRD Section 9 (Sub-PRD Index) matches actual files
+- [ ] [Master-Sub] Each Sub-PRD contains Section 3.4 Feature Breakdown
 
-[For Master-Sub structure ONLY:]
-  □ All {sub_prd_count} Sub-PRD files exist
-  □ Each Sub-PRD file size > 3KB (not empty placeholder)
-  □ Master PRD Section index links match actual Sub-PRD files
-  □ No broken file references
-  □ Each Sub-PRD contains module-specific Feature Breakdown
-
-IF any check fails → STOP and report error, fix before proceeding
-IF all checks pass → Proceed to Step 12d
-```
+IF any check fails → Report error and fix before proceeding.
 
 ---
 
-### Step 12d: Request Confirmation
+### Step 12e: Request Confirmation
 
-After verification passes, show summary and request user confirmation:
+Present summary to user:
 
-**Simple PRD Output:**
+**Single PRD:**
 ```
-PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
+PRD generated: {path}
 ```
 
-**Complex PRD Output (with modeling):**
-```
-Business Modeling generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-bizs-modeling.md
-PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
+**Master-Sub PRD:**
 ```
+Master PRD: {master_path}
+Sub-PRDs ({sub_prd_count} files):
+  1. {module-1}: {sub_prd_1_path}
+  2. {module-2}: {sub_prd_2_path}
+  ...
+  N. {module-N}: {sub_prd_N_path}
 
-**Master-Sub PRD Output:**
-```
-Master PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
-Sub-PRDs generated ({sub_prd_count} files):
-  - [feature-name]-sub-[module1].md
-  - [feature-name]-sub-[module2].md
-  - ...
+Total files generated: {sub_prd_count + 1}
 ```
 
-Please confirm the following key points:
-1. Is the feature boundary accurate?
-2. Are the acceptance criteria quantifiable?
-3. Is the Not In Scope complete?
-4. **[For complex requirements]** Is the Master-Sub structure appropriate?
-5. **[For existing features]** Are the [EXISTING]/[MODIFIED]/[NEW] markers accurate?
+Confirm:
+1. Feature boundary accurate?
+2. Acceptance criteria quantifiable?
+3. Not In Scope complete?
+4. [Master-Sub] Module decomposition appropriate?
+5. [Existing features] EXISTING/MODIFIED/NEW markers accurate?
 
-After confirmation, you can start the Solution Agent for solution planning.
+After user confirms, proceed to Step 13 to write progress files and finalize PRD stage.
 
 ## Step 13: Write Progress Files
 
@@ -657,7 +668,7 @@ Read and update the WORKFLOW-PROGRESS.json file:
 
 1. **Read**: `speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json`
 2. **Update the following fields**:
-   - `current_stage` = "02_feature_design"
+   - `current_stage` = "01_prd" (keep current stage — the next agent will update this when it starts)
    - `01_prd.status` = "confirmed"
    - `01_prd.completed_at` = `<current-ISO-timestamp>`
    - `01_prd.confirmed_at` = `<current-ISO-timestamp>`

package/.speccrew/skills/speccrew-pm-sub-prd-generate/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: speccrew-pm-sub-prd-generate
+description: Generate a single Sub-PRD document for one module. Used by PM Agent's worker dispatch to parallelize Sub-PRD generation across multiple modules. Each worker invocation generates one complete Sub-PRD file based on the PRD template.
+tools: Read, Write, Glob, Grep
+---
+
+# Trigger Scenarios
+
+- PM Agent dispatches worker to generate Sub-PRD for a specific module
+- Worker receives module context from PM Agent's dispatch plan
+
+# Input Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| module_name | Yes | Human-readable module name (e.g., "Customer Management") |
+| module_key | Yes | Module identifier for file naming (e.g., "customer") |
+| module_scope | Yes | What this module covers |
+| module_entities | Yes | Core business entities in this module |
+| module_user_stories | Yes | User stories specific to this module |
+| module_requirements | Yes | Functional requirements for this module (P0/P1/P2) |
+| module_features | Yes | Feature Breakdown entries for this module (Feature IDs, Types, Dependencies) |
+| module_dependencies | No | Dependencies on other modules |
+| master_prd_path | Yes | Path to the Master PRD (for cross-referencing) |
+| feature_name | Yes | System-level feature name (for file naming prefix) |
+| template_path | Yes | Path to PRD-TEMPLATE.md |
+| output_path | Yes | Full path for the Sub-PRD output file |
+
+# Absolute Constraints
+
+> **These rules apply to ALL document generation steps. Violation = task failure.**
+
+1. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire document content in a single operation. Always use targeted `search_replace` on specific sections.
+2. **MANDATORY: Template-first workflow** — Copy template MUST execute before filling sections.
+
+# Workflow
+
+## Step 1: Load Context
+
+1. Read Master PRD at `{master_prd_path}` to understand:
+   - System-wide background and goals
+   - Cross-module dependency matrix
+   - This module's position in the overall system
+
+2. Read PRD template at `{template_path}`
+
+## Step 2: Create Sub-PRD File
+
+1. Copy template content to `{output_path}` using `create_file`
+2. Replace the title: `# PRD - [Feature Name]` → `# Sub-PRD - {module_name}`
+
+## Step 3: Fill Module-Specific Content
+
+Fill each section using `search_replace`:
+
+### 3.1 Section 1: Background & Goals
+- 1.1 Background: Why this module exists within the system, what problem it solves
+- 1.2 Goals: Module-specific business objectives
+
+### 3.2 Section 2: User Stories
+- 2.1 Target Users: Users who interact with this specific module
+- 2.2 User Scenarios: Module-specific user stories in "As a / I want / So that" format
+
+### 3.3 Section 3: Functional Requirements
+- 3.1 Use Case Diagram: Module-specific use case diagram (Mermaid flowchart TB)
+- 3.2 Business Process Flow: Module-internal process flow
+- 3.3 Feature List: Module features with P0/P1/P2 priority
+- 3.4 Feature Breakdown: **REQUIRED** — Fill with `{module_features}` data:
+  - Feature ID, Feature Name, Type (Page+API / API-only), Pages/Endpoints count, Description
+  - Feature Dependencies table
+- 3.5 Feature Details: Detailed descriptions for each feature including:
+  - Requirement Description
+  - Interaction Flow
+  - Boundary Conditions table
+  - Exception Scenarios
+
+### 3.4 Section 4: Non-functional Requirements
+- Module-specific performance, security, compatibility requirements
+- Reference Master PRD for system-wide NFRs
+
+### 3.5 Section 5: Acceptance Criteria
+- 5.1 Must Have: Module-specific acceptance items
+- 5.2 Should Have: Module-specific nice-to-have items
+
+### 3.6 Section 6: Boundary Description
+- 6.1 In Scope: What this module covers
+- 6.2 Out of Scope: What this module explicitly does NOT cover
+
+### 3.7 Section 7: Assumptions & Dependencies
+- Dependencies on other modules (reference Master PRD dependency matrix)
+- External system dependencies
+- Prerequisites
+
+> ⚠️ **FORBIDDEN: `create_file` to rewrite the entire document. MUST use `search_replace` per section.**
+
+## Step 4: Verify Output
+
+1. Read the generated file to verify:
+   - File exists and is non-empty
+   - File size > 3KB (not a placeholder)
+   - Section 3.4 Feature Breakdown is populated
+   - Title contains module name
+
+2. Report result:
+
+```
+IF verification passes:
+  → Output: "✅ Sub-PRD generated: {output_path}"
+IF verification fails:
+  → Output: "❌ Sub-PRD verification failed: {reason}"
+  → Attempt to fix the specific issue
+```

package/package.json

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