speccrew 0.3.11 → 0.3.13

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

@@ -50,9 +50,9 @@ Before starting work, check the workflow progress state:
 3. **If WORKFLOW-PROGRESS.json does not exist**:
    - **MUST use script to initialize:**
      ```bash
-     node speccrew-workspace/scripts/update-progress.js init-workflow \
+     node speccrew-workspace/scripts/update-progress.js update-workflow \
        --file speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json \
-       --iteration {iteration}
+       --stage 01_prd --status in_progress
      ```
    - **Fallback** (ONLY if script file does not exist):
      Create manually with the following structure:
@@ -241,6 +241,13 @@ complexity_notes: <if complex, note affected modules>
 
 ## Phase 3: Invoke Skill
 
+> ⚠️ **PM AGENT ORCHESTRATION PRINCIPLE (Phase 3-5)**
+> You are the ORCHESTRATOR, NOT the WRITER:
+> - Phase 3: DO NOT generate Master PRD yourself → Skill generates it
+> - Phase 4: DO NOT generate Sub-PRD yourself → Workers generate them
+> - Phase 5: DO NOT modify PRD content yourself → Only verify and present
+> - **If Skill fails: STOP and report error to user. DO NOT generate content as fallback.**
+
 Based on the complexity assessment in Phase 1, invoke the appropriate skill:
 
 **For Simple Requirements:**
@@ -257,25 +264,89 @@ Pass the following context to the Skill:
 
 ### After Skill Completes
 
-When the invoked skill returns:
+**Step A: Check Skill Execution Status**
+
+- IF Skill FAILED or returned error → Go to **Phase 3a: Error Recovery**
+- IF Skill SUCCEEDED → Go to **Phase 3b: Validate & Route**
 
-1. **Check if Master-Sub structure was selected** (from skill Step 8 output)
-2. **If Master-Sub**: Skill will output a Sub-PRD Dispatch Plan → **MANDATORY: Execute Phase 4**
-3. **If Single PRD**: Skill completed the entire PRD → **Skip Phase 4, go to Phase 5**
+### Phase 3a: Error Recovery (Skill Failed)
+
+> ⚠️ **ABORT CONDITIONS — Execution MUST STOP:**
+> - Skill reported execution failure or was interrupted
+> - No PRD document was generated
+> - PRD file exists but is incomplete or malformed
+>
+> **FORBIDDEN ACTIONS:**
+> - DO NOT generate Master PRD as fallback
+> - DO NOT generate Sub-PRDs as fallback
+> - DO NOT create partial PRD documents
+> - DO NOT proceed to Phase 4 or Phase 5
+
+Actions:
+1. Report error to user: "Skill execution failed: [specific reason]"
+2. Ask user: "Retry with additional clarification?" or "Abort current workflow?"
+3. IF retry → Return to Phase 2, gather more context, then retry Phase 3
+4. IF abort → END workflow
+
+### Phase 3b: Validate & Route (Skill Succeeded)
+
+1. **Identify PRD structure type** (from Skill output):
+   - Master-Sub structure → Validate Dispatch Plan (Step 2)
+   - Single PRD → Skip to Phase 5
+
+2. **Validate Dispatch Plan (Master-Sub only)**:
+   - [ ] Master PRD file exists and is readable
+   - [ ] Dispatch Plan contains module list (count ≥ 2)
+   - [ ] Each module has: module_name, module_key, module_scope, module_entities
+   - [ ] template_path and output_dir are defined
+   
+   IF ANY validation fails:
+   → STOP. Report: "Dispatch Plan incomplete: [missing items]"
+   → Ask user to retry Skill execution
+   → DO NOT proceed to Phase 4
+
+3. **Route**:
+   - Master-Sub + Dispatch Plan valid → **MANDATORY: Execute Phase 4**
+   - Single PRD → **Skip Phase 4, go to Phase 5**
 
 > ⚠️ **DO NOT present results to user before Phase 4 completes (for complex requirements).**
 > The Master PRD alone is incomplete without Sub-PRDs.
 
 ---
 
+> ⚠️ **MANDATORY RULES FOR PHASE 3:**
+> 1. DO NOT generate Master PRD yourself — it MUST be generated by Skill
+> 2. DO NOT generate any PRD content as fallback if Skill fails
+> 3. DO NOT skip Skill failure validation
+> 4. MUST validate Dispatch Plan completeness before entering Phase 4
+>
+> **ABORT CONDITIONS:**
+> - IF Skill execution failed → STOP and report to user
+> - IF PRD output is missing or incomplete → STOP and report to user
+> - IF PM Agent attempts to generate PRD content itself → STOP (ORCHESTRATOR ONLY)
+
+---
+
 > ⚠️ **MANDATORY RULES FOR PHASE 4 (Sub-PRD Worker Dispatch):**
 > These rules apply to ALL complex requirements (3+ modules). Violation = workflow failure.
 >
 > 1. **DO NOT skip Phase 4 when Master-Sub structure is present** — If the Skill output indicates "Master-Sub PRD structure", Phase 4 MUST execute.
 > 2. **DO NOT generate Sub-PRDs yourself** — Each Sub-PRD MUST be generated by invoking `speccrew-task-worker` with `speccrew-pm-sub-prd-generate/SKILL.md`. You are the orchestrator, NOT the writer.
-> 3. **DO NOT create DISPATCH-PROGRESS.json manually** — Use the script: `node speccrew-workspace/scripts/update-progress.js init-dispatch`.
+> 3. **DO NOT create DISPATCH-PROGRESS.json manually** — Use the script: `node speccrew-workspace/scripts/update-progress.js init --stage sub_prd_dispatch --tasks '<JSON_ARRAY>'`.
 > 4. **DO NOT dispatch Sub-PRDs sequentially** — All workers MUST execute in parallel (batch of 6 if modules > 6).
 > 5. **DO NOT proceed to Phase 5 without verification** — After ALL workers complete, execute Phase 5 Verification Checklist before presenting to user.
+>
+> **ABORT CONDITIONS for Phase 4:**
+> - IF Dispatch Plan was not generated by Skill → STOP and return to Skill
+> - IF DISPATCH-PROGRESS.json initialization failed → STOP and report error
+> - IF PM Agent attempts to generate Sub-PRD content itself → STOP (you are ORCHESTRATOR, not WRITER)
+>
+> **FORBIDDEN ACTIONS in Phase 4:**
+> - DO NOT ask user to select which modules to generate first
+> - DO NOT ask user to provide or select templates (template path comes from Skill output)
+> - DO NOT offer strategy choices (generate all / generate 3 first / pick priority)
+> - DO NOT generate any Sub-PRD document content directly
+> - JUST DISPATCH ALL WORKERS AND WAIT FOR COMPLETION
 
 ## Phase 4: Sub-PRD Worker Dispatch (Master-Sub Structure Only)
 
@@ -300,11 +371,18 @@ From the Skill's Step 12c output, collect:
 
 **MANDATORY: Initialize dispatch tracking with script:**
 ```bash
-node speccrew-workspace/scripts/update-progress.js init-dispatch \
+node speccrew-workspace/scripts/update-progress.js init \
   --file speccrew-workspace/iterations/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
-  --tasks "module-key-1,module-key-2,module-key-3,..."
+  --stage sub_prd_dispatch \
+  --tasks '[{"id":"module-key-1","name":"Module 1 Name"},{"id":"module-key-2","name":"Module 2 Name"}]'
 ```
 
+> **PowerShell Compatibility Note:**
+> PowerShell cannot properly parse JSON in command-line arguments. Use file-based approach:
+> 1. Write tasks JSON to a temporary file (e.g., `tasks-temp.json`)
+> 2. Read file content in the command: `node scripts/update-progress.js init --stage sub_prd_dispatch --tasks (Get-Content tasks-temp.json -Raw)`
+> 3. Or use: `Get-Content tasks-temp.json | node scripts/update-progress.js init --stage sub_prd_dispatch --tasks -`
+
 > ⚠️ DO NOT create DISPATCH-PROGRESS.json manually with PowerShell or any other method.
 > If the script fails, STOP and report the error to the user.
 
@@ -324,7 +402,24 @@ node speccrew-workspace/scripts/update-progress.js update-task \
 
 ### 4.3 Dispatch Workers
 
-Invoke `speccrew-task-worker` agents in parallel, one per module:
+**PM Agent Role: ORCHESTRATOR ONLY**
+
+You are the dispatcher, NOT the writer. Your job is to:
+1. Invoke `speccrew-task-worker` for EACH module
+2. Pass the correct skill_path and context
+3. Wait for all workers to complete
+4. Collect results
+
+**Implementation:**
+
+For EACH module in the dispatch plan, invoke a new `speccrew-task-worker` agent:
+- **skill_path**: Search with glob `**/speccrew-pm-sub-prd-generate/SKILL.md`
+- **context**: 
+  - `module_name`: from dispatch plan
+  - `module_key`: from dispatch plan
+  - `master_prd_path`: path to Master PRD
+  - `template_path`: PRD template path (from Step 7 glob search result)
+  - `output_dir`: `speccrew-workspace/iterations/{iteration}/01.product-requirement/`
 
 Each worker receives:
 - `skill_path`: `speccrew-pm-sub-prd-generate/SKILL.md`
@@ -342,6 +437,10 @@ Each worker receives:
   - `template_path`: Path to PRD-TEMPLATE.md
   - `output_path`: `{output_dir}/{feature_name}-sub-{module_key}.md`
 
+**Batch Strategy:**
+- If modules ≤ 6: dispatch ALL in parallel
+- If modules > 6: dispatch in batches of 6, wait for batch completion before next batch
+
 **Parallel execution pattern:**
 ```
 Worker 1: Module "customer"     → crm-system-sub-customer.md
@@ -351,7 +450,12 @@ 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.
+**All workers execute simultaneously (or in batches).** Wait for all workers to complete before proceeding.
+
+**Before proceeding to Phase 5, verify:**
+- [ ] All workers were dispatched via speccrew-task-worker
+- [ ] No Sub-PRD was generated by PM Agent directly
+- [ ] All workers completed (check DISPATCH-PROGRESS.json)
 
 ### 4.4 Collect Results
 
@@ -435,9 +539,9 @@ After user confirms (HARD STOP passed), update `.checkpoints.json`:
 
 | 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 |
+| PRD Document | `speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/[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.product-requirement/[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.product-requirement/[feature-name]-sub-[module].md` | One per module, generated by worker dispatch |
 
 # Constraints
 

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

@@ -663,17 +663,17 @@ Before writing any file, create a complete list of ALL files to generate:
 
 | # | File | Path |
 |---|------|------|
-| 1 | PRD | {iteration}/01.prd/{feature-name}-prd.md |
+| 1 | PRD | {iteration}/01.product-requirement/{feature-name}-prd.md |
 
 **For Master-Sub Structure (present this table to user):**
 
 | # | 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 |
+| 1 | Master PRD | (system overview) | {iteration}/01.product-requirement/{feature-name}-prd.md |
+| 2 | Sub-PRD | {module-1-name} | {iteration}/01.product-requirement/{feature-name}-sub-{module-1-key}.md |
+| 3 | Sub-PRD | {module-2-name} | {iteration}/01.product-requirement/{feature-name}-sub-{module-2-key}.md |
 | ... | ... | ... | ... |
-| N+1 | Sub-PRD | {module-N-name} | {iteration}/01.prd/{feature-name}-sub-{module-N-key}.md |
+| N+1 | Sub-PRD | {module-N-name} | {iteration}/01.product-requirement/{feature-name}-sub-{module-N-key}.md |
 
 Total files: 1 (Master) + N (Sub-PRDs) = N+1 files.
 
@@ -684,7 +684,7 @@ Total files: 1 (Master) + N (Sub-PRDs) = N+1 files.
 ### 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`
+2. Create document using `create_file` at: `{iteration}/01.product-requirement/{feature-name}-prd.md`
 
 3. Fill content using `search_replace` per section:
 

package/package.json

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