speccrew 0.3.10 → 0.3.12

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:
@@ -273,9 +273,21 @@ When the invoked skill returns:
 >
 > 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,9 +312,10 @@ 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"}]'
 ```
 
 > ⚠️ DO NOT create DISPATCH-PROGRESS.json manually with PowerShell or any other method.
@@ -324,7 +337,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 +372,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 +385,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 +474,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

@@ -76,32 +76,122 @@ Use progressive questioning to clarify requirements. Do NOT ask all questions at
 > - **Domain Glossary**: Unify key business terms to eliminate ambiguity across stakeholders.
 > These elements should naturally flow into the clarification summary, NOT as a separate document.
 
-### Round 1: Core Understanding
+### File-Based Clarification Workflow
 
-Ask these first (2-3 questions max per round):
+> ⚠️ **All clarification rounds use file-based interaction, NOT chat-based.**
+> This prevents users from having to copy-paste large amounts of content in chat.
 
-| Question | Purpose |
-|----------|---------|
-| What problem does this feature solve? What is the business context? | Confirm background and motivation |
-| Who are the target users and what are the core usage scenarios? | Identify user scope and mainstream use cases |
+**Round 1: Core Understanding**
 
-### Round 2: Scope & Boundaries
+1. **Create** `.clarification-summary.md` in the iteration's `01.product-requirement/` directory:
+   ```
+   speccrew-workspace/iterations/{iteration}/01.product-requirement/.clarification-summary.md
+   ```
+
+2. **Write** Round 1 questions to the file using this format:
+
+   ```markdown
+   # Requirements Clarification
+
+   ## Round 1: Core Understanding
+   
+   > **Instructions**: Please fill in your answers directly after each "**Answer:**" marker below, then save the file and notify me that you have completed your responses.
+
+   ### 1. Business Background & Goals
+   
+   Based on the requirement document, the system aims to solve:
+   - [PM's understanding point 1]
+   - [PM's understanding point 2]
+   - ...
+   
+   **Answer:** <!-- Fill your confirmation or corrections here -->
+
+   ### 2. Target Users & Scenarios
+   
+   The document identifies the following user roles:
+   - Role 1: description
+   - Role 2: description
+   
+   Questions:
+   - Are there additional roles not mentioned?
+   - [Other specific questions]
+   
+   **Answer:** <!-- Fill your answers here -->
+
+   ### 3. System Scope & Boundaries
+   
+   The functional scope includes:
+   - Module 1
+   - Module 2
+   - ...
+   
+   Questions:
+   - Are all modules required for Phase 1?
+   - [Other scope questions]
+   
+   **Answer:** <!-- Fill your answers here -->
+   ```
 
-Based on Round 1 answers, ask:
+3. **Notify user** with a brief message:
+   ```
+   📝 Clarification questions written to:
+   `01.product-requirement/.clarification-summary.md`
+   
+   Please open the file, fill in your answers after each "**Answer:**" marker, save, and let me know when done.
+   ```
+
+4. **HARD STOP** — Wait for user to confirm they have answered.
+
+5. **Read** the updated `.clarification-summary.md` file.
+
+6. **Evaluate** if answers are sufficient for Sufficiency Checks.
+
+**Round 2 (if needed): Scope & Boundaries**
+
+7. **Append** Round 2 questions to the SAME file:
+
+   ```markdown
+   ---
+
+   ## Round 2: Scope & Boundaries
+   
+   > Based on your Round 1 answers, I need to clarify the following details.
+   > Please fill in your answers after each "**Answer:**" marker.
+
+   ### 1. Out-of-Scope Items
+   
+   Based on the requirement, the following appear to be out of scope:
+   - [Item 1]
+   - [Item 2]
+   
+   Questions:
+   - Are there any explicit exclusions?
+   - [Other boundary questions]
+   
+   **Answer:** <!-- Fill your answers here -->
+
+   ### 2. Existing System Relationship
+   
+   Questions:
+   - Does this overlap with any existing system capabilities?
+   - Should this reuse or replace existing functionality?
+   
+   **Answer:** <!-- Fill your answers here -->
+
+   ### 3. Constraints
+   
+   Questions:
+   - Are there timeline constraints?
+   - Technology or budget constraints?
+   
+   **Answer:** <!-- Fill your answers here -->
+   ```
 
-| Question | Purpose |
-|----------|---------|
-| What is explicitly out of scope? | Clarify boundaries |
-| Does this overlap with any existing system capabilities? | Identify reuse vs new build |
-| Are there constraints (timeline, technology, budget)? | Clarify constraints early |
+8. **Notify user** again and wait for response.
 
-### Round 3: Detail & Acceptance (if needed)
+9. **Read** the updated file and evaluate Sufficiency Checks.
 
-| Question | Purpose |
-|----------|---------|
-| What does "done" look like? Any specific acceptance criteria? | Confirm definition of done |
-| Are there non-functional requirements (performance, security)? | Identify NFRs |
-| What is the priority relative to other work? | Confirm priority |
+**Round 3 (if still needed): Detail & Acceptance** — Same pattern: append to the file, notify, wait, read.
 
 ### Sufficiency Check
 
@@ -114,41 +204,35 @@ Sufficient to proceed when ALL of:
 - [ ] Scope boundaries (in/out) are defined
 - [ ] Relationship to existing system is understood
 
-If ANY is unclear → ask follow-up questions targeting the gap
-If ALL are clear → proceed to Step 1 Output
+If ANY is unclear → append follow-up questions to the clarification file
+If ALL are clear → proceed to Finalize Clarification File
 ```
 
-### Step 1 Output: Generate Clarification Summary
+### Finalize Clarification File
 
-After Sufficiency Check passes, generate a clarification summary file:
+After all clarification rounds complete, append the Sufficiency Check results and Key Decisions to the file:
 
-```
-Path: speccrew-workspace/iterations/{iteration}/01.product-requirement/.clarification-summary.md
-```
-
-**Content template:**
 ```markdown
-# Clarification Summary
-
-## Input Type
-- [ ] Complete requirement document provided
-- [ ] Incomplete input (progressive clarification performed)
+---
 
-## Clarification Rounds
-- Round 1 (Core Understanding): [Summary of Q&A]
-- Round 2 (Scope & Boundaries): [Summary of Q&A]
-- Round 3 (Detail & Acceptance): [If applicable, Summary of Q&A]
+## Sufficiency Check
 
-## Sufficiency Check Status
-- [x] Business problem is clearly understood
-- [x] Target users and core scenarios identified
-- [x] Scope boundaries (in/out) are defined
-- [x] Relationship to existing system is understood
+| Check Item | Status |
+|-----------|--------|
+| Core business problem clearly defined | ✅ |
+| Target user roles and permissions identified | ✅ |
+| System scope and boundaries confirmed | ✅ |
+| Key business rules clarified | ✅ |
 
 ## Key Decisions
-- [Record any key decisions made during clarification]
+
+| # | Decision | Rationale |
+|---|----------|----------|
+| 1 | [Decision] | [From user's answer in Round X] |
+| 2 | [Decision] | [From user's answer in Round X] |
 
 ## Proceed Gate
+
 ✅ All checks passed. Ready for Step 2.
 ```
 
@@ -579,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.
 
@@ -600,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/.speccrew/skills/speccrew-pm-requirement-simple/SKILL.md

@@ -37,7 +37,19 @@ This skill applies ISA-95 Stages 1-3 in lightweight mode:
 
 ### Step 1: Quick Clarification
 
-Confirm the requirement in 1-3 rounds:
+**For simple requirements with 1-3 questions:**
+- Ask directly in chat (acceptable for very short clarifications)
+
+**For requirements needing 4+ questions:**
+- Use file-based clarification (same as complex skill):
+  1. Write questions to `.clarification-summary.md` in the iteration's `01.product-requirement/` directory
+  2. User fills answers in file after each "**Answer:**" marker
+  3. User notifies PM
+  4. PM reads and proceeds
+
+> **Default to chat-based** for simple requirements unless the clarification content is lengthy.
+
+Clarification topics:
 
 1. **What to change**: Which page/function/module is affected?
 2. **What the change is**: Add field? Modify logic? New sub-feature?

package/package.json

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