@tailor-platform/erp-kit 0.2.1 → 0.2.2

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

@@ -0,0 +1,126 @@
+---
+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.
+---
+
+# Module Requirements Workflow
+
+Collaborative workflow for creating ERP module requirements. Uses parallel agents for research, then human validates and decides scope.
+
+## Workflow
+
+```
+SETUP → DISPATCH AGENTS → AGGREGATE & SCOPE → CREATE → REVIEW
+```
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `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.
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 2 Agent tool calls in parallel — one per research concern.
+Each agent receives: MODULE_NAME, DOMAIN, relevant context.
+
+| Agent | Prompt Template                                                    | Inputs                             |
+| ----- | ------------------------------------------------------------------ | ---------------------------------- |
+| 1     | [references/erp-research.md](references/erp-research.md)           | MODULE_NAME, DOMAIN                |
+| 2     | [references/boundary-analysis.md](references/boundary-analysis.md) | MODULE_NAME, DOMAIN, OTHER_MODULES |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{DOMAIN}}` with the business domain
+4. Replace `{{OTHER_MODULES}}` with the actual file paths
+5. Dispatch the agent with the filled prompt
+
+## Step 3: Aggregate & Scope Decision
+
+After ALL agents return:
+
+1. Collect findings from each agent
+2. Build a **feature candidate table** by combining:
+   - Features identified from ERP/SaaS research (Agent 1)
+   - Module boundaries and dependencies (Agent 2)
+3. For each feature, assign Include/Skip and the reasoning
+
+Present as a **feature candidate list**:
+
+### Feature Candidates
+
+For each feature:
+
+- **Feature:** feature name
+- **Description:** what it does (1-2 sentences)
+- **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.
+
+## Step 4: Create — Agent per feature
+
+First, scaffold the module if it doesn't exist:
+
+```bash
+erp-kit scaffold --modules-root <MODULES_ROOT> module <module-name>
+```
+
+Then, for each `Include` feature, launch an Agent:
+
+| Agent per feature | Prompt Template                                        | Inputs                                                           |
+| ----------------- | ------------------------------------------------------ | ---------------------------------------------------------------- |
+| N                 | [references/feature-doc.md](references/feature-doc.md) | MODULE_NAME, FEATURE_NAME, FEATURE_DESCRIPTION, RESEARCH_CONTEXT |
+
+- `FEATURE_NAME`: the feature name from the candidate list
+- `FEATURE_SLUG`: kebab-case version (e.g., `role-based-access-control`)
+- `FEATURE_DESCRIPTION`: the description from the candidate list
+- `RESEARCH_CONTEXT`: relevant findings from Agent 1 (ERP/SaaS research) for this feature
+
+Parallelize across all features.
+
+After all agents complete, run validation:
+
+```bash
+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.
+
+**Iteration pattern:**
+
+1. User identifies issue (e.g., "X is too broad, split it")
+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`.
+
+## Validation
+
+Always run before completing:
+
+```bash
+pnpm run module:doc:check
+```
+
+## References
+
+- [Module structure](../erp-kit-module-shared/references/structure.md)

package/skills/erp-kit-module-1-requirements/references/boundary-analysis.md

@@ -0,0 +1,51 @@
+# Module Boundary Analysis
+
+## Context
+
+Module: {{MODULE_NAME}}
+Domain: {{DOMAIN}}
+Other module READMEs: {{OTHER_MODULES}}
+
+## Instructions
+
+Analyze how the proposed {{MODULE_NAME}} module fits within the existing module landscape.
+
+1. Read ALL other module READMEs at the paths above
+2. For each existing module, extract:
+   - Module purpose and scope
+   - Key entities it owns
+   - Features it provides
+3. Analyze boundaries:
+   - What entities might be shared with existing modules?
+   - What dependencies will this module have on others?
+   - What dependencies might others have on this module?
+   - Are there potential scope overlaps?
+
+## Boundary Checks
+
+| Check                | Question                                                |
+| -------------------- | ------------------------------------------------------- |
+| entity_ownership     | Which entities are new vs shared with existing modules? |
+| scope_overlap        | Does this domain overlap with existing module scopes?   |
+| dependency_direction | What are the expected dependency directions?            |
+| integration_points   | Where will this module need to integrate with others?   |
+
+## Output Format
+
+Return your analysis as a structured markdown report:
+
+### Existing Module Landscape
+
+Table of existing modules with columns: Module, Relationship (none/depends_on/depended_by/overlaps), Detail
+
+### Shared Entities
+
+Table with columns: Entity, Owned By, Referenced By
+
+### Boundary Concerns
+
+Table with columns: Concern, Severity (high/medium/low), Recommendation
+
+### Integration Points
+
+Table with columns: With Module, Type (data_reference/command_call/event), Description

package/skills/erp-kit-module-1-requirements/references/erp-research.md

@@ -0,0 +1,57 @@
+# ERP Research
+
+## Context
+
+Module: {{MODULE_NAME}}
+Domain: {{DOMAIN}}
+
+## Instructions
+
+Research established ERP solutions and leading domain-specific SaaS for the {{DOMAIN}} domain and compile findings.
+
+1. **Web search** established ERP platforms for the domain
+   - Search: "Odoo {{DOMAIN}} features"
+   - Search: "Oracle ERP Cloud {{DOMAIN}}"
+   - Search: "SAP {{DOMAIN}} module"
+2. **Web search** leading SaaS products in the {{DOMAIN}} domain
+   - Search: "best {{DOMAIN}} software" or "top {{DOMAIN}} SaaS"
+   - Identify 2-3 market-leading SaaS products specialized in this domain
+   - Research their core features, data models, and workflows
+3. **Fetch documentation** from official sources when available:
+   - Odoo: https://www.odoo.com/documentation/19.0/applications.html
+   - Oracle: https://docs.oracle.com/en/cloud/saas/index.html
+   - SAP: Search SAP Docs
+   - Domain SaaS: Fetch product documentation or feature pages
+4. **Identify** common features across solutions:
+   - Core entities and their attributes
+   - Common workflows and state machines
+   - Compliance requirements
+   - Integration points
+5. **Categorize** features by scope level:
+   - Minimal: Basic CRUD, core entities
+   - Core: Essential workflows, standard compliance
+   - Comprehensive: Advanced features, full compliance, integrations
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Sources Consulted
+
+List which ERP systems and domain SaaS products were researched.
+
+### Core Entities
+
+Table of entities with columns: Entity, Description, Scope (minimal/core/comprehensive)
+
+### Common Features
+
+Table of features with columns: Feature, Description, Scope, Found In
+
+### Workflows
+
+For each workflow: name, description, and which scope level it belongs to.
+
+### Compliance Requirements
+
+List any regulatory or compliance requirements found.

package/skills/erp-kit-module-1-requirements/references/feature-doc.md

@@ -0,0 +1,61 @@
+# Feature Documentation
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature: {{FEATURE_NAME}}
+Feature description: {{FEATURE_DESCRIPTION}}
+Research context: {{RESEARCH_CONTEXT}}
+
+## Instructions
+
+Write a feature documentation file for the {{FEATURE_NAME}} feature.
+
+1. Read existing feature docs in `{{MODULES_ROOT}}/{{MODULE_NAME}}/docs/features/` for style reference
+2. Scaffold the file:
+   ```bash
+   erp-kit scaffold --modules-root {{MODULES_ROOT}} feature {{MODULE_NAME}} {{FEATURE_SLUG}}
+   ```
+3. Fill in the scaffolded file following the structure below
+
+## Feature Doc Structure
+
+### Overview
+
+1-2 paragraphs explaining what the feature does and why it exists.
+
+### Business Purpose
+
+Bulleted list of business needs this feature addresses.
+
+### Process Flow
+
+Mermaid flowchart showing the main workflow. Use `flowchart TD` format.
+
+### Scenario Patterns
+
+Bulleted list of concrete usage scenarios. Each pattern:
+
+- **Pattern name**: Brief description of when/how this scenario occurs
+
+### Test Cases
+
+Bulleted list of testable assertions. Each test case should be a single sentence starting with a verb or condition:
+
+- "Creating X with valid data should succeed"
+- "X must be unique (no duplicates)"
+- "Deactivating X while Y should be prevented"
+
+Cover: happy paths, uniqueness/validation, authorization, edge cases.
+
+### Reference Links (optional)
+
+Links to relevant standards, specs, or external documentation.
+
+## Guidelines
+
+- Keep the overview concise (~100-200 words)
+- Scenario patterns should reflect real business use cases, not implementation details
+- Test cases should be verifiable from the feature spec alone (no implementation knowledge needed)
+- Use the research context to inform realistic scenarios and edge cases
+- Do not reference other features' internal details; describe integration points at a high level

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

@@ -0,0 +1,112 @@
+---
+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.
+---
+
+# Requirements Review
+
+Review **requirements quality** and **module boundary consistency** for a module.
+
+## When to Use
+
+- After writing module requirements and feature documentation (step 1)
+- When validating that features follow ERP best practices
+- When checking module boundaries against existing modules
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `MODULE_README`: `<MODULES_ROOT>/<MODULE_NAME>/README.md`
+- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/features/*.md`
+- `OTHER_MODULES`: glob `<MODULES_ROOT>/*/README.md` (excluding current module)
+- `OTHER_FEATURES`: glob `<MODULES_ROOT>/*/docs/features/*.md` (excluding current module)
+
+Verify at least `MODULE_README` exists. If not, stop with: "No module README found for module <MODULE_NAME>. Run erp-kit-module-1-requirements first."
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 2 Agent tool calls in parallel — one per review concern.
+Each agent receives: MODULE_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)             | MODULE_README, FEATURE_DOCS                                |
+| 2     | [references/boundary-consistency-check.md](references/boundary-consistency-check.md) | MODULE_README, FEATURE_DOCS, OTHER_MODULES, OTHER_FEATURES |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{MODULE_README}}`, `{{FEATURE_DOCS}}`, `{{OTHER_MODULES}}`, `{{OTHER_FEATURES}}` 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
+
+**Module:** <MODULE_NAME>
+
+---
+
+### 1. Best Practices
+
+| Feature | Check | Status | Detail |
+| ------- | ----- | ------ | ------ |
+
+(Populated from agent 1 issues)
+
+---
+
+### 2. Module Boundary Consistency
+
+| Feature | Overlapping Module | Overlap Area | Recommendation |
+| ------- | ------------------ | ------------ | -------------- |
+
+(Populated from agent 2 issues where check is `boundary_overlap`)
+
+---
+
+### 3. Dependency Analysis
+
+| Feature | Depends On Module | Dependency Type | Status |
+| ------- | ----------------- | --------------- | ------ |
+
+(Populated from agent 2 issues where check is `dependency_analysis`)
+
+---
+
+### 4. Summary
+
+| Aspect               | Status | Details           |
+| -------------------- | ------ | ----------------- |
+| Best Practices       |        | X/Y checks passed |
+| Boundary Consistency |        | X/Y checks passed |
+
+### 5. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Critical boundary issues (highest priority)
+2. Best practice violations
+3. Improvement suggestions
+
+## References
+
+- [Requirements report format](references/requirements-report-format.md)
+- For requirements creation, see erp-kit-module-1-requirements

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

@@ -0,0 +1,79 @@
+# Domain Best Practices Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Module README: {{MODULE_README}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+1. Read the module README at the path above
+2. Read ALL feature docs at the paths above
+3. **Web search** established ERP systems (Odoo, SAP, Oracle) and leading domain SaaS for this module's domain to understand industry-standard patterns
+4. For each feature, evaluate whether the **domain design itself** follows industry best practices
+5. Return results as markdown per the Output Format section
+
+## Domain Design Checks
+
+For each feature doc, evaluate the design decisions against ERP/SaaS industry norms:
+
+| Check ID                | Question                                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| entity_design           | Does the entity model follow industry-standard patterns? (e.g., Person/Organization split, address normalization) |
+| state_machine_design    | Do state transitions match how this domain typically works in production ERP systems?                             |
+| business_rules_validity | Are the business rules realistic and aligned with real-world domain constraints?                                  |
+| missing_capabilities    | Are there standard domain capabilities that are conspicuously absent?                                             |
+| over_engineering        | Are there features or rules that go beyond what's standard and add unnecessary complexity?                        |
+| compliance_alignment    | Does the design account for relevant industry standards or regulations? (e.g., ISO, tax law)                      |
+
+### Module-Level Checks
+
+| Check ID              | Question                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| domain_model_fit      | Does the module's entity decomposition match how this domain is typically modeled in ERPs? |
+| integration_readiness | Are the integration points (what other modules will need) well-anticipated?                |
+
+## How to Check
+
+For each feature:
+
+1. Identify the domain area (e.g., partner management, inventory, purchasing)
+2. Research how Odoo, SAP, Oracle, and leading SaaS products design this domain area
+3. Compare the feature's entity model, state transitions, and business rules against industry patterns
+4. Flag deviations — some deviations are intentional simplifications (acceptable), others are design gaps (flag them)
+
+## Common Domain Design Issues
+
+- **Missing standard entity splits**: e.g., not distinguishing Person vs Organization in partner management
+- **Non-standard state machines**: e.g., missing common states like "Draft" or "Pending Approval" that most ERPs include
+- **Unrealistic business rules**: e.g., rules that would break in multi-currency or multi-tenant scenarios
+- **Missing regulatory hooks**: e.g., tax handling that doesn't account for regional variations
+- **Over-simplified relationships**: e.g., 1-1 where industry standard is N-N (e.g., contacts to organizations)
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Check Results
+
+For each finding:
+
+- **Feature:** feature name
+- **Check:** check ID
+- **Status:** pass / fail / warn
+- **Detail:** what was found and why it matters
+- **Industry reference:** what Odoo/SAP/Oracle/SaaS does differently (if applicable)
+
+### Recommendations
+
+Numbered list grouped by priority (critical → high → medium → low). Each item should reference a specific industry practice and explain the recommended change.
+
+### Summary
+
+Table with columns: Metric, Count
+
+- Total checks
+- Passed
+- Failed
+- Warned

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

@@ -0,0 +1,70 @@
+# Boundary Consistency Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Module README: {{MODULE_README}}
+Feature docs: {{FEATURE_DOCS}}
+Other module READMEs: {{OTHER_MODULES}}
+Other module features: {{OTHER_FEATURES}}
+
+## Instructions
+
+1. Read the module README and ALL feature docs for {{MODULE_NAME}}
+2. Read ALL other module READMEs and their feature docs
+3. For each feature in {{MODULE_NAME}}, check for boundary overlaps and dependency issues
+4. Return results as markdown per the Output Format section
+
+## Boundary Checks
+
+For each feature in the target module:
+
+| Check ID            | Question                                                                  |
+| ------------------- | ------------------------------------------------------------------------- |
+| boundary_overlap    | Does this feature overlap with features in other modules?                 |
+| entity_ownership    | Is each entity owned by exactly one module? No shared entity definitions? |
+| dependency_analysis | Are cross-module dependencies explicit and well-defined?                  |
+| scope_leakage       | Does this feature handle concerns that belong to another module?          |
+
+### How to Check
+
+1. Extract all entities and operations from the target module's features
+2. Extract all entities and operations from other modules' features
+3. Compare for overlaps:
+   - Same entity name in multiple modules → likely boundary issue
+   - Same operation on same entity → scope leakage
+   - Feature referencing another module's entities without explicit dependency → implicit dependency
+4. For each overlap, determine if it's:
+   - **Legitimate shared reference** (e.g., User entity referenced by many modules)
+   - **Boundary violation** (e.g., both modules try to manage the same entity lifecycle)
+   - **Missing dependency** (e.g., module uses entity without declaring dependency)
+
+## Common Boundary Patterns
+
+- **Ownership conflicts**: Two modules both define CRUD for the same entity
+- **Scope creep**: Module handles validation/workflow that belongs elsewhere
+- **Missing integration points**: Module needs data from another module but doesn't declare it
+- **Redundant features**: Same capability implemented in multiple modules
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Check Results
+
+Table with columns: Feature, Target (overlapping module/feature), 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-module-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 implementation 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.