@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/skills/erp-kit-app-7-impl-review/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: erp-kit-app-7-impl-review
+description: Review implementation parity between documentation and code for app-compose applications. Use after frontend implementation (step 6) to validate code matches documentation.
+---
+
+# Implementation Parity Review
+
+Review **implementation consistency** between Tier 3-4 documentation and actual backend/frontend code.
+
+## When to Use
+
+- After backend and frontend implementation, verify code matches documentation
+- Before merging feature branches
+- Quality check during code review
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
+- `APP_NAME`: basename of APP_ROOT
+- `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
+- `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
+- `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/modules/*/resolvers/*.ts`
+- `BACKEND_EXECUTORS`: glob `<APP_ROOT>/backend/executors/*.ts`
+- `BACKEND_MODULES`: `<APP_ROOT>/backend/src/modules.ts`
+- `BACKEND_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
+- `FRONTEND_PAGES`: glob `<APP_ROOT>/frontend/src/app/(main)/**/*.tsx`
+
+Verify at least `RESOLVER_DOCS` or `SCREEN_DOCS` is non-empty. If no docs exist, stop with: "No docs found for app <APP_NAME>."
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 4 Agent tool calls in parallel — one per parity check.
+Each agent receives: APP_NAME, relevant doc/code file paths.
+Each agent returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
+If a doc or code directory is empty, the agent reports "no files found" and skips.
+
+| Agent | Prompt Template                                                                  | Inputs                                              |
+| ----- | -------------------------------------------------------------------------------- | --------------------------------------------------- |
+| 1     | [references/resolver-doc-code-parity.md](references/resolver-doc-code-parity.md) | RESOLVER_DOCS, BACKEND_RESOLVERS, BACKEND_EXECUTORS |
+| 2     | [references/screen-doc-code-parity.md](references/screen-doc-code-parity.md)     | SCREEN_DOCS, FRONTEND_PAGES                         |
+| 3     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | RESOLVER_DOCS, BACKEND_MODULES, BACKEND_CONFIG      |
+| 4     | (build verification — inline, no template)                                       | APP_ROOT                                            |
+
+For agents 1-3:
+
+1. Read the prompt template file
+2. Replace `{{APP_NAME}}` with the resolved app name
+3. Replace doc/code path placeholders with the actual file paths
+4. Dispatch the agent with the filled prompt
+
+For agent 4 (build verification):
+
+Run build checks inline:
+
+```bash
+cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
+cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
+```
+
+Report pass/fail for each check.
+
+## Step 3: Aggregate Results
+
+After ALL agents return:
+
+1. Collect the JSON results from each agent
+2. Merge all `gaps[]` arrays into a single list
+3. Merge all `inconsistencies[]` arrays into a single list
+4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
+5. Calculate totals across all summaries
+6. Render the final report below
+
+## Report Format
+
+Render the aggregated results as markdown:
+
+### Implementation Parity Review Report
+
+**Application:** <APP_NAME>
+
+---
+
+### 1. Resolver Doc → Backend Code Coverage
+
+| Resolver Doc | Module Command | Implemented | Error Handling | Gap |
+| ------------ | -------------- | ----------- | -------------- | --- |
+
+(Populated from agent 1 gaps)
+
+---
+
+### 2. Screen Doc → Frontend Code Coverage
+
+| Screen Doc | Screen Type | Page Exists | Fields Match | Gap |
+| ---------- | ----------- | ----------- | ------------ | --- |
+
+(Populated from agent 2 gaps)
+
+---
+
+### 3. Module Wiring Consistency
+
+| Resolver | Required Module | Wired in modules.ts | Config Reference | Gap |
+| -------- | --------------- | ------------------- | ---------------- | --- |
+
+(Populated from agent 3 gaps)
+
+---
+
+### 4. Build Verification
+
+| Check | Backend | Frontend |
+| ----- | ------- | -------- |
+| Lint  |         |          |
+| Types |         |          |
+| Build | N/A     |          |
+
+(Populated from agent 4 results)
+
+---
+
+### 5. Missing Implementation
+
+#### Missing Backend Resolvers
+
+| Resolver Doc | Expected File | Purpose |
+| ------------ | ------------- | ------- |
+
+#### Missing Frontend Pages
+
+| Screen Doc | Expected Path | Screen Type |
+| ---------- | ------------- | ----------- |
+
+#### Missing Module Wiring
+
+| Module | Referenced by Resolver | Status |
+| ------ | ---------------------- | ------ |
+
+(Populated from all agents' gaps where status is `fail`)
+
+---
+
+### 6. Inconsistencies
+
+| Type | Location | Issue |
+| ---- | -------- | ----- |
+
+(Populated from all agents' `inconsistencies[]`)
+
+---
+
+### 7. Summary
+
+| Aspect                       | Status | Details           |
+| ---------------------------- | ------ | ----------------- |
+| Resolver Doc → Code Coverage |        | X/Y checks passed |
+| Screen Doc → Code Coverage   |        | X/Y checks passed |
+| Module Wiring Consistency    |        | X/Y checks passed |
+| Build Verification           |        | pass / fail       |
+
+### 8. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Implement missing resolvers/pages (highest priority)
+2. Fix module wiring gaps
+3. Resolve field/type mismatches
+4. Fix build errors
+
+## References
+
+- [Implementation parity report format](references/impl-parity-report-format.md)
+- For backend patterns, see erp-kit-app-5-impl-backend
+- For frontend patterns, see erp-kit-app-6-impl-frontend

package/skills/erp-kit-app-7-impl-review/references/impl-parity-report-format.md

@@ -0,0 +1,52 @@
+# Implementation Parity Report Format
+
+All implementation parity check agents return results in this JSON structure.
+
+## Schema
+
+```json
+{
+  "check_type": "<one of: resolver-doc-code-parity, screen-doc-code-parity, module-wiring-parity>",
+  "app": "<app-name>",
+  "gaps": [
+    {
+      "source": "<source doc or code path>",
+      "target": "<target code or 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. type_mismatch, missing_field>",
+      "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`: doc and code are consistent
+- `fail`: gap or mismatch found
+- `skip`: target code/doc missing or empty, check could not run
+
+### inconsistencies[]
+
+Cross-cutting issues that don't fit a single gap entry (e.g., type mismatches, naming violations, missing patterns).
+
+### summary
+
+Aggregate counts. `total_checks = passed + failed + skipped`.

package/skills/erp-kit-app-7-impl-review/references/module-wiring-parity.md

@@ -0,0 +1,84 @@
+# Module Wiring Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Resolver docs: {{RESOLVER_DOCS}}
+Backend modules file: {{BACKEND_MODULES}}
+Backend config file: {{BACKEND_CONFIG}}
+
+## Instructions
+
+1. Read ALL resolver docs at the paths above
+2. Read the modules file (`src/modules.ts`)
+3. Read the config file (`tailor.config.ts`)
+4. Verify all required modules are wired and configured
+5. Return results as JSON per the Output Format section
+
+## Extraction: Resolver Docs
+
+From each resolver doc, extract:
+
+- Module it depends on (which `defineXxxModule` it needs)
+- Commands it calls (which module command functions)
+
+## Extraction: modules.ts
+
+From the modules file, extract:
+
+- All `defineXxxModule()` calls
+- Inter-module dependency wiring (e.g., primitives passed to item-management)
+- Exported `db`, `commands`, and `executors`
+
+## Extraction: tailor.config.ts
+
+From the config file, extract:
+
+- DB namespace configuration
+- Resolver/executor glob patterns
+- Auth configuration (IdP, Auth, user profile)
+- Generator configuration
+
+## Parity Checks
+
+| Check ID             | Question                                                         |
+| -------------------- | ---------------------------------------------------------------- |
+| module_wired         | Is every module referenced by resolvers wired in modules.ts?     |
+| dependency_order     | Are inter-module dependencies passed correctly?                  |
+| exports_complete     | Are db, commands, and executors all exported?                    |
+| config_resolver_glob | Does the resolver glob in config cover all resolver directories? |
+| config_executor_glob | Does the executor glob in config cover all executor files?       |
+| config_db_namespace  | Is the DB namespace configured?                                  |
+| config_auth          | Is auth configured with IdP, Auth, and user profile?             |
+
+### How to Check
+
+1. Build a set of required modules from resolver docs
+2. Check each required module appears as a `defineXxxModule()` call in modules.ts
+3. Verify dependency wiring (e.g., if item-management resolvers exist, primitives must be wired into it)
+4. Check tailor.config.ts resolver glob pattern covers all module resolver directories
+5. Verify auth is configured if any resolver requires authentication
+
+## Common Gap Patterns
+
+- **Missing module**: Resolver references a module not wired in modules.ts
+- **Missing dependency**: Module wired but not given required dependencies
+- **Glob mismatch**: Config resolver glob doesn't cover a module's resolvers directory
+- **Missing auth**: Resolvers exist but no auth configured
+- **Missing executors**: Module has event handlers but no executor glob configured
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "module-wiring-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-app-7-impl-review/references/resolver-doc-code-parity.md

@@ -0,0 +1,86 @@
+# Resolver Doc → Backend Code Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Resolver docs: {{RESOLVER_DOCS}}
+Backend resolvers: {{BACKEND_RESOLVERS}}
+Backend executors: {{BACKEND_EXECUTORS}}
+
+## Instructions
+
+1. Read ALL resolver docs at the paths above
+2. Read ALL backend resolver code files at the paths above
+3. Read ALL backend executor code files at the paths above
+4. For each resolver doc, check if it has a corresponding implementation
+5. Return results as JSON per the Output Format section
+
+## 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 (name, type, required/optional)
+- Error scenarios (error codes and conditions)
+- Expected output shape
+
+## Extraction: Backend Code
+
+From each resolver file (`src/modules/*/resolvers/*.ts`), extract:
+
+- Resolver name (from `createResolver()` call or filename)
+- Module command called (import path and function name)
+- Input parameter handling (`context.input.*` accesses)
+- Error handling (`result.error.code` switch cases)
+- Return value structure
+
+From each executor file (`executors/*.ts`), extract:
+
+- Executor name and which module event handler it re-exports
+
+## Parity Checks
+
+| Check ID             | Question                                                        |
+| -------------------- | --------------------------------------------------------------- |
+| resolver_impl_exists | Does a backend resolver file exist for each resolver doc?       |
+| command_reference    | Does the resolver code call the correct module command?         |
+| input_coverage       | Does the resolver handle all documented input parameters?       |
+| error_handling       | Does the resolver handle all documented error scenarios?        |
+| return_shape         | Does the resolver return the documented output shape?           |
+| executor_exists      | Does an executor exist for each module that has event handlers? |
+| no_direct_mutation   | Does the resolver avoid directly mutating module-owned tables?  |
+
+### How to Check
+
+1. For each resolver doc, find the corresponding code file by name
+2. Verify the code imports and calls the documented module command
+3. Check that `context.input.*` accesses match documented inputs
+4. Check that error `switch` cases cover all documented error codes
+5. Verify return value structure matches documentation
+6. Check executors re-export module event handlers without custom logic
+
+## Common Gap Patterns
+
+- **Missing resolver file**: Doc exists but no code file
+- **Wrong command**: Code calls a different module command than documented
+- **Missing input handling**: Doc specifies an input parameter not accessed in code
+- **Missing error cases**: Error scenario in doc not handled in code's switch
+- **Direct table mutation**: Code uses `db.insertInto()` on module-owned tables instead of module commands
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "resolver-doc-code-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-app-7-impl-review/references/screen-doc-code-parity.md

@@ -0,0 +1,86 @@
+# Screen Doc → Frontend Code Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Screen docs: {{SCREEN_DOCS}}
+Frontend pages: {{FRONTEND_PAGES}}
+
+## Instructions
+
+1. Read ALL screen docs at the paths above
+2. Read ALL frontend page/component files at the paths above
+3. For each screen doc, check if a corresponding page implementation exists
+4. Return results as JSON per the Output Format section
+
+## Extraction: Screen Docs
+
+From each screen doc, extract:
+
+- Screen name (from filename or heading)
+- Screen type: ListView, Form (create/edit), or DetailView
+- Fields/columns specified
+- Actions specified (create, edit, delete, activate, etc.)
+- Navigation targets
+
+## Extraction: Frontend Code
+
+From frontend pages, identify:
+
+- Page files (`page.tsx`) and their routes
+- Component files (tables, forms, details, actions)
+- GraphQL fragments and queries used
+- Form fields and validation schemas (Zod)
+- Table columns defined
+- Action buttons and navigation
+
+### Screen Type → File Pattern
+
+| Screen Type   | Expected 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`              |
+
+## Parity Checks
+
+| Check ID          | Question                                                      |
+| ----------------- | ------------------------------------------------------------- |
+| page_exists       | Does a page file exist for each screen doc?                   |
+| component_exists  | Do the expected components exist for the screen type?         |
+| field_coverage    | Does the page/component render all documented fields/columns? |
+| action_coverage   | Does the page implement all documented actions?               |
+| screen_type_match | Does the implementation match the documented screen type?     |
+
+### How to Check
+
+1. For each screen doc, map the screen name to an expected route path
+2. Check if the expected `page.tsx` and component files exist
+3. Read component code and verify documented fields appear (in table columns, form fields, or detail fields)
+4. Verify documented actions appear as buttons, links, or mutations
+5. Confirm the implementation pattern matches the screen type (table for ListView, form for Form, etc.)
+
+## Common Gap Patterns
+
+- **Missing page**: Screen doc exists but no page file
+- **Missing component**: Page exists but table/form/detail component missing
+- **Missing fields**: Doc specifies columns/fields not rendered in code
+- **Missing actions**: Doc specifies actions not implemented
+- **Type mismatch**: Doc says ListView but implementation is a DetailView
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "screen-doc-code-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-app-shared/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: erp-kit-app-shared
+description: Shared references for erp-kit app skills. Not invoked directly — referenced by erp-kit-app-1 through erp-kit-app-7.
+---
+
+# erp-kit-app-shared
+
+Canonical reference files shared across app skills. Individual skills reference these instead of maintaining their own copies.
+
+## References
+
+- [Schema constraints](references/schema-constraints.md) — H1 heading rules and validation constraints enforced by `erp-kit app check`
+- [Naming conventions](references/naming-conventions.md) — File and heading naming patterns for all doc types
+- [Link format reference](references/link-format-reference.md) — Canonical doc-to-doc link formats across tiers
+- [Resolver classification](references/resolver-classification.md) — Custom vs built-in resolver decision table and operation mapping

package/skills/erp-kit-app-shared/references/link-format-reference.md

@@ -0,0 +1,13 @@
+# Link Format Reference
+
+Canonical link formats used across all documentation tiers.
+
+## Doc-to-Doc Links
+
+| 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`       |
+| Story         | Resolver      | `../../../resolver/<name>.md`       |

package/skills/erp-kit-app-shared/references/naming-conventions.md

@@ -0,0 +1,21 @@
+# Naming Conventions
+
+## File Naming
+
+| Doc Type | Pattern                              | Example                          |
+| -------- | ------------------------------------ | -------------------------------- |
+| Actor    | kebab-case                           | `sales-representative.md`        |
+| Flow     | kebab-case directory                 | `employee-onboarding/README.md`  |
+| Story    | `<actor>--<story-name>.md`           | `admin--create-user.md`          |
+| Screen   | kebab-case, noun-focused             | `supplier-list.md`               |
+| Resolver | camelCase action-verb                | `createSupplierInvitation.md`    |
+
+## Heading Conventions
+
+See [schema-constraints.md](schema-constraints.md) for H1 heading rules enforced by `erp-kit app check`.
+
+Additional conventions:
+
+- Story heading: Title Case of story name after `--` prefix (e.g., `admin--create-user.md` → `# Create User`)
+- Screen heading: Title Case of filename slug
+- Resolver heading: camelCase matching filename

package/skills/erp-kit-app-shared/references/resolver-classification.md

@@ -0,0 +1,23 @@
+# Resolver Classification
+
+## Custom vs Built-in
+
+| 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.
+
+## Operation → Resolver Mapping
+
+| Flow Operation       | Resolver Type | Naming Pattern         |
+| -------------------- | ------------- | ---------------------- |
+| Create/Add entity    | Mutation      | `create<Entity>`       |
+| Update/Modify entity | Mutation      | `update<Entity>`       |
+| Delete/Remove entity | Mutation      | `delete<Entity>`       |
+| Activate entity      | Mutation      | `activate<Entity>`     |
+| Deactivate entity    | Mutation      | `deactivate<Entity>`   |
+| Assign X to Y        | Mutation      | `assign<X>To<Y>`       |
+| Submit/Approve       | Mutation      | `submit<Entity>` etc.  |
+| View/List/Get        | Query         | Built-in (no resolver) |

package/skills/erp-kit-app-shared/references/schema-constraints.md

@@ -0,0 +1,25 @@
+# Schema Constraints
+
+Rules enforced by `erp-kit app check`. **Never recommend changes that violate them.**
+
+## H1 Heading Rules
+
+| Doc Type      | H1 Rule                                              | Example                                                  |
+| ------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| README.md     | Must be `# README` (literal)                         | `# README`                                               |
+| Actor         | Slug must match filename                             | `admin.md` → `# Admin`, `sales-rep.md` → `# Sales Rep`  |
+| Business Flow | Kebab-case matching folder name (`[a-zA-Z0-9_\-]+`)  | `employee-onboarding/README.md` → `# employee-onboarding` |
+| Story         | Slug matches filename after actor prefix removal     | `admin--create-user.md` → `# Create User`               |
+
+## Requirements Structure
+
+The `## Industry Context` section contains `### Target Industry` and `### Domain Terminology` subsections. Requirements are bare list items under `### Domain Terminology` — do **not** add a separate `## Requirements` heading.
+
+## Naming Conventions
+
+- Files: kebab-case (e.g., `sales-representative.md`)
+- Business flow H1 headings are kebab-case — do **not** flag them as inconsistent with title-case actor headings. They follow different schemas.
+
+## Validation Notes
+
+- `app check` outputs "No matching files found" for doc types that don't exist yet (e.g., stories at Tier 2, screens at Tier 3). This is expected.