speccrew 0.3.13 → 0.4.0

package/.speccrew/skills/speccrew-pm-requirement-analysis/templates/PRD-TEMPLATE.md

@@ -1,5 +1,18 @@
 # PRD - [Feature Name]
 
+> ⚠️ **CRITICAL: PM Stage Content Boundary**
+>
+> **DO NOT INCLUDE in this PRD:**
+> - Database table structures, ER diagrams, SQL queries
+> - API endpoint definitions, HTTP methods, request/response JSON schemas
+> - Design class diagrams, component diagrams, deployment diagrams
+> - Code snippets, pseudocode, implementation logic
+> - Technical terminology (e.g., UUID, JWT, REST, JSON, Microservice)
+> - Technical metrics (e.g., "code files", "CPU usage", "latency < 100ms")
+>
+> **These belong to:** Feature Designer (interaction design, API contracts) or System Designer (technical architecture).
+> **Required:** Use BUSINESS LANGUAGE only. Describe WHAT needs to happen, not HOW the system implements it.
+
 ## 1. Background & Goals
 
 ### 1.1 Background
@@ -114,13 +127,15 @@ graph TB
 
 **Process Description:**
 
-| Stage | Description | Input | Output | Responsible Role |
-|-------|-------------|-------|--------|------------------|
+| Stage | Description | Input (business terms) | Output (business terms) | Responsible Role |
+|-------|-------------|------------------------|-------------------------|------------------|
 | Stage 1 | [Description] | [Input data] | [Output data] | [Role] |
 | Stage 2 | [Description] | [Input data] | [Output data] | [Role] |
 | Stage 3 | [Description] | [Input data] | [Output data] | [Role] |
 | Stage 4 | [Description] | [Input data] | [Output data] | [Role] |
 
+*Note: Describe data in BUSINESS TERMS only (e.g., "customer info", "order status"). DO NOT use database column names, JSON fields, or SQL types.*
+
 ### 3.3 Feature List
 
 | Feature | Priority | Description | Acceptance Criteria |
@@ -158,12 +173,12 @@ graph TB
 3. [Step 3]
 
 **Boundary Conditions:**
-| Condition Type | Scenario Description | Expected Handling |
-|----------------|---------------------|-------------------|
-| Edge Cases | [e.g., empty input, too long, special characters] | [Handling method] |
-| Concurrency/Race | [e.g., duplicate submission, concurrent operations] | [Handling method] |
-| Permission Boundary | [e.g., unauthorized access, not logged in] | [Handling method] |
-| Dependency Failure | [e.g., third-party service unavailable] | [Handling method] |
+| Condition Type | Scenario Description | Business Handling Rule |
+|----------------|---------------------|------------------------|
+| Edge Cases | [e.g., customer name empty] | [e.g., "Show error message to user", NOT "throw Exception"] |
+| Concurrency/Race | [e.g., duplicate submission, concurrent operations] | [Handling method in business language] |
+| Permission Boundary | [e.g., unauthorized access, not logged in] | [Handling method in business language] |
+| Dependency Failure | [e.g., third-party service unavailable] | [Handling method in business language] |
 
 **Exception Scenarios:**
 - [Exception 1]: [Handling method]
@@ -197,12 +212,12 @@ graph LR
 
 **Operation Steps Detail:**
 
-| Step | Action | Expected Outcome | Exception Handling |
-|------|--------|------------------|-------------------|
-| 1 | [User action] | [Expected result] | [Error handling] |
-| 2 | [User action] | [Expected result] | [Error handling] |
-| 3 | [User action] | [Expected result] | [Error handling] |
-| 4 | [User action] | [Expected result] | [Error handling] |
+| Step | Action | Expected Outcome | Business Exception Handling |
+|------|--------|------------------|-----------------------------|
+| 1 | [User action] | [Expected result] | [Business handling rule, e.g., "Show friendly error message"] |
+| 2 | [User action] | [Expected result] | [Business handling rule] |
+| 3 | [User action] | [Expected result] | [Business handling rule] |
+| 4 | [User action] | [Expected result] | [Business handling rule] |
 
 ## 4. Non-functional Requirements
 

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

@@ -0,0 +1,272 @@
+---
+name: speccrew-pm-requirement-clarify
+description: SpecCrew PM Requirement Clarification Skill. Dual-mode support (simple/complex). Produces .clarification-summary.md as interface contract for downstream PRD generation. First step in PRD workflow.
+tools: Read, Write, Glob, Grep
+---
+
+# Skill Overview
+
+Requirement clarification with dual-mode support. Produces `.clarification-summary.md` as the interface contract.
+
+## Trigger Scenarios
+
+- User provides initial requirement description
+- PM Agent needs to clarify before PRD generation
+- Requirement complexity assessment needed
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `requirement_file` | string | Yes | Path to requirement document |
+| `iteration_path` | string | Yes | Path to iteration directory |
+| `complexity_hint` | enum | No | `simple` or `complex`. Auto-detect if not provided |
+
+## Methodology Foundation
+
+Applies ISA-95 Stage 1 (Domain Description) for clarification:
+- Define domain boundary, participants, glossary
+- Results flow into `.clarification-summary.md` only
+
+## PM Stage Content Boundary
+
+> **DO NOT include:** API definitions, DB structures, code snippets, technical terminology. These belong to Feature Designer or System Designer.
+
+---
+
+# Workflow
+
+## Absolute Constraints
+
+> **Violation = task failure**
+
+1. **FORBIDDEN:** `create_file` for documents — use `search_replace` on templates
+2. **FORBIDDEN:** Full-file rewrite — use targeted `search_replace`
+3. **MANDATORY:** Template-first workflow
+
+## Step 1: Load Requirement Document
+
+**Actions:**
+1. Read `requirement_file`
+2. Extract: business problem, target users, functional scope, constraints
+
+## Step 2: Load System Knowledge (IF EXISTS)
+
+**Actions:**
+1. Read `knowledges/bizs/system-overview.md` if exists
+2. Read related `{module}/{module}-overview.md` files if exist
+
+> ⚠️ Knowledge files are OPTIONAL. Proceed without them if absent.
+
+## Step 3: Determine Complexity Mode
+
+**Auto-detect criteria:**
+
+| Criteria | Simple | Complex |
+|----------|--------|---------|
+| Modules | 1 | 2+ or new domain |
+| Features | 1-5 | 6+ |
+| Integration points | 0-1 | 2+ |
+
+**Logic:** `complex` if modules >= 2 OR features >= 6 OR new_domain
+
+## Step 4: Execute Clarification (Dual Mode)
+
+### 4.1 Simple Mode
+
+- 1-3 key questions, chat-based
+- Topics: What to change, what the change is, business reason, acceptance criteria
+
+> ⚠️ **Switch to file-based if 4+ questions needed**
+
+### 4.2 Complex Mode (File-Based)
+
+> ⚠️ **All rounds use file-based interaction, NOT chat-based.**
+
+**Round 1: Core Understanding**
+
+Create `.clarification-questions-round-1.md`:
+```markdown
+# Requirements Clarification - Round 1
+
+> Fill answers after each "**Answer:**" marker, then notify me.
+
+## 1. Business Background & Goals
+Based on the document, the system aims to solve: [points]
+
+**Questions:**
+- Is this understanding correct?
+- What is the primary business goal?
+
+**Answer:** <!-- Fill here -->
+
+## 2. Target Users & Scenarios
+Roles identified: [list]
+
+**Questions:**
+- Additional roles not mentioned?
+- Primary use cases for each role?
+
+**Answer:** <!-- Fill here -->
+
+## 3. System Scope & Boundaries
+Scope includes: [modules]
+
+**Questions:**
+- All modules required for Phase 1?
+- What is explicitly out of scope?
+
+**Answer:** <!-- Fill here -->
+```
+
+Notify user:
+```
+📝 Round 1 questions written to:
+`01.product-requirement/.clarification-questions-round-1.md`
+
+Please fill answers after each "**Answer:**" marker, save, and notify me.
+```
+
+**HARD STOP** — Wait for user confirmation, then read file.
+
+**Round 2: Scope & Boundaries (if needed)**
+
+Create `.clarification-questions-round-2.md` with:
+- Out-of-Scope Items confirmation
+- Integration Boundaries (external systems)
+- Business Rules & Constraints
+
+**Round 3: Detail & Acceptance (if still needed)**
+
+Same pattern with focused follow-up questions.
+
+## Step 5: Sufficiency Check
+
+> ⚠️ **ALL 4 checks must pass before proceeding.**
+
+| # | Check Item | Pass Criteria |
+|---|------------|---------------|
+| 1 | Scope boundaries are clear | Explicit in/out scope defined |
+| 2 | Key business rules are documented | At least 1 rule identified |
+| 3 | Priority/phasing decisions are made | Phase 1 scope is clear |
+| 4 | Integration boundaries are identified | Integration points listed or "none" confirmed |
+
+**Logic:** If all 4 pass → Step 6. Else if round < 3 → next round. Else → proceed with gaps noted.
+
+## Step 6: Generate .clarification-summary.md
+
+**Output:** `{iteration_path}/01.product-requirement/.clarification-summary.md`
+
+**Format:**
+```markdown
+# Clarification Summary
+
+## Complexity
+- Level: [simple | complex]
+- Rationale: [reason]
+
+## Key Decisions
+| # | Decision | Rationale | Source |
+|---|----------|-----------|--------|
+| 1 | [text] | [reason] | Round X |
+
+## Clarification Q&A
+
+### Round 1
+| # | Question | Answer | Impact |
+|---|----------|--------|--------|
+| 1 | [Q] | [A] | [Impact] |
+
+### Round 2 (if applicable)
+[Same format]
+
+### Round 3 (if applicable)
+[Same format]
+
+## Sufficiency Checks
+- [x] Scope boundaries are clear
+- [x] Key business rules are documented
+- [x] Priority/phasing decisions are made
+- [x] Integration boundaries are identified
+
+## Notes
+[Additional remarks or gaps]
+```
+
+## Step 7: Initialize .checkpoints.json
+
+> ⚠️ **MANDATORY: Use `update-progress.js` script for all JSON files.**
+
+```bash
+node speccrew-workspace/scripts/update-progress.js write-checkpoint \
+  --file {iteration_path}/01.product-requirement/.checkpoints.json \
+  --checkpoint requirement_clarification \
+  --passed true
+```
+
+**Generated structure:**
+```json
+{
+  "stage": "01_prd",
+  "checkpoints": {
+    "requirement_clarification": {
+      "passed": true,
+      "confirmed_at": "2026-04-10T12:00:00.000Z",
+      "description": "Requirement clarification completed",
+      "clarification_file": ".clarification-summary.md",
+      "complexity": "simple|complex",
+      "sufficiency_checks": {
+        "scope_boundaries": true,
+        "business_rules": true,
+        "priority_phasing": true,
+        "integration_boundaries": true
+      }
+    }
+  }
+}
+```
+
+## Step 8: Output Completion
+
+```
+✅ Requirement Clarification Complete
+
+Complexity Level: [simple | complex]
+Clarification File: {path}/.clarification-summary.md
+Checkpoint File: {path}/.checkpoints.json
+
+Key Decisions:
+- [Decision 1]
+- [Decision 2]
+
+Sufficiency Checks: 4/4 ✅
+
+Next: Proceed to PRD generation.
+```
+
+---
+
+# Output Checklist
+
+- [ ] Requirement document loaded
+- [ ] System knowledge loaded (if exists)
+- [ ] Complexity mode determined
+- [ ] Clarification conducted (appropriate mode)
+- [ ] All 4 Sufficiency Checks passed
+- [ ] `.clarification-summary.md` created
+- [ ] `.checkpoints.json` initialized via script
+
+---
+
+# Constraints
+
+**Must do:**
+- Always perform at least 1 clarification round
+- Use file-based for complex mode or 4+ questions
+- Pass all 4 Sufficiency Checks
+- Use `update-progress.js` for JSON files
+
+**Must not do:**
+- Skip clarification based on urgency
+- Use chat for complex requirements
+- Manually write JSON files

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

@@ -0,0 +1,342 @@
+---
+name: speccrew-pm-requirement-model
+description: SpecCrew PM Requirement Modeling Skill. Applies ISA-95 Stages 1-3 for business domain analysis, WBS decomposition, and module ordering. Produces .module-design.md as interface contract for downstream PRD generation. Second step in PRD workflow.
+tools: Read, Write, Glob, Grep
+---
+
+# Skill Overview
+
+ISA-95 business modeling and module decomposition. Produces `.module-design.md` as the interface contract for PRD generation.
+
+## Trigger Scenarios
+
+- Clarification completed (`.clarification-summary.md` exists)
+- Complex requirements requiring ISA-95 analysis
+- Multi-module system requiring decomposition
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `iteration_path` | string | Yes | Path to iteration directory |
+| `clarification_file` | string | No | Path to clarification summary (default: `{iteration_path}/01.product-requirement/.clarification-summary.md`) |
+
+## Methodology Foundation
+
+Applies ISA-95 Stages 1-3 as structured analysis framework:
+
+| Stage | Purpose | Output |
+|-------|---------|--------|
+| Stage 1: Domain Description | Boundary, actors, glossary | Domain model |
+| Stage 2: Functions in Domain | WBS decomposition | Function map |
+| Stage 3: Functions of Interest | MoSCoW prioritization | MVP scope |
+
+## PM Stage Content Boundary
+
+> **DO NOT include:** API definitions, DB structures, code snippets, technical terminology. These belong to Feature Designer or System Designer.
+
+---
+
+# Workflow
+
+## Absolute Constraints
+
+> **Violation = task failure**
+
+1. **FORBIDDEN:** `create_file` for documents — use `search_replace` on templates
+2. **FORBIDDEN:** Full-file rewrite — use targeted `search_replace`
+3. **MANDATORY:** Template-first workflow
+
+## Step 1: Verify Prerequisites
+
+**MANDATORY:** `.clarification-summary.md` MUST exist in the iteration directory.
+
+**IF missing → ABORT immediately:**
+```
+❌ ERROR: .clarification-summary.md not found.
+   Path: {iteration_path}/01.product-requirement/.clarification-summary.md
+   
+   This skill requires completed clarification. Please run speccrew-pm-requirement-clarify first.
+```
+
+**Actions:**
+1. Read `.clarification-summary.md`
+2. Extract: complexity level, key decisions, clarified scope, business rules
+3. IF complexity == "simple" → Skip to Step 4 (minimal module design)
+
+## Step 2: ISA-95 Business Modeling (Complex Requirements)
+
+> ⚠️ **This is a THINKING PROCESS with user checkpoints.**
+
+### 2.1 Stage 1 - Domain Description
+
+**Actions:**
+- Define domain boundary (in-scope, out-of-scope)
+- Identify external participants (users, systems, agents)
+- Create domain glossary (business terms only)
+
+**Output format:**
+```markdown
+### Domain Description
+- **System Boundary**: [what's included/excluded]
+- **Actors**: [user roles, external systems]
+- **Domain Glossary**: [term: definition]
+```
+
+**Checkpoint A:** Present to user for confirmation.
+```
+📝 Domain Description Complete
+
+System Boundary: [summary]
+Actors: [list]
+
+Does this match your understanding? Reply "确认" to proceed or provide corrections.
+```
+
+**HARD STOP** — Wait for user confirmation before proceeding.
+
+### 2.2 Stage 2 - Functions in Domain (WBS)
+
+**Actions:**
+- Create WBS decomposition (2-3 levels)
+- Map functions to business capabilities
+- Identify module boundaries
+
+**Output format:**
+```markdown
+### Domain Functions (WBS)
+- Function 1
+  - Sub-function 1.1
+  - Sub-function 1.2
+- Function 2
+  - Sub-function 2.1
+```
+
+### 2.3 Stage 3 - Functions of Interest (MoSCoW)
+
+**Actions:**
+- Apply MoSCoW prioritization
+- Identify core vs non-core functions
+- Define MVP scope
+
+**Output format:**
+```markdown
+### Focus Functions (MoSCoW)
+| Priority | Function | Rationale |
+|----------|----------|-----------|
+| Must | [function] | [why core] |
+| Should | [function] | [why important] |
+| Could | [function] | [why deferred] |
+| Won't | [function] | [why excluded] |
+```
+
+**Checkpoint B:** Present MVP scope for confirmation.
+```
+📝 MVP Scope Defined
+
+Must-have (Phase 1): [list]
+Should-have (Phase 2): [list]
+
+Is this prioritization correct? Reply "确认" to proceed.
+```
+
+**HARD STOP** — Wait for user confirmation.
+
+**Checkpoint C:** Present complete analysis summary.
+```
+📝 ISA-95 Analysis Complete
+
+[Summary of all 3 stages]
+
+Ready to proceed with module decomposition? Reply "确认".
+```
+
+**HARD STOP** — Wait for final confirmation before Step 3.
+
+## Step 3: Module Decomposition & Ordering
+
+### 3.1 Define Module List
+
+**Actions:**
+- Map WBS functions to modules
+- Define scope for each module
+- Identify key entities per module
+
+**Output format:**
+```markdown
+## Module List
+| Module | Key | Scope | Key Entities | Owner Domain |
+|--------|-----|-------|-------------|--------------|
+| [Name] | [key] | [scope] | [entities] | [domain] |
+```
+
+### 3.2 Cross-Module Dependency Matrix
+
+**Actions:**
+- Identify data flows between modules
+- Document dependency types (Data/API/Event)
+- Note shared entities
+
+**Output format:**
+```markdown
+## Dependency Matrix
+| Source Module | Target Module | Type | Description |
+|--------------|---------------|------|-------------|
+| [A] | [B] | Data | [shared entity] |
+```
+
+### 3.3 Implementation Phases
+
+**Actions:**
+- Sort modules by dependency (least dependent first)
+- Group into phases (typically 3)
+- Validate no circular dependencies
+
+**Output format:**
+```markdown
+## Implementation Phases
+- **Phase 1** (Foundation): [modules with no upstream deps]
+- **Phase 2** (Core): [modules depending on Phase 1]
+- **Phase 3** (Extension): [remaining modules]
+```
+
+**User Confirmation:**
+```
+📝 Module Decomposition Complete
+
+[Module list table]
+[Dependency matrix]
+[Implementation phases]
+
+Please review. Reply "确认" to finalize or request changes.
+```
+
+**HARD STOP** — Wait for user confirmation.
+
+## Step 4: Generate .module-design.md
+
+**Output:** `{iteration_path}/01.product-requirement/.module-design.md`
+
+**Complete format:**
+```markdown
+# Module Design
+
+## ISA-95 Analysis Summary
+
+### Domain Description
+- **System Boundary**: [description]
+- **Actors**: [list]
+- **Domain Glossary**: [terms]
+
+### Domain Functions (WBS)
+[WBS structure]
+
+### Focus Functions (MoSCoW)
+| Priority | Function | Rationale |
+|----------|----------|-----------|
+| Must | [fn] | [rationale] |
+| Should | [fn] | [rationale] |
+| Could | [fn] | [rationale] |
+
+## Module List
+| Module | Key | Scope | Key Entities | Owner Domain | Phase |
+|--------|-----|-------|-------------|--------------|-------|
+| [name] | [key] | [scope] | [entities] | [domain] | [1/2/3] |
+
+## Dependency Matrix
+| Source | Target | Type | Description |
+|--------|--------|------|-------------|
+| [A] | [B] | [type] | [desc] |
+
+## Implementation Phases
+- **Phase 1**: [foundation modules]
+- **Phase 2**: [dependent modules]
+- **Phase 3**: [independent modules]
+```
+
+**For simple requirements:** Include minimal sections (Domain Description + Module List with 1 module).
+
+## Step 5: Update .checkpoints.json
+
+> ⚠️ **MANDATORY: Use `update-progress.js` script for all JSON files.**
+
+```bash
+node speccrew-workspace/scripts/update-progress.js write-checkpoint \
+  --file {iteration_path}/01.product-requirement/.checkpoints.json \
+  --checkpoint requirement_modeling \
+  --passed true
+```
+
+**Generated structure:**
+```json
+{
+  "stage": "01_prd",
+  "checkpoints": {
+    "requirement_clarification": { ... },
+    "requirement_modeling": {
+      "passed": true,
+      "confirmed_at": "2026-04-10T12:00:00.000Z",
+      "description": "ISA-95 modeling and module decomposition completed",
+      "module_design_file": ".module-design.md",
+      "isa95_stages": {
+        "domain_description": true,
+        "functions_in_domain": true,
+        "functions_of_interest": true
+      },
+      "module_count": 3,
+      "implementation_phases": 3
+    }
+  }
+}
+```
+
+## Step 6: Output Completion
+
+```
+✅ Requirement Modeling Complete
+
+Module Design File: {path}/.module-design.md
+Checkpoint File: {path}/.checkpoints.json
+
+Summary:
+- Complexity: [simple | complex]
+- Modules: [count]
+- Phases: [count]
+- Dependencies: [count]
+
+Next: Proceed to PRD generation.
+```
+
+---
+
+# Output Checklist
+
+- [ ] `.clarification-summary.md` verified (prerequisite)
+- [ ] ISA-95 Stage 1 complete (Domain Description)
+- [ ] Checkpoint A passed (domain boundary confirmed)
+- [ ] ISA-95 Stage 2 complete (Functions in Domain)
+- [ ] ISA-95 Stage 3 complete (Functions of Interest)
+- [ ] Checkpoint B passed (MVP scope confirmed)
+- [ ] Checkpoint C passed (complete analysis confirmed)
+- [ ] Module list defined
+- [ ] Dependency matrix created
+- [ ] Implementation phases determined
+- [ ] Module decomposition confirmed with user
+- [ ] `.module-design.md` created
+- [ ] `.checkpoints.json` updated via script
+
+---
+
+# Constraints
+
+**Must do:**
+- Verify `.clarification-summary.md` exists before starting
+- Use 3 checkpoints (A/B/C) for progressive user confirmation
+- Define clear module boundaries with minimal coupling
+- Use `update-progress.js` for JSON files
+
+**Must not do:**
+- Skip user checkpoints in complex mode
+- Include technical implementation details
+- Create circular module dependencies
+- Manually write JSON files