@tailor-platform/erp-kit 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @tailor-platform/erp-kit
 
+## 0.4.1
+
+### Patch Changes
+
+- 4aada62: - Fix relative shared imports to use package self-reference for consistent module resolution
+  - Fix priority calibration in requirements review skill to improve accuracy
+  - Fix severity validation in module-2 requirements review skill
+  - Update module-4-plan-review skill and regenerate .agents/skills
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/cli.mjs

@@ -863,7 +863,7 @@ function generateErrors(moduleName, docs) {
 	}
 	if (lines.length === 0) return "";
 	return `// @generated — do not edit
-import { createDomainError } from "../../../shared";
+import { createDomainError } from "@tailor-platform/erp-kit/module";
 
 ${lines.join("\n")}`;
 }
@@ -871,7 +871,7 @@ ${lines.join("\n")}`;
 //#region src/generator/generate-permissions.ts
 function generatePermissions(moduleName, commandNames) {
 	return `// @generated — do not edit
-import { definePermissions } from "../../../shared";
+import { definePermissions } from "@tailor-platform/erp-kit/module";
 
 export const { permissions, own, all } = definePermissions("${moduleName}", [
 ${[...commandNames].sort().map((name) => `  "${name}",`).join("\n")}
@@ -883,9 +883,9 @@ ${[...commandNames].sort().map((name) => `  "${name}",`).join("\n")}
 function generateCommandShell(doc) {
 	return [
 		`// @generated — do not edit`,
-		`import { defineCommand } from "../../../shared";`,
 		`import { permissions } from "../lib/permissions.generated";`,
 		`import { run } from "./${doc.commandName}";`,
+		`import { defineCommand } from "@tailor-platform/erp-kit/module";`,
 		``,
 		`export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
 		``
@@ -894,8 +894,8 @@ function generateCommandShell(doc) {
 function generateQueryShell(doc) {
 	return [
 		`// @generated — do not edit`,
-		`import { defineQuery } from "../../../shared";`,
 		`import { run } from "./${doc.commandName}";`,
+		`import { defineQuery } from "@tailor-platform/erp-kit/module";`,
 		``,
 		`export const ${doc.commandName} = defineQuery(run);`,
 		``
@@ -909,8 +909,8 @@ function toPascal(name) {
 const templates = {
 	command: { render: (name) => {
 		const inputType = `${toPascal(name)}Input`;
-		return `import { ok, type CommandContext } from "../../../shared";
-import type { Transaction } from "../generated/kysely-tailordb";
+		return `import type { Transaction } from "../generated/kysely-tailordb";
+import { ok, type CommandContext } from "@tailor-platform/erp-kit/module";
 
 export interface ${inputType} {
   // TODO: define input fields
@@ -926,9 +926,9 @@ export async function run(db: Transaction, input: ${inputType}, ctx: CommandCont
 		const pascal = toPascal(name);
 		return `import { describe, expect, it } from "vitest";
 import { createMockDb } from "../../../testing/index";
-import type { CommandContext } from "../../../shared";
 import type { Transaction } from "../generated/kysely-tailordb";
 import { run, ${pascal}Input } from "./${name}";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
 
 describe("${name} - test scenario", () => {
   const ctx: CommandContext = {
@@ -946,8 +946,8 @@ describe("${name} - test scenario", () => {
 	} },
 	query: { render: (name) => {
 		const inputType = `${toPascal(name)}Input`;
-		return `import type { ReadonlyDB } from "../../../shared";
-import type { DB } from "../generated/kysely-tailordb";
+		return `import type { DB } from "../generated/kysely-tailordb";
+import type { ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface ${inputType} {
   // TODO: define input fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

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

@@ -10,7 +10,7 @@ Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.
 ## Workflow Phases
 
 ```
-GATHER → CLARIFY → CREATE → VALIDATE
+GATHER → CLARIFY → CREATE → STORY EXTRACTION → VALIDATE
 ```
 
 ### Phase 1: Gather
@@ -61,7 +61,9 @@ erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
     README.md                                ← Tier 1 (from app init)
     docs/
       actors/{actor-name}.md                 ← Tier 2 (from generate doc actors)
-      business-flow/{flow-name}/README.md    ← Tier 2 (from generate doc business-flow)
+      business-flow/{flow-name}/
+        README.md                              ← Tier 2 (from generate doc business-flow)
+        story/{actor}--{story-name}.md         ← Tier 2 (from Phase 3b story extraction)
 ```
 
 **Schema constraints:** See [erp-kit-app-shared/references/schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.md) for H1 heading rules, naming conventions, and requirements structure.
@@ -70,7 +72,32 @@ erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
 
 **Business flow `## Stories` section:**
 
-At Tier 2, story files do not exist yet. Use `- TBD` as a placeholder to avoid broken link violations. Replace with actual story links in `/erp-kit-app-3-plan`.
+Use `- TBD` as a placeholder during flow creation. These will be replaced with actual story links in Phase 3b below.
+
+### Phase 3b: Story Extraction
+
+After creating business flows, extract and create story documentation.
+
+1. **Collect** all business flow docs: glob `<APP_ROOT>/docs/business-flow/*/README.md`
+2. **Dispatch story extraction agents** — one Agent per business flow (parallelize if possible). Each agent:
+   - Reads the prompt template from [references/story-extraction.md](references/story-extraction.md)
+   - Replace `{{APP_NAME}}` with the resolved app name
+   - Replace `{{ACTOR_DOCS}}` with the actor doc file paths
+   - Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for that agent
+   - Dispatch the agent with the filled prompt
+
+3. **Scaffold & populate** story docs from agent results:
+
+```bash
+# For each story identified
+erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
+```
+
+4. **Link stories** in business flow READMEs: replace `- TBD` placeholders in each flow's `## Stories` section with actual links:
+
+```markdown
+- [Story Title](./story/<actor>--<story-name>.md)
+```
 
 ### Phase 4: Validate
 
@@ -87,6 +114,7 @@ See [schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.
 | `requirements.yml`  | 1    | `README.md`                           |
 | `actors.yml`        | 2    | `docs/actors/<name>.md`               |
 | `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md` |
+| `story.yml`         | 2    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
 
 ## Next Step
 

package/skills/{erp-kit-app-3-plan → erp-kit-app-1-requirements}/references/story-extraction.md

@@ -6,12 +6,6 @@ App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
 
-## Available Modules
-
-The following modules are available in erp-kit. Use this to determine whether a story needs custom resolvers or can rely on built-in queries.
-
-{{MODULE_OVERVIEW}}
-
 ## Instructions
 
 1. Read ALL actor docs at the paths above
@@ -55,10 +49,10 @@ For each story, extract:
 
 ### Resolver Classification
 
-For each story, determine using the module overview:
+For each story, determine:
 
-- **Needs resolvers**: Story involves create/update/delete operations → mark as `- TBD` for resolvers
-- **Read-only**: Story only views/lists data and built-in queries suffice → mark as `None` for resolvers
+- **Needs resolvers**: Story involves create/update/delete operations → mark as `TBD` for resolvers
+- **Read-only**: Story only views/lists data → mark as `None` for resolvers
 
 ## Naming Convention
 

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

@@ -22,12 +22,13 @@ Define shared context for all agents:
 - `APP_README`: `<APP_ROOT>/README.md`
 - `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
 
 Verify at least `APP_README` exists. If not, stop with: "No application README found at <APP_ROOT>. Run erp-kit-app-1-requirements first."
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 2 Agent tool calls in parallel — one per review concern.
+Launch 3 Agent tool calls in parallel — one per review concern.
 Each agent receives: APP_NAME, relevant doc file paths.
 Each agent returns: structured markdown per [references/requirements-report-format.md](references/requirements-report-format.md).
 
@@ -35,13 +36,15 @@ Each agent returns: structured markdown per [references/requirements-report-form
 | ----- | ------------------------------------------------------------------------------------ | ------------------------------------------ |
 | 1     | [references/best-practices-check.md](references/best-practices-check.md)             | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
 | 2     | [references/boundary-consistency-check.md](references/boundary-consistency-check.md) | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
+| 3     | [references/story-quality-check.md](references/story-quality-check.md)               | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS, STORY_DOCS |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
 3. Replace `{{APP_README}}`, `{{ACTOR_DOCS}}`, `{{BUSINESS_FLOW_DOCS}}` with the actual file paths
-4. Dispatch the agent with the filled prompt
+4. Replace `{{STORY_DOCS}}` with the story doc file paths (agent 3 only)
+5. Dispatch the agent with the filled prompt
 
 ## Step 3: Aggregate & Validate
 
@@ -52,7 +55,18 @@ After ALL agents return:
 3. Merge all `recommendations[]` arrays into a single list
 4. **Filter out** any recommendation that would violate `erp-kit app check` schema constraints (e.g., title-casing business flow H1 headings)
 5. Calculate totals across all summaries
-6. Render the final report below
+
+## Step 4: Priority Validation
+
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
+
+- **"Is this even this application's responsibility?"** — If the concern belongs to a module or is out of scope, drop it from the report
+- **"Does this block proceeding to planning?"** → `critical`
+- **"Will this force Tier 3-4 rework (stories, screens, resolvers)?"** → `high`
+- **"Is this a quality improvement with no rework risk?"** → `medium`
+- All no → `low`, regardless of subagent label
+
+## Step 5: Render Report
 
 ## Report Format
 
@@ -82,14 +96,24 @@ Render the aggregated results as markdown:
 
 ---
 
-### 3. Summary
+### 3. Story Quality
+
+| Story/Flow | Check | Status | Detail |
+| ---------- | ----- | ------ | ------ |
+
+(Populated from agent 3 issues)
+
+---
+
+### 4. Summary
 
 | Aspect                    | Status | Details           |
 | ------------------------- | ------ | ----------------- |
 | Best Practices            |        | X/Y checks passed |
 | Documentation Consistency |        | X/Y checks passed |
+| Story Quality             |        | X/Y checks passed |
 
-### 4. Recommendations
+### 5. Recommendations
 
 Numbered list of actionable fixes, grouped by priority:
 

package/skills/erp-kit-app-2-requirements-review/references/story-quality-check.md

@@ -0,0 +1,67 @@
+# Story Quality Check
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
+
+## Instructions
+
+1. Read ALL actor docs at the paths above
+2. Read ALL business flow docs at the paths above
+3. Read ALL story docs at the paths above
+4. Validate story quality against the checks below
+5. Return results per the report format at the bottom
+
+## Checks
+
+### Story-to-Flow Parity
+
+For each business flow:
+- Every flow must have at least one story
+- Every story must map to exactly one flow (via its directory location)
+- The `## Stories` section in each flow README must link to all stories in its `story/` directory
+- No broken links in `## Stories` sections
+
+### Naming Conventions
+
+- Story filename must follow `<actor>--<story-name>.md` pattern (double-dash separator)
+- Actor slug in filename must match an existing actor doc
+- Story name portion must be kebab-case
+
+### Content Completeness
+
+For each story:
+- Must have scenario patterns (non-empty)
+- Must have preconditions and postconditions
+- Must have screen references (can be TBD at this stage)
+- Must have resolver classification (TBD for mutations, None for read-only)
+
+### Actor Consistency
+
+- Actor referenced in story filename must exist in `docs/actors/`
+- Actor referenced in story content must match the filename actor
+
+## Output Format
+
+Return findings as structured markdown:
+
+### Issues
+
+For each issue found:
+
+- **Check:** which check failed
+- **Scope:** which file/story/flow is affected
+- **Severity:** critical / high / medium / low
+- **Detail:** what's wrong and how to fix it
+
+### Summary
+
+| Check | Passed | Failed | Total |
+| ----- | ------ | ------ | ----- |
+| Story-to-Flow Parity | | | |
+| Naming Conventions | | | |
+| Content Completeness | | | |
+| Actor Consistency | | | |

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

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-3-plan
-description: Create Tier 3-4 documentation (stories, screens, resolvers) by breaking down business flows. Use after completing requirements review with erp-kit-app-2-requirements-review.
+description: Create Tier 3-4 documentation (screens, resolvers) by breaking down business flows and existing stories. Use after completing requirements review with erp-kit-app-2-requirements-review.
 ---
 
 # Business Flow Breakdown to Stories, Screens, and Resolvers
 
-Convert Tier 2 business flows into Tier 3 (stories, screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
+Convert Tier 2 business flows and stories into Tier 3 (screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
 
 ## When to Use
 
@@ -20,6 +20,7 @@ Tier 1-2 documentation must exist:
 - `README.md` (requirements)
 - `docs/actors/*.md` (actor definitions)
 - `docs/business-flow/*/README.md` (business workflows)
+- `docs/business-flow/<flow>/story/<actor>--<name>.md` (story definitions)
 
 ## Step 1: Setup
 
@@ -29,45 +30,55 @@ Define shared context for all agents:
 - `APP_NAME`: basename of APP_ROOT
 - `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
 - `MODULE_OVERVIEW`: output of `erp-kit doc modules`
 
 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/. Run erp-kit-app-1-requirements first."
 
+Verify at least `STORY_DOCS` is non-empty. If no story docs exist, stop with: "No story docs found. Run erp-kit-app-1-requirements first to create stories."
+
 Collect module overview:
 
 ```bash
 erp-kit doc modules
 ```
 
-This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — all three agents receive it.
+This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — both agents receive it.
+
+> **Sync barrier:** `MODULE_OVERVIEW` must be collected before dispatching agents.
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 3 Agent tool calls in parallel — one per extraction concern.
-Each agent receives: APP_NAME, relevant doc file paths, and MODULE_OVERVIEW.
+For each business flow in BUSINESS_FLOW_DOCS, launch 2 Agent tool calls in parallel — one per extraction concern.
+
+Each agent pair receives: APP_NAME, ACTOR_DOCS, the single business flow's STORY_DOCS, MODULE_OVERVIEW, and only that flow's BUSINESS_FLOW_DOC (singular).
 
-| Agent | Prompt Template                                                        | Inputs                                                    |
-| ----- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
-| 1     | [references/story-extraction.md](references/story-extraction.md)       | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
-| 2     | [references/screen-extraction.md](references/screen-extraction.md)     | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
-| 3     | [references/resolver-extraction.md](references/resolver-extraction.md) | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
+| Agent | Prompt Template                                                        |
+| ----- | ---------------------------------------------------------------------- |
+| A     | [references/screen-extraction.md](references/screen-extraction.md)     |
+| B     | [references/resolver-extraction.md](references/resolver-extraction.md) |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
-3. Replace `{{ACTOR_DOCS}}`, `{{BUSINESS_FLOW_DOCS}}` with the actual file paths
-4. Replace `{{MODULE_OVERVIEW}}` with the output from `erp-kit doc modules`
-5. Dispatch the agent with the filled prompt
+3. Replace `{{ACTOR_DOCS}}` with the actor doc file paths
+4. Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for this iteration
+5. Replace `{{STORY_DOCS}}` with ONLY the stories under this flow's `story/` directory
+6. Replace `{{MODULE_OVERVIEW}}` with the output from `erp-kit doc modules`
+7. Dispatch the agent with the filled prompt
+
+With N business flows, this produces N × 2 parallel agents.
 
 ## Step 3: Aggregate & Present Plan
 
 After ALL agents return:
 
-1. Collect extraction results from each agent
-2. Present consolidated plan to user:
-   - Stories to create (with actor, flow, scenario patterns)
-   - Screens to create (with type, fields, actions)
+1. Collect extraction results from each agent, grouped by business flow
+2. **Deduplicate screens**: Screens referenced by multiple flows should appear once — merge field lists and story references
+3. Present consolidated plan to user:
+   - Existing stories (from STORY_DOCS, for reference)
+   - Screens to create (deduplicated, with type, fields, actions)
    - Resolvers to create (with operation type, module mapping)
 ## Step 4: Resolve Module Gaps
 
@@ -88,9 +99,6 @@ For resolvers that reference erp-kit modules, use `MODULE_OVERVIEW` as the sourc
 Scaffold using `erp-kit` CLI:
 
 ```bash
-# Tier 3: Stories
-erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
-
 # Tier 3: Screens
 erp-kit app generate doc screen <screen-name> -p {APP_ROOT}/{APP_NAME}
 
@@ -100,12 +108,6 @@ erp-kit app generate doc resolver <resolver-name> -p {APP_ROOT}/{APP_NAME}
 
 Fill scaffolded docs with details from agent extraction results.
 
-**After creating stories**, replace `- TBD` placeholders in the `## Stories` section of each business flow README with actual links:
-
-```markdown
-- [Story Title](./story/<actor>--<story-name>.md)
-```
-
 **After creating resolvers**, replace `- TBD` placeholders in the `## Resolvers` section of each story with actual links:
 
 ```markdown
@@ -126,11 +128,10 @@ See [erp-kit-app-shared/references/naming-conventions.md](../erp-kit-app-shared/
 
 ## Schema Reference
 
-| Schema         | Tier | Output Path                                          |
-| -------------- | ---- | ---------------------------------------------------- |
-| `story.yml`    | 3    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
-| `screen.yml`   | 3    | `docs/screen/<name>.md`                              |
-| `resolver.yml` | 4    | `docs/resolver/<name>.md`                            |
+| Schema         | Tier | Output Path               |
+| -------------- | ---- | ------------------------- |
+| `screen.yml`   | 3    | `docs/screen/<name>.md`   |
+| `resolver.yml` | 4    | `docs/resolver/<name>.md` |
 
 ## Common Patterns
 
@@ -144,7 +145,7 @@ See [erp-kit-app-shared/references/naming-conventions.md](../erp-kit-app-shared/
 
 ## Tips
 
-- One business flow typically produces 3-8 stories
+- Stories are created in step 1 (erp-kit-app-1-requirements) — this step consumes them
 - Stories should be completable in a single user session
 - Screens can be shared across multiple stories
 - Prefer built-in queries over custom resolvers for simple list/get operations

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

@@ -5,6 +5,7 @@
 App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
 
 ## Available Modules
 
@@ -22,8 +23,9 @@ erp-kit doc module <module-name> command <command-name>
 
 1. Read ALL actor docs at the paths above
 2. Read ALL business flow docs at the paths above
-3. Identify GraphQL resolvers needed for each business flow, using the module overview and `erp-kit doc module <name> command` for detail
-4. Return results as a structured markdown report
+3. Read ALL story docs at the paths above
+4. Identify GraphQL resolvers needed for each business flow and story, using the module overview and `erp-kit doc module <name> command` for detail
+5. Return results as a structured markdown report
 
 ## Extraction Rules
 

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

@@ -5,6 +5,7 @@
 App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
 
 ## Available Modules
 
@@ -22,9 +23,10 @@ erp-kit doc module <module-name> model <model-name>
 
 1. Read ALL actor docs at the paths above
 2. Read ALL business flow docs at the paths above
-3. Identify screens needed for each business flow
-4. For screens that display or edit module entities, use `erp-kit doc module <name> model` to understand the entity's domain
-5. Return results as a structured markdown report
+3. Read ALL story docs at the paths above
+4. Identify screens needed for each business flow and story
+5. For screens that display or edit module entities, use `erp-kit doc module <name> model` to understand the entity's domain
+6. Return results as a structured markdown report
 
 ## Extraction Rules
 

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

@@ -44,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.
@@ -67,6 +69,8 @@ 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/resolvers/`, one per executor under `executors/`.
@@ -77,6 +81,12 @@ For each resolver, check whether its spec (`docs/resolver/*.md`) documents 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.

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,12 +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: