speccrew 0.3.8 → 0.3.10

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

@@ -48,7 +48,14 @@ Before starting work, check the workflow progress state:
    - If `current_stage` is not `01_prd`, this iteration may already be in progress at a later stage
    - If `01_prd.status` is `confirmed`, check resume state (Step 0.2)
 3. **If WORKFLOW-PROGRESS.json does not exist**:
-   - Create initial WORKFLOW-PROGRESS.json in the iteration directory:
+   - **MUST use script to initialize:**
+     ```bash
+     node speccrew-workspace/scripts/update-progress.js init-workflow \
+       --file speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json \
+       --iteration {iteration}
+     ```
+   - **Fallback** (ONLY if script file does not exist):
+     Create manually with the following structure:
      ```json
      {
        "iteration": "{iteration-name}",
@@ -248,8 +255,28 @@ Pass the following context to the Skill:
 - Clarification Q&A records (if any)
 - Complexity routing decision (simple|complex)
 
+### After Skill Completes
+
+When the invoked skill returns:
+
+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**
+
+> ⚠️ **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 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`.
+> 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.
+
 ## Phase 4: Sub-PRD Worker Dispatch (Master-Sub Structure Only)
 
 **IF the Skill output includes a Sub-PRD Dispatch Plan (from Step 12c), execute this phase.**
@@ -269,17 +296,19 @@ From the Skill's Step 12c output, collect:
   - `module_user_stories`, `module_requirements`, `module_features`
   - `module_dependencies`
 
-### 4.2 Initialize Dispatch Progress Tracking
-
-Before dispatching workers, initialize `DISPATCH-PROGRESS.json`:
+### 4.1b Initialize Dispatch Progress Tracking
 
+**MANDATORY: Initialize dispatch tracking with script:**
 ```bash
 node speccrew-workspace/scripts/update-progress.js init-dispatch \
   --file speccrew-workspace/iterations/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
-  --tasks "module-1,module-2,module-3,..."
+  --tasks "module-key-1,module-key-2,module-key-3,..."
 ```
 
-After each worker completes, update its status:
+> ⚠️ 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.
+
+After each worker completes:
 ```bash
 node speccrew-workspace/scripts/update-progress.js update-task \
   --file speccrew-workspace/iterations/{iteration}/01.product-requirement/DISPATCH-PROGRESS.json \
@@ -412,13 +441,36 @@ After user confirms (HARD STOP passed), update `.checkpoints.json`:
 
 # Constraints
 
-⚠️ **MANDATORY CLARIFICATION RULE**:
-- **NEVER skip requirement clarification entirely**
-- **Even with complete requirement documents, perform at least 1 confirmation round**
-- **Document all clarification in progress tracking**
-- **If user rushes to skip, explain risks and still confirm critical points**
+### MANDATORY Phase Execution Order
+
+Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 (if complex) → Phase 5
+
+> ⚠️ Phases MUST execute in order. DO NOT skip any phase.
+> Phase 4 is MANDATORY for complex requirements (3+ modules).
+
+### MANDATORY CLARIFICATION RULE
+
+- **NEVER skip requirement clarification** regardless of input quality
+- **NEVER proceed to PRD generation without .clarification-summary.md**
+- **NEVER assume requirement completeness** — always verify with at least 1 round
+
+### MANDATORY WORKER DISPATCH RULE
+
+- **For complex requirements (3+ modules): Phase 4 is MANDATORY**
+- **MUST dispatch `speccrew-task-worker` with `speccrew-pm-sub-prd-generate/SKILL.md` for each Sub-PRD**
+- **DO NOT generate Sub-PRDs yourself** — you are the orchestrator, not the writer
+- **MUST use `update-progress.js` for all progress file operations** — DO NOT create JSON files manually
+
+### MANDATORY TEMPLATE PATH
+
+- **PRD Template**: Search with glob `**/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md`
+- **BIZS Modeling Template**: Search with glob `**/speccrew-pm-requirement-analysis/templates/BIZS-MODELING-TEMPLATE.md`
+- **Sub-PRD Template**: The Sub-PRD worker skill (`speccrew-pm-sub-prd-generate/SKILL.md`) receives template_path as parameter — pass the found PRD template path to the worker
+- **DO NOT search for templates in bizs/, knowledges/, project source, or other unrelated directories**
+- **DO NOT try to find templates by listing all .md files in the project**
+- **Templates are ALWAYS in the skill's own `templates/` subfolder**, accessed via glob pattern
 
-**Must do:**
+### 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 review and confirmation after PRD completion
@@ -427,10 +479,12 @@ After user confirms (HARD STOP passed), update `.checkpoints.json`:
 - Perform Complexity Assessment & Skill Routing at Phase 1 to determine simple vs complex workflow
 - For complex requirements (3+ modules), dispatch Sub-PRD generation to parallel workers using `speccrew-pm-sub-prd-generate/SKILL.md`
 
-**Must not do:**
+### 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.
+- Do not create WORKFLOW-PROGRESS.json or DISPATCH-PROGRESS.json manually when the script is available
+- Do not search for PRD templates outside the skill's templates/ directory
 

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

@@ -50,13 +50,22 @@ This skill applies the ISA-95 six-stage methodology (Stages 1-3) as an internal
 
 ⚠️ **MANDATORY: This step CANNOT be skipped.**
 
-```
-IF user provided a complete requirement document:
-  → Perform at least 1 confirmation round (verify understanding, scope, priorities)
-  → Generate clarification summary
-IF user provided incomplete input:
-  → Perform full progressive clarification (Round 1 → Round 2 → optional Round 3)
-```
+**ABORT CONDITIONS — If ANY of these apply, workflow MUST STOP:**
+- `.clarification-summary.md` file was not generated
+- Sufficiency Checks are not ALL marked as ✅
+- No Q&A round was conducted with the user
+
+**DO NOT proceed to Step 2 without completing this step.**
+
+**MANDATORY CLARIFICATION LOGIC:**
+- ALWAYS perform at least 1 clarification round, REGARDLESS of input completeness
+- NEVER skip clarification based on user urgency or perceived completeness
+- COMPLETE ALL Sufficiency Checks before proceeding
+
+**Clarification Depth:**
+- User provided complete requirement document → Minimum 1 confirmation round to verify understanding
+- User provided incomplete input → Minimum 2 rounds (Core scope + Boundaries), 3rd round if needed
+- User says "skip clarification" → REFUSE. Explain: "Clarification ensures PRD quality and cannot be skipped."
 
 Use progressive questioning to clarify requirements. Do NOT ask all questions at once.
 
@@ -145,21 +154,21 @@ Path: speccrew-workspace/iterations/{iteration}/01.product-requirement/.clarific
 
 ### Proceed Gate to Step 2
 
-**Before proceeding to Step 2, verify BOTH conditions:**
+⚠️ **HARD STOP — Proceed Gate:**
 
-```
-□ All Sufficiency Check items marked as ✅
-□ .clarification-summary.md file exists and is complete
+**ABORT if ANY condition is missing:**
+- [ ] `.clarification-summary.md` file MUST exist with complete content
+- [ ] ALL 4 Sufficiency Checks MUST be marked as ✅
+- [ ] At least 1 confirmed round of clarification Q&A
+- [ ] Key Decisions section MUST be filled
 
-IF both conditions met → Proceed to Step 2
-IF any condition fails → STOP and complete the missing items
-```
+**IF ANY condition fails:**
+→ REFUSE to proceed to Step 2
+→ Continue clarification until ALL conditions pass
 
-After clarification is confirmed sufficient, write initial `.checkpoints.json`:
+**ONLY after ALL conditions verified → Proceed to Step 2**
 
-```bash
-# Create or update checkpoint file
-```
+After clarification is confirmed sufficient, write initial `.checkpoints.json`:
 
 Write the following structure to `speccrew-workspace/iterations/{iteration}/01.product-requirement/.checkpoints.json`:
 
@@ -362,10 +371,24 @@ Phase 3 (Extension): Remaining modules
 
 ## Step 7: Read PRD Template
 
-Read the template file:
-```
-speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md
-```
+**Locate and read the PRD template file using this search strategy:**
+
+1. **Search** for the template using glob pattern:
+   ```
+   **/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md
+   ```
+   This will find the template regardless of IDE adapter path (.qoder/, .claude/, .cursor/, .speccrew/).
+
+2. **Read** the found template file.
+
+3. **If BIZS modeling template is needed** (for complex systems with 3+ modules):
+   ```
+   **/speccrew-pm-requirement-analysis/templates/BIZS-MODELING-TEMPLATE.md
+   ```
+
+> ⚠️ **DO NOT manually search in these directories:** bizs/, knowledges/, workspace docs, project src/
+> The template is ALWAYS located in the skill's own `templates/` subfolder.
+> If glob returns no results, check if speccrew was properly initialized (`speccrew init`).
 
 After reading the template, check if any required information is missing based on:
 - Template structure requirements
@@ -629,8 +652,11 @@ Total files: 1 (Master) + N (Sub-PRDs) = N+1 files.
 
 **IF Step 8 determined Master-Sub structure:**
 
-⚠️ **IMPORTANT: Sub-PRD generation is handled by the PM Agent through parallel worker dispatch.**
-**DO NOT generate Sub-PRD files sequentially in this skill.**
+⚠️ **CRITICAL — Sub-PRD Generation Rules:**
+
+1. **DO NOT generate Sub-PRD files in this Skill** — this Skill outputs the dispatch plan ONLY
+2. **DO NOT skip Sub-PRD generation** — If modules > 1, Sub-PRDs are REQUIRED
+3. **This Skill MUST RETURN control to PM Agent for Phase 4 execution**
 
 Prepare and output the dispatch plan for the PM Agent:
 
@@ -657,11 +683,18 @@ For each module, collect and output the following context data:
 After outputting the dispatch plan:
 
 ```
-→ 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.
+→ **MANDATORY: RETURN to PM Agent Phase 4 (Sub-PRD Worker Dispatch)**
+→ PM Agent MUST invoke speccrew-task-worker for each module
+→ Each worker uses speccrew-pm-sub-prd-generate/SKILL.md
+→ All workers execute in parallel
+→ After ALL workers complete → PM Agent executes Phase 5 Verification
 ```
 
+**IF PM Agent skips Phase 4:**
+- Sub-PRDs will NOT be generated
+- Master PRD alone is INCOMPLETE for Feature Design stage
+- Entire PRD stage must be redone
+
 **IF Single PRD Structure:** Skip this step (no Sub-PRDs needed).
 
 ---

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

@@ -80,9 +80,19 @@ node speccrew-workspace/scripts/update-progress.js update-workflow \
 
 ### Step 3: Read PRD Template
 
-Read: `speccrew-workspace/docs/templates/PRD-TEMPLATE.md`
+**Locate and read the PRD template:**
 
-If not found, check: `.speccrew/skills/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md`
+1. **Search** for the template using glob pattern:
+   ```
+   **/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md
+   ```
+   > Note: Simple requirement skill shares the PRD template with the complex requirement skill.
+
+2. **Read** the found template file.
+
+> ⚠️ **DO NOT search in bizs/, knowledges/, or project source directories.**
+> The template is ALWAYS located in the skill's own `templates/` subfolder.
+> If glob returns no results, check if speccrew was properly initialized (`speccrew init`).
 
 ### Step 4: Generate Single PRD
 

package/package.json

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