@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,111 @@
+---
+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
+```
+
+## References
+
+- [Module structure](references/structure.md)

package/skills/1-module-docs/references/structure.md

@@ -0,0 +1,22 @@
+# Module Directory Structure
+
+```
+src/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── command/      # Domain commands + tests (*.test.ts co-located)
+├── lib/          # Internal shared code (errors.ts, types.ts)
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated code (do not edit)
+├── index.ts      # Public exports
+└── module.ts     # Module definition
+```
+
+## Rules
+
+- `db/`: Only documentable model definitions, no helpers
+- `executor/`: Async executors as factory functions (see executors.md)
+- `command/`: Domain commands + co-located tests, no utilities
+- `lib/`: Internal errors and types (not documented)
+- `testing/`: Fixtures for tests only
+- Run `pnpm generate` after modifying `db/` models

package/skills/2-module-feature-breakdown/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: 2-module-feature-breakdown
+description: Use when breaking down a feature spec into model and command documentation. Triggers on feature implementation planning, creating model docs, creating command docs, or when user references model.yml/command.yml schemas.
+---
+
+# Feature Breakdown to Model/Command Docs
+
+Convert feature specifications into structured model and command documentation following framework schemas.
+
+## When to Use
+
+- User has a feature spec (e.g., `docs/features/*.md`) and wants implementation docs
+- User asks to create model or command documentation
+- User references `model.yml` or `command.yml` schemas
+
+## Workflow
+
+```
+ANALYZE → SCAFFOLD → POPULATE → VALIDATE
+```
+
+### 1. Analyze
+
+Read the feature spec and identify:
+
+- **Models**: Entities with state, fields, relationships
+- **Commands**: Operations that change state (look for verbs in state diagrams)
+
+### 2. Scaffold
+
+For each model and command, scaffold the documentation files using `erp-kit` CLI:
+
+```bash
+erp-kit scaffold --modules-root modules model <module-name> <model-name>
+erp-kit scaffold --modules-root modules command <module-name> <command-name>
+```
+
+### 3. Populate
+
+Fill in the scaffolded docs with details analyzed from Step 1.
+
+### 4. Validate
+
+Run `pnpm run module:doc:check` and fix any violations.
+
+## Schema Quick Reference
+
+Schemas are bundled in `@tailor-platform/erp-kit` (model.yml, command.yml).
+
+## Common Patterns
+
+| Feature Element       | Documentation Type               |
+| --------------------- | -------------------------------- |
+| Entity with fields    | Model doc                        |
+| State machine         | Model doc with State Transitions |
+| Verb in state diagram | Command doc                      |
+| CRUD operation        | Command doc                      |
+| Validation logic      | Command doc Business Rules       |
+
+## Validation
+
+Always run before completing:
+
+```bash
+pnpm run module:doc:check
+```
+
+## References
+
+- [Module structure](references/structure.md)
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)

package/skills/2-module-feature-breakdown/references/commands.md

@@ -0,0 +1,48 @@
+# Command Implementation
+
+## defineCommand Pattern
+
+Commands that don't need custom fields use `defineCommand` directly:
+
+```typescript
+export const myCommand = defineCommand(permissions.myCommand, async (db: DB, input: Input) => { ... });
+```
+
+## Factory Function Pattern (custom fields)
+
+Commands that insert into a table with user-extensible fields use a `makeCreateX<CF>()` factory:
+
+- Export only `makeCreateX` — no default instance
+- Generic `CF extends Record<string, unknown>` for custom fields
+- Input type: `CreateXInput & CF`
+- Destructure known fields, rest-spread custom fields into `.values()` before known fields
+- Cast custom fields: `...(customFields as Record<string, unknown>)`
+- `module.ts` wires with `makeCreateX<FieldsToInsertable<F>>()`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/skills/2-module-feature-breakdown/references/models.md

@@ -0,0 +1,29 @@
+# Database Models
+
+## Factory Function Pattern
+
+Each model is a `createXType<const F>(params)` factory:
+
+- Params interface generic: `F extends Record<string, TailorAnyDBField>`
+- `fields?: F` — optional custom fields from parent modules
+- Spread as `...(params.fields ?? {}) as F` to preserve type information
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+- Export a default instance: `export const x = createXType({})`
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/skills/2-module-feature-breakdown/references/structure.md

@@ -0,0 +1,22 @@
+# Module Directory Structure
+
+```
+src/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── command/      # Domain commands + tests (*.test.ts co-located)
+├── lib/          # Internal shared code (errors.ts, types.ts)
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated code (do not edit)
+├── index.ts      # Public exports
+└── module.ts     # Module definition
+```
+
+## Rules
+
+- `db/`: Only documentable model definitions, no helpers
+- `executor/`: Async executors as factory functions (see executors.md)
+- `command/`: Domain commands + co-located tests, no utilities
+- `lib/`: Internal errors and types (not documented)
+- `testing/`: Fixtures for tests only
+- Run `pnpm generate` after modifying `db/` models

package/skills/3-module-doc-review/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: 3-module-review
+description: Review feature parity between feature documentation and command/model documentation. Use when validating that all feature scenarios are covered by command docs, and that all required models exist.
+---
+
+# Feature Parity Review Workflow
+
+Review **documentation consistency** between feature specs and command/model docs.
+
+## Purpose
+
+Verify that feature documentation (high-level business requirements) is properly covered by command documentation (command specifications) and model documentation (data structures).
+
+```
+Feature Docs (What)  →  Command Docs (How)  →  Model Docs (With What)
+     ↓                        ↓                       ↓
+  Scenarios              Business Rules          Data Structures
+  Process Flows          Error Scenarios         Relationships
+  Test Cases             Process Flows           Constraints
+```
+
+## When to Use
+
+- After writing feature documentation, check for gaps in command/model documentation
+- After writing command/model documentation, verify consistency with features
+- Quality check during documentation review
+
+## Workflow
+
+```
+FEATURE DOCS → COMMAND DOCS → MODEL DOCS → COMPARE → REPORT
+```
+
+## Step-by-Step
+
+### 1. Read Feature Documentation
+
+Read ALL feature docs:
+
+```
+modules/<module-name>/docs/features/*.md
+```
+
+### 2. Read Command Documentation
+
+Read ALL command docs:
+
+```
+modules/<module-name>/docs/commands/*.md
+```
+
+### 3. Read Model Documentation
+
+Read ALL model docs:
+
+```
+modules/<module-name>/docs/models/*.md
+```
+
+### 4. Feature → Command Parity Check
+
+For each feature's scenarios and test cases:
+
+| Check Item             | Question                                                                   |
+| ---------------------- | -------------------------------------------------------------------------- |
+| Command existence      | Does a command doc exist to implement the scenario?                        |
+| Business rule coverage | Are feature test cases covered by command business rules?                  |
+| Error handling         | Are expected error cases from feature included in command error scenarios? |
+| Process flow alignment | Does feature process flow match command process flow?                      |
+
+#### How to Check
+
+1. List all scenario patterns from feature
+2. Identify required operations (verbs) for each scenario: "Add", "Update", "Delete", "Set default", etc.
+3. Verify corresponding command doc exists
+4. Map feature test cases to command business rules / error scenarios
+
+### 5. Feature → Model Parity Check
+
+For each entity mentioned in feature:
+
+| Check Item       | Question                                                           |
+| ---------------- | ------------------------------------------------------------------ |
+| Model existence  | Does a model doc exist for entities mentioned in feature?          |
+| State management | Do feature state transitions match model state transitions?        |
+| Relationships    | Are relationships shown in feature defined in model relationships? |
+
+### 6. Command → Model Consistency Check
+
+For each command doc:
+
+| Check Item                 | Question                                                       |
+| -------------------------- | -------------------------------------------------------------- |
+| Target model               | Does a model doc exist for the model that command operates on? |
+| State transition alignment | Do state changes by command match model state transitions?     |
+
+### 7. Report Findings
+
+```markdown
+## Feature Parity Review Report
+
+**Module:** <module-name>
+
+---
+
+### 1. Feature → Command Coverage
+
+| Feature     | Scenarios   | Required Commands                  | Documented Commands       | Gap                |
+| ----------- | ----------- | ---------------------------------- | ------------------------- | ------------------ |
+| <feature-1> | N scenarios | <cmd-a>, <cmd-b>, <cmd-c>, <cmd-d> | <cmd-a>, <cmd-b>, <cmd-c> | ❌ <cmd-d> missing |
+| <feature-2> | N scenarios | <cmd-e>, <cmd-f>, <cmd-g>          | -                         | ❌ No command docs |
+
+---
+
+### 2. Feature → Model Coverage
+
+| Feature     | Required Models      | Documented Models    | Gap |
+| ----------- | -------------------- | -------------------- | --- |
+| <feature-1> | <Model-A>            | <Model-A>            | ✅  |
+| <feature-2> | <Model-B>, <Model-A> | <Model-B>, <Model-A> | ✅  |
+| <feature-3> | <Model-C>, <Model-A> | <Model-C>, <Model-A> | ✅  |
+
+---
+
+### 3. Test Case → Business Rule Mapping
+
+| Feature     | Test Case                                  | Covered by Command      | Status            |
+| ----------- | ------------------------------------------ | ----------------------- | ----------------- |
+| <feature-1> | "<test case description from feature doc>" | <cmd-a> (business rule) | ✅                |
+| <feature-1> | "<test case description from feature doc>" | <cmd-c> (business rule) | ✅                |
+| <feature-2> | "<test case description from feature doc>" | -                       | ❌ No command doc |
+
+---
+
+### 4. Missing Documentation
+
+#### Missing Command Docs
+
+| Feature     | Expected Command | Purpose               |
+| ----------- | ---------------- | --------------------- |
+| <feature-2> | <cmd-e>          | <purpose description> |
+| <feature-2> | <cmd-f>          | <purpose description> |
+| <feature-2> | <cmd-g>          | <purpose description> |
+
+#### Missing Model Docs
+
+(none found)
+
+---
+
+### 5. Inconsistencies
+
+| Type                      | Location                               | Issue                                                             |
+| ------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| State transition mismatch | <feature-1> feature vs <Model-A> model | Feature shows "<cmd-x>" but no command doc exists                 |
+| Missing error scenario    | <feature-2> feature                    | "<error case from test cases>" has no corresponding command error |
+
+---
+
+### 6. Summary
+
+| Aspect                     | Status | Details                                     |
+| -------------------------- | ------ | ------------------------------------------- |
+| Feature → Command Coverage | ⚠️     | X/Y features have complete command coverage |
+| Feature → Model Coverage   | ✅     | All required models documented              |
+| Test Case Coverage         | ⚠️     | X/Y test cases mapped to business rules     |
+| Documentation Consistency  | ⚠️     | N inconsistencies found                     |
+
+### 7. Recommendations
+
+1. **Create missing command docs:**
+   - List all missing commands grouped by feature
+
+2. **Add missing business rules to existing command docs:**
+   - Feature test cases not yet mapped to command business rules
+3. **Resolve inconsistencies:**
+   - Align state transitions between feature and model docs
+```
+
+## Common Gaps
+
+### Feature → Command
+
+- **Orphaned scenarios**: Feature describes operation but no command doc exists
+- **Missing CRUD**: Feature implies create/update/delete but only some are documented
+- **Implicit commands**: Feature scenario requires helper command not documented
+- **Default handling**: Feature mentions "default" selection but no setDefault command
+
+### Feature → Model
+
+- **Missing models**: Feature references entity with no model doc
+- **State mismatch**: Feature shows states not in model's state diagram
+- **Relationship gaps**: Feature implies relationship not in model doc
+
+### Test Case → Business Rule
+
+- **Uncovered test cases**: Feature test case has no corresponding business rule
+- **Missing error scenarios**: Feature error case not in command's error scenarios
+- **Validation gaps**: Feature constraint not enforced by any command
+
+## Quick Reference: Extraction Patterns
+
+### From Feature Docs
+
+```markdown
+## Scenario Patterns
+
+- **Add <entity>**: ... → Command: add<Entity> / create<Entity>
+- **Change default <entity>**: ... → Command: setDefault<Entity>
+
+## Test Cases
+
+- Adding a <entity> with valid data creates it in active status
+  → Business rule in add<Entity>
+- Only one <entity> can be default per <parent> at a time
+  → Business rule in setDefault<Entity>
+```
+
+### Expected Command Docs for Feature
+
+| Feature Operation | Expected Command Doc |
+| ----------------- | -------------------- |
+| "Add X"           | addX / createX       |
+| "Update X"        | updateX              |
+| "Delete X"        | deleteX              |
+| "Set default X"   | setDefaultX          |
+| "Activate X"      | activateX            |
+| "Deactivate X"    | deactivateX          |
+| "Assign X to Y"   | assignXToY           |
+| "Remove X from Y" | removeXFromY         |
+
+## References
+
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)
+- [Testing patterns](references/testing.md)

package/skills/3-module-doc-review/references/commands.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "packages/erp-kit/src/modules/*/command/*.ts"
+  - "!packages/erp-kit/src/modules/*/command/*.test.ts"
+---
+
+# Command Implementation
+
+## defineCommand Pattern
+
+Commands that don't need custom fields use `defineCommand` directly:
+
+```typescript
+export const myCommand = defineCommand(permissions.myCommand, async (db: DB, input: Input) => { ... });
+```
+
+## Factory Function Pattern (custom fields)
+
+Commands that insert into a table with user-extensible fields use a `makeCreateX<CF>()` factory:
+
+- Export only `makeCreateX` — no default instance
+- Generic `CF extends Record<string, unknown>` for custom fields
+- Input type: `CreateXInput & CF`
+- Destructure known fields, rest-spread custom fields into `.values()` before known fields
+- Cast custom fields: `...(customFields as Record<string, unknown>)`
+- `module.ts` wires with `makeCreateX<FieldsToInsertable<F>>()`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/skills/3-module-doc-review/references/models.md

@@ -0,0 +1,29 @@
+# Database Models
+
+## Factory Function Pattern
+
+Each model is a `createXType<const F>(params)` factory:
+
+- Params interface generic: `F extends Record<string, TailorAnyDBField>`
+- `fields?: F` — optional custom fields from parent modules
+- Spread as `...(params.fields ?? {}) as F` to preserve type information
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+- Export a default instance: `export const x = createXType({})`
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/skills/3-module-doc-review/references/testing.md

@@ -0,0 +1,37 @@
+# Testing Patterns
+
+## Test Coverage Goal
+
+Tests should cover all paths in the corresponding `docs/commands/*.md`:
+
+- **Process Flow**: Each branch in the mermaid flowchart = one test case
+- **Error Scenarios**: Each error code listed = one test case
+- **Idempotent paths**: If flowchart shows "Already exists? → Return existing"
+
+## Mock Database
+
+```typescript
+const { db, spies } = createMockDb<DB>();
+
+// Single return
+spies.select.mockReturnValue(entity);
+
+// Sequential returns (in query execution order)
+spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
+```
+
+## Custom Fields Passthrough
+
+For `makeCreateX` factory commands, add one test verifying custom fields reach `.values()`:
+
+- Instantiate with concrete type: `makeCreateX<{ myField: string }>()`
+- Assert with `spies.values`: `expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ myField: "value" }))`
+- Use `toHaveBeenNthCalledWith(n, ...)` when multiple inserts occur (e.g., audit events)
+
+## Fixtures (`src/testing/fixtures.ts`)
+
+- Import `Schema` from `lib/types` (not `Namespace` from generated code)
+- Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`
+- Fixed IDs for traceability: `"entity-1"`
+- Consistent timestamp: `new Date("2024-01-01T00:00:00.000Z")`
+- `updatedAt: null` for base fixtures