@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/schemas/app-compose/actors.yml

@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "slug(filename) == slug(heading)"
+    children:
+      # Brief context for authorization decisions - REQUIRED
+      - heading: "## Overview"
+        description: |
+          1-2 sentences: who this actor is and their authority level.
+          Not a job description — context for authorization decisions.
+
+      # What flows this actor participates in - REQUIRED
+      - heading: "## Authorized Business Flows"
+        description: |
+          Business flows this actor participates in.
+          Format: [Flow Name](../business-flow/<flow>/README.md) — role
+          Roles: initiator, approver, viewer
+          Add conditions inline when needed, e.g. (< $1000)
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 2

package/schemas/app-compose/business-flow.yml

@@ -0,0 +1,50 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# SPEC TIER 3 (primary navigation structure)
+# Business flow file: business-flow/<flow-name>/README.md
+# Stories are nested: business-flow/<flow-name>/story/<actor>--<story-name>.md
+# Defines end-to-end business processes
+
+structure:
+  - heading:
+      pattern: "# [a-zA-Z0-9_\\-]+"
+    children:
+      # Brief description of this business flow - REQUIRED
+      - heading: "## Overview"
+
+      # Who initiates and participates in this flow - REQUIRED
+      - heading: "## Actors Involved"
+        description: |
+          List actors that participate in this business flow.
+          Link to actor docs. ie. ../../actors/<actor-name>.md
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Diagram representing this flow - REQUIRED
+      - heading: "## Flow Diagram"
+        code_blocks:
+          - min: 1
+            lang: mermaid
+
+      # Links to user stories nested under this flow - REQUIRED
+      - heading: "## Stories"
+        description: |
+          Link to story docs in ./story/ folder that comprise this business flow.
+          Format: ./story/<actor>--<story-name>.md
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/requirements.yml

@@ -0,0 +1,33 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading: "# README"
+    children:
+      # What this application does - REQUIRED
+      - heading: "## Overview"
+
+      # Target industry and domain knowledge - REQUIRED
+      - heading: "## Industry Context"
+        children:
+          - heading: "### Target Industry"
+            description: |
+              The industry sector this application serves
+              (e.g., Manufacturing, Retail, Healthcare, Finance, Logistics)
+
+          - heading: "### Domain Terminology"
+            description: |
+              Key terms and concepts specific to this domain
+            lists:
+              - min: 0
+                type: unordered
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/resolver.yml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# IMPLEMENTATION TIER
+# Resolver file: resolver/<resolverName>.md
+# Documents GraphQL operations (queries, mutations, subscriptions)
+
+# TODO: check against resolver implementations via CI/CD pipeline
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    description: |
+      Document the GraphQL operation - mainly mutations.
+    children:
+      # What this Resolver does - REQUIRED
+      - heading: "## Overview"
+
+      # Which modules and what parts are used - REQUIRED
+      - heading: "## Modules Commands Used"
+        description: |
+          List modules and specific features/commands used from each.
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Error Handling
+      - heading: "## Exception Handling"
+        optional: true
+        description: |
+          Document possible errors returned by this operation.
+        tables:
+          - min: 1
+            required_headers:
+              - Error Code
+              - Description
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/screen.yml

@@ -0,0 +1,81 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# IMPLEMENTATION TIER
+# Screen file: screen/<screenName>.md
+# TODO: should check existance of screens via CI/CD pipeline
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this screen does - REQUIRED
+      - heading: "## Overview"
+
+      # Screen Type
+      - heading: "## Screen Type"
+        description: |
+          Specify the type of screen (e.g., Form, ListView, DetailView).
+        required_text:
+          - pattern: "(Form|ListView|DetailView)"
+            regex: true
+        children:
+          - heading: "### Form Details"
+            description: |
+              If the screen is a Form provide details about the form fields.
+            optional: true
+            children:
+              - heading: "#### Input Fields"
+                tables:
+                  - min: 1
+                    required_headers:
+                      - Field Name
+                      - Field Type
+                      - Required (Yes/No)
+          - heading: "### ListView Details"
+            description: |
+              If the screen is a ListView provide details about the table displayed.
+            optional: true
+            children:
+              - heading: "#### Required Columns"
+                tables:
+                  - min: 1
+                    required_headers:
+                      - Column Name
+                      - Hideable (Yes/No)
+                      - Sort-able (Yes/No)
+                      - Filter-able (Yes/No)
+                      - Searchable (Yes/No)
+          - heading: "### DetailView Details"
+            description: |
+              If the screen is a DetailView provide actions available on this screen.
+            optional: true
+            children:
+              - heading: "#### Displayed Fields"
+                lists:
+                  - min: 1
+                    type: unordered
+                    min_items: 1
+              - heading: "#### Available Actions"
+                lists:
+                  - min: 1
+                    type: unordered
+                    min_items: 1
+
+      - heading: "## Access Control"
+        description: |
+          Specify the actors that have access to this screen.
+          Use links to actor documents (e.g., [buyer-administrator](../actors/buyer-administrator.md)).
+        lists:
+          - min: 1
+            type: unordered
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/app-compose/story.yml

@@ -0,0 +1,67 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# SPEC TIER 3 (nested under business-flow)
+# Story filename format: <actor>--<story-name>.md
+# Example: sales-manager--create-sales-order.md
+# Heading must match story name (after --): # Create Sales Order
+# Defines WHAT users accomplish (the requirement)
+
+structure:
+  - heading:
+      # Validates: slug of text after "--" matches heading
+      # trimPrefix removes "actor--" prefix, leaving story name
+      # e.g., "sales-manager--create-sales-order" -> "create-sales-order" -> matches "# Create Sales Order"
+      expr: 'slug(trimPrefix(filename, "^[a-z-]+--")) == slug(heading)'
+    description: |
+      User story defining a specific requirement within a business flow.
+      The name of the story should start with the actor followed by `--` and the story name.
+    children:
+      - heading: "## User Story"
+        description: |
+          Define the user story in the format:
+          As a [role], I want [goal], so that [benefit].
+
+      # Diagram representing this story - REQUIRED
+      - heading: "## Story Diagram"
+        description: |
+          Mermaid sequence diagram showing user interactions with screens.
+          Focus on actors, UI screens, and business outcomes.
+          Avoid technical details (APIs, databases, endpoints).
+        code_blocks:
+          - min: 1
+            lang: mermaid
+
+      # Scenario Patterns, including edge cases - REQUIRED
+      - heading: "## Scenario Patterns"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Test cases must be covered - REQUIRED
+      - heading: "## Test Cases"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Screens that implement this story - REQUIRED
+      # Enables M:N relationship between stories and screens
+      - heading: "## Screens"
+        description: |
+          Link to screen docs that implement this story's UI.
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/module/command.yml

@@ -0,0 +1,52 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this command does - REQUIRED
+      - heading: "## Overview"
+
+      # Business rules - REQUIRED
+      # Rules, constraints, and validation logic
+      - heading: "## Business Rules"
+        allow_additional: true
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # How it works - REQUIRED
+      # Step-by-step flow or workflow
+      - heading: "## Process Flow"
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # External dependencies - OPTIONAL
+      # Commands from other modules that this command depends on
+      - heading: "## External Dependencies"
+        description: "e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Error handling - REQUIRED
+      # How errors are handled
+      - heading: "## Error Scenarios"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/module/feature.yml

@@ -0,0 +1,58 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "slug(filename) == slug(heading)"
+    children:
+      # ===================
+      # REQUIRED SECTIONS
+      # ===================
+
+      # What this feature does - REQUIRED
+      - heading: "## Overview"
+
+      # Business context - REQUIRED
+      # Why this feature exists and what problem it solves
+      - heading: "## Business Purpose"
+
+      # How it works - REQUIRED
+      # Process flow
+      - heading: "## Process Flow"
+        description: |
+          Describe the end-to-end process flow of this feature.
+          If multiple flows exist, split them into different diagrams and explain each.
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # Scenario Patterns, including edge cases - REQUIRED
+      - heading: "## Scenario Patterns"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Test cases must be covered - REQUIRED
+      - heading: "## Test Cases"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Links to any related references - REQUIRED
+      - heading: "## Reference Links"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/module/model.yml

@@ -0,0 +1,70 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      - heading: "## Description"
+      - heading: "## Domain Model Definitions"
+        children:
+          - heading: "### Model type"
+            description: |
+              Model type must be one of Standard, AppendOnly, or Stateful
+               - AppendOnly: AppendOnly model where records can be added but not modified or deleted
+               - Stateful: Stateful model with state transitions
+            required_text:
+              - pattern: "(Standard|AppendOnly|Stateful)"
+                regex: true
+            children:
+              - heading: "#### State Transitions"
+                description: |
+                  Define the state transitions for Stateful models.
+                  Commands should correspond to those defined in the "### Command Definitions" section.
+                optional: true
+                code_blocks:
+                  - lang: mermaid
+                    min: 1
+
+          - heading: "### Command Definitions"
+            description: |
+              Definitions of commands this domain model supports.
+              Should match with the commands defined in modules/**/docs/commands/*.md and link to them.
+              Commands heavily influenced by Model type:
+                - Standard: Create, Update, Delete (Some model may choose to not implement Delete)
+                - AppendOnly: Create
+                - Stateful: Create, State Transition Commands
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
+          - heading: "### Models"
+            description: |
+              Actual database models necessary for the domain model.
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+
+          - heading: "### Invariants"
+            description: |
+              Invariants that must always hold true for this domain model.
+              - Assume the model boundary (the unit within which consistency is guaranteed) is already defined, and list what must always be true within that boundary.
+              - Express each invariant as part of the concept’s definition (what makes the concept valid), not as an implementation detail (no DB constraints, computed columns, etc.).
+              - If a constraint depends on lifecycle state, write it explicitly as a state-scoped invariant (state x condition that must always hold).
+
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
+          - heading: "### Relationships"
+
+# Global link validation settings
+links:
+  validate_internal: true # check anchor links (#section-name)
+  validate_files: true # check relative file links (./other.md)
+# Global heading validation rules
+heading_rules:
+  no_skip_levels: true # disallow skipping levels (e.g., h1 -> h3)
+  unique: true # all headings must be unique
+  max_depth: 4 # maximum heading depth (1-6)

package/schemas/module/module.yml

@@ -0,0 +1,50 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading: "# README"
+    children:
+      # ===================
+      # REQUIRED SECTIONS
+      # ===================
+
+      # What this module does - REQUIRED
+      - heading: "## Overview"
+
+      # Main capabilities - REQUIRED
+      - heading: "## Key Features"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Module scope - REQUIRED
+      - heading: "## Module Scope"
+        children:
+          - heading: "### In Scope"
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+          - heading: "### Out of Scope"
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+
+      # Module dependencies - REQUIRED
+      - heading: "## Module Dependencies"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/skills/1-module-docs/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: 1-module-docs
+description: Create ERP module documentation following framework schemas. Use when starting a new module, documenting an existing module, or when user asks to create module docs, feature docs, or design module features. Guides collaborative research, scoping, and iterative feature breakdown.
+---
+
+# Module Documentation Workflow
+
+Collaborative workflow for creating ERP module documentation. Human and AI work together through research, scoping, design validation, and iterative refinement.
+
+## Workflow Phases
+
+```
+RESEARCH → SCOPE → DESIGN → CREATE → REVIEW
+```
+
+### Phase 1: Research
+
+Study established ERP solutions for the module domain:
+
+1. **Web search** Odoo, Oracle ERP Cloud, SAP for the domain (e.g., "Odoo inventory management features")
+2. **Fetch documentation** from official sources when available
+3. **Identify** common features, models, workflows, compliance requirements
+4. **Summarize** findings before proceeding
+
+Key ERP references:
+
+- Odoo: https://www.odoo.com/documentation/19.0/applications.html
+- Oracle: https://docs.oracle.com/en/cloud/saas/index.html
+- SAP: Search SAP Docs
+
+### Phase 2: Scope
+
+Present scope options to user. Use AskUserQuestion:
+
+| Option                 | Description                                                             |
+| ---------------------- | ----------------------------------------------------------------------- |
+| **Minimal**            | Core entities only, basic CRUD, no workflows                            |
+| **Core (Recommended)** | Essential features for production use, foundational for other modules   |
+| **Comprehensive**      | Full feature set including advanced workflows, compliance, integrations |
+
+Wait for user selection before proceeding.
+
+### Phase 3: Design
+
+Present features incrementally for validation:
+
+1. **List proposed features** as a table (feature name, purpose)
+2. **Wait for user approval** of feature list
+3. For each feature, briefly describe:
+   - What it does
+   - Key scenarios
+4. **Ask**: "Does this feature breakdown look right?"
+
+Keep descriptions concise (~100-200 words per section). Do not present all details at once.
+
+### Phase 4: Create
+
+Generate documentation following framework schemas.
+
+**File structure:**
+
+```
+modules/<module-name>/
+├── README.md                           # module.yml schema
+└── docs/
+    └── features/
+        └── <feature-name>.md           # feature.yml schema
+```
+
+**Naming conventions:**
+
+- Feature files: kebab-case (e.g., `role-based-access-control.md`)
+- Headings: Title Case
+
+Create with `erp-kit` CLI:
+
+```bash
+erp-kit scaffold --modules-root modules module <module-name>
+erp-kit scaffold --modules-root modules feature <module-name> <feature-name>
+```
+
+### Phase 5: Review
+
+After creating docs, user reviews and may request changes:
+
+**Split detection**: If a feature covers multiple distinct workflows, split into separate feature files.
+
+**Iteration pattern:**
+
+1. User identifies issue (e.g., "X is too broad, split it")
+2. Create new feature file for split-out content
+3. Remove split content from original file
+4. Update README.md feature list if needed
+
+Continue iterating until user approves.
+
+# Framework Schemas Reference
+
+Schemas are bundled in `@tailor-platform/erp-kit`.
+
+## Validation
+
+Always run before completing:
+
+```bash
+pnpm run module:doc:check
+```