@tailor-platform/erp-kit 0.0.1 → 0.1.1

package/skills/5-module-implementation-review/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: 5-module-implementation-review
+description: Review implementation parity between documentation and code. Use when validating that TDD implementation (step 4) matches model docs, command docs, and test coverage requirements.
+---
+
+# Implementation Parity Review Workflow
+
+Review **implementation consistency** between documentation and actual code.
+
+## Purpose
+
+Verify that TDD implementation (models, commands, tests) properly implements what's documented in model docs and command docs.
+
+```
+Model Docs (Schema)     →  src/db/*.ts (Implementation)
+     ↓                           ↓
+  Fields                    createEntityType()
+  Relationships             Foreign keys
+  State Transitions         Status enums
+
+Command Docs (Spec)     →  src/command/*.ts (Implementation)
+     ↓                           ↓
+  Business Rules            Validation logic
+  Error Scenarios           Error classes
+  Process Flows             Branching logic
+
+Command Docs (Spec)     →  src/command/*.test.ts (Tests)
+     ↓                           ↓
+  Process Flow branches     Test cases
+  Error scenarios           Error assertions
+  Idempotent paths          Return existing tests
+```
+
+## When to Use
+
+- After TDD implementation (step 4), verify it matches documentation
+- Before merging feature branches
+- Quality check during code review
+
+## Workflow
+
+```
+MODEL DOCS → MODEL CODE → COMMAND DOCS → COMMAND CODE → TESTS → COMPARE → REPORT
+```
+
+## Step-by-Step
+
+### 1. Read Model Documentation
+
+Read ALL model docs:
+
+```
+modules/<module-name>/docs/models/*.md
+```
+
+Extract for each model:
+
+- Field names and types
+- Required vs optional fields
+- Relationships (foreign keys)
+- State transitions (if stateful)
+- Constraints
+
+### 2. Read Model Implementation
+
+Read ALL model files:
+
+```
+modules/<module-name>/src/db/*.ts
+```
+
+Extract for each model:
+
+- Fields in `createEntityType()`
+- Status enums (base + additional)
+- Foreign key references
+- Field descriptions
+
+### 3. Read Command Documentation
+
+Read ALL command docs:
+
+```
+modules/<module-name>/docs/commands/*.md
+```
+
+Extract for each command:
+
+- Business rules
+- Error scenarios (with codes)
+- Process flow branches
+- Input/output types
+
+### 4. Read Command Implementation
+
+Read ALL command files:
+
+```
+modules/<module-name>/src/command/*.ts
+```
+
+Extract for each command:
+
+- Validation logic implemented
+- Error classes thrown
+- Branching paths (if/else, early returns)
+- Input interface fields
+- Return type structure
+
+### 5. Read Error Implementation
+
+Read error definitions:
+
+```
+modules/<module-name>/src/lib/errors.ts
+```
+
+Extract:
+
+- Error class names
+- Error codes
+- Error message patterns
+
+### 6. Read Test Implementation
+
+Read ALL test files:
+
+```
+modules/<module-name>/src/command/*.test.ts
+```
+
+Extract for each command:
+
+- Test case descriptions
+- Error assertions
+- Happy path coverage
+- Edge case coverage
+
+### 7. Model Doc → Model Code Parity Check
+
+| Check Item         | Question                                                         |
+| ------------------ | ---------------------------------------------------------------- |
+| Field coverage     | Does code include all fields from model doc?                     |
+| Type accuracy      | Do field types match doc specification?                          |
+| Required fields    | Are required fields enforced (no default, not nullable)?         |
+| Relationship impl  | Are foreign key fields implemented for documented relationships? |
+| State transitions  | Does status enum include all documented states?                  |
+| Field descriptions | Do `.description()` calls match doc field descriptions?          |
+
+### 8. Command Doc → Command Code Parity Check
+
+| Check Item              | Question                                                   |
+| ----------------------- | ---------------------------------------------------------- |
+| Business rule impl      | Is each documented business rule implemented in code?      |
+| Error scenario coverage | Does code throw errors for all documented error scenarios? |
+| Error code accuracy     | Do error codes in code match documented codes?             |
+| Process flow alignment  | Do code branches match documented process flow?            |
+| Input type coverage     | Does input interface include all documented inputs?        |
+| Return type accuracy    | Does return type match documented output?                  |
+| Dual function pattern   | Does command follow `_fn` internal / `fn` public pattern?  |
+
+### 9. Command Doc → Test Coverage Check
+
+| Check Item            | Question                                                   |
+| --------------------- | ---------------------------------------------------------- |
+| Process flow coverage | Does each branch in process flow have a test case?         |
+| Error scenario tests  | Does each documented error scenario have a test assertion? |
+| Happy path tests      | Are success paths tested?                                  |
+| Idempotent path tests | If doc shows "already exists → return", is this tested?    |
+
+### 10. Report Findings
+
+```markdown
+## Implementation Parity Review Report
+
+**Module:** <module-name>
+
+---
+
+### 1. Model Doc → Model Code Coverage
+
+| Model Doc | Fields Documented | Fields Implemented | Gap                 |
+| --------- | ----------------- | ------------------ | ------------------- |
+| <Model-A> | N fields          | N fields           | ✅                  |
+| <Model-B> | N fields          | N-1 fields         | ❌ `fieldX` missing |
+
+---
+
+### 2. Model State Transitions
+
+| Model     | Documented States        | Implemented States | Gap                |
+| --------- | ------------------------ | ------------------ | ------------------ |
+| <Model-A> | PENDING, ACTIVE, REMOVED | PENDING, ACTIVE    | ❌ REMOVED missing |
+| <Model-B> | ACTIVE, INACTIVE         | ACTIVE, INACTIVE   | ✅                 |
+
+---
+
+### 3. Command Doc → Command Code Coverage
+
+| Command Doc | Business Rules | Implemented | Gap                              |
+| ----------- | -------------- | ----------- | -------------------------------- |
+| <cmd-a>     | 3 rules        | 3 rules     | ✅                               |
+| <cmd-b>     | 4 rules        | 3 rules     | ❌ "rule X validation" not found |
+
+---
+
+### 4. Error Scenario Implementation
+
+| Command Doc | Error Code       | Implemented in errors.ts | Thrown in command | Test assertion |
+| ----------- | ---------------- | ------------------------ | ----------------- | -------------- |
+| <cmd-a>     | ENTITY_NOT_FOUND | ✅ EntityNotFoundError   | ✅                | ✅             |
+| <cmd-a>     | INVALID_STATE    | ❌ Not defined           | ❌                | ❌             |
+| <cmd-b>     | DUPLICATE_ENTRY  | ✅ DuplicateEntryError   | ✅                | ❌ No test     |
+
+---
+
+### 5. Process Flow → Test Coverage
+
+| Command Doc | Process Flow Branches | Test Cases | Gap                              |
+| ----------- | --------------------- | ---------- | -------------------------------- |
+| <cmd-a>     | 3 branches            | 3 tests    | ✅                               |
+| <cmd-b>     | 4 branches            | 2 tests    | ❌ Missing "already exists" test |
+
+---
+
+### 6. Implementation Pattern Compliance
+
+| Command | Dual Function Pattern | Input Interface Exported | JSDoc Present |
+| ------- | --------------------- | ------------------------ | ------------- |
+| <cmd-a> | ✅ `_cmdA` + `cmdA`   | ✅                       | ✅            |
+| <cmd-b> | ❌ Only `cmdB`        | ✅                       | ❌            |
+
+---
+
+### 7. Missing Implementation
+
+#### Missing in Model Code
+
+| Model Doc | Missing Item | Type   | Doc Reference               |
+| --------- | ------------ | ------ | --------------------------- |
+| <Model-A> | `fieldX`     | Field  | "fieldX: uuid, required"    |
+| <Model-A> | `REMOVED`    | Status | State diagram shows REMOVED |
+
+#### Missing in Command Code
+
+| Command Doc | Missing Item     | Type          | Doc Reference            |
+| ----------- | ---------------- | ------------- | ------------------------ |
+| <cmd-b>     | validation for X | Business rule | "Rule: X must be unique" |
+
+#### Missing Error Classes
+
+| Command Doc | Error Code    | Expected Class    |
+| ----------- | ------------- | ----------------- |
+| <cmd-a>     | INVALID_STATE | InvalidStateError |
+
+#### Missing Tests
+
+| Command Doc | Missing Test Case                | Doc Reference         |
+| ----------- | -------------------------------- | --------------------- |
+| <cmd-b>     | "entity already exists → return" | Process flow branch 2 |
+| <cmd-b>     | "throws DUPLICATE_ENTRY"         | Error scenario 3      |
+
+---
+
+### 8. Inconsistencies
+
+| Type                | Location       | Issue                                       |
+| ------------------- | -------------- | ------------------------------------------- |
+| Type mismatch       | Model-A.fieldX | Doc: string, Code: number                   |
+| Error code mismatch | cmd-a          | Doc: USER_NOT_FOUND, Code: ENTITY_NOT_FOUND |
+| Missing description | Model-B.fieldY | No `.description()` but doc has description |
+
+---
+
+### 9. Summary
+
+| Aspect                        | Status | Details                           |
+| ----------------------------- | ------ | --------------------------------- |
+| Model Doc → Code Coverage     | ⚠️     | X/Y models fully implemented      |
+| Command Doc → Code Coverage   | ⚠️     | X/Y commands fully implemented    |
+| Error Scenario Implementation | ❌     | X/Y errors defined and thrown     |
+| Test Coverage                 | ⚠️     | X/Y process branches have tests   |
+| Pattern Compliance            | ✅     | All commands follow dual function |
+
+### 10. Recommendations
+
+1. **Add missing model fields:**
+   - Model-A: add `fieldX` field
+
+2. **Add missing status values:**
+   - Model-A: add `REMOVED` to status enum
+
+3. **Implement missing business rules:**
+   - cmd-b: add validation for "X must be unique"
+
+4. **Define missing error classes:**
+   - Add `InvalidStateError` in errors.ts
+
+5. **Add missing test cases:**
+   - cmd-b: test "entity already exists → return existing"
+   - cmd-b: test "throws DUPLICATE_ENTRY on duplicate"
+
+6. **Fix inconsistencies:**
+   - Model-A.fieldX: change type to string per doc
+```
+
+## Common Gaps
+
+### Model Doc → Model Code
+
+- **Missing fields**: Doc specifies field but not in code
+- **Type mismatches**: Doc says string, code uses number
+- **Missing status values**: State diagram shows state not in enum
+- **Missing relationships**: Doc shows FK but not implemented
+- **Missing descriptions**: Doc has field description but no `.description()`
+
+### Command Doc → Command Code
+
+- **Unimplemented business rules**: Rule in doc but no validation code
+- **Missing error throws**: Error scenario documented but not thrown
+- **Wrong error codes**: Code and doc use different error codes
+- **Missing process branches**: Flowchart branch not in code logic
+- **Missing dual function**: Only public function, no internal `_fn`
+
+### Command Doc → Tests
+
+- **Uncovered process branches**: Flowchart branch has no test
+- **Missing error tests**: Error scenario has no assertion
+- **Missing idempotent tests**: "Return existing" path untested
+- **Missing edge cases**: Boundary conditions not tested
+
+## Quick Reference: Extraction Patterns
+
+### From Model Docs
+
+```markdown
+## Fields
+
+| Field    | Type   | Required |
+| -------- | ------ | -------- | ---------------------------------------- |
+| id       | uuid   | yes      | → Check: field exists, type matches      |
+| name     | string | yes      | → Check: not nullable                    |
+| status   | enum   | yes      | → Check: enum values match state diagram |
+| parentId | uuid   | yes      | → Check: foreign key implemented         |
+
+## State Diagram
+
+PENDING → ACTIVE → REMOVED
+→ Check: all states in enum
+```
+
+### From Command Docs
+
+```markdown
+## Business Rules
+
+1. Entity must exist → Check: validation in code
+2. Status must be ACTIVE → Check: status check in code
+
+## Error Scenarios
+
+| Code           | Condition      |
+| -------------- | -------------- | ----------------------------------- |
+| NOT_FOUND      | Entity missing | → Check: error class + throw + test |
+| INVALID_STATUS | Wrong status   | → Check: error class + throw + test |
+
+## Process Flow (mermaid)
+
+graph TD
+A[Start] --> B{Exists?}
+B -->|Yes| C[Return] → Check: test for "already exists"
+B -->|No| D[Create] → Check: test for "create new"
+```
+
+### From Implementation
+
+```typescript
+// Model: check fields match doc
+export function createEntityType(params) {
+  return {
+    fields: {
+      /* verify each field */
+    },
+  };
+}
+
+// Command: check business rules
+export async function _myCommand(db, input) {
+  // Check: validation for each business rule
+  if (!entity) throw new EntityNotFoundError(); // Check: matches doc error
+  // Check: each branch matches process flow
+}
+
+// Test: check coverage
+describe("myCommand", () => {
+  it("creates entity when valid"); // Check: happy path
+  it("returns existing if found"); // Check: idempotent path
+  it("throws NOT_FOUND when missing"); // Check: error scenario
+});
+```
+
+## References
+
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)
+- [Error patterns](references/errors.md)
+- [Testing patterns](references/testing.md)
+- [Export order](references/exports.md)

package/skills/5-module-implementation-review/references/commands.md

@@ -0,0 +1,45 @@
+# Command Implementation
+
+## Dual Function Pattern
+
+Two functions per operation: internal `_fn` and public `fn`.
+
+**Internal function (`_myFunction`):**
+
+- Takes concrete `DB` type from `generated/kysely-tailordb`
+- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
+- Contains actual implementation
+
+**Public function (`myFunction`):**
+
+- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
+- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
+- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
+
+## 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/5-module-implementation-review/references/errors.md

@@ -0,0 +1,7 @@
+# Error Classes
+
+Naming convention:
+
+- `name`: Class name exactly, `as const`
+- `code`: SCREAMING_SNAKE_CASE, `as const`
+- Constructor includes context (IDs, values)

package/skills/5-module-implementation-review/references/exports.md

@@ -0,0 +1,8 @@
+# Module Exports
+
+Export order:
+
+1. `defineModule` from module.ts
+2. Generated types (enum values + types separately)
+3. Error classes (for typed catch blocks)
+4. Domain functions with input types

package/skills/5-module-implementation-review/references/models.md

@@ -0,0 +1,30 @@
+# Database Models
+
+## Factory Function Pattern
+
+```typescript
+export function createEntityType(params: {
+  fields?: Record<string, unknown>;
+  additionalStatuses?: string[];
+});
+```
+
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+
+## 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/5-module-implementation-review/references/testing.md

@@ -0,0 +1,29 @@
+# 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);
+```
+
+## 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

package/skills/app-compose-1-requirement-analysis/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: app-compose-1-requirement-analysis
+description: Create Tier 1-2 documentation (requirements, actors, business-flow) for examples/. Use when starting a new application or documenting high-level requirements and workflows.
+---
+
+# Application Requirement Analysis Workflow
+
+Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.
+
+## Workflow Phases
+
+```
+GATHER → CLARIFY → CREATE → VALIDATE
+```
+
+### Phase 1: Gather
+
+Understand the application's purpose and scope:
+
+1. **Identify** what the application does (business purpose)
+2. **List** target users (actors) and their roles
+3. **Understand** business goals and success criteria
+4. **Capture** key workflows the application must support
+
+Focus on "what" the application should do, not "how" it will be implemented.
+
+### Phase 2: Clarify
+
+Use AskUserQuestion to clarify undefined requirements:
+
+| Category          | Example Questions                              |
+| ----------------- | ---------------------------------------------- |
+| Authentication    | External IdP / Password / Out of scope?        |
+| User Operations   | Direct creation / Email invitation / Both?     |
+| Roles             | Fixed roles (Admin/User) / Custom roles?       |
+| User Self-Service | View only / Profile edit / Password change?    |
+| Lifecycle         | Create only / Full lifecycle (activate/deact)? |
+
+Ask 3-4 questions at a time using multiSelect where appropriate.
+
+### Phase 3: Create
+
+Generate documentation using `erp-kit` CLI:
+
+```bash
+# Tier 1: Requirements
+erp-kit scaffold --app-root examples requirements <app-name>
+
+# Tier 2: Actors
+erp-kit scaffold --app-root examples actors <app-name> <actor-name>
+
+# Tier 2: Business Flows
+erp-kit scaffold --app-root examples business-flow <app-name> <flow-name>
+```
+
+**Naming conventions:**
+
+- Files: kebab-case (e.g., `sales-representative.md`)
+- H1 heading slug must match filename slug
+
+**Authorized Business Flows format (in actor docs):**
+
+```markdown
+- [Flow Name](../business-flow/<flow>/README.md) — role
+```
+
+Roles: `initiator`, `approver`, `viewer`
+
+### Phase 4: Validate
+
+```bash
+pnpm run app:doc:check
+```
+
+## Schema Reference
+
+| Schema              | Tier | Output Path                           |
+| ------------------- | ---- | ------------------------------------- |
+| `requirements.yml`  | 1    | `README.md`                           |
+| `actors.yml`        | 2    | `docs/actors/<name>.md`               |
+| `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md` |
+
+## Next Step
+
+After completing Tier 1-2, use `/app-compose-2-requirements-breakdown` to create Tier 3 documentation.
+
+## References
+
+- [Application structure](references/structure.md)

package/skills/app-compose-1-requirement-analysis/references/structure.md

@@ -0,0 +1,27 @@
+# Application Directory Structure
+
+```
+{app_name}/
+├── backend/
+│   ├── src/
+│   │   ├── modules.ts              # Declaring module usage
+│   │   ├── modules/
+│   │   │   └── {module-name}/      # Module-specific directory
+│   │   │       ├── resolvers/      # API Definition to expose graphql apis
+│   │   │       └── executors/      # PubSub Automation (one file per declaration)
+│   │   └── generated/              # Auto-generated code (do not edit)
+│   └── tailor.config.ts            # tailor application config
+│
+└── frontend/
+    └── src/
+        ├── pages/                  # File-based routing (auto-discovered by Vite plugin)
+        │   └── {page-path}/
+        │       ├── page.tsx
+        │       └── {page-path}/
+        │           ├── components/
+        │           └── page.tsx
+        ├── components/
+        │   └── ui/                 # Generic UI components
+        ├── graphql/                # gql.tada settings
+        └── providers/              # react providers
+```