@tailor-platform/erp-kit 0.2.1 → 0.2.2

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {
-    "erp-kit": "./dist/cli.js"
+    "erp-kit": "./dist/cli.mjs"
   },
   "files": [
     "CHANGELOG.md",
-    "dist",
     "LICENSE",
+    "dist",
     "schemas",
     "skills",
-    "src"
+    "src",
+    "templates"
   ],
   "type": "module",
   "exports": {
@@ -34,12 +35,12 @@
   "devDependencies": {
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.17.1",
+    "@tailor-platform/sdk": "1.25.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.1.0",
-    "eslint": "9.39.4",
-    "kysely": "0.28.10",
-    "tsup": "^8.0.0",
+    "eslint": "10.0.3",
+    "kysely": "0.28.11",
+    "tsdown": "0.21.2",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
     "@tailor-platform/eslint-config": "0.0.1"
@@ -47,14 +48,14 @@
   "peerDependencies": {
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.17.1",
-    "kysely": "0.28.10"
+    "@tailor-platform/sdk": "1.25.1",
+    "kysely": "0.28.11"
   },
   "engines": {
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "generate": "for dir in src/modules/*/; do [ -f \"$dir/tailor.config.ts\" ] && (cd \"$dir\" && echo \"Generating $dir...\" && tailor-sdk generate); done",
     "lint": "eslint --cache .",
     "lint:fix": "eslint --cache --fix .",
@@ -64,8 +65,8 @@
     "test:primitives": "vitest run src/modules/primitives/",
     "test:user-management": "vitest run src/modules/user-management/",
     "test:shared": "vitest run src/modules/shared/",
-    "mock:start": "node dist/cli.js mock start",
-    "mock:validate": "node dist/cli.js mock validate",
+    "mock:start": "node dist/cli.mjs mock start",
+    "mock:validate": "node dist/cli.mjs mock validate",
     "doc:gen": "POLITTY_DOCS_UPDATE=true vitest run src/cli.doc.test.ts",
     "doc:check": "vitest run src/cli.doc.test.ts"
   }

package/schemas/app-compose/story.yml

@@ -55,6 +55,18 @@ structure:
             type: unordered
             min_items: 1
 
+      # Resolvers that implement this story's backend operations - OPTIONAL
+      # Enables M:N relationship between stories and resolvers
+      # Stories that only read data (browse, view, list) may not need resolvers
+      - heading: "## Resolvers"
+        description: |
+          Link to resolver docs that implement this story's backend operations.
+          Write "None" if this story does not require any resolvers.
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
 # Link validation
 links:
   validate_internal: true

package/schemas/module/command.yml

@@ -41,6 +41,15 @@ structure:
             type: unordered
             min_items: 1
 
+      # Test cases - REQUIRED
+      # Each item corresponds to an it() block in the test file
+      - heading: "## Test Cases"
+        description: "List test case descriptions that correspond to it() blocks in the test file.\ne.g. `- returns error when code is empty`"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
 # Link validation
 links:
   validate_internal: true

package/schemas/module/module.yml

@@ -30,6 +30,10 @@ structure:
               - min: 1
                 type: unordered
                 min_items: 1
+          - heading: "### Scope Decision Rationale"
+            description: "Explain why capabilities are in-scope or out-of-scope — domain alignment, separation of concerns, etc."
+            paragraphs:
+              min: 1
 
       # Module dependencies - REQUIRED
       - heading: "## Module Dependencies"

package/schemas/module/query.yml

@@ -41,6 +41,15 @@ structure:
             type: unordered
             min_items: 1
 
+      # Test cases - REQUIRED
+      # Each item corresponds to an it() block in the test file
+      - heading: "## Test Cases"
+        description: "List test case descriptions that correspond to it() blocks in the test file.\ne.g. `- returns product when found by id`"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
 # Link validation
 links:
   validate_internal: true

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

@@ -43,8 +43,8 @@ Ask 3-4 questions at a time using multiSelect where appropriate.
 Generate documentation using `erp-kit` CLI:
 
 ```bash
-# Tier 1: Requirements
-erp-kit app scaffold requirements <app-name> --root examples
+# Tier 1: Requirements + project structure
+erp-kit app scaffold app <app-name> --root examples
 
 # Tier 2: Actors
 erp-kit app scaffold actors <app-name> <actor-name> --root examples
@@ -62,7 +62,7 @@ erp-kit app scaffold business-flow <app-name> <flow-name> --root examples
 
 **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-2-breakdown`.
+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`.
 
 ### Phase 4: Validate
 
@@ -80,4 +80,4 @@ pnpm run app:doc:check
 
 ## Next Step
 
-After completing Tier 1-2, use `/erp-kit-app-2-breakdown` to create Tier 3 documentation.
+After completing Tier 1-2, use `/erp-kit-app-2-requirements-review` to review documentation quality.

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

@@ -0,0 +1,102 @@
+---
+name: erp-kit-app-2-requirements-review
+description: Review requirements quality and documentation consistency for app-compose applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
+---
+
+# Requirements Review
+
+Review **requirements quality** and **documentation consistency** for an app-compose application's Tier 1-2 documentation.
+
+## When to Use
+
+- After writing application requirements and business flows (step 1)
+- When validating that actors, flows, and sequences follow best practices
+- When checking for gaps or inconsistencies in Tier 1-2 documentation
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
+- `APP_NAME`: basename of APP_ROOT
+- `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`
+
+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.
+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).
+
+| Agent | Prompt Template                                                                      | Inputs                                     |
+| ----- | ------------------------------------------------------------------------------------ | ------------------------------------------ |
+| 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 |
+
+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
+
+## Step 3: Aggregate Results
+
+After ALL agents return:
+
+1. Collect the markdown results from each agent
+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
+
+## Report Format
+
+Render the aggregated results as markdown:
+
+### Requirements Review Report
+
+**Application:** <APP_NAME>
+
+---
+
+### 1. Best Practices
+
+| Check | Scope | Status | Detail |
+| ----- | ----- | ------ | ------ |
+
+(Populated from agent 1 issues)
+
+---
+
+### 2. Documentation Consistency
+
+| Actor/Flow | Check | Status | Detail |
+| ---------- | ----- | ------ | ------ |
+
+(Populated from agent 2 issues)
+
+---
+
+### 3. Summary
+
+| Aspect                    | Status | Details           |
+| ------------------------- | ------ | ----------------- |
+| Best Practices            |        | X/Y checks passed |
+| Documentation Consistency |        | X/Y checks passed |
+
+### 4. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Critical documentation gaps (highest priority)
+2. Best practice violations
+3. Improvement suggestions
+
+## References
+
+- [Requirements report format](references/requirements-report-format.md)
+- For requirements creation, see erp-kit-app-1-requirements

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

@@ -0,0 +1,66 @@
+# Application Best Practices Check
+
+## Context
+
+App: {{APP_NAME}}
+App README: {{APP_README}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+1. Read the application README at the path above
+2. Read ALL actor docs and business flow docs at the paths above
+3. **Web search** app-compose and ERP application best practices (actor modeling, business flow design, user journey patterns)
+4. Evaluate whether the Tier 1-2 documentation follows best practices
+5. Return results as markdown per the Output Format section
+
+## Application Design Checks
+
+For each actor and business flow, evaluate:
+
+| Check ID                 | Question                                                                                     |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| actor_completeness       | Does each actor have a clear role description, permissions scope, and linked business flows? |
+| actor_separation         | Are actor responsibilities well-separated? No single actor doing everything?                 |
+| flow_coherence           | Does each business flow have a clear trigger, logical step sequence, and defined outcome?    |
+| sequence_diagram_quality | Do sequence diagrams accurately represent actor interactions and system responses?           |
+| requirement_coverage     | Do business flows collectively cover the requirements stated in README?                      |
+| missing_flows            | Are there obvious workflows missing based on the stated requirements?                        |
+| flow_granularity         | Are flows at the right level of granularity? (not too coarse, not too fine)                  |
+| error_path_coverage      | Do flows account for error paths and edge cases, not just happy paths?                       |
+
+## Common Application Design Issues
+
+- **Overloaded actors**: A single actor responsible for too many unrelated flows
+- **Missing system actor**: Automated/system-triggered flows not represented as an actor
+- **Disconnected flows**: Flows that don't link to each other when they should (e.g., an approval flow that doesn't connect to the submission flow)
+- **Missing error flows**: Only happy-path documented, no handling of rejections, cancellations, or failures
+- **Vague requirements**: README states features that no business flow implements
+- **Inconsistent granularity**: Some flows are very detailed while others are hand-wavy
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Check Results
+
+For each finding:
+
+- **Scope:** actor name, flow name, or "application-level"
+- **Check:** check ID
+- **Status:** pass / fail / warn
+- **Detail:** what was found and why it matters
+
+### Recommendations
+
+Numbered list grouped by priority (critical → high → medium → low). Each item should explain the issue and the recommended fix.
+
+### Summary
+
+Table with columns: Metric, Count
+
+- Total checks
+- Passed
+- Failed
+- Warned

package/skills/erp-kit-app-2-requirements-review/references/boundary-consistency-check.md

@@ -0,0 +1,69 @@
+# Documentation Consistency Check
+
+## Context
+
+App: {{APP_NAME}}
+App README: {{APP_README}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+1. Read the application README at the path above
+2. Read ALL actor docs and business flow docs at the paths above
+3. Cross-reference actors, flows, and requirements for internal consistency
+4. Return results as markdown per the Output Format section
+
+## Consistency Checks
+
+| Check ID               | Question                                                                         |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| actor_flow_cross_ref   | Is every actor referenced in at least one business flow?                         |
+| flow_actor_cross_ref   | Does every business flow reference only actors that have actor docs?             |
+| actor_link_validity    | Do actor docs link to business flows that exist?                                 |
+| flow_link_validity     | Do business flow docs link to actor docs that exist?                             |
+| readme_flow_coverage   | Does every requirement/feature in README have a corresponding business flow?     |
+| naming_consistency     | Are actor and flow names consistent across all documents? (no typos, no aliases) |
+| diagram_actor_match    | Do sequence diagram participants match the "Actors Involved" section?            |
+| flow_step_completeness | Does every flow step identify a responsible actor?                               |
+
+### How to Check
+
+1. Extract all actor names from actor docs (filename slugs and H1 headings)
+2. Extract all flow names from business flow docs (directory names and H1 headings)
+3. For each actor doc, check "Authorized Flows" links resolve to existing flows
+4. For each flow doc, check "Actors Involved" references match existing actor docs
+5. For each sequence diagram, verify participants match the actors listed in "Actors Involved"
+6. Compare README features/requirements against business flow coverage
+
+## Common Consistency Issues
+
+- **Phantom actors**: Flow references an actor with no actor doc
+- **Orphaned actors**: Actor doc exists but no flow references them
+- **Broken links**: Actor→flow or flow→actor links point to non-existent files
+- **Name drift**: Actor called "Admin" in one doc and "Administrator" in another
+- **Diagram mismatch**: Sequence diagram uses different participant names than "Actors Involved"
+- **Uncovered requirements**: README lists a feature but no business flow implements it
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Check Results
+
+Table with columns: Actor/Flow, Check, Status (pass/fail/warn), Detail
+
+One row per check performed.
+
+### Recommendations
+
+Numbered list grouped by priority (critical → high → medium → low). Each item is an actionable recommendation.
+
+### Summary
+
+Table with columns: Metric, Count
+
+- Total checks
+- Passed
+- Failed
+- Warned

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

@@ -0,0 +1,25 @@
+# Requirements Report Format
+
+All requirements review agents return results as structured markdown.
+
+## Expected Sections
+
+### Check Results
+
+A table with one row per check performed. Columns vary by agent type but always include:
+
+- **Status**: `pass` (no issues), `fail` (significant issue), or `warn` (minor concern)
+- **Detail**: Human-readable description of the finding
+
+### Recommendations
+
+A numbered list of actionable suggestions, grouped by priority:
+
+- **critical**: must fix before proceeding to planning
+- **high**: should fix, may cause issues downstream
+- **medium**: recommended improvement
+- **low**: nice to have
+
+### Summary
+
+A summary table with aggregate counts: total checks, passed, failed, warned.

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

@@ -0,0 +1,157 @@
+---
+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.
+---
+
+# 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.
+
+## When to Use
+
+- User has Tier 1-2 documentation and wants to plan Tier 3-4
+- User asks to create story, screen, or resolver documentation
+- User wants to break down business flows into actionable specs
+
+## Prerequisites
+
+Tier 1-2 documentation must exist:
+
+- `README.md` (requirements)
+- `docs/actors/*.md` (actor definitions)
+- `docs/business-flow/*/README.md` (business workflows)
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
+- `APP_NAME`: basename of APP_ROOT
+- `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
+- `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+
+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."
+
+## 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.
+
+| Agent | Prompt Template                                                        | Inputs                                   |
+| ----- | ---------------------------------------------------------------------- | ---------------------------------------- |
+| 1     | [references/story-extraction.md](references/story-extraction.md)       | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
+| 2     | [references/screen-extraction.md](references/screen-extraction.md)     | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
+| 3     | [references/resolver-extraction.md](references/resolver-extraction.md) | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
+
+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. Dispatch the agent with the filled prompt
+
+## 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)
+   - Resolvers to create (with operation type, module mapping)
+3. Wait for user approval
+
+## Step 4: Check Module Dependencies
+
+Before creating resolver docs, verify required modules exist:
+
+```bash
+ls packages/erp-kit/src/modules/
+```
+
+For each resolver that references a module command, check the module and command exist:
+
+```bash
+ls packages/erp-kit/src/modules/<module-name>/docs/commands/
+```
+
+**If modules don't exist:**
+
+1. Identify needed modules — group resolver operations by domain
+2. Create module docs first — use `erp-kit-module-1-requirements` skill
+3. Return to this step after modules have documented commands
+
+**Only reference existing module commands** in resolver documentation.
+
+## Step 5: Scaffold & Populate
+
+After approval, scaffold using `erp-kit` CLI:
+
+```bash
+# Tier 3: Stories
+erp-kit app scaffold story <app> <flow>/<actor>--<story> --root examples
+
+# Tier 3: Screens
+erp-kit app scaffold screen <app> <screen-name> --root examples
+
+# Tier 4: Resolvers
+erp-kit scaffold --app-root examples resolver <app> <resolver-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
+- [resolverName](../../../resolver/resolverName.md)
+```
+
+Read-only stories should have `None` under `## Resolvers`.
+
+## Step 6: Validate
+
+```bash
+pnpm run app:doc:check
+```
+
+## Naming Conventions
+
+- Story filename: `<actor>--<story-name>.md` (double-dash separator)
+- Story heading: Title Case of story name (after `--`)
+- Screen filename: kebab-case, noun-focused (e.g., `supplier-list.md`)
+- Resolver filename: camelCase action-verb (e.g., `createSupplierInvitation.md`)
+
+## 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`                            |
+
+## Common Patterns
+
+| Flow Element         | Documentation Type           |
+| -------------------- | ---------------------------- |
+| User action step     | Story                        |
+| UI requirement       | Screen                       |
+| Actor in flow        | Story actor                  |
+| Create/Update/Delete | Resolver (Mutation)          |
+| View/List/Search     | Resolver (Query) or built-in |
+
+## Tips
+
+- One business flow typically produces 3-8 stories
+- 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
+
+## Next Step
+
+After completing Tier 3-4, use `/erp-kit-app-4-plan-review` to validate documentation parity.