@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {
@@ -33,24 +33,18 @@
     "zod": "4.3.6"
   },
   "devDependencies": {
-    "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.25.2",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.1.0",
     "@typescript-eslint/parser": "^8.57.0",
     "eslint": "10.0.3",
-    "kysely": "0.28.11",
     "tsdown": "0.21.3",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
     "@tailor-platform/eslint-config": "0.0.1"
   },
   "peerDependencies": {
-    "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.25.2",
-    "kysely": "0.28.11"
+    "@tailor-platform/sdk": "1.25.4"
   },
   "engines": {
     "node": ">=24"
@@ -63,9 +57,6 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:primitives": "vitest run src/modules/primitives/",
-    "test:user-management": "vitest run src/modules/user-management/",
-    "test:shared": "vitest run src/modules/shared/",
     "mock:start": "node dist/cli.mjs mock start",
     "mock:validate": "node dist/cli.mjs mock validate",
     "doc:gen": "POLITTY_DOCS_UPDATE=true vitest run src/cli.doc.test.ts",

package/skills/erp-kit-app-2-requirements-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-2-requirements-review
-description: Review requirements quality and documentation consistency for app-compose applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
+description: Review requirements quality and documentation consistency for applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
 ---
 
 # Requirements Review
 
-Review **requirements quality** and **documentation consistency** for an app-compose application's Tier 1-2 documentation.
+Review **requirements quality** and **documentation consistency** for an application's Tier 1-2 documentation.
 
 ## When to Use
 

package/skills/erp-kit-app-2-requirements-review/references/best-practices-check.md

@@ -19,7 +19,7 @@ This review targets Tier 1-2 documentation only. Stories (`## Stories` section i
 
 1. Read the application README at the path above
 2. Read ALL actor docs and business flow docs at the paths above
-3. **Web search** app-compose and ERP application best practices (actor modeling, business flow design, user journey patterns)
+3. **Web search** ERP application best practices (actor modeling, business flow design, user journey patterns)
 4. Evaluate whether the Tier 1-2 documentation follows best practices
 5. **Verify** that none of your recommendations would violate the schema constraints above
 6. Return results as markdown per the Output Format section

package/skills/erp-kit-app-3-plan/references/resolver-extraction.md

@@ -34,9 +34,12 @@ erp-kit doc module <module-name> command <command-name>
 For each business flow step that modifies data:
 
 1. Identify the operation type (create, update, delete, approve, etc.)
-2. Map to a resolver name using camelCase action-verb convention
-3. Identify the module command the resolver will call. If no erp-kit module covers the domain, flag it as a module gap.
-4. Extract inputs, outputs, and error scenarios
+2. Determine if the operation needs a resolver:
+   - If the operation is a **scheduled job, cron task, webhook handler, or system-triggered process** that doesn't expose a GraphQL endpoint → mark the story's Resolvers section as `N/A — <reason>` (e.g., `N/A — background job`). No resolver doc is needed.
+   - Otherwise, continue to step 3.
+3. Map to a resolver name using camelCase action-verb convention
+4. Identify the module command the resolver will call. If no erp-kit module covers the domain, flag it as a module gap.
+5. Extract inputs, outputs, and error scenarios
 
 ### Operation → Resolver Mapping
 

package/skills/erp-kit-app-4-plan-review/SKILL.md

@@ -24,6 +24,7 @@ Define shared context for all agents:
 - `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
 - `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
+- `MODULE_METADATA`: run `pnpm erp-kit doc modules --format json` and capture the JSON output. This provides authoritative module names, commands, queries, models, and dependencies for validation.
 
 Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exist, stop with: "No business flow docs found under <APP_ROOT>/docs/."
 
@@ -40,15 +41,16 @@ If a doc directory is empty, the agent reports "no docs found" and skips.
 | A     | [references/business-flow-story-parity.md](references/business-flow-story-parity.md) | One per business flow      | Single BUSINESS_FLOW_DOC + its STORY_DOCS     |
 | B     | [references/actor-flow-parity.md](references/actor-flow-parity.md)                   | One per actor              | Single ACTOR_DOC + all BUSINESS_FLOW_DOCS     |
 | C     | [references/story-screen-parity.md](references/story-screen-parity.md)               | One per story              | Single STORY_DOC + all SCREEN_DOCS            |
-| D     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | One per story              | Single STORY_DOC + all RESOLVER_DOCS          |
-| E     | [references/orphan-detection.md](references/orphan-detection.md)                     | One global agent           | ALL doc paths                                 |
+| D     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | One per story              | Single STORY_DOC + all RESOLVER_DOCS + MODULE_METADATA |
+| E     | [references/orphan-detection.md](references/orphan-detection.md)                     | One global agent           | ALL doc paths + MODULE_METADATA               |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
 3. Replace doc path placeholders with the actual file paths for that item
-4. Dispatch the agent with the filled prompt
+4. Replace `{{MODULE_METADATA}}` with the JSON output (Group D and E agents only)
+5. Dispatch the agent with the filled prompt
 
 With F flows, A actors, and S stories, this produces F + A + S + S + 1 parallel agents.
 

package/skills/erp-kit-app-4-plan-review/references/orphan-detection.md

@@ -8,6 +8,7 @@ Story docs: {{STORY_DOCS}}
 Screen docs: {{SCREEN_DOCS}}
 Actor docs: {{ACTOR_DOCS}}
 Resolver docs: {{RESOLVER_DOCS}}
+Module metadata (JSON): {{MODULE_METADATA}}
 
 ## Instructions
 
@@ -38,6 +39,7 @@ For each doc, record all outgoing link targets (resolved to actual file paths).
 | orphan_screens   | Are there screens not referenced by any story?       |
 | orphan_actors    | Are there actors not participating in any flow?      |
 | orphan_resolvers | Are there resolvers not referenced by any story?     |
+| invalid_module_ref | Do resolvers reference modules or commands/queries that don't exist in installed modules? |
 
 ### How to Check
 
@@ -45,6 +47,7 @@ For each doc, record all outgoing link targets (resolved to actual file paths).
 2. **Orphan screens**: For each file in SCREEN_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
 3. **Orphan actors**: For each file in ACTOR_DOCS, check if any business flow README links to it AND the actor doc links to at least one flow. If neither condition is met, it is an orphan.
 4. **Orphan resolvers**: For each file in RESOLVER_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
+5. **Invalid module references**: Parse MODULE_METADATA JSON. For each resolver doc, extract the module and command/query it calls. Verify the module name exists in MODULE_METADATA and the command/query name appears in that module's `docs.command` or `docs.query` array. Report any mismatches.
 
 ## Common Gap Patterns
 

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

@@ -5,6 +5,7 @@
 App: {{APP_NAME}}
 Story docs: {{STORY_DOCS}}
 Resolver docs: {{RESOLVER_DOCS}}
+Module metadata (JSON): {{MODULE_METADATA}}
 
 ## Instructions
 
@@ -20,10 +21,19 @@ From each story doc, extract:
 - Story name (from filename or heading)
 - Resolver section content:
   - `None` → read-only story, skip resolver checks
+  - `N/A` (with optional reason, e.g., `N/A — background job`) → story intentionally has no resolver (skip checks). Common for scheduled jobs, cron tasks, webhook handlers, and system-triggered processes that don't expose a GraphQL endpoint.
   - `- 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: Module Metadata
+
+Parse the MODULE_METADATA JSON array. Build a lookup map:
+- Key: module name (e.g., `"business-partner"`)
+- Value: `{ commands: string[], queries: string[] }` from `docs.command` and `docs.query` arrays
+
+This is the authoritative source for which modules, commands, and queries exist.
+
 ## Extraction: Resolver Docs
 
 From each resolver doc, extract:
@@ -44,14 +54,20 @@ For each story:
 | 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? |
+| module_command_existence | Does the module and command/query referenced in each resolver exist in installed modules? |
 
 ### 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)
+3. If `N/A` (with or without reason) → skip (intentionally no resolver, e.g., background job)
+4. If `- TBD` → fail: resolver docs not yet created
+5. If links present → verify each link resolves to a file in RESOLVER_DOCS
+6. Cross-check story operations against resolver types (mutation for writes, query for reads)
+7. For each resolver that references a module and command/query, verify against MODULE_METADATA:
+   - The module name must exist as an entry in the metadata array
+   - The command name must appear in that module's `docs.command` array, or the query name in `docs.query`
+   - If either is missing, report as `module_command_existence` gap
 
 ## Link Format Reference
 
@@ -65,6 +81,8 @@ For each story:
 - **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)
+- **Non-existent module**: Resolver references a module that isn't installed (not in MODULE_METADATA)
+- **Non-existent command/query**: Resolver references a command or query that doesn't exist in the referenced module
 
 ## Output Format
 

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

@@ -1,11 +1,11 @@
 ---
 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.
+description: Implement backend code for 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
+# Application 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).
+Implement backend resolvers and application configuration for an application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolvers).
 
 ## When to Use
 
@@ -46,6 +46,15 @@ Classify resolvers per [erp-kit-app-shared/references/resolver-classification.md
 
 > **Parallelize if possible:** Dispatch one agent per resolver spec to extract inputs, outputs, module mapping, and error scenarios. Each agent reads a single resolver doc and returns structured analysis.
 
+### Phase 1b: Scaffolded Code Orientation
+
+`erp-kit app generate code` produces two kinds of files:
+
+- **Reference examples** — `src/resolvers/createUser.ts`, `src/modules.ts`, `src/executors/permissionCreated.ts` show the implementation pattern (command invocation, error handling, context creation). Use these as a guide.
+- **Generated stubs** — Minimal resolver files created from `docs/resolver/*.md`. These are your starting points for actual implementation.
+
+When implementing in Phase 4, follow the patterns from the reference examples. Once all actual resolvers are implemented, delete the reference files that aren't needed by your app.
+
 ### Phase 2: Wire Modules (`src/modules.ts`)
 
 Create the module wiring file that composes all required erp-kit modules.

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

@@ -1,17 +1,17 @@
 ---
 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.
+description: Implement frontend code for 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 application.
 ---
 
-# App-Compose Frontend Implementation
+# Application Frontend Implementation
 
-Implement frontend pages for an app-compose application, driven by screen spec documentation and a deployed backend.
+Implement frontend pages for an 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
+- Building the frontend UI for an application after backend deployment
 
 ## Prerequisites
 
@@ -45,6 +45,10 @@ Run `pnpm generate` in the frontend directory to fetch the GraphQL schema from t
 
 > **Sync barrier:** Schema generation must complete before page implementation. Generated types are shared across all pages.
 
+### Phase 2b: Scaffolded Code Orientation
+
+The scaffolded frontend includes example pages under `src/pages/user-management/` as a reference implementation. Use these to understand the page patterns (ListView, Form, DetailView), component structure, and GraphQL fragment conventions before implementing your actual pages.
+
 ### Phase 3: Implement Frontend Pages
 
 > **Barrier step:** Write shared layout and router files before dispatching page agents. These files are shared across all pages and must not be modified by individual page agents.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Review implementation parity between documentation and code for applications. Use after frontend implementation (step 6) to validate code matches documentation.
 ---
 
 # Implementation Parity Review

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

@@ -21,3 +21,6 @@ Prefer built-in queries over custom resolvers for list/get operations where poss
 | Assign X to Y        | Mutation      | `assign<X>To<Y>`       |
 | Submit/Approve       | Mutation      | `submit<Entity>` etc.  |
 | View/List/Get        | Query         | Built-in (no resolver) |
+| Scheduled/Cron job   | N/A           | No resolver — background worker/job |
+| Webhook handler      | N/A           | No resolver — external trigger |
+| System event         | N/A           | No resolver — internal event processing |

package/skills/erp-kit-module-2-requirements-review/SKILL.md

@@ -79,41 +79,14 @@ Render the aggregated results as markdown:
 
 ---
 
-### 1. Best Practices
-
-| Feature | Check | Status | Detail |
-| ------- | ----- | ------ | ------ |
-
-(Populated from agent 1 issues)
-
----
-
-### 2. Module Boundary Consistency
-
-| Feature | Overlapping Module | Overlap Area | Recommendation |
-| ------- | ------------------ | ------------ | -------------- |
-
-(Populated from agent 2 issues where check is `boundary_overlap`)
-
----
-
-### 3. Dependency Analysis
-
-| Feature | Depends On Module | Dependency Type | Status |
-| ------- | ----------------- | --------------- | ------ |
-
-(Populated from agent 2 issues where check is `dependency_analysis`)
-
----
-
-### 4. Summary
+### 1. Summary
 
 | Aspect               | Status | Details           |
 | -------------------- | ------ | ----------------- |
 | Best Practices       |        | X/Y checks passed |
 | Boundary Consistency |        | X/Y checks passed |
 
-### 5. Recommendations
+### 2. Recommendations
 
 Numbered list of actionable fixes, grouped by severity:
 
@@ -121,7 +94,7 @@ Numbered list of actionable fixes, grouped by severity:
 2. `major` — best practice violations, missing capabilities (should fix)
 3. `nit` — cosmetic, stylistic, minor improvements (informational only)
 
-### 6. Verdict
+### 3. Verdict
 
 **Verdict: APPROVED / NEEDS CHANGES**
 

package/skills/erp-kit-module-3-update-plan/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: erp-kit-module-3-update-plan
+description: Update model/command/query documentation based on plan review (step 4) feedback. Use after erp-kit-module-4-plan-review returns NEEDS CHANGES to apply targeted fixes without re-creating existing docs.
+---
+
+# Fix Plan Documentation from Review Feedback
+
+Apply targeted fixes to model, command, and query documentation based on plan review feedback. Unlike erp-kit-module-3-plan which creates docs from scratch, this skill reads the review report and applies only the necessary changes.
+
+## When to Use
+
+- After erp-kit-module-4-plan-review returns **NEEDS CHANGES**
+- User wants to fix specific gaps or inconsistencies flagged by the review
+- User says "fix the review findings" or "apply the review feedback"
+
+## Step 1: Setup
+
+Define shared context:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/features/*.md`
+- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/models/*.md`
+- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/commands/*.md`
+- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/queries/*.md`
+
+Verify that at least some model/command/query docs exist. If none exist, stop with: "No existing docs found. Use erp-kit-module-3-plan to create docs first."
+
+## Step 2: Extract & Triage Review Findings
+
+Look at the conversation history for the most recent plan review report (from erp-kit-module-4-plan-review). Extract all `critical` and `major` findings.
+
+If no review report is found in conversation history, ask the user: "No review report found in this conversation. Please either run /erp-kit-module-4-plan-review first, or paste the review findings."
+
+### Severity Re-evaluation
+
+The review may over-classify findings. Before accepting each finding, re-evaluate it by reading the relevant feature docs:
+
+- **"Is this a real gap or a design choice?"** — If the feature intentionally omits a command/query/model (e.g., handled by another module, deferred to a later phase, or covered by a generic mechanism), **reject** the finding
+- **"Does the feature doc explicitly require this?"** — Only accept findings for capabilities the feature doc actually specifies. Reject findings that invent requirements the feature does not mention
+- **"Does this block implementation?"** → accept as `critical`
+- **"Will this cause rework during implementation?"** → accept as `major`
+- Neither → downgrade to `nit` (informational only, do not fix)
+
+### Categorize accepted findings into:
+
+1. **Missing docs** — new model/command/query docs that need to be created
+2. **Incomplete docs** — existing docs with missing fields, business rules, or error scenarios
+3. **Inconsistencies** — mismatches between feature docs and model/command/query docs
+
+## Step 3: Plan the Delta
+
+Produce a targeted fix plan listing **only** the changes needed. Format:
+
+### Fix Plan
+
+**Findings rejected** (design choices or not required by feature docs):
+- (list rejected findings with reason — these will NOT be fixed)
+
+**Findings downgraded to nit** (informational, no action):
+- (list downgraded findings with reason)
+
+**Docs to create:**
+- (list new docs with purpose — scaffold these)
+
+**Docs to update:**
+- (list existing docs with specific changes needed — edit in place)
+
+**Docs unchanged:**
+- (explicitly note docs that are fine — do NOT touch these)
+
+## Step 4: Apply Fixes
+
+For each item in the fix plan:
+
+### Missing docs → Scaffold & Populate
+
+Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
+
+```bash
+erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+```
+
+Populate the new docs using the extraction rules from:
+
+- [Model extraction](references/model-extraction.md)
+- [Command extraction](references/command-extraction.md)
+- [Query extraction](references/query-extraction.md)
+
+### Incomplete docs → Edit in place
+
+Read the existing doc, then edit it directly to add the missing content. Do NOT re-scaffold or overwrite.
+
+### Inconsistencies → Align with feature spec
+
+Read both the feature doc and the model/command/query doc, then edit the model/command/query doc to align with the feature spec.
+
+**Important**: Do NOT touch docs listed as "unchanged."
+
+## Step 5: Dispatch Refinement Agents (parallelize)
+
+Launch up to 3 Agent tool calls in parallel — one per doc type that had changes — to review and refine the modified docs. Skip agents for doc types with no changes.
+
+Each agent receives: MODULE_NAME, the list of **changed** doc file paths only, and FEATURE_DOCS for cross-reference.
+
+| Agent | Prompt Template                                                                          | Inputs                                             |
+| ----- | ---------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| 1     | [model-extraction.md](references/model-extraction.md)           | MODULE_NAME, changed model doc paths, FEATURE_DOCS |
+| 2     | [command-extraction.md](references/command-extraction.md)       | MODULE_NAME, changed command doc paths, FEATURE_DOCS |
+| 3     | [query-extraction.md](references/query-extraction.md)           | MODULE_NAME, changed query doc paths, FEATURE_DOCS |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{FEATURE_DOCS}}` with the actual file paths
+4. Add to the prompt: "Read the docs at [doc paths]. These were just modified to fix review findings. Cross-reference against the feature docs and the extraction rules. Fix any remaining issues. Edit files directly."
+5. Dispatch the agent with the filled prompt
+
+## Step 6: Validate
+
+Run `pnpm run module:doc:check` and fix any violations.
+
+## References
+
+- [Naming convention](references/naming.md)
+- [Module structure](../erp-kit-module-shared/references/structure.md)
+- [Model extraction rules](references/model-extraction.md)
+- [Command extraction rules](references/command-extraction.md)
+- [Query extraction rules](references/query-extraction.md)

package/skills/erp-kit-module-3-update-plan/references/command-extraction.md

@@ -0,0 +1,87 @@
+# Command Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract command (write operation) definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify operations that change state
+3. For each operation, extract:
+   - Command name (following naming convention)
+   - Input parameters
+   - Business rules and validations
+   - Error scenarios
+   - Process flow (step-by-step)
+
+## Naming Convention
+
+See [naming.md](naming.md) for the full canonical verb vocabulary.
+
+Key mappings:
+
+| Feature Operation    | Command Name   |
+| -------------------- | -------------- |
+| "Create X" / "Add X" | `createX`      |
+| "Update X"           | `updateX`      |
+| "Delete X"           | `deleteX`      |
+| "Deactivate X"       | `deactivateX`  |
+| "Activate X"         | `activateX`    |
+| "Reactivate X"       | `reactivateX`  |
+| "Set default X"      | `setDefaultX`  |
+| "Assign X to Y"      | `assignXToY`   |
+| "Remove X from Y"    | `removeXFromY` |
+| "Revoke X from Y"    | `revokeXFromY` |
+| "Move X"             | `moveX`        |
+| "Log X"              | `logX`         |
+
+**Banned verbs**: `archive`, `unarchive`, `disable`, `enable`, `add...To...`, `unlink`
+
+## Extraction Rules
+
+### Business Rules
+
+- Extract explicit validation rules from feature scenarios
+- Extract implicit rules from test cases ("should not allow X when Y")
+- Map each rule to an error scenario
+
+### Error Scenarios
+
+- For each business rule violation, define an error code
+- Follow SCREAMING_SNAKE_CASE convention
+- Categories: NOT_FOUND, DUPLICATE, LOCKED/INACTIVE, INVALID_STATE, NO_OP
+
+### Process Flow
+
+- Extract step-by-step flow from feature scenarios
+- Identify branching points (conditional logic)
+- Map to validate → query → mutate pattern
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Commands
+
+For each command:
+
+#### <commandName>
+
+- **Source features:** list of feature files
+- **Target model:** ModelName
+- **Inputs:**
+
+| Param | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Business Rules:**
+
+| Rule | Error Code | Error Message |
+| ---- | ---------- | ------------- |
+
+- **Process Flow:** numbered steps
+- **Permissions:** list

package/skills/erp-kit-module-3-update-plan/references/model-extraction.md

@@ -0,0 +1,72 @@
+# Model Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract entity/model definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify entities that need database models
+3. For each entity, extract:
+   - Fields and their types
+   - Relationships to other entities
+   - State machines (if stateful)
+   - Required constraints (unique, required, etc.)
+4. Resolve cross-feature entity references (same entity mentioned in multiple features)
+
+## Extraction Rules
+
+### Entity Identification
+
+- Look for nouns that represent persistent data
+- Check for explicit "Entity" or "Model" mentions
+- Identify implicit entities from relationship descriptions
+
+### Field Extraction
+
+- Map feature attributes to database field types
+- Identify required vs optional fields
+- Note any validation constraints
+
+### State Machine Extraction
+
+- Look for state diagrams or transition descriptions
+- Extract all possible states
+- Map transitions to operations (verbs → commands)
+
+### Relationship Extraction
+
+- Identify foreign key relationships (N-1, 1-1)
+- Identify junction table needs (N-N)
+- Note cross-module entity references
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Models
+
+For each model:
+
+#### <ModelName>
+
+- **Source features:** list of feature files
+- **Fields:**
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Relationships:**
+
+| Type | Target | Field | Cross-module |
+| ---- | ------ | ----- | ------------ |
+
+- **States:** list of states (if stateful)
+- **State Transitions:**
+
+| From | To  | Trigger (command) |
+| ---- | --- | ----------------- |