moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-library-mermaid/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: "moai-library-mermaid"
+description: "Enterprise Mermaid diagramming skill for Claude Code using MCP Playwright. Use when creating architecture diagrams, flowcharts, sequence diagrams, or visual documentation."
+version: 7.0.0
+category: "library"
+modularized: true
+updated: 2026-01-08
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+## Quick Reference
+
+Mermaid Diagram Expert v7.0.0 - Pure skill-based Mermaid rendering for Claude Code with MCP Playwright integration.
+
+This skill provides complete Mermaid 11.12.2 syntax for all 21 diagram types, MCP Playwright integration for rendering SVG and PNG outputs, ready-to-use examples and reference documentation, and enterprise diagram patterns with best practices.
+
+To invoke this skill, use the standard skill invocation pattern with the skill name moai-library-mermaid.
+
+### Supported Diagram Types
+
+The skill supports 21 diagram types organized into five categories:
+
+Structural Diagrams include Flowchart for process flows and decision trees, Sequence for interaction sequences and message flows, Class for object-oriented class relationships, ER for entity-relationship databases, Block for block diagram structures, and State for state machines and stateful flows.
+
+Timeline and Tracking diagrams include Timeline for chronological events and milestones, Gantt for project scheduling and timelines, and Gitgraph for Git workflow and branching visualization.
+
+Architecture and Design diagrams include C4 for Context, Container, Component, and Code architecture diagrams, Architecture for system architecture diagrams, and Requirement for requirements and traceability documentation.
+
+Data Visualization diagrams include Pie Chart for pie and donut charts, XY Chart for scatter and line charts, Sankey for flow diagrams with proportional width, and Radar for multi-variable comparison charts.
+
+User and Process diagrams include Mindmap for hierarchical mind mapping, User Journey for user experience flows, Kanban for board state visualization, and Packet for network packet structures.
+
+### MCP Playwright Integration
+
+This skill integrates with MCP Playwright for diagram rendering. The MCP configuration in the project mcp.json file enables the Playwright server, which can be configured to use npx with the anthropic-ai playwright-mcp package.
+
+To render diagrams, the MCP Playwright server must be configured in the project MCP settings, Node.js must be installed on the system, and Playwright must be available through npx.
+
+---
+
+## Implementation Guide
+
+### Diagram Syntax Examples
+
+Flowchart diagrams use the flowchart keyword followed by direction indicators such as TD for top-down or LR for left-right. Nodes are defined with brackets for shapes, and connections use arrow syntax with optional labels.
+
+```mermaid
+flowchart TD
+  Start([Start]) --> Input[Input Data]
+  Input --> Process{Validation}
+  Process -->|Valid| Calculate[Calculate Result]
+  Process -->|Invalid| Error[Error Handler]
+  Calculate --> Output[Output]
+  Error --> Output
+  Output --> End([End])
+```
+
+Sequence diagrams define participants first, then show interactions using arrow notation. Solid arrows represent synchronous calls, while dashed arrows represent responses.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant API
+  participant Database
+
+  User->>API: GET /users
+  API->>Database: SELECT * FROM users
+  Database-->>API: User records
+  API-->>User: JSON response
+```
+
+C4 Context diagrams use the C4Context keyword and define boundaries, persons, systems, and relationships using dedicated functions for each element type.
+
+```mermaid
+C4Context
+  title System Context diagram for Internet Banking System
+  Enterprise_Boundary(b0, "Banking System") {
+    Person(customer, "Banking Customer", "A customer using the banking system")
+    System(banking_system, "Internet Banking System", "Allows customers to check accounts")
+  }
+  System_Ext(mail_system, "E-mail System", "External mail system")
+  Rel(customer, banking_system, "Uses", "HTTP/HTTPS")
+  Rel(banking_system, mail_system, "Sends e-mail", "SMTP")
+```
+
+### Diagram Categories
+
+Process and Flow diagrams encompass Flowchart, Sequence, State, Timeline, Gitgraph, and User Journey diagram types. These diagrams represent dynamic processes and temporal sequences.
+
+Structure and Design diagrams include Class, ER, Block, Architecture, and C4 types. These diagrams represent static structures and system compositions.
+
+Data and Analytics diagrams cover Pie Chart, XY Chart, Sankey, and Radar types. These diagrams visualize quantitative data and comparative metrics.
+
+Planning and Organization diagrams include Gantt, Mindmap, Kanban, and Requirement types. These diagrams support project management and requirements tracking.
+
+Network and Technical diagrams currently include the Packet type with additional types reserved for future extensions.
+
+### Best Practices
+
+Clarity and Readability guidelines recommend using descriptive labels for all nodes, keeping diagram complexity moderate with a maximum of 20 to 30 nodes, and using consistent styling and color schemes throughout the diagram.
+
+Performance considerations include breaking complex diagrams into multiple smaller diagrams, using subgraphs to organize large flowcharts, and limiting text length within nodes to maintain rendering performance.
+
+Accessibility requirements include providing text alternatives for all diagrams, using both color and shape differentiation rather than color alone, and including descriptive titles and legends for context.
+
+Organization practices recommend grouping related diagrams in directories, using consistent naming conventions for diagram files, and documenting diagram purposes in comments within the source files.
+
+---
+
+## Advanced Patterns
+
+### Integration with MoAI-ADK
+
+This skill is designed for use within Claude Code during various development phases:
+
+During the architecture phase with the moai:1-plan command, create system design diagrams to visualize proposed solutions and component relationships.
+
+During the documentation phase with the moai:3-sync command, generate visual documentation including flowcharts, sequence diagrams, and architecture overviews.
+
+During code review phases, use diagrams to communicate system design visually and highlight areas of concern or proposed changes.
+
+During onboarding processes, create diagrams that help new team members understand architecture, data flows, and system boundaries.
+
+### Common Architecture Patterns
+
+API Architecture patterns typically use C4 diagrams to show system context with API gateway, backend services, database layer, and cache layer relationships.
+
+Microservices Flow patterns use sequence diagrams to illustrate client requests flowing through API gateway to individual services and their data stores.
+
+Data Pipeline patterns use flowchart diagrams to show data movement through extract, transform, load, validate, and report stages.
+
+### Context7 Integration
+
+For the latest Mermaid documentation, use Context7 library resolution and documentation tools. The current stable version is Mermaid 11.12.2 as of December 2025.
+
+Official documentation is available at mermaid.js.org/intro for general documentation and mermaid.js.org/config/setup/modules/mermaidAPI.html for API reference.
+
+Release notes and migration guides are available in the Mermaid GitHub repository releases section.
+
+### Learning Resources
+
+The official Mermaid site is located at mermaid.js.org. An interactive live editor for testing diagrams is available at mermaid.live. The complete syntax guide is at mermaid.js.org/syntax/.
+
+For working examples of all 21 diagram types, see the examples.md file in this skill directory. For extended reference documentation, see reference.md. For optimization techniques, see optimization.md. For complex diagram patterns, see advanced-patterns.md.
+
+---
+
+## Works Well With
+
+This skill integrates with several agents and other skills:
+
+Agents that work well with this skill include workflow-docs for documentation with diagrams, workflow-spec for SPEC diagrams and requirements visualization, and design-uiux for architecture visualization and interface documentation.
+
+Skills that complement this skill include moai-docs-generation for comprehensive documentation generation, moai-workflow-docs for diagram validation and documentation workflows, and moai-library-nextra for architecture documentation sites.
+
+Commands that utilize this skill include moai:3-sync for documentation with embedded diagrams and moai:1-plan for SPEC creation with visual architecture diagrams.
+
+Focus: Pure skill-based Mermaid rendering with MCP Playwright integration

moai_adk/templates/.claude/skills/moai-library-mermaid/examples.md

@@ -0,0 +1,270 @@
+# Example Diagrams - All 21 Types
+
+Quick reference examples for each Mermaid diagram type.
+
+## 1. Flowchart Example
+
+```mermaid
+flowchart TD
+ Start([Start]) --> Input[Input Data]
+ Input --> Process{Validation}
+ Process -->|Valid| Calculate[Calculate Result]
+ Process -->|Invalid| Error[Error Handler]
+ Calculate --> Output[Output]
+ Error --> Output
+ Output --> End([End])
+ 
+ style Start fill:#90EE90
+ style End fill:#FFB6C6
+ style Error fill:#FFB6C6
+```
+
+## 2. Sequence Diagram Example
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant API
+ participant Database
+ 
+ User->>API: GET /users
+ API->>Database: SELECT * FROM users
+ Database-->>API: User records
+ API-->>User: JSON response
+```
+
+## 3. Class Diagram Example
+
+```mermaid
+classDiagram
+ class Animal {
+ string name
+ eat()
+ }
+ class Dog {
+ bark()
+ }
+ Animal <|-- Dog
+```
+
+## 4. State Diagram Example
+
+```mermaid
+stateDiagram-v2
+ [*] --> Idle
+ Idle --> Working: start
+ Working --> Idle: complete
+ Working --> Error: fail
+ Error --> Idle: reset
+ Idle --> [*]
+```
+
+## 5. ER Diagram Example
+
+```mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ ORDER ||--|{ ORDER-ITEM : contains
+ PRODUCT ||--o{ ORDER-ITEM : "included in"
+ 
+ CUSTOMER {
+ int id PK
+ string email
+ }
+```
+
+## 6. Gantt Chart Example
+
+```mermaid
+gantt
+ title Project Schedule
+ dateFormat YYYY-MM-DD
+ 
+ section Phase 1
+ Design :des, 2025-01-01, 30d
+ Implementation :impl, after:des, 45d
+ Testing :test, after:impl, 20d
+```
+
+## 7. Mindmap Example
+
+```mermaid
+mindmap
+ root((Project))
+ Planning
+ Timeline
+ Resources
+ Execution
+ Development
+ Testing
+ Delivery
+ Deployment
+ Documentation
+```
+
+## 8. Timeline Example
+
+```mermaid
+timeline
+ title Development Timeline
+ 2025-01 : Project Start : Team Assembled
+ 2025-02 : Development
+ 2025-03 : Testing
+ 2025-04 : Launch
+```
+
+## 9. Git Graph Example
+
+```mermaid
+gitGraph
+ commit id: "Initial"
+ branch develop
+ commit id: "Feature 1"
+ checkout main
+ merge develop
+ commit id: "v1.0"
+```
+
+## 10. C4 Diagram Example
+
+```mermaid
+C4Context
+ title System Context
+ Person(user, "User", "Needs service")
+ System(system, "System", "Provides service")
+ Rel(user, system, "Uses")
+```
+
+## 11. User Journey Example
+
+```mermaid
+journey
+ title Onboarding
+ section Sign Up
+ Form : 4 : User
+ Verify : 3 : User
+ section Setup
+ Profile : 5 : User
+```
+
+## 12. Requirement Diagram Example
+
+```mermaid
+requirementDiagram
+ requirement REQ1 {
+ id: 1
+ text: Authentication
+ risk: High
+ }
+ element webapp {
+ type: Software
+ }
+ REQ1 - satisfies - webapp
+```
+
+## 13. Pie Chart Example
+
+```mermaid
+pie title Stack Distribution
+ "Frontend" : 40
+ "Backend" : 35
+ "DevOps" : 25
+```
+
+## 14. Quadrant Chart Example
+
+```mermaid
+quadrantChart
+ title Priority Matrix
+ x-axis Low --> High
+ y-axis Low --> High
+ Task A: [0.2, 0.8]
+ Task B: [0.8, 0.2]
+```
+
+## 15. XY Chart Example
+
+```mermaid
+xychart-beta
+ title Performance
+ x-axis [Jan, Feb, Mar]
+ y-axis "Response Time" 0 --> 300
+ line [150, 160, 145]
+```
+
+## 16. Block Diagram Example
+
+```mermaid
+block-beta
+ columns 3
+ A["Input"]
+ B["Process"]
+ C["Output"]
+ A --> B --> C
+```
+
+## 17. Kanban Example
+
+```mermaid
+kanban
+ section Todo
+ Task 1
+ Task 2
+ 
+ section Doing
+ Task 3
+ 
+ section Done
+ Task 4
+```
+
+## 18. Sankey Diagram Example
+
+```mermaid
+sankey-beta
+ Users, 100
+ Users, Development, 60
+ Users, QA, 40
+ Development, Production, 60
+ QA, Production, 40
+```
+
+## 19. Packet Diagram Example
+
+```mermaid
+packet-beta
+ 0-7: Source Port
+ 8-15: Dest Port
+ 16-31: Sequence
+ 32-47: ACK
+```
+
+## 20. Radar Chart Example
+
+```mermaid
+radar
+ title Skills
+ Frontend: 90
+ Backend: 85
+ DevOps: 75
+ Design: 70
+ max: 100
+```
+
+## 21. Architecture Diagram Example
+
+```mermaid
+graph TB
+ Web["Web App"]
+ API["API Server"]
+ DB["Database"]
+ Cache["Redis"]
+ 
+ Web --> API
+ API --> DB
+ API --> Cache
+```
+
+---
+
+For more examples, visit [mermaid.live](https://mermaid.live)