@tailor-platform/erp-kit 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tailor-platform/erp-kit
 
+## 0.2.1
+
+### Patch Changes
+
+- 4c94ba6: Add erp-kit-app-5-implementation skill, remove app-4-design and app-5-design-review skills
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -274,9 +274,8 @@ App-compose workflow:
 1. `erp-kit-app-1-requirements` — Tier 1-2: requirements, actors, business flows
 2. `erp-kit-app-2-breakdown` — Tier 3: stories and screens
 3. `erp-kit-app-3-doc-review` — Review doc parity
-4. `erp-kit-app-4-design` — Create UI mockups from screen specs
-5. `erp-kit-app-5-design-review` — Review mockups against specs
-6. `erp-kit-app-6-impl-spec` — Tier 4: resolver specs
+4. `erp-kit-app-4-impl-spec` — Tier 4: resolver specs
+5. `erp-kit-app-5-implementation` — Implement backend and frontend
 
 Mock workflow:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

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

@@ -24,6 +24,9 @@ structure:
 
       # Diagram representing this flow - REQUIRED
       - heading: "## Flow Diagram"
+        description: |
+          Mermaid sequence diagram showing actor interactions across the flow.
+          Use actors from "Actors Involved" as participants.
         code_blocks:
           - min: 1
             lang: mermaid

package/schemas/app-compose/story.yml

@@ -24,7 +24,7 @@ structure:
       # Diagram representing this story - REQUIRED
       - heading: "## Story Diagram"
         description: |
-          Mermaid sequence diagram showing user interactions with screens.
+          Mermaid flowchart showing user interactions with screens.
           Focus on actors, UI screens, and business outcomes.
           Avoid technical details (APIs, databases, endpoints).
         code_blocks:

package/skills/erp-kit-app-1-requirements/SKILL.md

@@ -44,13 +44,13 @@ Generate documentation using `erp-kit` CLI:
 
 ```bash
 # Tier 1: Requirements
-erp-kit scaffold --app-root examples requirements <app-name>
+erp-kit app scaffold requirements <app-name> --root examples
 
 # Tier 2: Actors
-erp-kit scaffold --app-root examples actors <app-name> <actor-name>
+erp-kit app scaffold actors <app-name> <actor-name> --root examples
 
 # Tier 2: Business Flows
-erp-kit scaffold --app-root examples business-flow <app-name> <flow-name>
+erp-kit app scaffold business-flow <app-name> <flow-name> --root examples
 ```
 
 **Naming conventions:**
@@ -58,13 +58,11 @@ erp-kit scaffold --app-root examples business-flow <app-name> <flow-name>
 - Files: kebab-case (e.g., `sales-representative.md`)
 - H1 heading slug must match filename slug
 
-**Authorized Business Flows format (in actor docs):**
+**Business flow diagram:** Use `sequenceDiagram` with actors from "Actors Involved" as participants. Show who initiates each step and the system responses.
 
-```markdown
-- [Flow Name](../business-flow/<flow>/README.md) — role
-```
+**Business flow `## Stories` section:**
 
-Roles: `initiator`, `approver`, `viewer`
+At Tier 2, story files do not exist yet. Use `- TBD` as a placeholder to avoid broken link violations. Replace with actual story links in `/erp-kit-app-2-breakdown`.
 
 ### Phase 4: Validate
 
@@ -83,7 +81,3 @@ pnpm run app:doc:check
 ## Next Step
 
 After completing Tier 1-2, use `/erp-kit-app-2-breakdown` to create Tier 3 documentation.
-
-## References
-
-- [Application structure](references/structure.md)

package/skills/erp-kit-app-2-breakdown/SKILL.md

@@ -46,10 +46,10 @@ Generate documentation using `erp-kit` CLI:
 
 ```bash
 # Tier 3: Stories
-erp-kit scaffold --app-root examples story <app> <flow>/<actor>--<story>
+erp-kit app scaffold story <app> <flow>/<actor>--<story> --root examples
 
 # Tier 3: Screens
-erp-kit scaffold --app-root examples screen <app> <screen-name>
+erp-kit app scaffold screen <app> <screen-name> --root examples
 ```
 
 **Naming conventions:**
@@ -58,7 +58,7 @@ erp-kit scaffold --app-root examples screen <app> <screen-name>
 - 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:
+**After creating stories**, replace `- TBD` placeholders in the `## Stories` section of each business flow README with actual links:
 
 ```markdown
 - [Story Title](./story/<actor>--<story-name>.md)
@@ -86,10 +86,3 @@ pnpm run app:doc:check
 ## Next Step
 
 After completing Tier 3, use `/erp-kit-app-3-doc-review` to validate documentation parity.
-
-## References
-
-- [Application structure](references/structure.md)
-- [ListView screen](references/screen-listview.md)
-- [Form screen](references/screen-form.md)
-- [DetailView screen](references/screen-detailview.md)

package/skills/erp-kit-app-3-doc-review/SKILL.md

@@ -109,8 +109,4 @@ examples/<app-name>/docs/actors/*.md                  # Actors
 
 ## Next Step
 
-After fixing all issues, use `/erp-kit-app-4-design` to create visual UI mockups from screen specifications.
-
-## References
-
-- [Application structure](references/structure.md)
+After fixing all issues, use `/erp-kit-app-4-impl-spec` to create implementation specifications from screen and story documentation.

package/skills/{erp-kit-app-6-impl-spec → erp-kit-app-4-impl-spec}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: erp-kit-app-6-impl-spec
-description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing design review with erp-kit-app-5-design-review.
+name: erp-kit-app-4-impl-spec
+description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing documentation review with erp-kit-app-3-doc-review.
 ---
 
 # Implementation Spec Workflow
@@ -9,14 +9,13 @@ Create Tier 4 documentation: GraphQL Resolvers (mutations and queries).
 
 ## Prerequisites
 
-Tier 1-3 documentation and design mockups must exist:
+Tier 1-3 documentation must exist:
 
 - `README.md` (requirements)
 - `docs/actors/*.md` (actors)
 - `docs/business-flow/*/README.md` (flows)
 - `docs/business-flow/*/story/*.md` (stories)
 - `docs/screen/*.md` (screens)
-- `docs/design.pen` (UI mockups)
 
 ## Workflow Phases
 
@@ -42,7 +41,7 @@ Map stories to resolvers:
 | View/List/Search     | Query         |
 | Real-time updates    | Subscription  |
 
-**Naming:** Use action-verb names: `create-`, `update-`, `delete-`, `submit-`, `approve-`
+**Naming:** Use camelCase action-verb names: `create`, `update`, `delete`, `submit`, `approve`
 
 ### Phase 3: Check Module Dependencies
 
@@ -51,13 +50,13 @@ Resolvers reference module commands. Before creating resolver docs, verify requi
 **Check existing modules:**
 
 ```bash
-ls modules/
+ls packages/erp-kit/src/modules/
 ```
 
 **Check module commands:**
 
 ```bash
-ls modules/<module-name>/docs/commands/
+ls packages/erp-kit/src/modules/<module-name>/docs/commands/
 ```
 
 **Map resolvers to modules:**
@@ -91,8 +90,8 @@ erp-kit scaffold --app-root examples resolver <app> <resolver-name>
 
 **Naming conventions:**
 
-- Filename must match H1 heading exactly (kebab-case)
-- Action-focused names: `create-supplier-invitation.md`
+- Filename must match H1 heading exactly (camelCase)
+- Action-focused names: `createSupplierInvitation.md`
 
 ### Phase 5: Validate
 
@@ -112,16 +111,6 @@ pnpm run app:doc:check
 - Group related operations logically
 - Document all error scenarios
 
-## Completion
+## Next Step
 
-After Tier 4, the application specification is complete:
-
-- **Tier 1**: Application overview
-- **Tier 2**: Actors and business workflows
-- **Tier 3**: User stories and screens
-- **Tier 4**: Implementation specifications
-
-## References
-
-- [Application structure](references/structure.md)
-- [Backend auth](references/auth.md)
+After completing Tier 4, use `/erp-kit-app-5-implementation` to implement backend resolvers and frontend pages.

package/skills/erp-kit-app-5-implementation/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: erp-kit-app-5-implementation
+description: Implement backend and frontend code for app-compose applications using erp-kit modules. Use after completing Tier 4 documentation (resolver specs) with erp-kit-app-4-impl-spec. Triggers when implementing resolvers, wiring modules, creating frontend pages, or building a full-stack application from documentation specs. Also use when the user mentions implementing an app, writing backend resolvers, creating frontend pages, or connecting erp-kit modules to an application.
+---
+
+# App-Compose Implementation
+
+Implement backend resolvers and frontend pages for an app-compose application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolver specs).
+
+## When to Use
+
+- Implementing backend resolvers from resolver spec docs
+- Creating frontend pages from screen spec docs
+- Wiring erp-kit modules into an application
+- Building full-stack code for an app-compose application
+
+## Prerequisites
+
+All four tiers of documentation must exist:
+
+- `README.md` — Application overview
+- `docs/actors/*.md` — Actor definitions
+- `docs/business-flow/*/README.md` + `story/*.md` — Business flows and user stories
+- `docs/screen/*.md` — Screen specifications (ListView, Form, DetailView)
+- `docs/resolver/*.md` — Resolver specifications (mutations, queries)
+
+## Workflow
+
+```
+ANALYZE DOCS → BACKEND SCAFFOLD → MODULE WIRING → CONFIG → RESOLVERS → GENERATED FILES → DEPLOY → FRONTEND SCAFFOLD → PAGES → VERIFY
+```
+
+### Phase 1: Analyze Documentation
+
+Read all resolver and screen specs to build a complete picture:
+
+1. **Resolver docs** (`docs/resolver/*.md`) — Identify which module commands each resolver calls, what inputs/outputs it needs, and what errors it handles
+2. **Screen docs** (`docs/screen/*.md`) — Identify screen types (ListView, Form, DetailView) and their fields/columns/actions
+3. **Command source types** — For each module command the resolver calls, read the input type at `node_modules/@tailor-platform/erp-kit/src/modules/<module>/command/<commandName>.ts`. Do not invent fields that don't exist in the command, and preserve the required/optional distinction.
+
+Classify resolvers into two categories:
+
+| Category             | Description                                                                        | Implementation                                                               |
+| -------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Custom resolvers** | Mutations that call module commands (create, update, activate, deactivate, assign) | Write `createResolver()` files                                               |
+| **Built-in queries** | List and get operations for reading data                                           | Handled automatically by `gqlOperations: "query"` in config — no code needed |
+
+Prefer built-in queries over custom resolvers for list/get operations where possible.
+
+### Phase 2: Backend Scaffold
+
+Set up the backend project structure and config files.
+
+**Read [backend reference](references/backend.md) § "Backend Scaffold" for the directory structure and boilerplate.**
+
+Key files: `package.json` (dependencies, scripts), `tsconfig.json` (path alias, types), `eslint.config.js`.
+
+### Phase 3: Wire Modules (`src/modules.ts`)
+
+Create the module wiring file that composes all required erp-kit modules.
+
+**Read [backend reference](references/backend.md) § "Module Wiring" for the composition pattern.**
+
+Key points:
+
+- Use `defineXxxModule()` functions from `@tailor-platform/erp-kit/module`
+- Pass inter-module dependencies explicitly (e.g., item-management needs primitives' unit type and query)
+- Export `db`, `commands`, and `executors` for use in resolvers
+
+### Phase 4: Configure Application (`tailor.config.ts`)
+
+**Read [backend reference](references/backend.md) § "Application Config" for the config pattern.**
+
+Key points:
+
+- Single DB namespace (`"main-db"`) with `gqlOperations: "query"` for automatic list/get queries
+- Resolver/executor discovery via glob patterns
+- Auth with OAuth2, DPoP, and user profile mapping
+- Generators for Kysely types and seed data
+
+### Phase 5: Implement Backend Resolvers and Executors
+
+Write one file per resolver under `src/modules/<module-name>/resolvers/`, one per executor under `executors/`.
+
+**Read [backend reference](references/backend.md) § "Resolver Patterns" and "Executor Patterns".**
+
+Do not directly mutate module-owned tables via Kysely — always use module commands.
+
+### Phase 6: Generated Files
+
+- **Kysely types** (`src/generated/kysely-tailordb.ts`) — Auto-generated by `pnpm generate` after deployment. Before deployment, create a minimal placeholder so the codebase typechecks.
+- **Seed data** (`seed/`) — `exec.mjs` runner + `data/*.jsonl` (records) and `data/*.schema.ts` (validation). Create seed records for initial data (permissions, roles, test users, etc.). Seeded users must have concrete permission keys required by the wired modules.
+
+### Phase 7: Deploy Backend
+
+Frontend implementation requires a deployed backend (for GraphQL schema generation). Prompt the user to:
+
+1. Create a workspace and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
+2. Run `pnpm deploy` and `pnpm generate`
+3. Run `pnpm seed` if seed data was created
+4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json` for frontend `.env`
+
+Wait for the user to confirm deployment is complete before proceeding.
+
+### Phase 8: Frontend Scaffold
+
+Set up the frontend project structure, config files, and generate GraphQL schema.
+
+**Read [frontend reference](references/frontend.md) § "Frontend Scaffold" for the directory structure, boilerplate, and schema generation.**
+
+Key files: `package.json`, `tsconfig.json`, `vite.config.ts`, `eslint.config.js`, UI components, `scripts/generate-graphql.mjs`. After scaffolding, run `pnpm generate` to fetch the GraphQL schema from the deployed backend.
+
+### Phase 9: Implement Frontend Pages
+
+Create pages driven by screen spec docs. Each screen type has a standard implementation pattern.
+
+**Read [frontend reference](references/frontend.md) § "Frontend Pages" for the full pattern catalog.**
+
+Page types and their file structure:
+
+| Screen Type   | Files                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| ListView      | `page.tsx` + `components/<entity>-table.tsx`                                                     |
+| Form (create) | `create/page.tsx` + `create/components/create-<entity>-form.tsx`                                 |
+| Form (edit)   | `[id]/edit/page.tsx` + `[id]/edit/components/edit-<entity>-form.tsx`                             |
+| DetailView    | `[id]/page.tsx` + `[id]/components/<entity>-detail.tsx` + `[id]/components/<entity>-actions.tsx` |
+
+Key frontend patterns:
+
+- **GraphQL fragments** — Each table/form/detail component exports its own fragment; page-level queries compose fragments
+- **gql.tada** — Type-safe GraphQL via `graphql()` from `@/graphql`
+- **React Hook Form + Zod** — Form validation with `zodResolver`
+- **urql** — `useQuery` for reads, `useMutation` for writes
+- **app-shell routing** — `Layout`, `Link`, `useParams`, `useNavigate` from `@tailor-platform/app-shell`
+
+### Phase 10: Verify
+
+```bash
+# Backend
+cd <app-root>/backend
+pnpm lint
+pnpm typecheck
+
+# Frontend
+cd <app-root>/frontend
+pnpm lint
+pnpm typecheck
+pnpm build
+```

package/skills/erp-kit-app-5-implementation/references/backend.md

@@ -0,0 +1,232 @@
+# Backend Implementation Patterns
+
+## Table of Contents
+
+- [Backend Scaffold](#backend-scaffold)
+- [Module Wiring](#module-wiring)
+- [Application Config](#application-config)
+- [Resolver Patterns](#resolver-patterns)
+- [Executor Patterns](#executor-pattern)
+
+---
+
+## Backend Scaffold
+
+```
+backend/
+├── src/
+│   ├── modules.ts                          # Module wiring
+│   ├── generated/kysely-tailordb.ts        # Auto-generated (placeholder until deploy)
+│   └── modules/<module-name>/
+│       ├── resolvers/<name>.ts
+│       └── executors/<name>.ts
+├── seed/                                   # Seed data scripts
+├── package.json
+├── tsconfig.json
+├── eslint.config.js
+└── tailor.config.ts
+```
+
+`package.json` key dependencies and scripts:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "generate": "tailor-sdk generate",
+    "deploy": "tailor-sdk apply --env-file-if-exists .env",
+    "lint": "eslint --cache .",
+    "typecheck": "tsc --noEmit",
+    "seed": "node --env-file-if-exists=.env seed/exec.mjs"
+  },
+  "dependencies": {
+    "@tailor-platform/erp-kit": "...",
+    "@tailor-platform/function-kysely-tailordb": "...",
+    "kysely": "..."
+  },
+  "devDependencies": {
+    "@tailor-platform/sdk": "...",
+    "@tailor-platform/function-types": "...",
+    "typescript": "..."
+  }
+}
+```
+
+`tsconfig.json` — requires `@/*` path alias and `@tailor-platform/function-types` in types:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node", "@tailor-platform/function-types"],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["**/*.ts"]
+}
+```
+
+---
+
+## Module Wiring
+
+`src/modules.ts` composes erp-kit modules and exports their parts for resolver use.
+
+```ts
+import { db as field } from "@tailor-platform/sdk";
+import {
+  definePrimitivesModule,
+  defineUserManagementModule,
+  defineItemManagementModule,
+} from "@tailor-platform/erp-kit/module";
+
+const primitivesModules = definePrimitivesModule({});
+
+const umModules = defineUserManagementModule({
+  dbNamespace: "main-db",
+  user: {
+    fields: {
+      /* custom fields */
+    },
+    additionalStatuses: ["SUSPENDED"],
+  },
+});
+
+// Pass inter-module dependencies explicitly
+const imModules = defineItemManagementModule({
+  primitives: {
+    db: { unit: primitivesModules.db.unit },
+    queries: { getUnit: primitivesModules.queries.getUnit },
+  },
+});
+
+// Destructure db into individual table exports (required for DB scanner)
+export const { db: primitivesDb, commands: primitivesCommands } = primitivesModules;
+export const { uomCategory, unit, currency, exchangeRate } = primitivesDb;
+
+export const { db: umDb, executors: umExecutors, commands: umCommands } = umModules;
+export const { user, permission, role, userRole, rolePermission, auditEvent } = umDb;
+
+export const { db: imDb, commands: imCommands } = imModules;
+export const { item, taxonomyNode, itemTaxonomyAssignment } = imDb;
+```
+
+Key conventions:
+
+- Prefix exports to avoid collisions (`umCommands`, `imCommands`, `primitivesCommands`)
+- Every module's `db` must be destructured into individual table exports — the DB scanner only picks up named exports
+- Extract individual executors for re-export in executor files
+
+---
+
+## Application Config
+
+`tailor.config.ts` defines the Tailor application configuration. Key structure:
+
+```ts
+export default defineConfig({
+  name: "<app-name>",
+  cors: ["http://localhost:5173", website.url],
+  db: {
+    "main-db": {
+      files: [`./src/modules.ts`],
+      gqlOperations: "query",
+    },
+  },
+  resolver: {
+    "main-resolver": { files: [`./src/modules/**/resolvers/**/*.ts`] },
+  },
+  executor: { files: [`./src/modules/**/executors/**/*.ts`] },
+  auth: auth,
+  idp: [idp],
+  staticWebsites: [website],
+});
+```
+
+Key points:
+
+- `gqlOperations: "query"` — Auto-generates list/get GraphQL queries for all DB types
+- Glob patterns for resolver/executor discovery
+- See [SDK configuration docs](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/configuration.md) for full config options
+
+### Auth configuration
+
+- Define IdP (`defineIdp`), Auth (`defineAuth`), and static website (`defineStaticWebSite`) using Tailor SDK
+- Prefer stable default naming: auth `default`, IdP `default`, OAuth2 client `default`
+- `userProfile.type` must reference the `user` DB type from `modules.ts`
+- `userProfile.usernameField`: stable unique field (e.g., `email`)
+- Include static website URL and localhost in CORS: `cors: ["http://localhost:5173", website.url]`
+- Frontend `VITE_TAILOR_CLIENT_ID` must come from `tailor-sdk oauth2client get default --json` — do not hardcode
+
+---
+
+## Resolver Patterns
+
+All resolvers export a default `createResolver()` from `@tailor-platform/sdk`.
+
+### Verify command input types
+
+Before implementing a resolver, read the command's type definition:
+
+```
+node_modules/@tailor-platform/erp-kit/src/modules/<module>/command/<commandName>.ts
+```
+
+The command source is the ground truth. Do not invent fields that don't exist, and preserve the required/optional distinction.
+
+### SDK type system
+
+See [Resolver docs](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/services/resolver.md) for the `t` namespace.
+
+`t.array()` and `t.boolean()` do **not exist**. Never attempt to use them.
+
+### Command-based mutation
+
+The most common pattern. Key points:
+
+```ts
+import { createContext } from "@tailor-platform/erp-kit/app";
+
+body: async (context) => {
+  const db = getDB("main-db");
+  const result = await imCommands.createItem(db, { ...context.input }, createContext(context));
+  if (!result.ok) throw result.error;
+  return { id: result.value.item.id, ... };
+},
+```
+
+- `context.input.optionalField ?? undefined` — Convert null to undefined for command inputs
+- `result.value.entity.nullableField ?? ""` — Handle nullable return values
+- `createContext(context)` wraps the resolver context for erp-kit commands
+- `getDB("main-db")` — Namespace must match `tailor.config.ts`
+
+### Error handling
+
+When the resolver spec documents specific error codes, use `result.error.code` to switch:
+
+```ts
+if (!result.ok) {
+  switch (result.error.code) {
+    case "USER_NOT_FOUND":
+      throw new Error(`User ${context.input.userId} not found`);
+    // ...
+  }
+}
+```
+
+Do not directly mutate module-owned tables via Kysely — always use module commands.
+
+---
+
+## Executor Patterns
+
+Executors re-export module-provided event handlers. One file per executor, no custom logic:
+
+```ts
+import { rolePermissionCreated } from "@/modules";
+export default rolePermissionCreated;
+```