@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/skills/erp-kit-module-4-plan-review/references/feature-query-parity.md

@@ -0,0 +1,70 @@
+# Feature → Query Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+Query docs: {{QUERY_DOCS}}
+
+## Instructions
+
+1. Read ALL feature docs at the paths above
+2. Read ALL query docs at the paths above
+3. For each feature, identify read-only operations
+4. Run every parity check below
+5. Return results as JSON per the Output Format section
+
+## Extraction: Read Operations
+
+Identify read-only operations in each feature:
+
+- "look up", "get", "list", "convert", "calculate"
+- Any data retrieval that doesn't modify state
+
+## Expected Query Docs for Feature
+
+| Feature Operation | Expected Query Doc  |
+| ----------------- | ------------------- |
+| "Get X"           | GetX                |
+| "Look up X by Y"  | GetX (with Y input) |
+| "List X by Y"     | ListXsByY           |
+| "Convert X"       | ConvertX            |
+| "Calculate X"     | CalculateX          |
+
+## Parity Checks
+
+For each read operation implied by the feature:
+
+| Check ID        | Question                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| query_existence | Does a query doc exist for lookups, conversions, or aggregations?     |
+| input_coverage  | Are all lookup dimensions documented (by id, by unique field, by FK)? |
+| error_handling  | Are error scenarios for missing data documented?                      |
+
+### How to Check
+
+1. Identify read-only operations in the feature
+2. Verify corresponding query doc exists in `docs/queries/`
+3. Check that query docs have error scenarios where applicable
+
+## Common Gap Patterns
+
+- **Missing query docs**: Feature implies read operation but no query doc exists
+- **Missing conversions**: Feature mentions unit/currency conversion but no query doc
+- **Missing lookups**: Feature requires data retrieval not covered by a query doc
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "feature-query-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-module-4-plan-review/references/parity-report-format.md

@@ -0,0 +1,52 @@
+# Parity Report Format
+
+All parity check agents return results in this JSON structure.
+
+## Schema
+
+```json
+{
+  "check_type": "<one of: feature-command-parity, feature-query-parity, feature-model-parity, command-model-consistency>",
+  "module": "<module-name>",
+  "gaps": [
+    {
+      "source": "<source doc path>",
+      "target": "<target doc path or 'missing'>",
+      "check": "<check_id from the agent's parity checks table>",
+      "status": "pass | fail | skip",
+      "detail": "<human-readable description of the finding>"
+    }
+  ],
+  "inconsistencies": [
+    {
+      "type": "<inconsistency type, e.g. state_transition_mismatch>",
+      "location": "<source vs target description>",
+      "detail": "<human-readable description>"
+    }
+  ],
+  "summary": {
+    "total_checks": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0
+  }
+}
+```
+
+## Field Reference
+
+### gaps[]
+
+One entry per parity check performed. `status` is:
+
+- `pass`: source and target are consistent
+- `fail`: gap or mismatch found
+- `skip`: target docs missing or empty, check could not run
+
+### inconsistencies[]
+
+Cross-cutting issues found during the check that don't fit a single gap entry (e.g., naming violations, state mismatches across multiple docs).
+
+### summary
+
+Aggregate counts. `total_checks = passed + failed + skipped`.

package/skills/erp-kit-module-5-impl/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: erp-kit-module-5-impl
+description: Implement features in modules using TDD. Use after plan review (step 4) to implement database models, commands, and queries with test-driven development.
+---
+
+# TDD Implementation for Module Development
+
+Implement features in modules using Test-Driven Development with per-item agent delegation.
+
+## When to Use
+
+- Implementing new domain commands in any module
+- Implementing read-only queries in any module
+- Adding database models with `@tailor-platform/sdk`
+- Creating tests with `@tailor-platform/erp-kit` testing utilities
+
+## Workflow
+
+```
+SETUP → DB MODELS (agents) → GENERATE → COMMANDS (agents) → QUERIES (agents) → EXPORT → VERIFY
+```
+
+## Step 1: Setup
+
+Define shared context:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/models/*.md`
+- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/commands/*.md`
+- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/queries/*.md`
+
+Verify at least one doc type exists. If none, stop with: "No docs found for module <MODULE_NAME>. Run steps 1-4 first."
+
+## Step 2: DB Models — Agent per model
+
+**Read [models rules](references/models.md) and [db-relations rules](references/db-relations.md) before dispatching.**
+
+For each model doc in `MODEL_DOCS`, launch an Agent:
+
+| Agent per model | Prompt Template                                      | Inputs                             |
+| --------------- | ---------------------------------------------------- | ---------------------------------- |
+| N               | [references/model-impl.md](references/model-impl.md) | MODULE_NAME, single MODEL_DOC path |
+
+Parallelize across models when they have no cross-dependencies.
+For models with foreign key dependencies, implement the referenced model first.
+
+After all model agents complete, run:
+
+```bash
+pnpm generate
+```
+
+## Step 3: Generate Code from Docs
+
+```bash
+erp-kit module generate code --root <root> <module>
+```
+
+Generated `.generated.ts` files provide: error classes, permission definitions, and command/query shells. Never edit these files.
+
+## Step 4: Commands — Agent per command
+
+**Read [commands rules](../erp-kit-module-shared/references/commands.md) and [testing rules](../erp-kit-module-shared/references/testing.md) before dispatching.**
+
+For each command doc in `COMMAND_DOCS`, launch an Agent:
+
+| Agent per command | Prompt Template                                          | Inputs                               |
+| ----------------- | -------------------------------------------------------- | ------------------------------------ |
+| N                 | [references/command-impl.md](references/command-impl.md) | MODULE_NAME, single COMMAND_DOC path |
+
+Each agent implements:
+
+1. Test fixtures in `testing/fixtures.ts` (if not already created)
+2. Tests in `command/<name>.test.ts`
+3. Implementation in `command/<name>.ts` (export `run` function)
+
+Parallelize across commands when they have no shared fixture dependencies.
+
+## Step 5: Queries — Agent per query
+
+**Read [queries rules](../erp-kit-module-shared/references/queries.md) before dispatching.**
+
+For each query doc in `QUERY_DOCS`, launch an Agent:
+
+| Agent per query | Prompt Template                                      | Inputs                             |
+| --------------- | ---------------------------------------------------- | ---------------------------------- |
+| N               | [references/query-impl.md](references/query-impl.md) | MODULE_NAME, single QUERY_DOC path |
+
+Each agent implements the query in `query/<name>.ts`.
+Parallelize across all queries.
+
+## Step 6: Export
+
+**Read [exports rules](references/exports.md) for export order.**
+
+Update `index.ts` with all new exports.
+
+## Step 7: Verify
+
+```bash
+pnpm generate   # Regenerate types if models changed
+pnpm lint       # Check code style
+pnpm typecheck  # Verify TypeScript types
+pnpm test       # Run all tests
+```
+
+## References
+
+- [Module structure](../erp-kit-module-shared/references/structure.md)
+- [Model patterns](references/models.md)
+- [Database relations](references/db-relations.md)
+- [Cross-module dependencies](references/cross-module-dependency.md)
+- [Command patterns](../erp-kit-module-shared/references/commands.md)
+- [Query patterns](../erp-kit-module-shared/references/queries.md)
+- [Generated code](references/generated-code.md)
+- [Testing patterns](../erp-kit-module-shared/references/testing.md)
+- [Export order](references/exports.md)

package/skills/erp-kit-module-5-impl/references/command-impl.md

@@ -0,0 +1,68 @@
+# Command Implementation
+
+## Context
+
+Module: {{MODULE_NAME}}
+Command doc: {{COMMAND_DOC}}
+
+## Instructions
+
+Implement a command with tests using TDD.
+
+1. Read the command doc at the path above
+2. Read the generated shell at `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/<name>.generated.ts`
+3. Read existing commands in `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/` for patterns
+4. Implement in this order: fixtures → tests → implementation
+
+## Implementation Rules
+
+**Read these references before implementing:**
+
+- [Command patterns](../../erp-kit-module-shared/references/commands.md) — run function, custom fields, CQRS
+- [Testing patterns](../../erp-kit-module-shared/references/testing.md) — mock DB, fixtures, test structure
+
+### Step 1: Test Fixtures
+
+Add fixtures to `{{MODULES_ROOT}}/{{MODULE_NAME}}/testing/fixtures.ts`:
+
+- Use fixed IDs: `"entity-1"`, `"entity-2"`
+- Create minimal valid entities for the command under test
+- Include fixtures for related entities if needed
+
+### Step 2: Write Tests
+
+Create `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/<name>.test.ts`:
+
+- Test every process flow branch from the doc
+- Test every error scenario from the doc
+- Test idempotent paths if applicable
+- Use `createMockDb<DB>()` for mock database
+- Assert on result type (ok/err) and values
+
+### Step 3: Implement
+
+Create `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/<name>.ts`:
+
+- Export a `run` function
+- Generated shell wraps with `defineCommand(permissions.xxx, run)`
+- Pattern: validate → query → mutate
+- Generic `CF` for custom fields support
+- Use `from` parameter for state transition commands
+
+### From Doc to Code
+
+| Doc Element      | Code Element                                    |
+| ---------------- | ----------------------------------------------- |
+| Business rules   | Validation checks in `run` function             |
+| Error scenarios  | Import from `errors.generated.ts`, return `err` |
+| Process flow     | Implementation steps in `run` function          |
+| Input parameters | `Input` interface (exported)                    |
+| Permissions      | Generated in `permissions.generated.ts`         |
+
+## Output
+
+Write files:
+
+- `{{MODULES_ROOT}}/{{MODULE_NAME}}/testing/fixtures.ts` (add fixtures, don't overwrite existing)
+- `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/<name>.test.ts`
+- `{{MODULES_ROOT}}/{{MODULE_NAME}}/command/<name>.ts`

package/skills/erp-kit-module-5-impl/references/exports.md

@@ -0,0 +1,10 @@
+# Module Exports
+
+Module `index.ts` exports are kept minimal:
+
+1. `defineModule` from module.ts
+2. `permissions`, `own`, `all` from `lib/permissions.generated`
+
+Error classes, input types, and query functions are **not** re-exported from `index.ts`. Consumers import them directly from their source files (e.g., `../lib/errors.generated`, `../command/createItem`). This avoids naming conflicts in the top-level barrel file when multiple modules define similar error classes.
+
+Test files are exempt from the ESLint cross-module import restriction and may use direct path imports freely.

package/skills/erp-kit-module-5-impl/references/model-impl.md

@@ -0,0 +1,45 @@
+# Model Implementation
+
+## Context
+
+Module: {{MODULE_NAME}}
+Model doc: {{MODEL_DOC}}
+
+## Instructions
+
+Implement a database model based on the documentation.
+
+1. Read the model doc at the path above
+2. Read existing models in `{{MODULES_ROOT}}/{{MODULE_NAME}}/db/` for patterns
+3. Implement the model in `{{MODULES_ROOT}}/{{MODULE_NAME}}/db/<model-name>.ts`
+
+## Implementation Rules
+
+**Read these references before implementing:**
+
+- [Model patterns](models.md) — factory function, generics, stateful enums
+- [Database relations](db-relations.md) — `.relation()` for foreign keys
+- [Cross-module dependencies](cross-module-dependency.md) — DB type injection
+
+### Key Patterns
+
+1. **Factory function**: `export function create<Model>Type<const F extends Record<string, TailorAnyDBField> = Record<string, never>>(params?: { customFields?: F })`
+2. **Timestamps**: Always include `db.fields.timestamps()`
+3. **Descriptions**: Add `.description()` on every field
+4. **Relations**: Use `.relation()` instead of plain `db.uuid()` for foreign keys
+5. **Stateful models**: Use `additionalStatuses` for extension, never replace base statuses
+
+### From Doc to Code
+
+| Doc Element        | Code Element                              |
+| ------------------ | ----------------------------------------- |
+| Fields table       | `db.fields.*` definitions                 |
+| Required fields    | Field without `.optional()`               |
+| Status/state enum  | `db.fields.enum()` with status values     |
+| Relationships      | `.relation()` with type and toward config |
+| Unique constraints | `.unique()` on fields or composite index  |
+
+## Output
+
+Write the model file to `{{MODULES_ROOT}}/{{MODULE_NAME}}/db/<model-name>.ts`.
+Follow existing patterns in the module's `db/` directory.

package/skills/erp-kit-module-5-impl/references/query-impl.md

@@ -0,0 +1,53 @@
+# Query Implementation
+
+## Context
+
+Module: {{MODULE_NAME}}
+Query doc: {{QUERY_DOC}}
+
+## Instructions
+
+Implement a read-only query based on the documentation.
+
+1. Read the query doc at the path above
+2. Read the generated shell at `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/<name>.generated.ts` (if exists)
+3. Read existing queries in `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/` for patterns
+4. Implement the query
+
+## Implementation Rules
+
+**Read these references before implementing:**
+
+- [Query patterns](../../erp-kit-module-shared/references/queries.md) — defineQuery, ReadonlyDB, conventions
+
+### Key Patterns
+
+1. **Generated queries**: Handle simple lookups automatically; write custom for joins/aggregations
+2. **ReadonlyDB**: Always use `ReadonlyDB<DB>` type for database access
+3. **QueryContext**: Use for dependency injection
+4. **Results**: Return `ok(data)` or `err(error)`
+
+### Query Naming Convention
+
+| Pattern             | Name                     |
+| ------------------- | ------------------------ |
+| Get single entity   | `get{Entity}`            |
+| List by status      | `list{Status}{Entities}` |
+| List all            | `list{Entities}`         |
+| Search with filters | `search{Entities}`       |
+| Calculate/convert   | `calculate{Result}`      |
+
+### From Doc to Code
+
+| Doc Element      | Code Element              |
+| ---------------- | ------------------------- |
+| Input parameters | Query input type          |
+| Output shape     | Return type               |
+| Filtering logic  | WHERE clauses             |
+| Aggregation      | SQL aggregation functions |
+| Business logic   | Post-query transformation |
+
+## Output
+
+Write the query file to `{{MODULES_ROOT}}/{{MODULE_NAME}}/query/<name>.ts`.
+Follow existing patterns in the module's `query/` directory.

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: erp-kit-module-6-impl-review
+description: Review implementation parity between documentation and code. Use after TDD implementation (step 5) to validate code matches documentation.
+---
+
+# Implementation Parity Review
+
+Review **implementation consistency** between documentation and actual code.
+
+## When to Use
+
+- After TDD implementation (step 4), verify it matches documentation
+- Before merging feature branches
+- Quality check during code review
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/models/*.md`
+- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/commands/*.md`
+- `MODEL_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/db/*.ts`
+- `COMMAND_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.ts` (exclude `*.test.ts` and `*.generated.ts`)
+- `TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.test.ts`
+- `ERROR_DEFS`: `<MODULES_ROOT>/<MODULE_NAME>/lib/errors.generated.ts`
+
+Verify at least `MODEL_DOCS` or `COMMAND_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 4 Agent tool calls in parallel — one per parity check.
+Each agent receives: MODULE_NAME, relevant doc/code file paths.
+Each agent returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
+If a doc or code directory is empty, the agent reports "no files found" and skips.
+Otherwise, query each sequentially.
+
+| Agent | Prompt Template                                                                        | Inputs                                            |
+| ----- | -------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| 1     | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)             | MODEL_DOCS, MODEL_CODE                            |
+| 2     | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)         | COMMAND_DOCS, COMMAND_CODE                        |
+| 3     | [references/error-implementation-parity.md](references/error-implementation-parity.md) | COMMAND_DOCS, ERROR_DEFS, COMMAND_CODE, TEST_CODE |
+| 4     | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)         | COMMAND_DOCS, TEST_CODE                           |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{TEST_CODE}}`, `{{ERROR_DEFS}}` with the actual file paths
+4. Dispatch the agent with the filled prompt
+
+## Step 3: Aggregate Results
+
+After ALL agents return:
+
+1. Collect the JSON results from each agent
+2. Merge all `gaps[]` arrays into a single list
+3. Merge all `inconsistencies[]` arrays into a single list
+4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
+5. Calculate totals across all summaries
+6. Render the final report below
+
+## Report Format
+
+Render the aggregated results as markdown:
+
+### Implementation Parity Review Report
+
+**Module:** <MODULE_NAME>
+
+---
+
+### 1. Model Doc → Model Code Coverage
+
+| Model Doc | Fields Documented | Fields Implemented | Gap |
+| --------- | ----------------- | ------------------ | --- |
+
+(Populated from agent 1 gaps where check is `field_coverage`)
+
+---
+
+### 2. Model State Transitions
+
+| Model | Documented States | Implemented States | Gap |
+| ----- | ----------------- | ------------------ | --- |
+
+(Populated from agent 1 gaps where check is `state_transitions`)
+
+---
+
+### 3. Command Doc → Command Code Coverage
+
+| Command Doc | Business Rules | Implemented | Gap |
+| ----------- | -------------- | ----------- | --- |
+
+(Populated from agent 2 gaps where check is `business_rule_impl`)
+
+---
+
+### 4. Error Scenario Implementation
+
+| Command Doc | Error Code | Generated in errors.generated.ts | Returned in command | Test assertion |
+| ----------- | ---------- | -------------------------------- | ------------------- | -------------- |
+
+(Populated from agent 3 gaps)
+
+---
+
+### 5. Process Flow → Test Coverage
+
+| Command Doc | Process Flow Branches | Test Cases | Gap |
+| ----------- | --------------------- | ---------- | --- |
+
+(Populated from agent 4 gaps where check is `process_flow_coverage`)
+
+---
+
+### 6. Implementation Pattern Compliance
+
+| Command | Generated Shell | Input Interface Exported | JSDoc Present |
+| ------- | --------------- | ------------------------ | ------------- |
+
+(Populated from agent 2 gaps where check is `generated_shell_pattern`, `input_interface_export`, `jsdoc_present`)
+
+---
+
+### 7. Missing Implementation
+
+#### Missing in Model Code
+
+| Model Doc | Missing Item | Type | Doc Reference |
+| --------- | ------------ | ---- | ------------- |
+
+#### Missing in Command Code
+
+| Command Doc | Missing Item | Type | Doc Reference |
+| ----------- | ------------ | ---- | ------------- |
+
+#### Missing Error Classes
+
+| Command Doc | Error Code | Expected Class |
+| ----------- | ---------- | -------------- |
+
+#### Missing Tests
+
+| Command Doc | Missing Test Case | Doc Reference |
+| ----------- | ----------------- | ------------- |
+
+(Populated from all agents' gaps where status is `fail`)
+
+---
+
+### 8. Inconsistencies
+
+| Type | Location | Issue |
+| ---- | -------- | ----- |
+
+(Populated from all agents' `inconsistencies[]`)
+
+---
+
+### 9. Summary
+
+| Aspect                        | Status | Details           |
+| ----------------------------- | ------ | ----------------- |
+| Model Doc → Code Coverage     |        | X/Y checks passed |
+| Command Doc → Code Coverage   |        | X/Y checks passed |
+| Error Scenario Implementation |        | X/Y checks passed |
+| Test Coverage                 |        | X/Y checks passed |
+
+### 10. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Add missing model fields/states (highest priority)
+2. Implement missing business rules
+3. Define missing error classes (re-run `erp-kit module generate code`)
+4. Add missing test cases
+5. Fix inconsistencies
+
+## References
+
+- [Implementation parity report format](references/impl-parity-report-format.md)
+- [Command patterns](references/commands.md)
+- [Error patterns](references/errors.md)
+- [Testing patterns](references/testing.md)