@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/skills/erp-kit-app-6-impl-frontend/references/detail-view.md

@@ -0,0 +1,255 @@
+# DetailView Pattern
+
+## File Structure
+
+```bash
+[id]/
+  page.tsx                          # route entry — fetches data, composes fragments
+  components/
+    <entity>-detail.tsx             # DescriptionCard with field definitions
+    <entity>-actions.tsx            # ActionPanel with mutation actions
+```
+
+## page.tsx
+
+```tsx
+import {
+  Layout,
+  useParams,
+  type AppShellPageProps,
+} from "@tailor-platform/app-shell";
+import { useQuery } from "urql";
+import { UserDetail, UserDetailFragment } from "./components/user-detail";
+import { UserActions, UserActionsFragment } from "./components/user-actions";
+import { graphql } from "@/graphql";
+import { ErrorFallback } from "@/components/composed/error-fallback";
+import { Loading } from "@/components/composed/loading";
+
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserDetail
+        ...UserActions
+      }
+    }
+  `,
+  [UserDetailFragment, UserActionsFragment],
+);
+
+const UserPage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: UserQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.user)
+    return (
+      <ErrorFallback
+        title="Failed to load user"
+        message="An error occurred while fetching the user details."
+        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
+      />
+    );
+
+  return (
+    <Layout>
+      <Layout.Header title="User Detail" />
+      <Layout.Column>
+        <UserDetail user={data.user} />
+      </Layout.Column>
+      <Layout.Column>
+        <UserActions user={data.user} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+
+UserPage.appShellPageProps = {
+  meta: { title: "User Detail" },
+} satisfies AppShellPageProps;
+export default UserPage;
+```
+
+## `<entity>-detail.tsx` — DescriptionCard
+
+```tsx
+import { DescriptionCard } from "@tailor-platform/app-shell";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+
+export const UserDetailFragment = graphql(`
+  fragment UserDetail on User {
+    id
+    name
+    email
+    status
+    createdAt
+    updatedAt
+  }
+`);
+
+export const UserDetail = ({
+  user: userFragment,
+}: {
+  user: FragmentOf<typeof UserDetailFragment>;
+}) => {
+  const user = readFragment(UserDetailFragment, userFragment);
+  return (
+    <DescriptionCard
+      data={user}
+      title="User Information"
+      columns={3}
+      fields={[
+        { key: "name", label: "Name" },
+        { key: "email", label: "Email", meta: { copyable: true } },
+        {
+          key: "status",
+          label: "Status",
+          type: "badge",
+          meta: {
+            badgeVariantMap: {
+              ACTIVE: "success",
+              PENDING: "warning",
+              INACTIVE: "neutral",
+            },
+          },
+        },
+        { type: "divider" },
+        {
+          key: "createdAt",
+          label: "Created At",
+          type: "date",
+          meta: { dateFormat: "medium" },
+        },
+        {
+          key: "updatedAt",
+          label: "Updated At",
+          type: "date",
+          meta: { dateFormat: "relative" },
+        },
+      ]}
+    />
+  );
+};
+```
+
+### DescriptionCard Field Types
+
+| `type`      | Description                       | `meta` options                                                               |
+| ----------- | --------------------------------- | ---------------------------------------------------------------------------- |
+| (omitted)   | Plain text                        | `copyable: true`                                                             |
+| `"badge"`   | Status badge with variant mapping | `badgeVariantMap: { VALUE: "success" \| "warning" \| "neutral" \| "error" }` |
+| `"date"`    | Formatted date/time               | `dateFormat: "short" \| "medium" \| "long" \| "relative"`                    |
+| `"divider"` | Horizontal rule                   | —                                                                            |
+
+### Multiple DescriptionCards
+
+When an entity has a logically distinct secondary collection (e.g. taxonomy assignments, related items), render it as a second `DescriptionCard` stacked below the primary one.
+
+## `<entity>-actions.tsx` — ActionPanel
+
+```tsx
+import { ActionPanel, useNavigate } from "@tailor-platform/app-shell";
+import { useMutation } from "urql";
+import { Pencil, UserX, UserCheck } from "lucide-react";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+import { useToast } from "@/hooks/use-toast";
+
+const DeactivateUserMutation = graphql(`
+  mutation DeactivateUser($userId: String!) {
+    deactivateUser(userId: $userId) {
+      id
+      status
+    }
+  }
+`);
+
+export const UserActionsFragment = graphql(`
+  fragment UserActions on User {
+    id
+    status
+  }
+`);
+
+export const UserActions = ({
+  user: userFragment,
+}: {
+  user: FragmentOf<typeof UserActionsFragment>;
+}) => {
+  const user = readFragment(UserActionsFragment, userFragment);
+  const navigate = useNavigate();
+  const toast = useToast();
+  const [{ fetching: deactivating }, deactivateUser] = useMutation(
+    DeactivateUserMutation,
+  );
+
+  return (
+    <ActionPanel
+      title="Actions"
+      actions={[
+        {
+          key: "edit",
+          label: "Edit User",
+          icon: <Pencil />,
+          onClick: () => navigate("edit"),
+        },
+        ...(user.status === "ACTIVE"
+          ? [
+              {
+                key: "deactivate",
+                label: "Deactivate User",
+                icon: <UserX />,
+                loading: deactivating,
+                onClick: () =>
+                  deactivateUser({ userId: user.id }).then((result) => {
+                    if (result.error) {
+                      toast.error(result.error);
+                      return;
+                    }
+                    toast.success("User deactivated successfully");
+                  }),
+              },
+            ]
+          : []),
+      ]}
+    />
+  );
+};
+```
+
+### Error Handling in Actions
+
+Always handle mutation results with `useToast`:
+
+```tsx
+import { useToast } from "@/hooks/use-toast";
+
+const toast = useToast();
+
+// In onClick:
+onClick: () =>
+  someMutation({ ... }).then((result) => {
+    if (result.error) {
+      toast.error(result.error); // accepts CombinedError directly
+      return;
+    }
+    toast.success("Action completed successfully");
+  }),
+```
+
+- `toast.error(result.error)` accepts `CombinedError` from urql directly — no manual message extraction needed
+- `toast.success(message)` for successful operations
+- Import from `@/hooks/use-toast`, not from `@tailor-platform/app-shell` directly (ESLint enforced)
+
+### ActionItem Fields
+
+| Field      | Type                          | Description                            |
+| ---------- | ----------------------------- | -------------------------------------- |
+| `key`      | `string`                      | React key                              |
+| `label`    | `string`                      | Visible row label                      |
+| `icon`     | `ReactNode`                   | Icon from `lucide-react`               |
+| `onClick`  | `() => void \| Promise<void>` | Use `useNavigate()` for routing        |
+| `disabled` | `boolean?`                    | Disable the row                        |
+| `loading`  | `boolean?`                    | Show spinner, make row non-interactive |

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

@@ -27,11 +27,7 @@ Key points:
 
 ### DetailView
 
-Key points:
-
-- Two-column `Layout`: detail on left, actions on right
-- `useParams()` to get entity ID from route
-- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields. Refer to existing examples in the codebase for props and field type usage.
+See **[detail-view.md](detail-view.md)** for the full pattern including `DescriptionCard` field types and `ActionPanel` usage.
 
 ### Form Pattern
 

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-7-impl-review
 description: Review implementation parity between documentation and code for applications. Use after frontend implementation (step 6) to validate code matches documentation.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Implementation Parity Review
 
 Review **implementation consistency** between Tier 3-4 documentation and actual backend/frontend code.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## Progress Logging
 
 Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
@@ -36,6 +42,7 @@ Define shared context for all agents:
 - `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/resolvers/*.ts`
 - `BACKEND_EXECUTORS`: glob `<APP_ROOT>/backend/executors/*.ts`
 - `BACKEND_MODULES`: `<APP_ROOT>/backend/src/modules.ts`
+- `BACKEND_MODULES_DB`: `<APP_ROOT>/backend/src/modules-db.ts`
 - `BACKEND_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
 - `FRONTEND_PAGES`: glob `<APP_ROOT>/frontend/src/app/(main)/**/*.tsx`
 
@@ -53,7 +60,7 @@ All review agents are read-only — no shared-file conflict risk.
 | ----- | -------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
 | A     | [references/resolver-doc-code-parity.md](references/resolver-doc-code-parity.md) | One per resolver   | Single RESOLVER_DOC + matching BACKEND_RESOLVER + BACKEND_EXECUTOR |
 | B     | [references/screen-doc-code-parity.md](references/screen-doc-code-parity.md)     | One per screen     | Single SCREEN_DOC + matching FRONTEND_PAGE directory         |
-| C     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | One per resolver   | Single RESOLVER_DOC + BACKEND_MODULES + BACKEND_CONFIG       |
+| C     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | One per resolver   | Single RESOLVER_DOC + BACKEND_MODULES + BACKEND_MODULES_DB + BACKEND_CONFIG |
 | D     | Build verification (inline)                                                      | One global agent   | All source paths                                             |
 
 With R resolvers and S screens, this produces R + S + R + 1 parallel agents.
@@ -119,7 +126,7 @@ Render the aggregated results as markdown:
 
 ### 3. Module Wiring Consistency
 
-| Resolver | Required Module | Wired in modules.ts | Config Reference | Gap |
+| Resolver | Required Module | Wired in modules.ts / modules-db.ts | Config Reference | Gap |
 | -------- | --------------- | ------------------- | ---------------- | --- |
 
 (Populated from agent 3 gaps)

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

@@ -5,12 +5,13 @@
 App: {{APP_NAME}}
 Resolver docs: {{RESOLVER_DOCS}}
 Backend modules file: {{BACKEND_MODULES}}
+Backend modules-db file: {{BACKEND_MODULES_DB}}
 Backend config file: {{BACKEND_CONFIG}}
 
 ## Instructions
 
 1. Read ALL resolver docs at the paths above
-2. Read the modules file (`src/modules.ts`)
+2. Read the modules file (`src/modules.ts`) and the modules-db file (`src/modules-db.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
@@ -22,13 +23,18 @@ From each resolver doc, extract:
 - Module it depends on (which `defineXxxModule` it needs)
 - Commands it calls (which module command functions)
 
-## Extraction: modules.ts
+## Extraction: modules.ts and modules-db.ts
 
-From the modules file, extract:
+From `modules.ts`, extract:
 
 - All `defineXxxModule()` calls
 - Inter-module dependency wiring (e.g., primitives passed to item-management)
-- Exported `db`, `commands`, and `executors`
+- Exported module objects (`umModules`, `imModules`, etc.)
+
+From `modules-db.ts`, extract:
+
+- Individual DB table exports (destructured from module objects)
+- This file must NOT be imported by resolvers
 
 ## Extraction: tailor.config.ts
 
@@ -43,7 +49,7 @@ From the config file, extract:
 
 | Check ID             | Question                                                         |
 | -------------------- | ---------------------------------------------------------------- |
-| module_wired         | Is every module referenced by resolvers wired in modules.ts?     |
+| module_wired         | Is every module referenced by resolvers wired in modules.ts and exported in modules-db.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? |
@@ -54,14 +60,14 @@ From the config file, extract:
 ### 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
+2. Check each required module appears as a `defineXxxModule()` call in modules.ts and its DB types are exported in modules-db.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
+4. Check tailor.config.ts db.files references modules-db.ts and resolver glob pattern covers all 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 module**: Resolver references a module not wired in modules.ts or not exported in modules-db.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

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

@@ -1,6 +1,8 @@
 ---
 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.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # erp-kit-app-shared

package/skills/erp-kit-mock-scenario/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-mock-scenario
 description: Scaffold a new Mockoon mock scenario with CRUD routes, error scenarios, and registry updates
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Mock Scenario Scaffolder
 
 Generate a complete Mockoon mock API config for a new provider scenario and wire it into the registry.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## Workflow
 
 ### Step 1: Identify target API

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-1-requirements
 description: Create ERP module requirements and feature documentation. Use when starting a new module, defining requirements, scoping features, or designing module architecture. Guides collaborative research, scoping, and iterative feature breakdown.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Module Requirements Workflow
 
 Autonomous workflow for creating ERP module requirements. Uses parallel agents for research, then automatically decides scope based on recommendations.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## Workflow
 
 ```

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-2-requirements-review
 description: Review requirements quality and module boundary consistency. Use after creating requirements (step 1) to validate best practices and cross-module boundaries.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Requirements Review
 
 Review **requirements quality** and **module boundary consistency** for a module.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - After writing module requirements and feature documentation (step 1)

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-3-plan
 description: Create implementation plan by breaking down feature specs into model, command, and query documentation. Use after requirements review (step 2) to plan the implementation structure.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Feature Breakdown to Model/Command/Query Docs
 
 Convert feature specifications into structured model, command, and query documentation. The main agent creates the plan and populates scaffolded docs, then parallel subagents refine each doc type.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - User has feature specs (e.g., `docs/features/*.md`) and wants implementation docs

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

@@ -1,12 +1,18 @@
 ---
 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.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # 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.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - After erp-kit-module-4-plan-review returns **NEEDS CHANGES**

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-4-plan-review
 description: Review parity between feature documentation and command/model/query documentation. Use after creating implementation plan (step 3) to validate completeness.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Feature Parity Review
 
 Review **documentation consistency** between feature specs and command/model/query docs.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - After writing feature documentation, check for gaps in command/model/query documentation

package/skills/erp-kit-module-5-impl/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-5-impl
 description: Implement features in modules using TDD. Use after plan review (step 4) to implement database models, commands, and queries with test-driven development.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # TDD Implementation for Module Development
 
 Implement features in modules using Test-Driven Development with per-item agent delegation.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - Implementing new domain commands in any module

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-module-6-impl-review
 description: Review implementation parity between documentation and code. Use after TDD implementation (step 5) to validate code matches documentation.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Implementation Parity Review
 
 Review **implementation consistency** between documentation and actual code.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## When to Use
 
 - After TDD implementation (step 4), verify it matches documentation
@@ -33,42 +39,39 @@ Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If n
 
 ## Step 2: Dispatch Agents (parallelize ALL agents in a single message)
 
-Split each parity check into its own agent, then further split by file batches when there are many files. Target **~5 agents per domain** (model, command, query) for maximum parallelism. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
+Split checks into agents by **domain + file batch**, not by check type. Command checks (C-1, C-2, C-3) run together in one agent per batch; query checks (Q-1, Q-2, Q-3) run together in one agent per batch. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
 
-If a doc or code directory is empty, skip that agent entirely.
+If a doc or code directory is empty, skip that domain entirely.
 
 ### Splitting Strategy
 
-1. **Each parity check type = separate agent** (never combine different check types in one agent)
-2. **File batching**: If a check has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent running the same check type on a subset of files.
+1. **Domain grouping**: C-1 + C-2 + C-3 in the same agent. Q-1 + Q-2 + Q-3 in the same agent. M-1 is its own agent.
+2. **File batching**: If a domain has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent.
 3. **Corresponding code/test files**: When batching by doc files, include only the matching code and test files for those specific docs (match by filename stem, e.g., `docs/commands/createFoo.md` → `command/createFoo.ts` + `command/createFoo.test.ts`).
 
 ### Agent Table
 
-| Check Type | Domain  | Prompt Template                                                                                            | Inputs per agent                                                     |
-| ---------- | ------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| M-1        | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                 | MODEL_DOCS (batch), MODEL_CODE (matching)                            |
-| C-1        | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)                              | COMMAND_DOCS (batch), COMMAND_CODE (matching)                        |
-| C-2        | Command | [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md)      | COMMAND_DOCS (batch), COMMAND_CODE (matching), ERROR_DEFS            |
-| C-3        | Command | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)                              | COMMAND_DOCS (batch), COMMAND_TEST_CODE (matching)                   |
-| Q-1        | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md)                                 | QUERY_DOCS (batch), QUERY_CODE (matching)                            |
-| Q-2        | Query   | [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md)          | QUERY_DOCS (batch), QUERY_CODE (matching), ERROR_DEFS               |
-| Q-3        | Query   | [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                                 | QUERY_DOCS (batch), QUERY_TEST_CODE (matching)                      |
+| Agent Type    | Domain  | Prompt Templates (all included in one agent)                                                                                                                                                                                                                                                     | Inputs per agent                                                                    |
+| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| M-1           | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                                       | MODEL_DOCS (batch), MODEL_CODE (matching)                                           |
+| C-1 + C-2 + C-3 | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md) + [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md) + [references/command-doc-test-parity.md](references/command-doc-test-parity.md) | COMMAND_DOCS (batch), COMMAND_CODE (matching), COMMAND_TEST_CODE (matching), ERROR_DEFS |
+| Q-1 + Q-2 + Q-3 | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md) + [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md) + [references/query-doc-test-parity.md](references/query-doc-test-parity.md)    | QUERY_DOCS (batch), QUERY_CODE (matching), QUERY_TEST_CODE (matching), ERROR_DEFS   |
 
 ### Batching Example
 
-If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 3 agents (C-1, C-2, C-3) → 9 command agents total. If it has 4 command docs: no batching needed, 3 agents (C-1, C-2, C-3).
+If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 1 agent (C-1+C-2+C-3) → 3 command agents total. If it has 4 command docs: no batching needed, 1 agent.
 
 For model docs: if 6 models → 2 batches (3+3) → 2 agents (M-1 × 2). If 3 models → 1 agent.
 
 ### Agent Dispatch
 
-For each agent:
+For combined agents (command or query), concatenate all prompt templates in order, then fill placeholders. For each agent:
 
-1. Read the prompt template file for that check type
-2. Replace `{{MODULE_NAME}}` with the resolved module name
-3. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
-4. Dispatch the agent with the filled prompt
+1. Read all prompt template files for that agent type
+2. Concatenate them in order with a `---` separator between each
+3. Replace `{{MODULE_NAME}}` with the resolved module name
+4. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
+5. Dispatch the agent with the filled prompt; instruct it to return a **single JSON result** with combined `gaps[]` and `inconsistencies[]` covering all check types
 
 **IMPORTANT**: Launch ALL agents across ALL domains in a single parallel message. Do not serialize by domain.
 

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

@@ -1,6 +1,8 @@
 ---
 name: erp-kit-module-shared
 description: Shared references for erp-kit module skills. Not invoked directly — referenced by erp-kit-module-1 through erp-kit-module-6.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # erp-kit-module-shared