@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/integrations/claude_code/skills/dr_09_ux_layer/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: LAYER_09_UX
+description: Expert knowledge for UX Layer modeling in Documentation Robotics
+triggers:
+  [
+    "UX",
+    "user interface",
+    "UI",
+    "view",
+    "component",
+    "screen",
+    "form",
+    "user experience",
+    "state machine"
+  ]
+version: 0.8.3
+---
+
+# UX Layer Skill
+
+**Layer Number:** 09
+**Specification:** Metadata Model Spec v0.8.3
+**Purpose:** Defines user experience using Three-Tier Architecture, specifying views, components, state machines, and interactions.
+
+---
+
+## Layer Overview
+
+The UX Layer captures **user experience design**:
+
+- **VIEWS** - Screens/pages, modals, dialogs, drawers, and panels
+- **COMPONENTS** - UI components (forms, tables, charts, cards)
+- **STATE MACHINES** - Experience states and transitions
+- **ACTIONS** - Interactive elements (buttons, links, voice commands)
+- **LAYOUTS** - Layout configurations (grid, flex, etc.)
+
+This layer uses **Three-Tier Architecture** (v0.5.0+):
+
+1. **Library Tier** - Reusable design system components
+2. **Application Tier** - Application-wide configuration
+3. **Experience Tier** - Experience-specific views and flows
+
+**Central Entity:** The **View** (page, modal, dialog, drawer, or panel) is the core modeling unit.
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "UX", "UI", "view", "screen", "component", "form"
+- Wants to define user interfaces or user experiences
+- Asks about state machines, transitions, or user flows
+- Needs to model screens, forms, or interactive elements
+- Wants to link UX to navigation, APIs, or business processes
+
+---
+
+## Entity Types
+
+> **CLI Introspection:** Run `dr schema types ux` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type.
+
+### Three-Tier Architecture (22 entities)
+
+**Library Tier:**
+
+- **UXLibrary** - Container for library components
+- **LibraryComponent** - Reusable component (form-field, table, chart, card)
+- **LibrarySubView** - Reusable component groupings
+- **StatePattern** - Reusable state machine patterns
+- **ActionPattern** - Reusable action definitions
+- **StateActionTemplate** - Reusable template for state lifecycle actions (required: `action`)
+- **TransitionTemplate** - Reusable template for state transitions (required: `to`, `trigger`)
+- **TableColumn** - Column definition for table components (required: `header`, `field`)
+- **ChartSeries** - Data series configuration for chart components (required: `label`, `dataField`)
+
+**Application Tier:**
+
+- **UXApplication** - Application-wide UX configuration
+
+**Experience Tier:**
+
+- **UXSpec** - Container for experience specification
+- **View** - Screen/page/modal/dialog/drawer/panel (required: `type`)
+- **SubView** - Component grouping within view
+- **ComponentInstance** - Instance of library component
+- **ComponentReference** - Reference to a library component by ID (required: `ref`)
+- **ActionComponent** - Interactive element (button, link, voice command)
+- **ExperienceState** - State in state machine
+- **StateAction** - Action during state lifecycle
+- **StateTransition** - Transition between states
+- **LayoutConfig** - Layout configuration for views and components (required: `type`)
+- **DataConfig** - Data binding configuration (required: `source`, `target`)
+- **ErrorConfig** - Error handling configuration for components
+
+---
+
+## Type Decision Tree
+
+Use this decision tree **before assigning a type** to any UX element.
+
+```
+LIBRARY TIER — reusable, cross-experience artifacts
+├── Component library container?                               → ux.uxlibrary
+├── Reusable UI component type (form, table, chart, card)?    → ux.librarycomponent
+├── Reusable grouping of components?                          → ux.librarysubview
+├── Reusable state machine pattern?                           → ux.statepattern
+├── Reusable action definition?                               → ux.actionpattern
+├── Reusable parameterized state action template?             → ux.stateactiontemplate
+│     (no lifecycle binding; has parameters array)
+├── Reusable transition template with animation?              → ux.transitiontemplate
+│     (has animationType/duration/easing; both `to` and `trigger` required)
+├── Column definition for a table component?                  → ux.tablecolumn
+└── Data series definition for a chart component?             → ux.chartseries
+
+APPLICATION TIER — app-wide UX configuration
+└── Application-wide UX configuration (channel required)?     → ux.uxapplication
+
+EXPERIENCE TIER — specific to a view or experience
+├── Top-level experience specification container?             → ux.uxspec
+├── Screen, page, modal, dialog, drawer, or panel?           → ux.view
+│     (required: type enum — page|modal|dialog|drawer|panel|overlay|embedded|full-screen)
+├── Section or grouping within a view?                        → ux.subview
+├── Placed instance of a component on a view?                 → ux.componentinstance
+│     (has `order` for positioning and `props` for overrides)
+├── Typed reference to a component by slot or variant?        → ux.componentreference
+│     (ref required; use when targeting a specific variant or slot, not placement)
+├── Interactive element (button, link, voice command)?        → ux.actioncomponent
+├── State in an experience state machine?                     → ux.experiencestate
+├── Concrete action bound to a state lifecycle?               → ux.stateaction
+│     (has lifecycle: on-enter|on-exit|on-transition and timing; no parameters)
+├── Concrete transition with trigger and optional guard?      → ux.statetransition
+│     (trigger required; has guard conditions and inline actions; no animation)
+├── Layout configuration (grid, flex, block, etc.)?           → ux.layoutconfig
+├── Data binding configuration (source → target)?             → ux.dataconfig
+└── Error handling configuration?                             → ux.errorconfig
+```
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (UX → Other Layers):**
+
+- `motivation.*` → Motivation Layer (UX supports goals)
+- `business.*` → Business Layer (UX realizes business processes)
+- `api.*` → API Layer (API calls from components)
+- `data-model.*` → Data Model Layer (schema references for data-bound components)
+- `navigation.*` → Navigation Layer (routing to views)
+
+**Incoming (Other Layers → UX):**
+
+- Navigation Layer → UX (routes point to views)
+- Business Layer → UX (business processes trigger UX flows)
+
+---
+
+## Design Best Practices
+
+1. **Reusability** - Use library components for consistency
+2. **State machines** - Model complex flows with states/transitions
+3. **Error handling** - Define error states, ErrorConfig, and recovery transitions
+4. **Accessibility** - Consider accessibility requirements
+5. **Responsive** - Design for multiple screen sizes
+6. **Performance** - Set performance targets (load time, interaction latency)
+
+---
+
+## React Flow / Graph Visualization Patterns
+
+When the codebase uses a graph visualization library (React Flow, D3, Cytoscape), apply these patterns in addition to the standard UX decision tree.
+
+### Configuration-Driven Node Renderer
+
+```tsx
+// src/core/nodes/components/UnifiedNode.tsx
+export function UnifiedNode({ data }: NodeProps<UnifiedNodeData>) {
+  const config = nodeConfigLoader.get(data.elementType);
+  return <div style={config.styles}>{data.name}</div>;
+}
+// src/core/nodes/nodeConfig.json  ← drives all 20 node type styles
+```
+
+→ `UnifiedNode.tsx` → `ux.librarycomponent.unified-node` (type: graph-node)
+→ `nodeConfig.json` → `data-model.objectschema.node-config`
+→ Do NOT create 20 separate elements for each node type in the config — the configuration-driven system as a whole is one `librarycomponent`
+
+### Custom Edge Type
+
+```tsx
+// src/core/edges/ElbowEdge.tsx
+export function ElbowEdge(props: EdgeProps) { ... }
+```
+
+→ `ux.librarycomponent.elbow-edge` (type: graph-edge)
+→ Each distinct custom edge type → one `librarycomponent`
+
+### Layer Container / Swimlane Node
+
+```tsx
+// src/core/nodes/LayerContainerNode.tsx
+export function LayerContainerNode({ data }: NodeProps) { ... }
+```
+
+→ `ux.librarycomponent.layer-container-node` (type: graph-container)
+
+### Graph Canvas Component
+
+```tsx
+// src/core/components/GraphViewer.tsx
+export function GraphViewer({ nodes, edges }) {
+  return <ReactFlow nodeTypes={nodeTypes} edgeTypes={edgeTypes} />;
+}
+```
+
+→ Already captured in the application layer as `ApplicationComponent`. Do NOT add it again as a UX element — the `ux.view.*` that represents the graph page already serves this purpose in the UX layer.
+
+### Sub-components (field lists, tooltips, badges)
+
+`FieldList.tsx`, `FieldTooltip.tsx`, `RelationshipBadge.tsx`, `BadgeRenderer.tsx` are internal implementation details of `UnifiedNode`. Do NOT add them as separate `librarycomponent` entries.
+
+---
+
+## Common Commands
+
+```bash
+# Add view
+dr add ux view "User Profile" --description "User profile page"
+
+# Add component instance
+dr add ux component-instance "Profile Form"
+
+# List views
+dr list ux --type view
+
+# Validate UX layer
+dr validate --layers ux
+
+# Export UX documentation
+dr export markdown --layers ux
+```
+
+---
+
+## Example: Login Screen
+
+A login page with a form component, state machine, and data binding:
+
+```bash
+# Add the view (page type, routable)
+dr add ux view "Login" --description "Login page" --attributes '{"type":"page","routable":true}'
+# → id: ux.view.login
+
+# Add a form component from the library
+dr add ux librarycomponent "Login Form" --description "Email/password form" --attributes '{"type":"form"}'
+# → id: ux.librarycomponent.login-form
+
+# Place the form as an instance on the login view
+dr add ux componentinstance "Login Form Instance"
+# → id: ux.componentinstance.login-form-instance
+
+# Add states for the login flow
+dr add ux experiencestate "Idle"
+dr add ux experiencestate "Submitting"
+dr add ux experiencestate "Error"
+
+# Add a transition: click submit → submitting
+dr add ux statetransition "Submit Clicked" --attributes '{"trigger":"click","to":"ux.experiencestate.submitting"}'
+# → id: ux.statetransition.submit-clicked
+
+# Add data config binding the form to the API
+dr add ux dataconfig "Login Data" --attributes '{"source":"api","target":"ux.componentinstance.login-form-instance"}'
+
+# Add error config for failed login
+dr add ux errorconfig "Login Error" --description "Show inline error on auth failure"
+```
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Not using library components (inconsistent UX)
+- ❌ Complex state machines without documentation
+- ❌ Not linking to API operations or navigation routes
+- ❌ Missing error states and handling
+- ❌ No performance targets defined
+
+---
+
+## Coverage Completeness Checklist
+
+Before declaring UX layer extraction complete, verify each type was considered:
+
+- [ ] **ux.uxlibrary** — Component library container
+- [ ] **ux.librarycomponent** — Reusable UI component (form-field, table, chart, card)
+- [ ] **ux.librarysubview** — Reusable grouping of components
+- [ ] **ux.statepattern** — Reusable state machine pattern
+- [ ] **ux.actionpattern** — Reusable action definition
+- [ ] **ux.stateactiontemplate** — Reusable state action template
+- [ ] **ux.transitiontemplate** — Reusable transition template
+- [ ] **ux.tablecolumn** — Column definition for table components
+- [ ] **ux.chartseries** — Data series configuration for chart components
+- [ ] **ux.uxapplication** — Application-wide UX configuration
+- [ ] **ux.uxspec** — Experience specification container
+- [ ] **ux.view** — Screen, page, modal, dialog, drawer, or panel (required: `type`)
+- [ ] **ux.subview** — Section or panel within a view
+- [ ] **ux.componentinstance** — Instance of a library component on a view
+- [ ] **ux.componentreference** — Reference to a library component by ID
+- [ ] **ux.actioncomponent** — Interactive element (button, link, voice command)
+- [ ] **ux.experiencestate** — State in experience state machine
+- [ ] **ux.stateaction** — Action executed during a state lifecycle
+- [ ] **ux.statetransition** — Transition between states
+- [ ] **ux.layoutconfig** — Layout configuration (grid, flex, block, etc.)
+- [ ] **ux.dataconfig** — Data binding configuration (source → target)
+- [ ] **ux.errorconfig** — Error handling configuration
+
+If any type has ZERO elements, explicitly decide:
+"This type doesn't apply to this codebase" with reasoning.

package/dist/integrations/claude_code/skills/dr_10_navigation_layer/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: LAYER_10_NAVIGATION
+description: Expert knowledge for Navigation Layer modeling in Documentation Robotics
+triggers:
+  [
+    "navigation",
+    "routing",
+    "route",
+    "flow",
+    "navigation guard",
+    "redirect",
+    "navigation flow"
+  ]
+version: 0.8.3
+---
+
+# Navigation Layer Skill
+
+**Layer Number:** 10
+**Specification:** Metadata Model Spec v0.8.3
+**Purpose:** Defines multi-modal navigation flows, routes, guards, and transitions between views.
+
+---
+
+## Layer Overview
+
+The Navigation Layer captures **navigation and routing**:
+
+- **GRAPH** - Top-level container for the entire navigation model (`navigationgraph`)
+- **ROUTES** - URL paths to views; types include `public`, `protected`, `redirect`, `alias`, `lazy` (`route`)
+- **ROUTE METADATA** - Auth requirements, layout, keepAlive metadata per route (`routemeta`)
+- **BREADCRUMBS** - Breadcrumb trail configuration per route (`breadcrumbconfig`)
+- **GUARDS** - Pre-navigation authorization/validation checks (`navigationguard`)
+- **GUARD CONDITIONS** - Boolean expressions evaluated by guards (`guardcondition`)
+- **GUARD ACTIONS** - Actions on guard failure: redirect, block, notify, prompt (`guardaction`)
+- **FLOWS** - Multi-step navigation sequences (`navigationflow`)
+- **FLOW STEPS** - Individual steps within a flow (`flowstep`)
+- **TRANSITIONS** - Directed transitions between routes with triggers (`navigationtransition`)
+- **CONTEXT** - Navigation-scoped context variables (`contextvariable`)
+
+This layer uses **Multi-Modal Navigation** supporting web, mobile, voice, and other modalities.
+
+**Central Entity:** The **Route** (URL path to view) is the core modeling unit.
+
+---
+
+## Entity Types
+
+> **CLI Introspection:** Run `dr schema types navigation` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type.
+
+### Core Navigation Entities (11 entities)
+
+| Entity Type              | Description                                                       |
+| ------------------------ | ----------------------------------------------------------------- |
+| **NavigationGraph**      | Top-level container representing the complete navigation model    |
+| **Route**                | URL path mapped to a view; the core modeling unit                 |
+| **RouteMeta**            | Auth, layout, and lifecycle metadata attached to a route          |
+| **NavigationGuard**      | Authorization/validation check executed before navigation         |
+| **GuardCondition**       | Boolean expression evaluated by a navigation guard                |
+| **GuardAction**          | Action taken when a guard fails (redirect, block, notify, prompt) |
+| **NavigationFlow**       | Multi-step navigation sequence                                    |
+| **FlowStep**             | A single step within a navigation flow                            |
+| **NavigationTransition** | Directed transition between two routes                            |
+| **ContextVariable**      | Navigation-scoped context data passed between routes              |
+| **BreadcrumbConfig**     | Breadcrumb trail configuration for a route                        |
+
+---
+
+## Type Decision Tree
+
+Use this decision tree **before assigning a type** to any navigation element.
+
+```
+Is this the top-level navigation model for an application?
+  → navigation.navigationgraph.*
+
+Is this a URL path/route that maps to a view?
+  → navigation.route.*
+
+Is this metadata about a route (auth requirements, layout, keepAlive)?
+  → navigation.routemeta.*
+
+Is this a breadcrumb configuration for a route?
+  → navigation.breadcrumbconfig.*
+
+Is this a guard that checks conditions before allowing navigation?
+  → navigation.navigationguard.*
+
+Is this a boolean expression/predicate evaluated inside a guard?
+  → navigation.guardcondition.*
+
+Is this the action to take when a guard fails (redirect, block, notify, prompt)?
+  → navigation.guardaction.*
+
+Is this a named multi-step navigation sequence (wizard, checkout, onboarding)?
+  → navigation.navigationflow.*
+
+Is this a single step within a navigation flow?
+  → navigation.flowstep.*
+
+Is this a directed transition between two specific routes with a trigger?
+  → navigation.navigationtransition.*
+
+Is this a context variable scoped to the navigation session?
+  → navigation.contextvariable.*
+```
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "navigation", "routing", "routes", "flows"
+- Wants to define URL paths or route guards
+- Asks about multi-step flows or navigation transitions
+- Needs to model navigation between screens
+- Wants to link navigation to UX views or business processes
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (Navigation → Other Layers):**
+
+- `view-ref` → UX Layer (which view does this route show?)
+- `business.realizes-process` → Business Layer (what process does this flow realize?)
+- `security.required-roles` → Security Layer (authorization requirements)
+- `apm.flow-metrics` → APM Layer (navigation analytics)
+
+**Incoming (Other Layers → Navigation):**
+
+- UX Layer → Navigation (views reference routes)
+- Business Layer → Navigation (processes trigger flows)
+
+---
+
+## Design Best Practices
+
+1. **Guards** - Add navigation guards for protected routes
+2. **Context** - Pass necessary context between routes
+3. **Analytics** - Track navigation flows for insights
+4. **Error handling** - Define fallback routes for errors
+5. **Deep linking** - Support deep linking for all routes
+6. **SEO** - Consider SEO requirements for public routes
+7. **Performance** - Lazy-load routes when appropriate
+
+---
+
+## Common Commands
+
+```bash
+# Add navigation graph (one per application)
+dr add navigation navigationgraph "My App Navigation"
+
+# Add route (types: public | protected | redirect | alias | lazy)
+dr add navigation route "User Profile Route" --description "User profile page route"
+
+# Add route metadata
+dr add navigation routemeta "Profile Route Meta"
+
+# Add breadcrumb configuration
+dr add navigation breadcrumbconfig "Profile Breadcrumb"
+
+# Add navigation guard
+dr add navigation navigationguard "Auth Guard"
+
+# Add guard condition
+dr add navigation guardcondition "Is Authenticated"
+
+# Add guard action (on failure)
+dr add navigation guardaction "Redirect To Login"
+
+# Add navigation flow
+dr add navigation navigationflow "Checkout Flow"
+
+# Add flow step
+dr add navigation flowstep "Cart Review Step"
+
+# Add transition between routes
+dr add navigation navigationtransition "Cart To Shipping"
+
+# Add context variable
+dr add navigation contextvariable "Cart ID"
+
+# List by type
+dr list navigation --type route
+dr list navigation --type navigationguard
+
+# Validate navigation layer
+dr validate --layers navigation
+
+# Export navigation map
+dr export plantuml --layers navigation
+```
+
+---
+
+## Example: Protected Profile Route
+
+```yaml
+id: navigation.route.user-profile
+name: "User Profile Route"
+type: route
+properties:
+  path: /profile/:userId
+  view-ref: ux.view.user-profile
+  guards:
+    - navigation.navigationguard.authentication
+    - navigation.navigationguard.profile-ownership
+  parameters:
+    - name: userId
+      type: string
+      format: uuid
+      required: true
+  meta:
+    title: "User Profile"
+    requiresAuth: true
+    allowedRoles:
+      - user
+      - admin
+  contextVariables:
+    - name: currentUserId
+      source: auth.user.id
+  dataMapping:
+    - source: route.params.userId
+      target: view.data.userId
+  security:
+    required-roles:
+      - security.role.authenticated-user
+  business:
+    realizes-process: business.process.profile-management
+  apm:
+    flow-metrics:
+      - apm.metric.profile-view-count
+      - apm.metric.profile-load-time
+```
+
+---
+
+## Example: Multi-Step Checkout Flow
+
+```yaml
+id: navigation.navigationflow.checkout
+name: "Checkout Flow"
+type: navigationflow
+properties:
+  steps:
+    - id: cart-review
+      route: /checkout/cart
+      view: ux.view.cart-review
+      onNext: validate-cart
+    - id: shipping-address
+      route: /checkout/shipping
+      view: ux.view.shipping-form
+      onNext: validate-address
+    - id: payment
+      route: /checkout/payment
+      view: ux.view.payment-form
+      onNext: validate-payment
+    - id: confirmation
+      route: /checkout/confirm
+      view: ux.view.order-confirmation
+      final: true
+  transitions:
+    - from: cart-review
+      to: shipping-address
+      trigger: next-button
+      guard: navigation.navigationguard.cart-not-empty
+    - from: shipping-address
+      to: payment
+      trigger: next-button
+      guard: navigation.navigationguard.valid-address
+    - from: payment
+      to: confirmation
+      trigger: submit
+      guard: navigation.navigationguard.payment-successful
+  context:
+    - cartId
+    - selectedAddress
+    - paymentMethod
+  business:
+    realizes-process: business.process.checkout
+```
+
+---
+
+## Coverage Completeness Checklist
+
+Before declaring navigation layer extraction complete, verify each type was considered:
+
+- [ ] `navigation.navigationgraph.*` — Top-level navigation model container
+- [ ] `navigation.route.*` — URL path to view mappings (core unit)
+- [ ] `navigation.routemeta.*` — Auth, layout, keepAlive metadata per route
+- [ ] `navigation.breadcrumbconfig.*` — Breadcrumb trail configuration
+- [ ] `navigation.navigationguard.*` — Pre-navigation authorization/validation checks
+- [ ] `navigation.guardcondition.*` — Boolean expressions evaluated by guards
+- [ ] `navigation.guardaction.*` — Actions taken on guard failure
+- [ ] `navigation.navigationflow.*` — Multi-step navigation sequences
+- [ ] `navigation.flowstep.*` — Individual steps within flows
+- [ ] `navigation.navigationtransition.*` — Directed transitions between routes
+- [ ] `navigation.contextvariable.*` — Navigation-scoped context data
+
+If any type has ZERO elements, explicitly decide:
+"This type doesn't apply to this codebase" with reasoning.
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Missing authentication guards on protected routes — use `navigationguard` + `guardcondition` + `guardaction` together
+- ❌ Using `navigation.guard.*` or `navigation.flow.*` as element IDs — correct types are `navigationguard` and `navigationflow`
+- ❌ Not decomposing guards into conditions (`guardcondition`) and actions (`guardaction`) — model these as separate elements
+- ❌ Complex flows without explicit `flowstep` elements — each step in a flow should be a distinct `flowstep`
+- ❌ Missing `routemeta` for protected routes — auth requirements belong in `routemeta`, not embedded in route properties
+- ❌ Missing cross-layer links to UX views (`view-ref`) and business processes (`realizes-process`)
+- ❌ No error/fallback routes defined — model these as `route` with `type: redirect`