speccrew 0.3.0 → 0.3.1

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

@@ -92,8 +92,89 @@ If WORKFLOW-PROGRESS.json does not exist (legacy iterations or new workspace):
 
 # Workflow
 
+## Phase 0.5: IDE Detection
+
+Detect current IDE environment and determine skill loading strategy:
+
+1. **Detect IDE**: Check environment variables or context to identify current IDE (Claude Code, Cursor, Qoder, etc.)
+2. **Set skill_path**: Based on IDE detection result, set the appropriate skill search path
+3. **Proceed to Requirement Assessment**
+
+---
+
+## Phase 1: Pre-Skill Requirement Assessment
+
+Before invoking the requirement analysis skill, assess the user input for completeness.
+
+### Sufficiency Check
+
+Evaluate user input against these criteria:
+
+| Criterion | Description | Assessment |
+|-----------|-------------|------------|
+| Business Problem Clarity | Is the core business problem clearly understood? | ✅/❌ |
+| Target Users & Scenarios | Are target users and core use cases identified? | ✅/❌ |
+| Scope Boundaries | Are inclusion/exclusion boundaries defined? | ✅/❌ |
+| System Relationship | Is the relationship with existing system understood? | ✅/❌ |
+
+### Clarification Protocol
+
+**IF ANY criterion NOT met**:
+- Execute progressive clarification (2-3 questions per round, minimum 2 rounds)
+- Questions should be specific and actionable
+- Document all clarification Q&A in progress tracking
+- Re-evaluate after each round
+
+**IF ALL criteria met** (user provided complete requirement document):
+- **STILL execute at least 1 confirmation round**:
+  1. Confirm understanding is correct
+  2. Confirm scope boundaries (what's in/out)
+  3. Confirm priorities and constraints
+- This ensures alignment even with comprehensive input
+
+### Complexity Pre-Assessment
+
+Before invoking skill, perform rough complexity assessment:
+
+- **Simple**: Single module, clear scope, minimal system integration
+- **Moderate**: 1-2 modules, some integration required
+- **Complex**: 2+ modules, significant integration, multi-stakeholder
+
+If requirement clearly involves **2+ modules**:
+- Flag this as `expected_complexity: complex`
+- Inform Skill that this is a complex requirement requiring thorough analysis
+
+### Pre-Skill Output
+
+After completing assessment, prepare the following to pass to Skill:
+
+```
+clarification_status: true|false
+clarification_rounds: <number>
+clarification_summary: <brief summary of key clarifications>
+expected_complexity: simple|moderate|complex
+complexity_notes: <if complex, note affected modules>
+```
+
+---
+
+⚠️ **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**
+
+---
+
+## Phase 2: Invoke Skill
+
 Invoke Skill: Find `speccrew-pm-requirement-analysis/SKILL.md` in the skills directory
 
+Pass the following context to the Skill:
+- User's original requirement input
+- Pre-skill assessment results (clarification_status, expected_complexity, etc.)
+- Clarification Q&A records (if any)
+
 # Deliverables
 
 | Deliverable | Path | Notes |
@@ -103,13 +184,22 @@ Invoke Skill: Find `speccrew-pm-requirement-analysis/SKILL.md` in the skills dir
 
 # 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**
+
 **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
+- Execute Pre-Skill Requirement Assessment before invoking the Skill
+- Pass clarification context and complexity assessment to the Skill
 
 **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
 

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

@@ -23,7 +23,17 @@ tools: Read, Write, Glob, Grep
 
 3. **MANDATORY: Template-first workflow** — Copy template MUST execute before filling sections. Skipping copy and writing content directly is FORBIDDEN.
 
-## Step 1: Requirements Clarification (Progressive Multi-Round)
+## Step 1: Requirements Clarification (MANDATORY)
+
+⚠️ **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)
+```
 
 Use progressive questioning to clarify requirements. Do NOT ask all questions at once.
 
@@ -66,7 +76,53 @@ Sufficient to proceed when ALL of:
 - [ ] Relationship to existing system is understood
 
 If ANY is unclear → ask follow-up questions targeting the gap
-If ALL are clear → proceed to Step 2
+If ALL are clear → proceed to Step 1 Output
+```
+
+### Step 1 Output: Generate Clarification Summary
+
+After Sufficiency Check passes, generate a clarification summary 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 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
+
+## Key Decisions
+- [Record any key decisions made during clarification]
+
+## Proceed Gate
+✅ All checks passed. Ready for Step 2.
+```
+
+### Proceed Gate to Step 2
+
+**Before proceeding to Step 2, verify BOTH conditions:**
+
+```
+□ All Sufficiency Check items marked as ✅
+□ .clarification-summary.md file exists and is complete
+
+IF both conditions met → Proceed to Step 2
+IF any condition fails → STOP and complete the missing items
 ```
 
 **Principles:**
@@ -274,6 +330,16 @@ If there are gaps or unclear points, ask the user to confirm before proceeding.
 
 Before writing, determine the PRD structure based on requirement complexity:
 
+### Structure Decision (MANDATORY IF/THEN)
+
+```
+IF modules_count >= 2 OR cross_module_dependencies exist:
+  → MANDATORY: Use Master-Sub Structure
+  → Record: sub_prd_count = len(module_list)
+ELSE:
+  → Use Single PRD Structure
+```
+
 ### Simple Requirements (Single Document)
 - Single feature with clear boundaries
 - Minimal dependencies on existing modules
@@ -420,47 +486,135 @@ If the iteration directory does not exist, refer to the `000-sample` directory s
 
 ## Step 12: Write Files Using Template-Fill Workflow
 
-### 12a Copy Template to Document Path
+⚠️ **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.**
+
+---
 
-For each document to write (PRD, and optionally Sub-PRDs):
+### Step 12a: Generate Master PRD
 
-1. **Read the template**: `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
-2. **Replace top-level placeholders** (feature name, iteration, date)
-3. **Create the document** using `create_file` at the path determined in Step 11
-4. **Verify**: Document has complete section structure
+**For BOTH Single and Master-Sub structures:**
 
-### 12b Fill Each Section Using search_replace
+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`
 
-Fill each section with content prepared in Step 9, using `search_replace` per section.
+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
 
 > ⚠️ **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 structure, repeat 12a + 12b for each Sub-PRD document.
+---
+
+### Step 12b: Generate Sub-PRDs (LOOP - MANDATORY for Master-Sub)
+
+**IF Step 8 determined Master-Sub structure, execute this loop:**
+
+```
+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
+
+  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)
+
+  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)
+
+NEXT module
+
+⚠️ STOP condition: All modules in module_list have been processed.
+```
+
+**Example loop execution:**
+```
+Iteration 1: Process module "inventory"
+  → Create: inventory-management-sub-inventory.md
+  → Fill: inventory-specific content
+  → Verify: file exists and has content
+
+Iteration 2: Process module "order"
+  → Create: inventory-management-sub-order.md
+  → Fill: order-specific content
+  → Verify: file exists and has content
+
+... continue until all modules processed
+```
+
+---
+
+### Step 12c: Verification Checklist (MANDATORY)
+
+**After all PRD files are generated, verify:**
+
+```
+□ Master PRD exists at {iteration}/01.product-requirement/{feature-name}-prd.md
+□ Master PRD file size > 2KB (not empty placeholder)
+
+[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
+```
+
+---
 
-### 12c Request Confirmation
+### Step 12d: Request Confirmation
 
-After writing files, show summary and request user confirmation:
+After verification passes, show summary and request user confirmation:
 
-### Simple PRD Output
+**Simple PRD Output:**
 ```
 PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
 ```
 
-### Complex PRD Output (with modeling)
+**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 Output
+**Master-Sub PRD Output:**
 ```
 Master PRD generated: speccrew-workspace/iterations/XXX-{type}-{name}/01.product-requirement/[feature-name]-prd.md
-Sub-PRDs generated:
+Sub-PRDs generated ({sub_prd_count} files):
   - [feature-name]-sub-[module1].md
   - [feature-name]-sub-[module2].md
+  - ...
 ```
 
 Please confirm the following key points:

package/package.json

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