@tailor-platform/erp-kit 0.2.0 → 0.2.2

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

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

package/skills/erp-kit-app-4-plan-review/references/story-resolver-parity.md

@@ -0,0 +1,83 @@
+# Story → Resolver Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Story docs: {{STORY_DOCS}}
+Resolver docs: {{RESOLVER_DOCS}}
+
+## Instructions
+
+1. Read ALL story docs at the paths above
+2. Read ALL resolver docs at the paths above
+3. For each story, check resolver coverage
+4. Return results as JSON per the Output Format section
+
+## Extraction: Story Docs
+
+From each story doc, extract:
+
+- Story name (from filename or heading)
+- Resolver section content:
+  - `None` → read-only story, skip resolver checks
+  - `- TBD` → story needs resolvers but none documented yet (fail)
+  - Resolver links (format: `../../../resolver/<name>.md`) → verify they exist
+- Operations described that imply mutations (create, update, delete, submit, approve, etc.)
+
+## Extraction: Resolver Docs
+
+From each resolver doc, extract:
+
+- Resolver name (from filename or heading)
+- Type: Mutation or Query
+- Module and command it calls
+- Input parameters and error scenarios
+
+## Parity Checks
+
+For each story:
+
+| Check ID           | Question                                                                 |
+| ------------------ | ------------------------------------------------------------------------ |
+| resolver_existence | Do all resolver links in the story resolve to existing docs?             |
+| resolver_coverage  | Does every non-read-only story have at least one resolver?               |
+| resolver_tbd       | Are there stories still showing `- TBD` for resolvers?                   |
+| link_validity      | Do resolver links in the story resolve to real files?                    |
+| operation_coverage | Do story operations (create/update/delete) have matching resolver types? |
+
+### How to Check
+
+1. Read each story's `## Resolvers` section
+2. If `None` → skip (read-only story)
+3. If `- TBD` → fail: resolver docs not yet created
+4. If links present → verify each link resolves to a file in RESOLVER_DOCS
+5. Cross-check story operations against resolver types (mutation for writes, query for reads)
+
+## Link Format Reference
+
+| From  | To       | Format                        |
+| ----- | -------- | ----------------------------- |
+| Story | Resolver | `../../../resolver/<name>.md` |
+
+## Common Gap Patterns
+
+- **TBD resolvers**: Story still has placeholder `- TBD` instead of resolver links
+- **Missing resolver docs**: Story links to a resolver that has no doc
+- **Operation mismatch**: Story describes a create operation but no create resolver exists
+- **Orphaned resolvers**: Resolver doc exists but no story links to it (covered by orphan detection)
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "story-resolver-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-app-4-plan-review/references/story-screen-parity.md

@@ -0,0 +1,73 @@
+# Story → Screen Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Story docs: {{STORY_DOCS}}
+Screen docs: {{SCREEN_DOCS}}
+
+## Instructions
+
+1. Read ALL story docs at the paths above
+2. Read ALL screen docs at the paths above
+3. For each story, extract referenced screens
+4. Run every parity check below against each story
+5. Return results as JSON per the Output Format section
+
+## Extraction: Story Docs
+
+From each story doc, extract:
+
+- Story name (from filename or heading)
+- All screen references (format: `../../../screen/<screen>.md`)
+- UI interactions described that imply screen usage
+
+## Extraction: Screen Docs
+
+From each screen doc, extract:
+
+- Screen name (from filename or heading)
+- Screen type and UI components described
+
+## Parity Checks
+
+For each story's screen references:
+
+| Check ID         | Question                                            |
+| ---------------- | --------------------------------------------------- |
+| screen_existence | Do all screens referenced in the story exist?       |
+| link_validity    | Do screen links in the story resolve to real files? |
+
+### How to Check
+
+1. List all screen references from each story doc
+2. Verify a corresponding screen doc exists for each reference
+3. Validate that all `../../../screen/<screen>.md` links resolve to actual files in SCREEN_DOCS
+
+## Link Format Reference
+
+| From  | To     | Format                        |
+| ----- | ------ | ----------------------------- |
+| Story | Screen | `../../../screen/<screen>.md` |
+
+## Common Gap Patterns
+
+- **Missing screen docs**: Story references a screen that has no doc
+- **Broken screen links**: Story links to a screen file that does not exist
+- **Implicit screens**: Story describes UI interaction but has no explicit screen link
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "story-screen-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-app-5-impl-backend/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: erp-kit-app-5-impl-backend
+description: Implement backend code for app-compose applications using erp-kit modules. Use after completing plan review with erp-kit-app-4-plan-review. Triggers when implementing backend resolvers, wiring modules, configuring applications, or when the user mentions implementing backend, writing resolvers, or connecting erp-kit modules.
+---
+
+# App-Compose Backend Implementation
+
+Implement backend resolvers and application configuration for an app-compose application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolvers).
+
+## When to Use
+
+- Implementing backend resolvers from resolver spec docs
+- Wiring erp-kit modules into an application
+- Configuring the Tailor application (auth, DB, resolvers)
+- Deploying the backend for frontend schema generation
+
+## 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 → MODULE WIRING → CONFIG → RESOLVERS → GENERATED FILES → VERIFY → DEPLOY
+```
+
+### 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: Wire Modules (`src/modules.ts`)
+
+Create the module wiring file that composes all required erp-kit modules.
+
+**Read [module wiring reference](references/module-wiring.md) 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 3: Configure Application (`tailor.config.ts`)
+
+**Read [application config reference](references/app-config.md) 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 4: Implement Backend Resolvers and Executors
+
+Write one file per resolver under `src/modules/<module-name>/resolvers/`, one per executor under `executors/`.
+
+**Read [resolver & executor patterns reference](references/resolver-patterns.md).**
+
+Do not directly mutate module-owned tables via Kysely — always use module commands.
+
+### Phase 5: 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 6: Verify
+
+```bash
+cd <app-root>/backend
+pnpm lint
+pnpm typecheck
+```
+
+### Phase 7: Deploy Backend & Next Steps
+
+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.
+
+After deployment is confirmed, proceed to frontend implementation with `/erp-kit-app-6-impl-frontend`.

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

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

package/skills/erp-kit-app-5-impl-backend/references/module-wiring.md

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

package/skills/erp-kit-app-5-impl-backend/references/resolver-patterns.md

@@ -0,0 +1,68 @@
+# Resolver & Executor Patterns
+
+## 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;
+```

package/skills/erp-kit-app-6-impl-frontend/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: erp-kit-app-6-impl-frontend
+description: Implement frontend code for app-compose applications. Use after deploying the backend with erp-kit-app-5-impl-backend. Triggers when implementing frontend pages, creating React components from screen specs, or when the user mentions implementing frontend, creating pages, or building UI for an app-compose application.
+---
+
+# App-Compose Frontend Implementation
+
+Implement frontend pages for an app-compose application, driven by screen spec documentation and a deployed backend.
+
+## When to Use
+
+- Implementing frontend pages from screen spec docs
+- Creating React components for ListView, Form, or DetailView screens
+- Building the frontend UI for an app-compose application after backend deployment
+
+## Prerequisites
+
+- Deployed backend (from `erp-kit-app-5-impl-backend`)
+- `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`
+- All four tiers of documentation:
+  - `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)
+
+## Workflow
+
+```
+ANALYZE SCREENS → GENERATE GRAPHQL SCHEMA → IMPLEMENT PAGES → VERIFY
+```
+
+### Phase 1: Analyze Screen Documentation
+
+Read all screen specs (`docs/screen/*.md`) to build a complete picture:
+
+1. **Screen types** — Identify each screen as ListView, Form (create/edit), or DetailView
+2. **Fields and columns** — Map required columns (ListView), form fields (Form), and detail fields (DetailView) from each spec
+3. **Actions** — Identify navigation actions (create, edit, back-to-list) and mutation actions (save, delete, activate/deactivate)
+
+### Phase 2: Generate GraphQL Schema
+
+Run `pnpm generate` in the frontend directory to fetch the GraphQL schema from the deployed backend.
+
+### Phase 3: Implement Frontend Pages
+
+Create pages driven by screen spec docs. Each screen type has a standard implementation pattern.
+
+**Read [pages reference](references/pages.md) 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 4: Verify
+
+```bash
+cd <app-root>/frontend
+pnpm lint
+pnpm typecheck
+pnpm build
+```