speccrew 0.1.0

package/.speccrew/skills/speccrew-knowledge-system-summarize/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: speccrew-knowledge-system-summarize
+description: Generate complete system-overview.md by reading all {{module_name}}-overview.md files. Aggregates module information, builds dependency graph, and creates system-level documentation. In incremental mode, this skill always regenerates the system overview from the latest module overviews.
+tools: Read, Write, Glob, Skill
+---
+
+# System Summarize - Complete System Overview
+
+Read all {{module_name}}-overview.md files, aggregate information to generate complete system-overview.md with module index, topology, and business flows.
+
+## Language Adaptation
+
+**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+
+- `language: "zh"` → Generate all content in 中文
+- `language: "en"` → Generate all content in English
+- Other languages → Use the specified language
+
+**All output content (system description, module summaries, flow descriptions) must be in the target language only.**
+
+## Trigger Scenarios
+
+- "Generate system overview from modules"
+- "Complete system documentation"
+- "Summarize all modules into system view"
+
+## User
+
+Worker Agent (speccrew-task-worker)
+
+## Input
+
+- `modules_path`: Path to modules directory (e.g., `speccrew-workspace/knowledges/bizs/`) containing all {{platform_type}}/{{module_name}}/{{module_name}}-overview.md files
+- `output_path`: Output path for system-overview.md (e.g., `speccrew-workspace/knowledges/bizs/`)
+- `language`: Target language for generated content (e.g., "zh", "en") - **REQUIRED**
+
+## Output
+
+- `{{output_path}}/system-overview.md` - Complete system overview
+
+## Workflow
+
+### Prerequisites
+
+Before starting, verify:
+
+- **Module overviews completed**: `modules_path` contains subdirectories for each platform_type, with module directories containing completed `*-overview.md` files (from Stage 3: module-summarize)
+- **Output location**: `system-overview.md` will be created at `output_path/system-overview.md`
+- **If no modules found**: Proceed with skeleton generation (see Edge Cases)
+
+### Edge Cases
+
+- **Empty modules directory**: If no `*-overview.md` files found, generate a skeleton system-overview.md with empty statistics and return `status: "warning"`.
+- **Incomplete module overviews**: If a module-overview.md only has Section 1-2 (initial version), use available data and note gaps with `<!-- DATA INCOMPLETE -->`.
+- **Same module name from different platforms**: Treat as separate modules. Use `{module_name} ({platform_type})` for display and `{module_name}_{platform_type}` as internal ID.
+- **Missing timestamp service**: If `speccrew-get-timestamp` is unavailable, use system current time as fallback.
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Step0[Step 0: Read System Overview Template]
+    Step0 --> Step1[Step 1: Discover All Modules]
+    Step1 --> Step2[Step 2: Read All Module Overviews]
+    Step2 --> Step3[Step 3: Build Module Index]
+    Step3 --> Step4[Step 4: Build Dependency Graph]
+    Step4 --> Step5[Step 5: Identify Business Domains]
+    Step5 --> Step6[Step 6: Identify End-to-End Flows]
+    Step6 --> Step7[Step 7: Generate system-overview.md]
+    Step7 --> Step8[Step 8: Report Results]
+    Step8 --> End([End])
+```
+
+### Step 0: Read System Overview Template
+
+Before processing, read the template file to understand the required content structure:
+- **Read**: `templates/SYSTEM-OVERVIEW-TEMPLATE.md`
+- **Purpose**: Understand the template chapters and example content requirements for system overview documents
+- **Key sections to follow**:
+  - Index and Overview (Statistics Overview, Module Quick Index)
+  - Section 1: System Overview (System Positioning, Business Domain Division with Mermaid diagram)
+  - Section 2: Functional Module Topology (Module Hierarchy, Module Dependency Diagram, Module List Index)
+  - Section 3: End-to-End Business Processes (Core Business Process List, Process-Module Mapping Matrix, Typical Business Process Diagram)
+  - Section 4: System Boundaries and Integration (External System Integration Diagram, Integration Interface List)
+  - Section 5: Requirement Assessment Guide
+  - Section 6: Change History
+
+### Step 1: Discover All Modules
+
+Find all `*-overview.md` files recursively under `modules_path`, including nested platform_type directories:
+
+```
+modules_path/
+├── platform_type_1/
+│   ├── module_1/
+│   │   └── module_1-overview.md
+│   └── module_2/
+│       └── module_2-overview.md
+└── platform_type_2/
+    └── module_3/
+        └── module_3-overview.md
+```
+
+**Example** (bizs knowledge):
+```
+knowledges/bizs/
+├── web-vue/
+│   ├── order/order-overview.md
+│   └── payment/payment-overview.md
+└── backend-java/
+    ├── order/order-overview.md
+    └── user/user-overview.md
+```
+
+Use recursive glob: `**/*-overview.md`
+Extract `platform_type` from the path structure for each discovered module.
+
+### Step 2: Read All Module Overviews
+
+For each discovered `*-overview.md`, extract:
+- Module name and purpose
+- Business domain
+- Platform type (from path: web-vue, backend-java, etc.)
+- Entity list (backend: DB entities; frontend: State/Props)
+- Dependencies (internal modules and external systems)
+- Feature count and API/Interface count
+
+**Multi-Tech Stack Aggregation Rules:**
+
+1. **Same-name modules from different platforms**: Treat as SEPARATE entries
+   - Display as: `order (web-vue)`, `order (backend-java)` in Module Quick Index
+   - Keep separate in all aggregations
+
+2. **Cross-platform dependencies**:
+   - web-vue/order may consume backend-java/order API
+   - backend-java/order may depend on backend-java/payment
+   - Show cross-platform dependencies clearly in Section 4
+
+3. **Entity aggregation**:
+   - Backend entities (DB tables, DTOs) and Frontend entities (Store State, Component Props) listed separately with platform annotation
+
+4. **Statistics**:
+   - Total modules = COUNT of all *-overview.md files
+   - Total entities = SUM across all modules
+   - Total APIs = SUM of backend APIs + frontend interfaces
+
+### Step 3: Build Module Index
+
+Create module index table:
+
+| Module | Domain | Purpose | Entities | APIs | Detail Doc |
+|--------|--------|---------|----------|------|------------|
+| order | Sales | Order lifecycle | Order, OrderItem | 8 | [View](order/order-overview.md) |
+| payment | Finance | Payment processing | Payment, Refund | 5 | [View](payment/payment-overview.md) |
+
+### Step 4: Build Dependency Graph
+
+**Extraction Rules:**
+1. Read Section 4 (Dependencies) from each module-overview.md
+2. Classify dependencies:
+   - **Internal**: Module-to-module dependencies within the system
+   - **External**: Third-party systems/services (Payment Gateway, ERP, etc.)
+
+3. **Internal dependencies** → Build directed graph:
+   - Node: module name (with platform_type annotation if multiple platforms)
+   - Edge: A → B means A depends on B
+   - Include cross-platform dependencies (e.g., web-vue/order → backend-java/order)
+
+4. **External dependencies** → Collect separately for Section 4: System Boundaries
+
+**Generate Mermaid dependency diagram:**
+- Show internal module dependencies only
+- Use `graph LR` for layout
+- Annotate platform_type if multiple platforms involved
+
+### Step 5: Identify Business Domains
+
+1. Read "Business Domain" field from each module-overview.md
+2. Collect unique domain names
+3. Group modules by domain (with platform_type):
+   
+   Example:
+   - Sales domain: web-vue/order, backend-java/order, backend-java/promotion
+   - User Management: web-vue/user, backend-java/user
+
+4. Generate domain-based Mermaid diagram with domains as subgraphs
+
+### Step 6: Identify End-to-End Flows
+
+Analyze cross-module dependencies to identify business flows:
+
+**Order-to-Payment Flow:**
+```
+USER → ORDER → INVENTORY → PAYMENT → NOTIFICATION
+```
+
+**Refund Flow:**
+```
+ORDER → PAYMENT → INVENTORY → NOTIFICATION
+```
+
+Create flow-module mapping matrix:
+
+| Flow / Module | ORDER | INVENTORY | PAYMENT | NOTIFICATION |
+|---------------|-------|-----------|---------|--------------|
+| Order-Payment | ✓ | ✓ | ✓ | ✓ |
+| Refund | ✓ | ✓ | ✓ | ✓ |
+
+### Step 7: Generate system-overview.md
+
+1. **Read Configuration**:
+   - Read `speccrew-workspace/docs/configs/tech-stack-mappings.json` → system tech stacks and display names
+   - Read `speccrew-workspace/docs/rules/mermaid-rule.md` → Mermaid diagram guidelines
+
+2. **Determine Technology Stack**:
+   - Extract platform types from discovered module paths
+   - Map platform_type to display name via tech-stack-mappings.json
+   - Example: `web-vue` → `Vue 3 + TypeScript`; `backend-java` → `Java 17 + Spring Boot`
+
+3. **Get Timestamp**:
+   - **CRITICAL**: Use the Skill tool to invoke `speccrew-get-timestamp` (no parameters needed, uses default format `YYYY-MM-DD-HHmmss`, returns timestamp string e.g. `2026-03-17-132645`)
+   - Use the returned timestamp as generation timestamp in document
+
+3. **Use template `templates/SYSTEM-OVERVIEW-TEMPLATE.md`, fill all sections**:
+   - Follow [Mermaid Diagram Guide](#mermaid-diagram-guide) for diagram generation
+
+**Section: Index and Overview** (NEW)
+- Generation timestamp (from get-timestamp skill)
+- Technology stack (from project config)
+- Statistics: module count, entity count, API count, flow count
+- Module quick index table
+
+**Section 1: System Overview**
+- System name from project config
+- Core positioning
+- Target users
+- Deployment type
+
+**Section 2: Module Topology**
+- Business domain diagram
+- Module hierarchy diagram
+- Module dependency diagram
+- Module index table (from Step 3)
+
+**Section 3: End-to-End Business Flows**
+- Core business process list
+- Flow-module mapping matrix (from Step 6)
+- Typical flow diagrams
+
+**Section 4: System Boundaries and Integration**
+- External system integration diagram
+- Integration interface list
+
+**Section 5: Requirement Assessment Guide**
+- Reference to `speccrew-pm-requirement-assess` skill
+- Quick location guide (which section to reference)
+
+Apply source traceability rules (see [Reference Guides > Source Traceability Guide](#source-traceability-guide))
+
+### Step 8: Report Results
+
+```
+System summarization completed:
+- Modules Processed: {{module_count}}
+- Entities Aggregated: {{entity_count}}
+- APIs Counted: {{api_count}}
+- Dependencies Mapped: {{dependency_count}}
+- Business Flows Identified: {{flow_count}}
+- Output: system-overview.md (complete)
+- Status: success
+```
+
+## Reference Guides
+
+### Mermaid Diagram Guide
+
+When generating Mermaid diagrams, follow these compatibility guidelines:
+
+**Key Requirements:**
+- Use only basic node definitions: `A[text content]`
+- No HTML tags (e.g., `<br/>`)
+- No nested subgraphs
+- No `direction` keyword
+- No `style` definitions
+- Use standard `graph TB/LR` syntax only
+
+**Diagram Types:**
+
+| Diagram Type | Use Case | Example |
+|---------|---------|------|
+| `graph TB/LR` | System structure, module dependencies | System architecture, module dependency graph |
+| `sequenceDiagram` | Cross-module interaction flow | User operation flow, service call chain |
+| `flowchart TD` | Business logic, conditional branches | State transition, exception handling |
+| `classDiagram` | Class structure, entity relationships | Data model, service interface |
+| `erDiagram` | Database table relationships | Entity relationship diagram |
+| `stateDiagram-v2` | State machine | Order status, approval status |
+
+### Source Traceability Guide
+
+Aggregate source file references from all module overview documents:
+
+> **Note**: Use relative paths from the generated document to the source file. Do NOT use `file://` protocol.
+
+1. **File Reference Block** (at document start):
+```markdown
+<cite>
+**Referenced Files**
+- Aggregated from all module overview documents
+- [OrderController.java](path/to/source/OrderController.java)
+- [PaymentController.java](path/to/source/PaymentController.java)
+</cite>
+```
+
+2. **Diagram Source** (after each Mermaid diagram):
+```markdown
+**Diagram Source**
+- Aggregated from: order-overview.md, payment-overview.md
+```
+
+3. **Section Source** (at end of document):
+```markdown
+**Section Source**
+- Aggregated from all module overview documents
+```
+
+## Return
+
+**Return Value (JSON format):**
+
+```json
+{
+  "status": "success|failed",
+  "output_file": "system-overview.md",
+  "message": "System summarization completed with N modules processed"
+}
+```
+
+---
+
+## Checklist
+
+- [ ] All {{module_name}}-overview.md files discovered
+- [ ] Module information extracted
+- [ ] Source file references aggregated from module documents
+- [ ] Module index table created
+- [ ] Dependency graph built
+- [ ] Business domains identified
+- [ ] End-to-end flows mapped
+- [ ] system-overview.md generated with all sections
+- [ ] Source traceability information included
+- [ ] Mermaid diagrams follow compatibility guidelines
+- [ ] Results reported
+

package/.speccrew/skills/speccrew-knowledge-system-summarize/templates/SYSTEM-OVERVIEW-TEMPLATE.md

@@ -0,0 +1,294 @@
+# System Overview Document - [System Name]
+
+> **Applicable Scenario**: Functional panoramic map of ToB software system, for AI Agent (PM Agent / Solution Agent) to read and understand system structure, module relationships, assisting requirement analysis and solution planning
+> **Target Audience**: devcrew-product-manager, devcrew-solution-manager, devcrew-developer
+> **Update Frequency**: Updated with major system iterations
+> 
+> <!-- AI-TAG: SYSTEM_OVERVIEW -->
+> <!-- AI-CONTEXT: Read this document to understand overall system structure, module division, business processes, used for requirement impact scope judgment and solution planning -->
+
+<cite>
+**Referenced Files**
+- Aggregated from all module overview documents
+- [{Module} Entry Point](../../{sourcePath}/{moduleEntryFile})
+  <!-- Examples: Java Backend: OrderController.java, Vue Frontend: OrderView.vue, React Frontend: OrderPage.tsx -->
+</cite>
+
+---
+
+## Index and Overview
+
+> **Generated At**: {{GeneratedAt}}  
+> **Tech Stack**: {{TechStack}}  
+> **Source Path**: `{{SourceRoot}}`
+
+### Statistics Overview
+
+| Metric | Count |
+|--------|-------|
+| Business Modules | {{ModuleCount}} |
+| Data Entities | {{EntityCount}} |
+| API Interfaces | {{ApiCount}} |
+| Business Processes | {{FlowCount}} |
+
+> **Note**: Data Entities include Backend Entities/Models and Frontend Types/Interfaces; API Interfaces include Backend REST APIs and Frontend Component Props/Events
+
+### Module Quick Index
+
+| Module Name | Platform | Business Domain | Module Responsibility | Entity Count | API/Interface Count | Detailed Document |
+|---|---|---|---|---|---|---|
+| *{module_name}* | *{platform_type}* | *{domain}* | *{description}* | *{count}* | *{count}* | [{module_name}-overview.md]({platform_type}/{module_name}/{module_name}-overview.md) |
+{{#each modules}}
+| {{name}} | {{platform}} | {{domain}} | {{description}} | {{entityCount}} | {{apiCount}} | [{{name}}-overview.md]({{platform}}/{{name}}/{{name}}-overview.md) |
+{{/each}}
+
+---
+
+## 1. System Overview
+
+### 1.1 System Positioning
+| Item | Description |
+|------|-------------|
+| System Name | {Fill in system name} |
+| Core Positioning | {One sentence describing what business problem the system solves} |
+| Target Users | {Main user groups, e.g., enterprise procurement staff, warehouse managers} |
+| Deployment Form | {BS/CS/Mobile/Hybrid} |
+
+### 1.2 Business Domain Division
+
+<!-- AI-TAG: DOMAIN_STRUCTURE -->
+<!-- AI-NOTE: Business domain division helps AI understand system boundaries and module ownership -->
+
+```mermaid
+graph TB
+    subgraph System["{System Name}"]
+        subgraph DA["Domain A - Core Domain Description"]
+            A1[Module A1]
+            A2[Module A2]
+            A3[Module A3]
+        end
+        
+        subgraph DB["Domain B - Support Domain Description"]
+            B1[Module B1]
+            B2[Module B2]
+        end
+        
+        subgraph DC["Domain C - Common Domain"]
+            UC[User Center]
+            PM[Permission Management]
+            NM[Notification]
+        end
+        
+        subgraph DD["Domain D - Integration Domain"]
+            TI[Third-party Interface]
+            DS[Data Sync]
+        end
+    end
+```
+
+**Diagram Source**
+- Aggregated from all module overview documents
+
+| Business Domain | Responsibility Description | Core Modules | Business Value |
+|-----------------|---------------------------|--------------|----------------|
+| {Domain A} | {One sentence description} | {Module A1, A2, A3} | {What problem it solves} |
+| {Domain B} | {One sentence description} | {Module B1, B2} | {What problem it solves} |
+
+---
+
+## 2. Functional Module Topology
+
+### 2.1 Module Hierarchy
+
+<!-- AI-TAG: MODULE_HIERARCHY -->
+<!-- AI-NOTE: Module hierarchy helps AI understand functional organization relationships -->
+
+```mermaid
+graph TD
+    SYS["{System Name}"]
+    
+    DA["Domain A"]
+    DB["Domain B"]
+    DC["Common Domain"]
+    
+    A1["Module A1 (Core)"]
+    A2["Module A2"]
+    A3["Module A3"]
+    B1["Module B1"]
+    B2["Module B2"]
+    UC["User Center"]
+    PM["Permission Management"]
+    
+    A1_1["Sub-feature A1-1"]
+    A1_2["Sub-feature A1-2"]
+    
+    SYS --> DA
+    SYS --> DB
+    SYS --> DC
+    
+    DA --> A1
+    DA --> A2
+    DA --> A3
+    DB --> B1
+    DB --> B2
+    DC --> UC
+    DC --> PM
+    
+    A1 --> A1_1
+    A1 --> A1_2
+```
+
+**Diagram Source**
+- Aggregated from module hierarchy analysis
+
+### 2.2 Module Dependency Diagram
+
+<!-- AI-TAG: MODULE_DEPENDENCIES -->
+<!-- AI-NOTE: Module dependency relationships are crucial for Solution Agent to plan solutions, affecting module call order and interface design -->
+
+```mermaid
+graph LR
+    A1["Module A1"] --> B1["Module B1"]
+    B1 --> C1["Module C1"]
+    A1 --> B2["Module B2"]
+    B1 --> B2
+```
+
+**Diagram Source**
+- Aggregated from module dependency analysis
+
+**Dependency Description:**
+- Arrow direction indicates dependency (A → B means A depends on B)
+- **Core Modules**: {Module A1, B1} - Business core
+- **External Dependencies**: {Module C1} - External systems
+- **Support Modules**: {Module B2} - Basic services
+
+### 2.3 Module List Index
+
+| Module Name | Platform | Business Domain | Module Responsibility | Detailed Document | Status |
+|---|---|---|---|---|---|
+| *{Module A1}* | *{backend/frontend}* | *{Domain A}* | *{One sentence responsibility}* | *[Link]({platform}/module-A1/module-A1-overview.md)* | ✅ Released |
+| {Module A1} | Java/Spring | {Domain A} | {One sentence responsibility} | [Link](backend/module-A1/module-A1-overview.md) | ✅ Released |
+| {Module A2} | Vue/React | {Domain A} | {One sentence responsibility} | [Link](frontend/module-A2/module-A2-overview.md) | 🚧 In Development |
+| {Module B1} | Java/Spring | {Domain B} | {One sentence responsibility} | [Link](backend/module-B1/module-B1-overview.md) | ✅ Released |
+
+---
+
+## 3. End-to-End Business Processes
+
+### 3.1 Core Business Process List
+
+| Process Name | Involved Modules | Process Description | Key Nodes |
+|--------------|------------------|---------------------|-----------|
+| {Process 1: e.g., Order Fulfillment} | {Module A1→B1→C1} | {Full process from order to delivery} | {Order→Review→Ship→Receive} |
+| {Process 2: e.g., Procurement Approval} | {Module A2→B2} | {From application to procurement completion} | {Apply→Approve→Order→Inbound} |
+
+### 3.2 Process-Module Mapping Matrix
+
+| Process/Module | Module A1 | Module A2 | Module B1 | Module B2 | Module C1 |
+|----------------|-----------|-----------|-----------|-----------|-----------|
+| Order Fulfillment | ✅ Create | - | ✅ Process | - | ✅ Settle |
+| Procurement Approval | - | ✅ Apply | - | ✅ Approve | - |
+| Inventory Count | ✅ Trigger | - | - | ✅ Execute | - |
+
+> ✅ indicates this process involves this module
+
+### 3.3 Typical Business Process Diagram
+
+<!-- AI-TAG: BUSINESS_FLOW -->
+<!-- AI-NOTE: Business processes help AI understand cross-module collaboration, important for PM Agent to judge requirement impact scope and Solution Agent to design solutions -->
+
+**Process Example: {Order Fulfillment Process}**
+
+```mermaid
+flowchart LR
+    Start([Start: Place Order]) --> A1[Module A1: Order Review]
+    A1 -->|Pass| B1[Module B1: Shipment Processing]
+    A1 -->|Reject| Reject[Exception Handling: Order Rejected]
+    B1 --> C1[Module C1: Settlement Processing]
+    C1 --> End([End: Order Complete])
+    Reject --> End
+```
+
+**Diagram Source**
+- Aggregated from cross-module flow analysis
+
+**Process Description:**
+| Step | Module | Processing Content | Output Status |
+|------|--------|-------------------|---------------|
+| 1 | Module A1 | Order review | Pass/Reject |
+| 2 | Module B1 | Shipment processing | Shipped |
+| 3 | Module C1 | Settlement processing | Settled |
+
+---
+
+## 4. System Boundaries and Integration
+
+### 4.1 External System Integration Diagram
+
+<!-- AI-TAG: EXTERNAL_INTEGRATION -->
+<!-- AI-NOTE: External integration information is crucial for Solution Agent to design APIs and integration solutions -->
+
+```mermaid
+graph TB
+    subgraph ThisSystem["This System"]
+        A[Module A]
+        B[Module B]
+        C[Module C]
+        D[Module D]
+    end
+    
+    ERP[ERP System]
+    PAY[Payment Platform]
+    LOG[Logistics Platform]
+    MSG[Message Gateway]
+    
+    A -->|Order Sync| ERP
+    B -->|Payment Request| PAY
+    C -->|Logistics Query| LOG
+    D -->|Notification Push| MSG
+```
+
+**Diagram Source**
+- Aggregated from external integration analysis
+
+### 4.2 Integration Interface List
+
+| Integration Party | Integration Type | Data Flow | Integration Content | Dependent Module |
+|-------------------|------------------|-----------|---------------------|------------------|
+| {ERP System} | {API} | {This System→ERP} | {Order Sync} | {Module A1} |
+| {Payment Platform} | {SDK} | {Bidirectional} | {Payment/Refund} | {Module C1} |
+
+---
+
+## 5. Requirement Assessment Guide
+
+> **Note**: For new requirement assessment, please use `devcrew-pm-requirement-assess` skill
+
+When PM Agent receives new requirements, should:
+
+1. **Read this document** to understand system structure and module relationships
+2. **Use assessment Skill** for standardized requirement analysis
+3. **Refer to the following information** to locate impact scope:
+   - Section 1.2: Business Domain Division
+   - Section 2.3: Module List Index
+   - Section 3.2: Process-Module Mapping Matrix
+   - Section 4.2: External Integration Interface List
+
+---
+
+## 6. Change History
+
+| Date | Version | Change Content | Changed Module | Change Type | Owner |
+|------|---------|----------------|----------------|-------------|-------|
+| {Date} | {v1.1} | {Added inventory alert} | {Module B1} | {New Feature} | {Zhang San} |
+| {Date} | {v1.0} | {System initial version} | {All} | {Initial Release} | {Li Si} |
+
+---
+
+**Document Status:** 📝 Draft / 👀 In Review / ✅ Published  
+**Last Updated:** {Date}  
+**Maintainer:** {Name}
+
+**Section Source**
+- Aggregated from all module overview documents