speccrew 0.3.13 → 0.4.0

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

@@ -28,69 +28,45 @@ This skill applies ISA-95 Stages 1-3 in lightweight mode:
 
 ## PM Stage Content Boundary
 
-> **DO NOT include in PRD:** API definitions, class diagrams, ER diagrams, code snippets, technical metrics.
-> These belong to Feature Designer or System Designer.
+> **PM Stage Content Boundary — DO NOT include:**
+> - API endpoint definitions, HTTP methods, request/response JSON
+> - Design class diagrams, component diagrams, deployment diagrams
+> - Database table structures, ER diagrams, SQL queries
+> - Code snippets, pseudocode, implementation logic
+> - Technical terminology (e.g., UUID, JWT, REST, Microservice, JSON)
+> - Technical metrics (e.g., "code files", "latency < 100ms", "CPU usage")
+>
+> These belong to **Feature Designer** (interaction design, API contracts) or **System Designer** (technical architecture).
+>
+> **Required:** Use business language only. Describe WHAT business operation needs to happen, not HOW the system implements it.
+> ✅ "Customer can search by name" ❌ "SELECT * FROM customers WHERE name LIKE '%keyword%'"
+> ✅ "Show friendly error message" ❌ "return HTTP 400 Bad Request"
 
 ---
 
-## Workflow
-
-### Step 1: Quick Clarification
-
-**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:
+## Prerequisites
 
-1. **What to change**: Which page/function/module is affected?
-2. **What the change is**: Add field? Modify logic? New sub-feature?
-3. **Business reason**: Why is this change needed?
-4. **Acceptance criteria**: How to verify the change is correct?
+> 🚨 MANDATORY: `.clarification-summary.md` MUST exist in the current iteration directory.
+> This file is generated by the `speccrew-pm-requirement-clarify` skill.
+> IF `.clarification-summary.md` is missing → ABORT immediately.
 
-> **ISA-95 Stage 1 Thinking** — Confirm affected module boundary and impacted user roles. No formal glossary needed.
-
-If requirement is already clear, skip and proceed.
+---
 
-**If requirement is complex** (3+ modules, 10+ features, new system), **STOP and redirect**:
-```
-⚠️ This requirement appears complex. Switching to full requirement analysis.
-Invoking skill: speccrew-pm-requirement-analysis/SKILL.md
-```
+## Workflow
 
-### Step 2: Initialize Tracking
+### Step 1: Read Clarification Summary
 
-1. **Determine iteration path**: Use existing or create `speccrew-workspace/iterations/{iteration-id}/`
+**Actions:**
+1. Read `.clarification-summary.md` from `{iteration_path}/01.product-requirement/`
+2. Extract: complexity level, key decisions, clarification Q&A, sufficiency checks
 
-2. **Create checkpoint file** at `01.product-requirement/.checkpoints.json`:
-```json
-{
-  "stage": "01_prd",
-  "complexity": "simple",
-  "checkpoints": {
-    "requirement_clarification": { "passed": true, "confirmed_at": "{REAL_TIMESTAMP}", "description": "Quick clarification completed" },
-    "prd_review": { "passed": false, "confirmed_at": null, "description": "User review and confirmation" }
-  }
-}
-```
-Get real timestamp via: `node -e "console.log(new Date().toISOString())"`
+**Verify complexity:**
+- IF complexity = "complex" → STOP and redirect to `speccrew-pm-requirement-analysis`
+- IF complexity = "simple" → proceed
 
-3. **Update WORKFLOW-PROGRESS.json** (if exists):
-```bash
-node speccrew-workspace/scripts/update-progress.js update-workflow \
-  --file speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json \
-  --stage 01_prd --status in_progress
-```
+> **ISA-95 Stage 1 Thinking** — Scope boundary already confirmed in clarification. Extract module boundary and impacted roles from summary.
 
-### Step 3: Read PRD Template
+### Step 2: Read PRD Template
 
 **Locate and read the PRD template:**
 
@@ -106,7 +82,7 @@ node speccrew-workspace/scripts/update-progress.js update-workflow \
 > 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
+### Step 3: Generate Single PRD
 
 Create PRD at: `speccrew-workspace/iterations/{iteration}/01.product-requirement/{feature-name}-prd.md`
 
@@ -128,71 +104,57 @@ Create PRD at: `speccrew-workspace/iterations/{iteration}/01.product-requirement
 | 6. Boundary | Clear in/out scope. |
 | 7. Assumptions | Only if there are assumptions to document. |
 
+> ⚠️ **Content Boundary Reminder for each section:**
+> - Background & Goals → Business reason only, NO technical architecture
+> - User Stories → "As a [role] I want [business action]" — NOT implementation method
+> - Functional Requirements → WHAT changes, not HOW to implement
+> - Feature List/Breakdown → Feature description is business outcome, NOT technical solution
+> - Acceptance Criteria → Business acceptance (e.g., "User can see result"), NOT technical tests (e.g., "API returns 200")
+
 > **ISA-95 Stage 3 Thinking** — All identified features are Must-have (P0). No MoSCoW filtering needed.
 
-### Step 5: Present for User Review
+### Step 4: Return to PM Agent
 
-Display PRD summary:
+**Output:**
 ```
 📄 PRD Generated: {feature-name}-prd.md
 
 Summary:
-- Scope: {brief scope}
+- Scope: {brief scope from clarification summary}
 - Features: {count} features
 - Modules affected: {module names}
+- Complexity: simple
 
-Please review and confirm the scope, acceptance criteria, and completeness.
-```
-
-⚠️ **HARD STOP — WAIT FOR USER CONFIRMATION**
-
-```
-DO NOT proceed until user explicitly confirms.
-IF user requests changes → update PRD, then re-present.
-ONLY after user confirms → proceed to Step 6.
-```
-
-### Step 6: Finalize PRD Stage
-
-After user confirms:
-
-1. **Update checkpoint** — set `prd_review.passed = true` with real timestamp
-
-2. **Update WORKFLOW-PROGRESS.json**:
-```bash
-node speccrew-workspace/scripts/update-progress.js update-workflow \
-  --file speccrew-workspace/iterations/{iteration}/WORKFLOW-PROGRESS.json \
-  --stage 01_prd --status confirmed \
-  --output "01.product-requirement/{feature-name}-prd.md"
+Returning to PM Agent for review and confirmation.
 ```
 
-3. **Output**: `✅ PRD confirmed. PRD stage is complete. Next: Start Feature Design in a new conversation.`
-
-4. **END** — Do not proceed further.
+> **DO NOT wait for user confirmation in this skill.**
+> Verification and confirmation are handled by PM Agent Phase 5.
 
 ---
 
 ## Output Checklist
 
+- [ ] `.clarification-summary.md` read and complexity verified
 - [ ] PRD file created at correct path
 - [ ] All relevant sections filled (skip empty optional sections)
 - [ ] No technical implementation details (no API, no code, no class diagrams)
 - [ ] Feature Breakdown table present with at least 1 feature
 - [ ] Acceptance criteria are concrete and testable
-- [ ] .checkpoints.json created with requirement_clarification passed
 - [ ] Business language only — no technical jargon
 
 ## Constraints
 
 **Must do:**
+- Verify `.clarification-summary.md` exists before proceeding
 - Keep PRD concise — 1-3 page PRDs
 - Use business language throughout
-- Verify with user before finalizing
-- Use real timestamps from `node -e "console.log(new Date().toISOString())"`
+- Extract key decisions from clarification summary into PRD
 
 **Must not do:**
-- Do not generate Master-Sub PRD structure
-- Do not dispatch worker agents
-- Do not generate API definitions, class diagrams, or technical artifacts
-- Do not skip user confirmation
-- Do not auto-transition to Feature Design stage
+- Proceed without `.clarification-summary.md`
+- Generate Master-Sub PRD structure
+- Dispatch worker agents
+- Generate API definitions, class diagrams, or technical artifacts
+- Wait for user confirmation (handled by PM Agent)
+- Auto-transition to Feature Design stage

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

@@ -4,6 +4,23 @@ description: Generate a single Sub-PRD document for one module. Used by PM Agent
 tools: Read, Write, Glob, Grep
 ---
 
+## PM Stage Content Boundary
+
+> ⚠️ **This Sub-PRD MUST adhere to PM Stage Content Boundary:**
+> - NO API endpoint definitions, HTTP methods, request/response JSON
+> - NO Database table structures, ER diagrams, SQL queries
+> - NO Design class diagrams, component diagrams, deployment diagrams
+> - NO Code snippets, pseudocode, implementation logic
+> - NO Technical terminology (e.g., UUID, JWT, REST, Microservice, JSON)
+> - NO Technical metrics (e.g., "code files", "latency < 100ms", "CPU usage")
+>
+> **Required:** Use BUSINESS LANGUAGE ONLY.
+> Describe WHAT business operation needs to happen, not HOW the system implements it.
+>
+> **ABORT CONDITIONS:**
+> - IF any section being generated contains SQL, API definitions, or code → STOP
+> - IF inherited module_requirements contain technical details → Strip them, use business descriptions only
+
 # Trigger Scenarios
 
 - PM Agent dispatches worker to generate Sub-PRD for a specific module
@@ -62,17 +79,17 @@ Fill each section using `search_replace`:
 - 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.1 Use Case Diagram: Module-specific use case diagram (Mermaid flowchart TB) — **Business use cases showing user interactions — NOT system APIs or technical components**
+- 3.2 Business Process Flow: Module-internal process flow — **Business process steps — NOT database operations or API calls**
+- 3.3 Feature List: Module features with P0/P1/P2 priority — **Business feature descriptions — NOT technical implementation**
 - 3.4 Feature Breakdown: **REQUIRED** — Fill with `{module_features}` data:
   - Feature ID, Feature Name, Type (User Interaction / Backend Process), Scope, Description
   - Feature Dependencies table
 - 3.5 Feature Details: Detailed descriptions for each feature including:
-  - Requirement Description
-  - Interaction Flow
-  - Boundary Conditions table
-  - Exception Scenarios
+  - Requirement Description — **Business requirements in business language**
+  - Interaction Flow — **User interaction steps in business terms**
+  - Boundary Conditions table — **Business scenarios and business handling rules**
+  - Exception Scenarios — **Business exception handling in business language**
 
 ### 3.4 Section 4: Non-functional Requirements
 - Module-specific performance, security, compatibility requirements
@@ -93,6 +110,14 @@ Fill each section using `search_replace`:
 
 > ⚠️ **FORBIDDEN: `create_file` to rewrite the entire document. MUST use `search_replace` per section.**
 
+### ⚠️ Content Boundary Validation
+
+Before filling each section, verify:
+- Feature descriptions use BUSINESS language (✅ "Customer can view order history" ❌ "GET /api/orders returns JSON")
+- Boundary conditions describe BUSINESS scenarios (✅ "Customer name is empty" ❌ "null pointer exception")
+- Exception handling describes BUSINESS rules (✅ "Show friendly error message" ❌ "return HTTP 400")
+- Process flows show BUSINESS steps (✅ "Customer submits order" ❌ "POST request to order service")
+
 ## Step 4: Verify Output
 
 1. Read the generated file to verify:

package/package.json

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

package/workspace-template/docs/rules/mermaid-rule.md

@@ -67,6 +67,19 @@ graph TB
 | `/` | File paths (`/pages/index`) | Remove leading `/` or use parentheses: `pages/index` |
 | `(` `)` | Function calls (`handleQuery()`) | Remove parentheses: `handleQuery` |
 
+**When Special Characters Must Be Preserved:**
+
+If node text must contain parentheses `()`, curly braces `{}`, square brackets `[]`, or colons `:`, wrap the entire text in double quotes to prevent Mermaid from misinterpreting them as shape definitions or syntax elements.
+
+| Wrong (Parse Error) | Correct (Quoted) |
+|---------------------|------------------|
+| `P1[选择对比组(如:面部左脸)]` | `P1["选择对比组(如:面部左脸)"]` |
+| `P2[上传图片(1-N张)]` | `P2["上传图片(1-N张)"]` |
+| `A[Task{ urgent }]` | `A["Task{ urgent }"]` |
+| `B[Array[0]]` | `B["Array[0]"]` |
+
+**Important:** The rule "Quoted node text [\"text\"]" in the Prohibited list refers to unnecessary quoting of plain text. When special characters are present, quoting becomes **required** for correct parsing.
+
 ### 5. Multi-line Text Handling
 
 ```