@tailor-platform/erp-kit 0.3.0 → 0.4.1

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

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-4-plan-review
-description: Review parity between Tier 2 (business flows, actors) and Tier 3-4 (stories, screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
+description: Review parity between Tier 2 (business flows, actors, stories) and Tier 3-4 (screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
 ---
 
 # Documentation Parity Review
 
-Review **documentation consistency** across Tier 2, 3, and 4 documentation.
+Review **documentation consistency** across Tier 2 (business flows, actors, stories), Tier 3 (screens), and Tier 4 (resolvers) documentation.
 
 ## When to Use
 
@@ -29,26 +29,29 @@ Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exis
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 5 Agent tool calls in parallel — one per parity check.
-Each agent receives: APP_NAME, relevant doc file paths.
+Dispatch agents in parallel — one per item in each group. All groups are dispatched simultaneously.
+
+Each agent receives: APP_NAME and the relevant doc file paths for its item.
 Each agent returns: structured JSON per [references/parity-report-format.md](references/parity-report-format.md).
 If a doc directory is empty, the agent reports "no docs found" and skips.
 
-| Agent | Prompt Template                                                                      | Inputs                         |
-| ----- | ------------------------------------------------------------------------------------ | ------------------------------ |
-| 1     | [references/business-flow-story-parity.md](references/business-flow-story-parity.md) | BUSINESS_FLOW_DOCS, STORY_DOCS |
-| 2     | [references/actor-flow-parity.md](references/actor-flow-parity.md)                   | ACTOR_DOCS, BUSINESS_FLOW_DOCS |
-| 3     | [references/story-screen-parity.md](references/story-screen-parity.md)               | STORY_DOCS, SCREEN_DOCS        |
-| 4     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | STORY_DOCS, RESOLVER_DOCS      |
-| 5     | [references/orphan-detection.md](references/orphan-detection.md)                     | ALL doc paths                  |
+| Group | Prompt Template                                                                      | Per-item scope             | Inputs per agent                              |
+| ----- | ------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------------- |
+| 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                                 |
 
 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
+3. Replace doc path placeholders with the actual file paths for that item
 4. Dispatch the agent with the filled prompt
 
+With F flows, A actors, and S stories, this produces F + A + S + S + 1 parallel agents.
+
 ## Step 3: Aggregate Results
 
 After ALL agents return:
@@ -56,7 +59,7 @@ 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
+4. Deduplicate: if two agents report the same gap (same `source + target + check`), keep only one
 5. Calculate totals across all summaries
 6. Render the final report below
 

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

@@ -27,9 +27,13 @@ All four tiers of documentation must exist:
 ## Workflow
 
 ```
-ANALYZE DOCS → MODULE WIRING → CONFIG → RESOLVERS → GENERATED FILES → VERIFY → DEPLOY
+ANALYZE DOCS → MODULE WIRING → CONFIG → RESOLVERS → GENERATED FILES → DEPLOY
 ```
 
+### Incremental Verification
+
+Run `pnpm lint` and `pnpm typecheck` after each of Phase 2, 3, and 4. Fix errors before moving on.
+
 ### Phase 1: Analyze Documentation
 
 Read all resolver and screen specs to build a complete picture:
@@ -40,6 +44,8 @@ Read all resolver and screen specs to build a complete picture:
 
 Classify resolvers per [erp-kit-app-shared/references/resolver-classification.md](../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 2: Wire Modules (`src/modules.ts`)
 
 Create the module wiring file that composes all required erp-kit modules.
@@ -63,28 +69,30 @@ Key points:
 - Auth with OAuth2, DPoP, and user profile mapping
 - Generators for Kysely types and seed data
 
+> **Sync barrier:** Module wiring and configuration must complete before resolver implementation. These files are shared across all resolvers.
+
 ### Phase 4: Implement Backend Resolvers and Executors
 
-Write one file per resolver under `src/modules/<module-name>/resolvers/`, one per executor under `executors/`.
+Write one file per resolver under `src/resolvers/`, one per executor under `executors/`.
 
 **Read [resolver & executor patterns reference](references/resolver-patterns.md).**
 
+For each resolver, check whether its spec (`docs/resolver/*.md`) documents error codes. If it does, implement a `switch(result.error.code)` block — do not use generic `throw result.error`.
+
 Do not directly mutate module-owned tables via Kysely — always use module commands.
 
+> **Parallelize if possible:** Dispatch one agent per resolver. Each agent writes only to its own files:
+> - `src/resolvers/<resolverName>.ts`
+> - `src/executors/<resolverName>.ts`
+>
+> **Shared-file guard:** `src/modules.ts` and `tailor.config.ts` are written in the sync barrier phase above. Resolver agents must NOT modify these files.
+
 ### 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
+### Phase 6: Deploy Backend & Next Steps
 
 Frontend implementation requires a deployed backend (for GraphQL schema generation). Prompt the user to:
 

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

@@ -1,26 +1,6 @@
 # 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],
-});
-```
+`tailor.config.ts` defines the Tailor application configuration. Refer to existing examples in the codebase for the full config structure.
 
 Key points:
 
@@ -30,7 +10,6 @@ Key points:
 
 ## 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`)

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

@@ -3,7 +3,6 @@
 `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,

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

@@ -42,18 +42,27 @@ body: async (context) => {
 
 ### Error handling
 
-When the resolver spec documents specific error codes, use `result.error.code` to switch:
+Resolver specs document error codes the command can return. When codes are documented, add a `case` for every documented code — generic `throw result.error` loses context for the frontend. The error code is a discriminated union, so TypeScript enforces exhaustive handling without a `default` branch.
+
+**Do this:**
 
 ```ts
 if (!result.ok) {
   switch (result.error.code) {
-    case "USER_NOT_FOUND":
-      throw new Error(`User ${context.input.userId} not found`);
-    // ...
+    case "INSUFFICIENT_STOCK":
+      throw new Error(`Stock insufficient for item ${context.input.itemId}`);
+    case "ORDER_ALREADY_CONFIRMED":
+      throw new Error("Cannot modify a confirmed order");
   }
 }
 ```
 
+**Not this:**
+
+```ts
+if (!result.ok) throw result.error;
+```
+
 Do not directly mutate module-owned tables via Kysely — always use module commands.
 
 ---

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

@@ -33,6 +33,8 @@ ANALYZE SCREENS → GENERATE GRAPHQL SCHEMA → IMPLEMENT PAGES → VERIFY
 
 Read all screen specs (`docs/screen/*.md`) to build a complete picture:
 
+> **Parallelize if possible:** Dispatch one agent per screen spec to extract page structure, fields, actions, and navigation. Each agent reads a single screen doc and returns structured analysis.
+
 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)
@@ -41,10 +43,21 @@ Read all screen specs (`docs/screen/*.md`) to build a complete picture:
 
 Run `pnpm generate` in the frontend directory to fetch the GraphQL schema from the deployed backend.
 
+> **Sync barrier:** Schema generation must complete before page implementation. Generated types are shared across all 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.
+
+Run `pnpm lint`, `pnpm typecheck`, and `pnpm gql-tada:check` regularly during implementation. Fix errors before moving on.
+
 Create pages driven by screen spec docs. Each screen type has a standard implementation pattern.
 
+> **Parallelize if possible:** Dispatch one agent per screen. Each agent writes only to its own directory:
+> - `src/pages/<screen-name>/`
+>
+> **Shared-file guard:** Layout files, router configuration, and generated types are written before dispatch. Page agents must NOT modify shared files.
+
 **Read [pages reference](references/pages.md) for the full pattern catalog.**
 
 Page types and their file structure:
@@ -70,5 +83,8 @@ Key frontend patterns:
 cd <app-root>/frontend
 pnpm lint
 pnpm typecheck
+pnpm gql-tada:check
 pnpm build
 ```
+
+After verification passes, proceed to implementation review with `/erp-kit-app-7-impl-review`.

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

@@ -31,27 +31,7 @@ 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:
-
-```tsx
-<DescriptionCard
-  data={resource}
-  title="Overview"
-  columns={3}
-  fields={[
-    { key: "name", label: "Name", meta: { copyable: true } },
-    {
-      key: "status",
-      label: "Status",
-      type: "badge",
-      meta: { badgeVariantMap: { ACTIVE: "success" } },
-    },
-    { key: "createdAt", label: "Created At", type: "date", meta: { dateFormat: "medium" } },
-  ]}
-/>
-```
-
-Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields. Refer to existing examples in the codebase for props and field type usage.
 
 ### Form Pattern
 
@@ -59,8 +39,11 @@ Create and edit forms share the same structure:
 
 - **React Hook Form + Zod** for validation with `zodResolver`
 - **urql `useMutation`** for GraphQL mutations
-- **Cache invalidation**: pass `additionalTypenames` to the mutation context so urql invalidates related queries (e.g., `createUser(values, { additionalTypenames: ["User"] })`)
-- **Toast notifications**: use `useToast` from `@tailor-platform/app-shell` (sonner-based, `Toaster` is built into AppShell) for success/error feedback
+- **Cache invalidation**: pass `additionalTypenames` to the mutation context so urql invalidates related queries after create/edit/delete. Without this, list pages will show stale data.
+  ```ts
+  createUser(values, { additionalTypenames: ["User"] })
+  ```
+- **Toast notifications**: `useToast` from `@/hooks/use-toast`. `toast.error()` accepts `CombinedError` directly (e.g., `toast.error(result.error)`)
 - **Navigate `".."`** to go back to list after success
 - Edit form pre-fills `defaultValues` from existing entity via fragment
 
@@ -81,6 +64,14 @@ Create and edit forms share the same structure:
 - **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
 - **Required: No** → `.optional()`
 
+#### Empty String Handling for Optional Fields
+
+React Hook Form defaults text inputs to `""`. For optional fields (e.g., `parentId`), convert empty strings to `undefined` before submitting to avoid backend errors. Use `||` not `??` — empty string is not nullish:
+
+```ts
+parentId: values.parentId || undefined,
+```
+
 ### Shared Component Patterns
 
 #### Fragment Collocation
@@ -117,13 +108,9 @@ const UserQuery = graphql(
 
 #### App.tsx
 
-- `AuthGuard`: implement yourself, pass via `guardComponent` prop. AuthProvider shows it automatically when `!isReady || !isAuthenticated`, so the guard only needs to render a sign-in UI — no state checks needed inside it
-- `GraphQLProvider`: pass `authClient.fetch` directly to urql's `fetch` option and `authClient.getAppUri()` for the URL
-- `useAuth()` returns `{ isAuthenticated, isReady, login, logout }` directly (not nested in `authState`)
-- Built-in `me` query returns the current user's `User` record — use it instead of writing a custom resolver for profile info
+Refer to existing examples in the codebase for `AuthGuard`, `GraphQLProvider`, auth client setup, and sidebar configuration.
+
 - Required env vars: `VITE_TAILOR_APP_URL`, `VITE_TAILOR_CLIENT_ID`
-- Auth client: create once in `src/lib/auth-client.ts` using `createAuthClient({ appUri, clientId })`
-- Sidebar: use `SidebarGroup` + `SidebarItem` for custom ordering
 
 #### Module-level page.tsx (required)
 
@@ -141,20 +128,3 @@ Every page component must:
 
 1. Be the **default export** of `page.tsx`
 2. Set `appShellPageProps` with at least `meta.title`
-
-#### Common imports
-
-```tsx
-import {
-  Layout,
-  Link,
-  useParams,
-  useNavigate,
-  type AppShellPageProps,
-} from "@tailor-platform/app-shell";
-import { useQuery, useMutation } from "urql";
-import { graphql, type FragmentOf, readFragment } from "@/graphql";
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-```

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

@@ -21,7 +21,7 @@ Define shared context for all agents:
 - `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_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_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
@@ -31,35 +31,39 @@ Verify at least `RESOLVER_DOCS` or `SCREEN_DOCS` is non-empty. If no docs exist,
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 4 Agent tool calls in parallel — one per parity check.
+Dispatch agents in parallel — one per item in each group. All groups are dispatched simultaneously.
 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.
+All review agents are read-only — no shared-file conflict risk.
 
-| 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                                            |
+| Group | Prompt Template                                                                  | Per-item scope     | Inputs per agent                                             |
+| ----- | -------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
+| 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       |
+| D     | Build verification (inline)                                                      | One global agent   | All source paths                                             |
 
-For agents 1-3:
+With R resolvers and S screens, this produces R + S + R + 1 parallel agents.
+
+For groups A-C:
 
 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
+3. Replace doc/code path placeholders with the actual file paths for that single item
+4. Dispatch one agent per item with the filled prompt
 
-For agent 4 (build verification):
+For group D (build & sync verification):
 
-Run build checks inline:
+Run build checks and source-doc sync check inline:
 
 ```bash
 cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
 cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
+erp-kit app sync-check -p <APP_ROOT>/..
 ```
 
-Report pass/fail for each check.
+Report pass/fail for each check. `sync-check` detects missing resolver implementations and orphaned docs, so groups A-C agents can skip file-existence checks and focus on content parity.
 
 ## Step 3: Aggregate Results
 
@@ -69,8 +73,9 @@ After ALL agents return:
 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
+5. Deduplicate findings: if agents from groups A and C report the same resolver issue, keep only one
+6. Calculate totals across all summaries
+7. Render the final report below
 
 ## Report Format
 
@@ -109,13 +114,14 @@ Render the aggregated results as markdown:
 
 ---
 
-### 4. Build Verification
+### 4. Build & Sync Verification
 
-| Check | Backend | Frontend |
-| ----- | ------- | -------- |
-| Lint  |         |          |
-| Types |         |          |
-| Build | N/A     |          |
+| Check      | Backend | Frontend |
+| ---------- | ------- | -------- |
+| Lint       |         |          |
+| Types      |         |          |
+| Build      | N/A     |          |
+| Sync-check |         | N/A      |
 
 (Populated from agent 4 results)
 
@@ -158,7 +164,7 @@ Render the aggregated results as markdown:
 | 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       |
+| Build & Sync Verification    |        | pass / fail       |
 
 ### 8. Recommendations
 

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

@@ -28,7 +28,7 @@ From each resolver doc, extract:
 
 ## Extraction: Backend Code
 
-From each resolver file (`src/modules/*/resolvers/*.ts`), extract:
+From each resolver file (`src/resolvers/*.ts`), extract:
 
 - Resolver name (from `createResolver()` call or filename)
 - Module command called (import path and function name)
@@ -42,28 +42,27 @@ From each executor file (`executors/*.ts`), extract:
 
 ## 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?  |
+| Check ID           | Question                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| 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?  |
+
+File existence checks (`resolver_impl_exists`) are handled by `erp-kit app sync-check` in the build verification step. This agent focuses on content parity only.
 
 ### 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
+1. For each resolver doc that has a corresponding code file, verify the code imports and calls the documented module command
+2. Check that `context.input.*` accesses match documented inputs
+3. Check that error `switch` cases cover all documented error codes
+4. Verify return value structure matches documentation
+5. 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

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

@@ -5,7 +5,7 @@ description: Create ERP module requirements and feature documentation. Use when
 
 # Module Requirements Workflow
 
-Collaborative workflow for creating ERP module requirements. Uses parallel agents for research, then human validates and decides scope.
+Autonomous workflow for creating ERP module requirements. Uses parallel agents for research, then automatically decides scope based on recommendations.
 
 ## Workflow
 
@@ -22,7 +22,7 @@ Define shared context for all agents:
 - `DOMAIN`: the business domain (e.g., "inventory management", "purchasing")
 - `OTHER_MODULES`: glob `<MODULES_ROOT>/*/README.md` (to understand existing module landscape)
 
-Ask the user for the MODULE_NAME and DOMAIN if not provided.
+Infer MODULE_NAME and DOMAIN from the current working directory or argument context. If insufficient, use the module's README or directory name.
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
@@ -63,9 +63,7 @@ For each feature:
 - **Recommendation:** `Include` or `Skip`
 - **Why:** reasoning for the recommendation
 
-Then ask the user: "推薦を変更したい機能はありますか？"
-
-The final feature set becomes the union of all `Include` features. Iterate until the user approves.
+The final feature set becomes the union of all `Include` features. Proceed with the recommended scope.
 
 ## Step 4: Create — Agent per feature
 
@@ -96,19 +94,15 @@ pnpm run module:doc:check
 
 ## Step 5: Review
 
-User reviews generated feature docs and may request changes.
-
-**Split detection**: If a feature covers multiple distinct workflows, split into separate feature files.
+**Split detection**: If a feature covers multiple distinct workflows, split into separate feature files automatically.
 
-**Iteration pattern:**
+**Auto-split pattern:**
 
-1. User identifies issue (e.g., "X is too broad, split it")
+1. Detect features that cover multiple distinct workflows
 2. Create new feature file for split-out content
 3. Remove split content from original file
 4. Update README.md feature list if needed
 
-Continue iterating until user approves.
-
 # Framework Schemas Reference
 
 Schemas are bundled in `@tailor-platform/erp-kit`.

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

@@ -52,7 +52,22 @@ After ALL agents return:
 2. Merge all `issues[]` arrays into a single list
 3. Merge all `recommendations[]` arrays into a single list
 4. Calculate totals across all summaries
-5. Render the final report below
+
+## Step 4: Severity Validation
+
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
+
+- **"Is this even this module's responsibility?"** — If the concern belongs to another module or is out of scope, drop it from the report
+- **"Does this block planning?"** → `critical`
+- **"Will this force model/command/query rework?"** → `major`
+- All no → `nit`, regardless of subagent label
+
+## Step 5: Determine Verdict
+
+- **APPROVED**: zero `critical` and zero `major`
+- **NEEDS CHANGES**: one or more `critical` or `major`
+
+## Step 6: Render Report
 
 ## Report Format
 
@@ -100,11 +115,20 @@ Render the aggregated results as markdown:
 
 ### 5. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
+
+1. `critical` — boundary issues, fundamental design flaws (must fix)
+2. `major` — best practice violations, missing capabilities (should fix)
+3. `nit` — cosmetic, stylistic, minor improvements (informational only)
+
+### 6. Verdict
+
+**Verdict: APPROVED / NEEDS CHANGES**
+
+- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
+- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."
 
-1. Critical boundary issues (highest priority)
-2. Best practice violations
-3. Improvement suggestions
+Severity counts: `critical: N, major: N, nit: N`
 
 ## References
 

package/skills/erp-kit-module-2-requirements-review/references/requirements-report-format.md

@@ -23,3 +23,22 @@ A numbered list of actionable suggestions, grouped by priority:
 ### Summary
 
 A summary table with aggregate counts: total checks, passed, failed, warned.
+
+## Router-Level Severity and Verdict
+
+The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.
+
+The router classifies each finding as:
+
+| Severity   | Meaning                                                                                     | Examples                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `critical` | Blocks progress — fundamental design flaw, missing required capability, or boundary violation | Missing entity ownership, overlapping CRUD with another module, broken state machine      |
+| `major`    | Should fix — will likely cause issues downstream but not a design blocker                    | Missing standard ERP state, unclear dependency direction, incomplete business rules       |
+| `nit`      | Nice to have — cosmetic, stylistic, or minor improvement suggestion                         | Naming convention preference, optional field suggestion, documentation wording improvement |
+
+Verdict rule:
+
+- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+- **NEEDS CHANGES**: one or more `critical` or `major` findings
+
+When verdict is APPROVED with nits, list the nits as informational notes — they do NOT block the review.

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

@@ -33,17 +33,15 @@ Use the extraction rules from:
 - [references/command-extraction.md](references/command-extraction.md) — write operations, business rules, error scenarios, process flows
 - [references/query-extraction.md](references/query-extraction.md) — read operations, lookups, aggregations, conversions
 
-Present consolidated plan to user:
+Produce consolidated plan:
 
 - Models to create (with fields, relationships, states)
 - Commands to create (with business rules, error scenarios)
 - Queries to create (with inputs, outputs)
 
-Wait for user approval.
-
 ## Step 3: Scaffold & Populate
 
-After approval, scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
+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>