@tailor-platform/erp-kit 0.2.1 → 0.3.0

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

@@ -1,88 +0,0 @@
----
-name: erp-kit-app-2-breakdown
-description: Create Tier 3 documentation (stories, screens) by breaking down business flows. Use after completing Tier 1-2 documentation with erp-kit-app-1-requirements.
----
-
-# 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 app scaffold story <app> <flow>/<actor>--<story> --root examples
-
-# Tier 3: Screens
-erp-kit app scaffold screen <app> <screen-name> --root examples
-```
-
-**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**, replace `- TBD` placeholders in the `## Stories` section of each business flow README with actual links:
-
-```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 `/erp-kit-app-3-doc-review` to validate documentation parity.

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

@@ -1,112 +0,0 @@
----
-name: erp-kit-app-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 `/erp-kit-app-4-impl-spec` to create implementation specifications from screen and story documentation.

package/skills/erp-kit-app-4-impl-spec/SKILL.md

@@ -1,116 +0,0 @@
----
-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
-
-Create Tier 4 documentation: GraphQL Resolvers (mutations and queries).
-
-## Prerequisites
-
-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)
-
-## Workflow Phases
-
-```
-ANALYZE → IDENTIFY → CHECK MODULES → CREATE → VALIDATE
-```
-
-### Phase 1: Analyze
-
-Read all story files and identify:
-
-1. **Operations** that modify data → mutations
-2. **Operations** that retrieve data → queries
-3. **Error scenarios** for each operation
-
-### Phase 2: Identify
-
-Map stories to resolvers:
-
-| Story Element        | Resolver Type |
-| -------------------- | ------------- |
-| Create/Update/Delete | Mutation      |
-| View/List/Search     | Query         |
-| Real-time updates    | Subscription  |
-
-**Naming:** Use camelCase action-verb names: `create`, `update`, `delete`, `submit`, `approve`
-
-### Phase 3: Check Module Dependencies
-
-Resolvers reference module commands. Before creating resolver docs, verify required modules exist.
-
-**Check existing modules:**
-
-```bash
-ls packages/erp-kit/src/modules/
-```
-
-**Check module commands:**
-
-```bash
-ls packages/erp-kit/src/modules/<module-name>/docs/commands/
-```
-
-**Map resolvers to modules:**
-
-| Resolver Operation | Typical Module        |
-| ------------------ | --------------------- |
-| User invite/roles  | `user-management`     |
-| Supplier CRUD      | `supplier-management` |
-| Document handling  | `document-management` |
-| Task workflows     | `task-management`     |
-
-**If modules don't exist:**
-
-1. **Identify needed modules** - Group resolver operations by domain
-2. **Create module docs first** - Use `erp-kit-module-1-docs` skill
-3. **Return to Tier 4** - After modules have documented commands
-
-```
-Tier 4 blocked → Create modules → Return to Tier 4
-```
-
-**Only reference existing module commands** in resolver documentation. Never reference modules or commands that don't exist.
-
-### Phase 4: Create
-
-Generate documentation using `erp-kit` CLI:
-
-```bash
-erp-kit scaffold --app-root examples resolver <app> <resolver-name>
-```
-
-**Naming conventions:**
-
-- Filename must match H1 heading exactly (camelCase)
-- Action-focused names: `createSupplierInvitation.md`
-
-### Phase 5: Validate
-
-```bash
-pnpm run app:doc:check
-```
-
-## Schema Reference
-
-| Schema         | Tier | Output Path               |
-| -------------- | ---- | ------------------------- |
-| `resolver.yml` | 4    | `docs/resolver/<name>.md` |
-
-## Tips
-
-- One story may require 1-3 resolvers
-- Group related operations logically
-- Document all error scenarios
-
-## Next Step
-
-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

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

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