@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

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

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

@@ -0,0 +1,85 @@
+---
+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.

package/skills/app-compose-2-requirements-breakdown/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: app-compose-2-requirements-breakdown
+description: Create Tier 3 documentation (stories, screens) by breaking down business flows. Use after completing Tier 1-2 documentation with app-compose-1-requirement-analysis.
+---
+
+# Requirements Breakdown Workflow
+
+Break down Tier 2 business flows into Tier 3 documentation: User Stories and Screens.
+
+## Prerequisites
+
+Tier 1-2 documentation must exist:
+
+- `README.md` (requirements)
+- `docs/actors/*.md` (actor definitions)
+- `docs/business-flow/*/README.md` (business workflows)
+
+## Workflow Phases
+
+```
+ANALYZE → BREAKDOWN → CREATE → VALIDATE
+```
+
+### Phase 1: Analyze
+
+Review existing Tier 2 documentation:
+
+1. **Read** all business flow files in `docs/business-flow/`
+2. **Identify** flow steps that represent user actions
+3. **Map** each step to the responsible actor
+4. **Note** data inputs/outputs for each step
+
+### Phase 2: Breakdown
+
+For each business flow, decompose into stories and screens:
+
+| Flow Element     | Maps To     |
+| ---------------- | ----------- |
+| User action step | Story       |
+| UI requirement   | Screen      |
+| Actor in flow    | Story actor |
+
+### Phase 3: Create
+
+Generate documentation using `erp-kit` CLI:
+
+```bash
+# Tier 3: Stories
+erp-kit scaffold --app-root examples story <app> <flow>/<actor>--<story>
+
+# Tier 3: Screens
+erp-kit scaffold --app-root examples screen <app> <screen-name>
+```
+
+**Naming conventions:**
+
+- Story filename: `<actor>--<story-name>.md` (double-dash separator)
+- Story heading: Title Case of story name (after `--`)
+- Screen filename: kebab-case, noun-focused (e.g., `supplier-list.md`)
+
+**After creating stories**, update `## Stories` section in business flow README:
+
+```markdown
+- [Story Title](./story/<actor>--<story-name>.md)
+```
+
+### Phase 4: Validate
+
+```bash
+pnpm run app:doc:check
+```
+
+## Schema Reference
+
+| Schema       | Tier | Output Path                                          |
+| ------------ | ---- | ---------------------------------------------------- |
+| `story.yml`  | 3    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
+| `screen.yml` | 3    | `docs/screen/<name>.md`                              |
+
+## Tips
+
+- One business flow typically produces 3-8 stories
+- Stories should be completable in a single user session
+- Screens can be shared across multiple stories
+
+## Next Step
+
+After completing Tier 3, use `/app-compose-3-doc-review` to validate documentation parity.

package/skills/app-compose-3-doc-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: app-compose-3-doc-review
+description: Review documentation parity between Tier 2 (business flows, actors) and Tier 3 (stories, screens). Use when validating that all business flow steps have corresponding stories, and that screens are properly linked.
+---
+
+# Documentation Parity Review Workflow
+
+Review **documentation consistency** between Tier 2 and Tier 3 documentation.
+
+## Purpose
+
+```
+Business Flow (Tier 2)  →  Stories (Tier 3)  →  Screens (Tier 3)
+        ↓                        ↓                     ↓
+   Flow Steps              User Actions           UI Components
+   Actors Involved         Scenario Patterns      Screen Types
+```
+
+## When to Use
+
+- After writing Tier 3 documentation, check for gaps
+- Before proceeding to Tier 4 (implementation spec)
+- Quality check during documentation review
+
+## Workflow
+
+```
+READ DOCS → PARITY CHECKS → REPORT
+```
+
+### Step 1: Read All Documentation
+
+```
+examples/<app-name>/docs/business-flow/*/README.md    # Flows
+examples/<app-name>/docs/business-flow/*/story/*.md   # Stories
+examples/<app-name>/docs/screen/*.md                  # Screens
+examples/<app-name>/docs/actors/*.md                  # Actors
+```
+
+### Step 2: Parity Checks
+
+#### Business Flow → Story
+
+| Check           | Question                                        |
+| --------------- | ----------------------------------------------- |
+| Story existence | Does each flow step have a corresponding story? |
+| Actor coverage  | Are all actors in flow represented in stories?  |
+| Link validity   | Do story links in flow README resolve?          |
+
+#### Actor → Business Flow
+
+| Check          | Question                                  |
+| -------------- | ----------------------------------------- |
+| Flow existence | Do all flows in "Authorized Flows" exist? |
+| Link validity  | Do flow links resolve correctly?          |
+
+#### Story → Screen
+
+| Check            | Question                           |
+| ---------------- | ---------------------------------- |
+| Screen existence | Do all screens in story exist?     |
+| Link validity    | Do screen links resolve correctly? |
+
+#### Orphan Detection
+
+| Check          | Question                                   |
+| -------------- | ------------------------------------------ |
+| Orphan stories | Stories not linked from any business flow? |
+| Orphan screens | Screens not referenced by any story?       |
+| Orphan actors  | Actors not participating in any flow?      |
+
+### Step 3: Report
+
+```markdown
+## Documentation Parity Review Report
+
+**Application:** <app-name>
+
+### Summary
+
+| Aspect                | Status   | Details           |
+| --------------------- | -------- | ----------------- |
+| Business Flow → Story | ✅/⚠️/❌ | X/Y flows covered |
+| Actor → Flow          | ✅/⚠️/❌ | All links valid   |
+| Story → Screen        | ✅/⚠️/❌ | X missing screens |
+| Orphan Detection      | ✅/⚠️/❌ | N orphans found   |
+
+### Gaps Found
+
+- [ ] Missing: <item>
+- [ ] Broken link: <source> → <target>
+- [ ] Orphan: <file>
+
+### Recommendations
+
+1. Create missing: ...
+2. Fix broken links: ...
+3. Remove or link orphans: ...
+```
+
+## Link Format Reference
+
+| From          | To            | Format                              |
+| ------------- | ------------- | ----------------------------------- |
+| Business Flow | Story         | `./story/<actor>--<name>.md`        |
+| Business Flow | Actor         | `../../actors/<actor>.md`           |
+| Actor         | Business Flow | `../business-flow/<flow>/README.md` |
+| Story         | Screen        | `../../../screen/<screen>.md`       |
+
+## Next Step
+
+After fixing all issues, use `/app-compose-4-design-mock` to create visual UI mockups from screen specifications.