@documentation-robotics/cli 0.1.0 → 0.1.5

package/dist/integrations/github_copilot/skills/dr_07_data_model_layer/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: LAYER_07_DATA_MODEL
+description: Expert knowledge for Data Model Layer modeling in Documentation Robotics
+triggers:
+  [
+    "JSON Schema",
+    "data model",
+    "schema",
+    "object schema",
+    "data structure",
+    "properties",
+    "validation",
+    "data type"
+  ]
+version: 0.8.1
+---
+
+# Data Model Layer Skill
+
+**Layer Number:** 07
+**Specification:** Metadata Model Spec v0.8.1
+**Purpose:** Defines logical data structures using JSON Schema Draft 7, specifying entities, properties, validation rules, and data governance.
+
+---
+
+## Layer Overview
+
+The Data Model Layer captures **logical data structures**:
+
+- **SCHEMAS** - Object, array, string, numeric schemas
+- **VALIDATION** - Type constraints, required fields, patterns, ranges
+- **COMPOSITION** - Schema combinations (allOf, anyOf, oneOf, not)
+- **GOVERNANCE** - Data classification, PII, retention policies
+- **INTEGRATION** - Links to business objects, database tables, API operations
+
+This layer uses **JSON Schema Draft 7** (industry standard) with custom extensions for cross-layer traceability.
+
+**Central Entity:** The **ObjectSchema** (defining an object structure) is the core modeling unit.
+
+---
+
+## Entity Types
+
+> **CLI Introspection:** Run `dr schema types data-model` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type.
+
+### Core JSON Schema Entities (17 entities)
+
+| Entity Type           | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| **JSONSchema**        | Root schema document                               |
+| **ObjectSchema**      | Defines object structure with properties           |
+| **ArraySchema**       | Defines array with items and constraints           |
+| **StringSchema**      | String validation (length, pattern, format)        |
+| **NumericSchema**     | Number/integer validation (min, max, multipleOf)   |
+| **SchemaComposition** | Combines schemas (allOf, anyOf, oneOf, not)        |
+| **SchemaProperty**    | Individual property definition                     |
+| **Reference**         | $ref to other schemas                              |
+| **DataGovernance**    | Governance annotations (classification, retention) |
+| **DatabaseMapping**   | Maps to physical database (x-database extension)   |
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "data model", "schema", "JSON Schema", "data structure"
+- Wants to define object structures, properties, or validation rules
+- Asks about data types, constraints, or data governance
+- Needs to model entities like User, Order, Product, etc.
+- Wants to link data models to APIs or databases
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (Data Model → Other Layers):**
+
+- `x-business-object-ref` → Business Layer (what business concept does this represent?)
+- `x-database` → Data Store Layer (how is this stored physically?)
+- `x-data-governance` → Security Layer (classification, PII, retention)
+- `x-apm-data-quality-metrics` → APM Layer (data quality monitoring)
+
+**Incoming (Other Layers → Data Model):**
+
+- API Layer → Data Model (request/response schemas via $ref)
+- UX Layer → Data Model (form validation rules)
+- Testing Layer → Data Model (input constraints for test partitioning)
+
+---
+
+## Validation Best Practices
+
+1. **Required fields** - Use `required` array for mandatory properties
+2. **Type validation** - Always specify `type` (object, array, string, number, etc.)
+3. **Format validation** - Use `format` for email, uuid, date-time, uri, etc.
+4. **Range validation** - Use min/max for numbers, minLength/maxLength for strings
+5. **Pattern validation** - Use `pattern` for regex validation (e.g., phone numbers)
+6. **Data governance** - Always add `x-data-governance` for sensitive data
+7. **Reusability** - Use `$ref` to reference shared schemas
+
+---
+
+## Common Commands
+
+```bash
+# Add object schema
+dr add data_model object-schema --name "User" --property type=object
+
+# List data models
+dr list data_model object-schema
+
+# Validate data model layer
+dr validate --layer data_model
+
+# Export as JSON Schema
+dr export --layer data_model --format json-schema
+```
+
+---
+
+## Example: User Schema
+
+```yaml
+id: data_model.object-schema.user
+name: "User Schema"
+type: object-schema
+properties:
+  type: object
+  required: [id, email, username]
+  properties:
+    id:
+      type: string
+      format: uuid
+      description: "Unique user identifier"
+    email:
+      type: string
+      format: email
+      description: "User email address"
+      x-data-governance:
+        classification: confidential
+        pii: true
+    username:
+      type: string
+      minLength: 3
+      maxLength: 50
+      pattern: "^[a-zA-Z0-9_-]+$"
+    created_at:
+      type: string
+      format: date-time
+    roles:
+      type: array
+      items:
+        type: string
+      description: "User role assignments"
+  x-business-object-ref: business.actor.user
+  x-database:
+    table: users
+    schema: public
+```
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Missing `type` field (validation will fail)
+- ❌ Not marking PII/sensitive data with governance
+- ❌ Overly complex schemas (break into smaller reusable schemas)
+- ❌ Not using `$ref` for shared definitions
+- ❌ Missing cross-layer links to business and database layers

package/dist/integrations/github_copilot/skills/dr_08_dataset_layer/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: LAYER_08_DATA_STORE
+description: Expert knowledge for Data Store Layer modeling in Documentation Robotics
+triggers:
+  [
+    "database",
+    "collection",
+    "namespace",
+    "data-store",
+    "NoSQL",
+    "MongoDB",
+    "DynamoDB",
+    "document store",
+    "access pattern",
+    "index",
+    "field"
+  ]
+version: 0.8.1
+---
+
+# Data Store Layer Skill
+
+**Layer Number:** 08
+**Specification:** Metadata Model Spec v0.8.1
+**Purpose:** Defines paradigm-neutral physical storage modeling, capturing databases, collections/tables, fields/columns, indexes, views, stored logic, validation rules, access patterns, event handlers, and retention policies across relational, document, key-value, time-series, and graph stores.
+
+---
+
+## Layer Overview
+
+The Data Store Layer captures **physical storage design** in a paradigm-neutral way:
+
+- **DATABASES** - Database instances (any paradigm)
+- **NAMESPACES** - Logical grouping of collections (schemas, keyspaces, databases)
+- **COLLECTIONS** - Primary storage units (tables, collections, streams, buckets)
+- **FIELDS** - Field/column definitions with types and constraints
+- **INDEXES** - Query optimization indexes
+- **VIEWS** - Derived or materialized views
+- **STORED LOGIC** - Stored procedures, triggers, user-defined functions
+- **VALIDATION RULES** - Database-level validation constraints
+- **ACCESS PATTERNS** - Query access patterns for performance modeling
+- **EVENT HANDLERS** - Event-driven data triggers
+- **RETENTION POLICIES** - Data lifecycle and retention rules
+
+This layer supports **multiple storage paradigms**: relational (PostgreSQL, MySQL), document (MongoDB, Firestore), key-value (Redis, DynamoDB), time-series (InfluxDB, TimescaleDB), and graph (Neo4j, Amazon Neptune).
+
+**Central Entity:** The **Collection** (table, document collection, stream) is the core modeling unit.
+
+> **CLI Introspection:** Run `dr schema types data-store` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type (e.g., `dr schema node data-store.collection`).
+
+---
+
+## Entity Types
+
+### Core Data Store Entities (11 entities)
+
+| Entity Type         | CLI Type          | Description                                                              |
+| ------------------- | ----------------- | ------------------------------------------------------------------------ |
+| **Database**        | `database`        | Database instance (any paradigm — relational, document, key-value, etc.) |
+| **Namespace**       | `namespace`       | Logical grouping of collections (schema, keyspace, database prefix)      |
+| **Collection**      | `collection`      | Primary storage unit (table, document collection, stream, bucket)        |
+| **Field**           | `field`           | Field or column definition with data type and constraints                |
+| **Index**           | `index`           | Query optimization index (B-tree, hash, compound, text, geospatial)      |
+| **View**            | `view`            | Derived or materialized view over one or more collections                |
+| **StoredLogic**     | `storedlogic`     | Stored procedures, triggers, and user-defined functions                  |
+| **ValidationRule**  | `validationrule`  | Database-level validation constraint or schema enforcement rule          |
+| **AccessPattern**   | `accesspattern`   | Named query access pattern (for performance and capacity planning)       |
+| **EventHandler**    | `eventhandler`    | Event-driven trigger or change-data-capture handler                      |
+| **RetentionPolicy** | `retentionpolicy` | Data lifecycle, TTL, and retention rule definition                       |
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "database", "collection", "namespace", "data-store", "NoSQL", "document store"
+- Wants to define collections, fields, indexes, or access patterns
+- Asks about storage design for MongoDB, DynamoDB, PostgreSQL, Redis, etc.
+- Needs to model physical storage for data models (any paradigm)
+- Wants to link physical storage to logical data models
+- Discusses event-driven data handling or change-data-capture
+- Asks about data retention, TTL policies, or lifecycle management
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (Data Store → Other Layers):**
+
+- `x-json-schema` → Data Model Layer (what logical schema does this implement?)
+- `x-governed-by-*` → Security Layer (data access policies)
+- `x-apm-performance-metrics` → APM Layer (query performance monitoring)
+
+**Incoming (Other Layers → Data Store):**
+
+- Data Model Layer → Data Store (physical storage mapping)
+- Application Layer → Data Store (database connections)
+- Technology Layer → Data Store (hosting infrastructure)
+
+---
+
+## Design Best Practices
+
+1. **Paradigm-neutral modeling** — Use `collection`/`field` regardless of whether the underlying store is relational or document
+2. **Access patterns first** — For NoSQL (DynamoDB, Cassandra), define `AccessPattern` entities before collections
+3. **Indexes** — Add indexes for frequent query paths; use `AccessPattern` to document which index serves which pattern
+4. **PII marking** — Use `x-pii` on `field` entities to mark sensitive data
+5. **Retention policies** — Always add a `RetentionPolicy` for collections with regulatory or storage requirements
+6. **Stored logic** — Capture stored procedures, triggers, and UDFs as `StoredLogic` entities
+7. **Event handlers** — Document CDC (change-data-capture) and event-driven triggers as `EventHandler` entities
+8. **Validation rules** — Add `ValidationRule` for database-level constraints beyond field-level type enforcement
+
+---
+
+## Common Commands
+
+```bash
+# Add a database instance
+dr add data-store database --name "users-db"
+
+# Add a namespace (schema or keyspace)
+dr add data-store namespace --name "public" --property parentDatabase=data-store.database.users-db
+
+# Add a collection (table or document collection)
+dr add data-store collection --name "users" --property parentNamespace=data-store.namespace.public
+
+# Add a field to a collection
+dr add data-store field --name "email" --property dataType=string --property nullable=false
+
+# Add an index
+dr add data-store index --name "idx-users-email" --property fields='["email"]' --property unique=true
+
+# Add an access pattern (for NoSQL capacity planning)
+dr add data-store accesspattern --name "get-user-by-email" --property queryType=point-lookup
+
+# List collections
+dr list data-store collection
+
+# Validate data-store layer
+dr validate --layer data-store
+
+# Introspect available types
+dr schema types data-store
+```
+
+---
+
+## Example: Users Collection (Paradigm-Neutral)
+
+```yaml
+id: data-store.collection.users
+name: "Users Collection"
+type: collection
+properties:
+  parentNamespace: data-store.namespace.public
+  paradigm: relational # or: document, key-value, time-series, graph
+  fields:
+    - id:
+        dataType: uuid
+        nullable: false
+        primaryKey: true
+    - email:
+        dataType: string
+        nullable: false
+        x-pii: true
+        x-encrypted: true
+    - username:
+        dataType: string
+        nullable: false
+    - created_at:
+        dataType: timestamp
+        nullable: false
+  x-json-schema: data-model.object-schema.user
+  x-apm-performance-metrics:
+    - apm.metric.users-query-latency
+```
+
+### Access Pattern (for DynamoDB/NoSQL)
+
+```yaml
+id: data-store.accesspattern.get-user-by-email
+name: "Get User by Email"
+type: accesspattern
+properties:
+  collection: data-store.collection.users
+  queryType: point-lookup
+  keyAttributes: ["email"]
+  consistencyLevel: strong
+  estimatedRps: 500
+```
+
+### Retention Policy
+
+```yaml
+id: data-store.retentionpolicy.users-audit-log
+name: "Users Audit Log Retention"
+type: retentionpolicy
+properties:
+  collection: data-store.collection.users-audit-log
+  ttlDays: 365
+  archiveAfterDays: 90
+  regulatoryBasis: "SOC2, GDPR Article 30"
+```
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Using SQL-only concepts (Table, Column, Constraint) — use paradigm-neutral `collection`, `field`, `validationrule`
+- ❌ Skipping `AccessPattern` for NoSQL stores (DynamoDB, Cassandra) — define access patterns first
+- ❌ Not marking PII fields with `x-pii`
+- ❌ Missing cross-layer links to data model layer (`x-json-schema`)
+- ❌ Forgetting `RetentionPolicy` for regulated data
+- ❌ Not documenting `EventHandler` for CDC or change-triggered workflows

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

@@ -0,0 +1,230 @@
+---
+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.1
+---
+
+# UX Layer Skill
+
+**Layer Number:** 09
+**Specification:** Metadata Model Spec v0.8.1
+**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** - Routable screens/pages with layouts
+- **COMPONENTS** - UI components (forms, tables, charts, cards)
+- **STATE MACHINES** - Experience states and transitions
+- **ACTIONS** - Interactive elements (buttons, links, voice commands)
+- **VALIDATION** - Client-side validation rules
+- **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** (routable screen) is the core modeling unit.
+
+---
+
+## 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 (26 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
+
+**Application Tier:**
+
+- **UXApplication** - Application-wide UX configuration
+
+**Experience Tier:**
+
+- **UXSpec** - Container for experience specification
+- **View** - Routable screen/page
+- **SubView** - Component grouping within view
+- **ComponentInstance** - Instance of library component
+- **ActionComponent** - Interactive element
+- **ExperienceState** - State in state machine
+- **StateAction** - Action during state lifecycle
+- **StateTransition** - Transition between states
+- **ValidationRule** - Client-side validation
+
+---
+
+## 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
+
+---
+
+## 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.*` → Data Model Layer (form validation rules)
+- `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. **Validation** - Add client-side validation rules
+4. **Accessibility** - Consider accessibility requirements
+5. **Responsive** - Design for multiple screen sizes
+6. **Performance** - Set performance targets (load time, interaction latency)
+7. **Error handling** - Define error states and messages
+
+---
+
+## Common Commands
+
+```bash
+# Add view
+dr add ux view --name "User Profile" --property route=/profile
+
+# Add component instance
+dr add ux component-instance --name "Profile Form"
+
+# List views
+dr list ux view
+
+# Validate UX layer
+dr validate --layer ux
+
+# Export UX documentation
+dr export --layer ux --format markdown
+```
+
+---
+
+## Example: Login View
+
+```yaml
+id: ux.view.login
+name: "Login View"
+type: view
+properties:
+  route: /login
+  layout:
+    type: centered
+    maxWidth: 400px
+  components:
+    - id: login-form
+      componentRef: library.component.form-field
+      dataBinding:
+        source: api.operation.login
+        submitAction: POST /api/auth/login
+      fields:
+        - name: email
+          type: email
+          required: true
+          validation:
+            - type: email-format
+            - type: required
+        - name: password
+          type: password
+          required: true
+          validation:
+            - type: min-length
+              value: 8
+  actions:
+    - id: submit-button
+      type: button
+      label: "Login"
+      action: submit-form
+      target: login-form
+    - id: forgot-password
+      type: link
+      label: "Forgot password?"
+      navigation: /forgot-password
+  states:
+    - id: idle
+      initial: true
+      onEnter: []
+    - id: submitting
+      onEnter:
+        - action: disable-form
+        - action: show-spinner
+    - id: success
+      onEnter:
+        - action: navigate
+          target: /dashboard
+    - id: error
+      onEnter:
+        - action: show-error
+        - action: enable-form
+  transitions:
+    - from: idle
+      to: submitting
+      trigger: submit
+    - from: submitting
+      to: success
+      trigger: success
+    - from: submitting
+      to: error
+      trigger: failure
+    - from: error
+      to: idle
+      trigger: retry
+  motivation:
+    supports-goals:
+      - motivation.goal.user-authentication
+  api:
+    operationId: login
+  navigation:
+    route-ref: navigation.route.login
+```
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Not using library components (inconsistent UX)
+- ❌ Missing validation rules (poor user experience)
+- ❌ Complex state machines without documentation
+- ❌ Not linking to API operations or navigation routes
+- ❌ Missing error states and handling
+- ❌ No performance targets defined