@vpxa/aikit 0.1.73 → 0.1.75

package/scaffold/general/skills/c4-architecture/SKILL.md

@@ -1,389 +0,0 @@
----
-name: c4-architecture
-description: "Generate architecture documentation using C4 model diagrams. Supports two output formats: Mermaid (md) for documentation and HTML/SVG for presentations. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: on-demand
-  inputs: [codebase, architecture]
-  outputs: [diagrams]
-  relatedSkills: [adr-skill]
----
-
-# C4 Architecture Documentation
-
-Generate software architecture documentation using C4 model diagrams in Mermaid syntax.
-
-## Workflow
-
-1. **Understand scope** - Determine which C4 level(s) are needed based on audience
-2. **Analyze codebase** - Explore the system to identify components, containers, and relationships
-3. **Generate diagrams** - Create Mermaid C4 diagrams at appropriate abstraction levels
-  > **Tip:** Use `present({ format: "html" })` to render diagrams as interactive visual output, rather than raw Mermaid code blocks. This provides a better viewing experience for stakeholders.
-4. **Document** - Write diagrams to markdown files with explanatory context
-
-## Format Selection
-
-This skill supports two output formats. Choose based on the audience and delivery method:
-
-> **Default rule:** When using the `present` tool to display architecture, **always use HTML/SVG format** (Method 2). It produces professional dark-themed diagrams with SVG icons, category colors, and summary cards. Use Mermaid only for saving to markdown docs or when the user explicitly requests it.
-
-| Format | Output | Best For | Delivery |
-|--------|--------|----------|----------|
-| **Mermaid (md)** | `.md` files with Mermaid code blocks | Developer docs, GitHub rendering, version control | Save to `docs/architecture/*.md` |
-| **HTML/SVG (html)** | Self-contained `.html` files | Stakeholder presentations, visual reviews, browser viewing | Save as `.html` or render via `present` tool |
-
-### Format Decision Tree
-
-```
-What is the goal?
-├── Save to docs / version control → Mermaid (md)
-├── Present via `present` tool → HTML/SVG (html) ← DEFAULT for present
-├── User says "Mermaid" or "markdown" → Mermaid (md)
-└── User says "show", "visualize", "present" → HTML/SVG (html)
-```
-
-### Present Tool Integration
-
-Both formats work with the `present` tool:
-
-**Mermaid format** - Use a `mermaid` content block:
-```js
-present({
-  format: "html",  // or "browser"
-  title: "System Architecture",
-  content: [
-    { type: "mermaid", title: "C4 Container Diagram", value: "C4Container\n  title Container Diagram\n  ..." }
-  ]
-})
-```
-
-**HTML/SVG format** - Use a `markdown` block with the full HTML structure. Pair with `metrics` and `cards` blocks for a complete dashboard. See [references/html-design-system.md](references/html-design-system.md#present-tool-integration) for the full composition pattern.
-
-```js
-present({
-  format: "html",  // or "browser" - both work
-  title: "System Architecture",
-  content: [
-    { type: "metrics", title: "Overview", value: [{ label: "Services", value: "6" }, ...] },
-    { type: "markdown", title: "Architecture Diagram", value: "<div class='arch-diagram'>...(inline SVG + CSS)...</div>" },
-    { type: "cards", title: "Summary", value: [{ title: "Frontend", body: "React SPA" }, ...] }
-  ]
-})
-```
-
-## C4 Diagram Levels
-
-Select the appropriate level based on the documentation need:
-
-| Level | Diagram Type | Audience | Shows | When to Create |
-|-------|-------------|----------|-------|----------------|
-| 1 | **C4Context** | Everyone | System + external actors | Always (required) |
-| 2 | **C4Container** | Technical | Apps, databases, services | Always (required) |
-| 3 | **C4Component** | Developers | Internal components | Only if adds value |
-| 4 | **C4Deployment** | DevOps | Infrastructure nodes | For production systems |
-| - | **C4Dynamic** | Technical | Request flows (numbered) | For complex workflows |
-
-**Key Insight:** "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value.
-
-## Quick Start Examples
-
-### System Context (Level 1)
-```mermaid
-C4Context
-  title System Context - Workout Tracker
-
-  Person(user, "User", "Tracks workouts and exercises")
-  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
-  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")
-
-  Rel(user, app, "Uses")
-  Rel(app, browser, "Persists data to", "IndexedDB")
-```
-
-### Container Diagram (Level 2)
-```mermaid
-C4Container
-  title Container Diagram - Workout Tracker
-
-  Person(user, "User", "Tracks workouts")
-
-  Container_Boundary(app, "Workout Tracker PWA") {
-    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
-    Container(pinia, "State Management", "Pinia", "Manages application state")
-    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
-  }
-
-  Rel(user, spa, "Uses")
-  Rel(spa, pinia, "Reads/writes state")
-  Rel(pinia, indexeddb, "Persists", "Dexie ORM")
-```
-
-### Component Diagram (Level 3)
-```mermaid
-C4Component
-  title Component Diagram - Workout Feature
-
-  Container(views, "Views", "Vue Router pages")
-
-  Container_Boundary(workout, "Workout Feature") {
-    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
-    Component(useTimer, "useTimer", "Composable", "Timer state machine")
-    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
-  }
-
-  Rel(views, useWorkout, "Uses")
-  Rel(useWorkout, useTimer, "Controls")
-  Rel(useWorkout, workoutRepo, "Saves to")
-```
-
-### Dynamic Diagram (Request Flow)
-```mermaid
-C4Dynamic
-  title Dynamic Diagram - User Sign In Flow
-
-  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
-  Container(spa, "Single-Page App", "React", "Banking UI")
-
-  Container_Boundary(api, "API Application") {
-    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
-    Component(security, "Security Service", "JWT", "Validates credentials")
-  }
-
-  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
-  Rel(signIn, security, "2. Validate")
-  Rel(security, db, "3. Query user", "SQL")
-
-  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")
-```
-
-### Deployment Diagram
-```mermaid
-C4Deployment
-  title Deployment Diagram - Production
-
-  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
-    Container(spa, "SPA", "React", "Web application")
-  }
-
-  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
-    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
-      Container(api, "API Service", "Node.js", "REST API")
-    }
-    Deployment_Node(rds, "RDS", "db.r5.large") {
-      ContainerDb(db, "Database", "PostgreSQL", "Application data")
-    }
-  }
-
-  Rel(spa, api, "API calls", "HTTPS")
-  Rel(api, db, "Reads/writes", "JDBC")
-```
-
-## HTML/SVG Format
-
-For HTML/SVG output, use the design system and template from the references.
-
-The component type registry, color palette, typography, and layout rules are defined in [references/html-design-system.md](references/html-design-system.md). This is the single source of truth - update colors, types, and icons there.
-
-Copy and customize [references/html-template.html](references/html-template.html) for each diagram. The template is self-contained and opens directly in any browser.
-
-### Component Categories
-
-See the design system for the full sub-type registry and icon slots.
-
-- Frontend - stroke `#22d3ee`
-- Backend - stroke `#34d399`
-- Data - stroke `#a78bfa`
-- Infrastructure - stroke `#fbbf24`
-- Messaging - stroke `#fb923c`
-- Security - stroke `#fb7185`
-- External - stroke `#94a3b8`
-- Monitoring - stroke `#38bdf8`
-
-### Minimal Component Box Example
-
-Use the design system's inline SVG component pattern inside the HTML template's main `<svg>`:
-
-```svg
-<g class="node backend">
-  <rect x="280" y="210" width="190" height="60" rx="6" />
-  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>
-  <text class="node-title" x="294" y="243">API Service</text>
-  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>
-</g>
-```
-
-## Element Syntax
-
-### People and Systems
-```
-Person(alias, "Label", "Description")
-Person_Ext(alias, "Label", "Description")       # External person
-System(alias, "Label", "Description")
-System_Ext(alias, "Label", "Description")       # External system
-SystemDb(alias, "Label", "Description")         # Database system
-SystemQueue(alias, "Label", "Description")      # Queue system
-```
-
-### Containers
-```
-Container(alias, "Label", "Technology", "Description")
-Container_Ext(alias, "Label", "Technology", "Description")
-ContainerDb(alias, "Label", "Technology", "Description")
-ContainerQueue(alias, "Label", "Technology", "Description")
-```
-
-### Components
-```
-Component(alias, "Label", "Technology", "Description")
-Component_Ext(alias, "Label", "Technology", "Description")
-ComponentDb(alias, "Label", "Technology", "Description")
-```
-
-### Boundaries
-```
-Enterprise_Boundary(alias, "Label") { ... }
-System_Boundary(alias, "Label") { ... }
-Container_Boundary(alias, "Label") { ... }
-Boundary(alias, "Label", "type") { ... }
-```
-
-### Relationships
-```
-Rel(from, to, "Label")
-Rel(from, to, "Label", "Technology")
-BiRel(from, to, "Label")                        # Bidirectional
-Rel_U(from, to, "Label")                        # Upward
-Rel_D(from, to, "Label")                        # Downward
-Rel_L(from, to, "Label")                        # Leftward
-Rel_R(from, to, "Label")                        # Rightward
-```
-
-### Deployment Nodes
-```
-Deployment_Node(alias, "Label", "Type", "Description") { ... }
-Node(alias, "Label", "Type", "Description") { ... }  # Shorthand
-```
-
-## Styling and Layout
-
-### Layout Configuration
-```
-UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
-```
-- `$c4ShapeInRow` - Number of shapes per row (default: 4)
-- `$c4BoundaryInRow` - Number of boundaries per row (default: 2)
-
-### Element Styling
-```
-UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")
-```
-
-### Relationship Styling
-```
-UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")
-```
-Use `$offsetX` and `$offsetY` to fix overlapping relationship labels.
-
-## Best Practices
-
-### Essential Rules
-
-1. **Every element must have**: Name, Type, Technology (where applicable), and Description
-2. **Use unidirectional arrows only** - Bidirectional arrows create ambiguity
-3. **Label arrows with action verbs** - "Sends email using", "Reads from", not just "uses"
-4. **Include technology labels** - "JSON/HTTPS", "JDBC", "gRPC"
-5. **Stay under 20 elements per diagram** - Split complex systems into multiple diagrams
-
-### Clarity Guidelines
-
-1. **Start at Level 1** - Context diagrams help frame the system scope
-2. **One diagram per file** - Keep diagrams focused on a single abstraction level
-3. **Meaningful aliases** - Use descriptive aliases (e.g., `orderService` not `s1`)
-4. **Concise descriptions** - Keep descriptions under 50 characters when possible
-5. **Always include a title** - "System Context diagram for [System Name]"
-
-### What to Avoid
-
-See [references/common-mistakes.md](references/common-mistakes.md) for detailed anti-patterns:
-- Confusing containers (deployable) vs components (non-deployable)
-- Modeling shared libraries as containers
-- Showing message brokers as single containers instead of individual topics
-- Adding undefined abstraction levels like "subcomponents"
-- Removing type labels to "simplify" diagrams
-
-## Microservices Guidelines
-
-### Single Team Ownership
-Model each microservice as a **container** (or container group):
-```mermaid
-C4Container
-  title Microservices - Single Team
-
-  System_Boundary(platform, "E-commerce Platform") {
-    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
-    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
-    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
-    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
-  }
-```
-
-### Multi-Team Ownership
-Promote microservices to **software systems** when owned by separate teams:
-```mermaid
-C4Context
-  title Microservices - Multi-Team
-
-  Person(customer, "Customer", "Places orders")
-  System(orderSystem, "Order System", "Team Alpha")
-  System(inventorySystem, "Inventory System", "Team Beta")
-  System(paymentSystem, "Payment System", "Team Gamma")
-
-  Rel(customer, orderSystem, "Places orders")
-  Rel(orderSystem, inventorySystem, "Checks stock")
-  Rel(orderSystem, paymentSystem, "Processes payment")
-```
-
-### Event-Driven Architecture
-Show individual topics/queues as containers, NOT a single "Kafka" box:
-```mermaid
-C4Container
-  title Event-Driven Architecture
-
-  Container(orderService, "Order Service", "Java", "Creates orders")
-  Container(stockService, "Stock Service", "Java", "Manages inventory")
-  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")
-  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")
-
-  Rel(orderService, orderTopic, "Publishes to")
-  Rel(stockService, orderTopic, "Subscribes to")
-  Rel(stockService, stockTopic, "Publishes to")
-  Rel(orderService, stockTopic, "Subscribes to")
-```
-
-## Output Location
-
-Write architecture documentation to `docs/architecture/` with naming convention:
-- `c4-context.md` - System context diagram
-- `c4-containers.md` - Container diagram
-- `c4-components-{feature}.md` - Component diagrams per feature
-- `c4-deployment.md` - Deployment diagram
-- `c4-dynamic-{flow}.md` - Dynamic diagrams for specific flows
-
-## Audience-Appropriate Detail
-
-| Audience | Recommended Diagrams |
-|----------|---------------------|
-| Executives | System Context only |
-| Product Managers | Context + Container |
-| Architects | Context + Container + key Components |
-| Developers | All levels as needed |
-| DevOps | Container + Deployment |
-
-## References
-
-- [references/c4-syntax.md](references/c4-syntax.md) - Complete Mermaid C4 syntax
-- [references/common-mistakes.md](references/common-mistakes.md) - Anti-patterns to avoid
-- [references/advanced-patterns.md](references/advanced-patterns.md) - Microservices, event-driven, deployment
-- [references/html-design-system.md](references/html-design-system.md) - Centralized HTML/SVG design system (types, colors, icons, present integration)
-- [references/html-template.html](references/html-template.html) - Self-contained HTML template for C4 diagrams