@tailor-platform/erp-kit 0.2.1 → 0.3.0

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

@@ -0,0 +1,107 @@
+---
+name: erp-kit-module-3-plan
+description: Create implementation plan by breaking down feature specs into model, command, and query documentation. Use after requirements review (step 2) to plan the implementation structure.
+---
+
+# Feature Breakdown to Model/Command/Query Docs
+
+Convert feature specifications into structured model, command, and query documentation. The main agent creates the plan and populates scaffolded docs, then parallel subagents refine each doc type.
+
+## When to Use
+
+- User has feature specs (e.g., `docs/features/*.md`) and wants implementation docs
+- User asks to create model, command, or query documentation
+- User references `model.yml` or `command.yml` schemas
+
+## Step 1: Setup
+
+Define shared context:
+
+- `MODULES_ROOT`: glob `**/modules/*/README.md` and derive the parent directory
+- `MODULE_NAME`: from argument or detect from current working directory
+- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/features/*.md`
+
+Verify at least `FEATURE_DOCS` is non-empty. If no feature docs exist, stop with: "No feature docs found for module <MODULE_NAME>. Run erp-kit-module-1-requirements first."
+
+## Step 2: Extract Plan (single agent)
+
+Read ALL feature docs and extract models, commands, and queries yourself (no subagents).
+
+Use the extraction rules from:
+
+- [references/model-extraction.md](references/model-extraction.md) — entity/model identification, field extraction, state machines, relationships
+- [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:
+
+- 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)):
+
+```bash
+erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+```
+
+Fill in the scaffolded docs with details from the extraction in Step 2.
+
+## Step 4: Dispatch Update Agents (parallelize)
+
+Launch 3 Agent tool calls in parallel — one per doc type — to review and refine populated docs.
+Each agent receives: MODULE_NAME, the list of created doc file paths, and FEATURE_DOCS for cross-reference.
+
+| Agent | Prompt Template                                                      | Inputs                                       |
+| ----- | -------------------------------------------------------------------- | -------------------------------------------- |
+| 1     | [references/model-extraction.md](references/model-extraction.md)     | MODULE_NAME, model doc paths, FEATURE_DOCS   |
+| 2     | [references/command-extraction.md](references/command-extraction.md) | MODULE_NAME, command doc paths, FEATURE_DOCS |
+| 3     | [references/query-extraction.md](references/query-extraction.md)     | MODULE_NAME, query doc paths, FEATURE_DOCS   |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{FEATURE_DOCS}}` with the actual file paths
+4. Add to the prompt: "Read the populated docs at [doc paths]. Cross-reference against the feature docs and the extraction rules. Fix any missing fields, incorrect types, incomplete business rules, or inconsistencies. Edit files directly."
+5. Dispatch the agent with the filled prompt
+
+## Step 5: Validate
+
+Run `pnpm run module:doc:check` and fix any violations.
+
+## Schema Quick Reference
+
+Schemas are bundled in `@tailor-platform/erp-kit` (model.yml, command.yml).
+
+## Common Patterns
+
+| Feature Element       | Documentation Type               |
+| --------------------- | -------------------------------- |
+| Entity with fields    | Model doc                        |
+| State machine         | Model doc with State Transitions |
+| Verb in state diagram | Command doc                      |
+| CRUD operation        | Command doc                      |
+| Validation logic      | Command doc Business Rules       |
+| Data lookup           | Query doc                        |
+| Unit/currency convert | Query doc                        |
+| Computed aggregation  | Query doc                        |
+
+## Validation
+
+Always run before completing:
+
+```bash
+pnpm run module:doc:check
+```
+
+## References
+
+- [Naming convention (PascalCase files + command verbs)](references/naming.md)
+- [Module structure](../erp-kit-module-shared/references/structure.md)

package/skills/erp-kit-module-3-plan/references/command-extraction.md

@@ -0,0 +1,87 @@
+# Command Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract command (write operation) definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify operations that change state
+3. For each operation, extract:
+   - Command name (following naming convention)
+   - Input parameters
+   - Business rules and validations
+   - Error scenarios
+   - Process flow (step-by-step)
+
+## Naming Convention
+
+See [naming.md](naming.md) for the full canonical verb vocabulary.
+
+Key mappings:
+
+| Feature Operation    | Command Name   |
+| -------------------- | -------------- |
+| "Create X" / "Add X" | `createX`      |
+| "Update X"           | `updateX`      |
+| "Delete X"           | `deleteX`      |
+| "Deactivate X"       | `deactivateX`  |
+| "Activate X"         | `activateX`    |
+| "Reactivate X"       | `reactivateX`  |
+| "Set default X"      | `setDefaultX`  |
+| "Assign X to Y"      | `assignXToY`   |
+| "Remove X from Y"    | `removeXFromY` |
+| "Revoke X from Y"    | `revokeXFromY` |
+| "Move X"             | `moveX`        |
+| "Log X"              | `logX`         |
+
+**Banned verbs**: `archive`, `unarchive`, `disable`, `enable`, `add...To...`, `unlink`
+
+## Extraction Rules
+
+### Business Rules
+
+- Extract explicit validation rules from feature scenarios
+- Extract implicit rules from test cases ("should not allow X when Y")
+- Map each rule to an error scenario
+
+### Error Scenarios
+
+- For each business rule violation, define an error code
+- Follow SCREAMING_SNAKE_CASE convention
+- Categories: NOT_FOUND, DUPLICATE, LOCKED/INACTIVE, INVALID_STATE, NO_OP
+
+### Process Flow
+
+- Extract step-by-step flow from feature scenarios
+- Identify branching points (conditional logic)
+- Map to validate → query → mutate pattern
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Commands
+
+For each command:
+
+#### <commandName>
+
+- **Source features:** list of feature files
+- **Target model:** ModelName
+- **Inputs:**
+
+| Param | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Business Rules:**
+
+| Rule | Error Code | Error Message |
+| ---- | ---------- | ------------- |
+
+- **Process Flow:** numbered steps
+- **Permissions:** list

package/skills/erp-kit-module-3-plan/references/model-extraction.md

@@ -0,0 +1,72 @@
+# Model Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract entity/model definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify entities that need database models
+3. For each entity, extract:
+   - Fields and their types
+   - Relationships to other entities
+   - State machines (if stateful)
+   - Required constraints (unique, required, etc.)
+4. Resolve cross-feature entity references (same entity mentioned in multiple features)
+
+## Extraction Rules
+
+### Entity Identification
+
+- Look for nouns that represent persistent data
+- Check for explicit "Entity" or "Model" mentions
+- Identify implicit entities from relationship descriptions
+
+### Field Extraction
+
+- Map feature attributes to database field types
+- Identify required vs optional fields
+- Note any validation constraints
+
+### State Machine Extraction
+
+- Look for state diagrams or transition descriptions
+- Extract all possible states
+- Map transitions to operations (verbs → commands)
+
+### Relationship Extraction
+
+- Identify foreign key relationships (N-1, 1-1)
+- Identify junction table needs (N-N)
+- Note cross-module entity references
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Models
+
+For each model:
+
+#### <ModelName>
+
+- **Source features:** list of feature files
+- **Fields:**
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Relationships:**
+
+| Type | Target | Field | Cross-module |
+| ---- | ------ | ----- | ------------ |
+
+- **States:** list of states (if stateful)
+- **State Transitions:**
+
+| From | To  | Trigger (command) |
+| ---- | --- | ----------------- |

package/skills/{erp-kit-module-2-feature-breakdown → erp-kit-module-3-plan}/references/naming.md

@@ -1,4 +1,18 @@
-# Command Naming Convention
+# Naming Convention
+
+## Doc File Names — PascalCase
+
+Documentation files under `docs/models/`, `docs/commands/`, and `docs/queries/` **must** use PascalCase. The code generator derives the camelCase command/query name by lowercasing the first character of the file name.
+
+| Doc type | File name format  | Example file       | Derived name    |
+| -------- | ----------------- | ------------------ | --------------- |
+| Model    | `{Entity}.md`     | `Product.md`       | —               |
+| Command  | `{VerbEntity}.md` | `CreateProduct.md` | `createProduct` |
+| Query    | `{VerbEntity}.md` | `GetProduct.md`    | `getProduct`    |
+
+**Never use kebab-case** (`create-product.md`) — the generator will produce a broken name (`create-product`).
+
+## Command Naming Convention
 
 Commands use imperative `{verb}{Entity}` format. Use this canonical verb vocabulary when scaffolding commands.
 

package/skills/erp-kit-module-3-plan/references/query-extraction.md

@@ -0,0 +1,59 @@
+# Query Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract read-only query definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify read operations needed by external consumers
+3. For each read operation, extract:
+   - Query name (following naming convention)
+   - Input parameters
+   - Output shape
+   - Business logic (filtering, aggregation, conversion)
+
+## Query Identification
+
+Queries are read-only operations for external consumers. Look for:
+
+- **Lookups**: "Get X by Y", "Find X where Z"
+- **Conversions**: "Convert X to Y", "Calculate X"
+- **Aggregations**: "Total X", "Count X by Y"
+- **Listings**: "List all X", "List X by status"
+
+See [CQRS read rule](../../erp-kit-module-shared/references/commands.md#command-side-reads-cqrs-separation) for when to use queries vs command-side reads.
+
+## Naming Convention
+
+| Operation           | Query Name               |
+| ------------------- | ------------------------ |
+| Get single entity   | `get{Entity}`            |
+| List by status      | `list{Status}{Entities}` |
+| List all            | `list{Entities}`         |
+| Search with filters | `search{Entities}`       |
+| Calculate/convert   | `calculate{Result}`      |
+| Aggregate           | `get{Aggregate}`         |
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Queries
+
+For each query:
+
+#### <queryName>
+
+- **Source features:** list of feature files
+- **Inputs:**
+
+| Param | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Output:** type (single/list/aggregate) and shape description
+- **Business logic:** description of filtering, aggregation, or transformation

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

@@ -0,0 +1,158 @@
+---
+name: erp-kit-module-4-plan-review
+description: Review parity between feature documentation and command/model/query documentation. Use after creating implementation plan (step 3) to validate completeness.
+---
+
+# Feature Parity Review
+
+Review **documentation consistency** between feature specs and command/model/query docs.
+
+## When to Use
+
+- After writing feature documentation, check for gaps in command/model/query documentation
+- After writing command/model/query documentation, verify consistency with features
+- Quality check during documentation 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
+- `FEATURE_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/features/*.md`
+- `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/commands/*.md`
+- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/queries/*.md`
+- `MODEL_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/models/*.md`
+
+Verify at least `FEATURE_DOCS` is non-empty. If no feature docs exist, stop with: "No feature docs found for module <MODULE_NAME>."
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 4 Agent tool calls in parallel — one per parity check.
+Each agent receives: MODULE_NAME, relevant doc file paths.
+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.
+Otherwise, query each sequentially.
+
+| Agent | Prompt Template                                                                    | Inputs                     |
+| ----- | ---------------------------------------------------------------------------------- | -------------------------- |
+| 1     | [references/feature-command-parity.md](references/feature-command-parity.md)       | FEATURE_DOCS, COMMAND_DOCS |
+| 2     | [references/feature-query-parity.md](references/feature-query-parity.md)           | FEATURE_DOCS, QUERY_DOCS   |
+| 3     | [references/feature-model-parity.md](references/feature-model-parity.md)           | FEATURE_DOCS, MODEL_DOCS   |
+| 4     | [references/command-model-consistency.md](references/command-model-consistency.md) | COMMAND_DOCS, MODEL_DOCS   |
+
+For each agent:
+
+1. Read the prompt template file
+2. Replace `{{MODULE_NAME}}` with the resolved module name
+3. Replace `{{FEATURE_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_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 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
+5. Calculate totals across all summaries
+6. Render the final report below
+
+## Report Format
+
+Render the aggregated results as markdown:
+
+### Feature Parity Review Report
+
+**Module:** <MODULE_NAME>
+
+---
+
+### 1. Feature → Command Coverage
+
+| Feature | Scenarios | Required Commands | Documented Commands | Gap |
+| ------- | --------- | ----------------- | ------------------- | --- |
+
+(Populated from agent 1 gaps where check is `command_existence`)
+
+---
+
+### 2. Feature → Query Coverage
+
+| Feature | Read Operations | Required Queries | Documented Queries | Gap |
+| ------- | --------------- | ---------------- | ------------------ | --- |
+
+(Populated from agent 2 gaps where check is `query_existence`)
+
+---
+
+### 3. Feature → Model Coverage
+
+| Feature | Required Models | Documented Models | Gap |
+| ------- | --------------- | ----------------- | --- |
+
+(Populated from agent 3 gaps where check is `model_existence`)
+
+---
+
+### 4. Test Case → Business Rule Mapping
+
+| Feature | Test Case | Covered by Command | Status |
+| ------- | --------- | ------------------ | ------ |
+
+(Populated from agent 1 gaps where check is `business_rule_coverage`)
+
+---
+
+### 5. Missing Documentation
+
+#### Missing Command Docs
+
+| Feature | Expected Command | Purpose |
+| ------- | ---------------- | ------- |
+
+#### Missing Query Docs
+
+| Feature | Expected Query | Purpose |
+| ------- | -------------- | ------- |
+
+#### Missing Model Docs
+
+| Feature | Expected Model | Purpose |
+| ------- | -------------- | ------- |
+
+(Populated from all agents' gaps where status is `fail`)
+
+---
+
+### 6. Inconsistencies
+
+| Type | Location | Issue |
+| ---- | -------- | ----- |
+
+(Populated from all agents' `inconsistencies[]`)
+
+---
+
+### 7. Summary
+
+| Aspect                      | Status | Details           |
+| --------------------------- | ------ | ----------------- |
+| Feature → Command Coverage  |        | X/Y checks passed |
+| Feature → Query Coverage    |        | X/Y checks passed |
+| Feature → Model Coverage    |        | X/Y checks passed |
+| Command → Model Consistency |        | X/Y checks passed |
+
+### 8. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Create missing docs (highest priority)
+2. Add missing business rules / error scenarios
+3. Resolve inconsistencies
+
+## References
+
+- [Parity report format](references/parity-report-format.md)
+- For implementation patterns (models, commands, testing), see erp-kit-module-5-impl

package/skills/erp-kit-module-4-plan-review/references/command-model-consistency.md

@@ -0,0 +1,46 @@
+# Command → Model Consistency Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Command docs: {{COMMAND_DOCS}}
+Model docs: {{MODEL_DOCS}}
+
+## Instructions
+
+1. Read ALL command docs at the paths above
+2. Read ALL model docs at the paths above
+3. For each command, identify its target model and state transitions
+4. Run every parity check below
+5. Return results as JSON per the Output Format section
+
+## Parity Checks
+
+For each command doc:
+
+| Check ID                   | Question                                                       |
+| -------------------------- | -------------------------------------------------------------- |
+| target_model               | Does a model doc exist for the model that command operates on? |
+| state_transition_alignment | Do state changes by command match model state transitions?     |
+
+## Common Gap Patterns
+
+- **Missing target model**: Command operates on a model with no model doc
+- **State transition mismatch**: Command changes status to a state not in model's state diagram
+- **Validation gaps**: Command enforces constraints not reflected in model doc
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "command-model-consistency",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-module-4-plan-review/references/feature-command-parity.md

@@ -0,0 +1,97 @@
+# Feature → Command Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+Command docs: {{COMMAND_DOCS}}
+
+## Instructions
+
+1. Read ALL feature docs at the paths above
+2. Read ALL command docs at the paths above
+3. For each feature, extract scenario patterns and test cases
+4. For each command doc, extract business rules, error scenarios, process flows
+5. Run every parity check below against each feature
+6. Return results as JSON per the Output Format section
+
+## Extraction: Feature Docs
+
+From each feature doc, extract:
+
+### Scenario Patterns
+
+- **Add <entity>**: ... → Expected command: create<Entity>
+- **Change default <entity>**: ... → Expected command: setDefault<Entity>
+
+### Test Cases
+
+- "Adding a <entity> with valid data creates it in active status"
+  → Maps to business rule in create<Entity>
+- "Only one <entity> can be default per <parent> at a time"
+  → Maps to business rule in setDefault<Entity>
+
+## Expected Command Docs for Feature
+
+See [command naming convention](../../erp-kit-module-3-plan/references/naming.md) for the full rule, disambiguation guide, and banned verbs.
+
+| Feature Operation    | Expected Command Doc | Notes                          |
+| -------------------- | -------------------- | ------------------------------ |
+| "Create X" / "Add X" | `createX`            | Never `addX`                   |
+| "Update X"           | `updateX`            |                                |
+| "Delete X"           | `deleteX`            | Hard delete only               |
+| "Deactivate X"       | `deactivateX`        | Soft-disable (reversible)      |
+| "Activate X"         | `activateX`          | Enable entity                  |
+| "Reactivate X"       | `reactivateX`        | Re-enable after deactivation   |
+| "Set default X"      | `setDefaultX`        | Singular value/reference       |
+| "Assign X to Y"      | `assignXToY`         | Never `addXToY`                |
+| "Remove X from Y"    | `removeXFromY`       | Generic relationship unlinking |
+| "Revoke X from Y"    | `revokeXFromY`       | RBAC/security domain only      |
+| "Move X"             | `moveX`              | Hierarchy position change      |
+| "Log X"              | `logX`               | Append-only audit/event        |
+
+**Banned verbs** — flag as naming violation inconsistency:
+`archive`, `unarchive`, `disable`, `enable`, `add...To...`, `unlink`
+
+## Parity Checks
+
+For each feature's scenarios and test cases:
+
+| Check ID               | Question                                                                   |
+| ---------------------- | -------------------------------------------------------------------------- |
+| command_existence      | Does a command doc exist to implement the scenario?                        |
+| business_rule_coverage | Are feature test cases covered by command business rules?                  |
+| error_handling         | Are expected error cases from feature included in command error scenarios? |
+| process_flow_alignment | Does feature process flow match command process flow?                      |
+
+### How to Check
+
+1. List all scenario patterns from feature
+2. Identify required operations (verbs) for each scenario
+3. Verify corresponding command doc exists using the Expected Command Docs table
+4. Map feature test cases to command business rules / error scenarios
+
+## Common Gap Patterns
+
+Watch for these specific patterns:
+
+- **Orphaned scenarios**: Feature describes operation but no command doc exists
+- **Missing CRUD**: Feature implies create/update/delete but only some are documented
+- **Implicit commands**: Feature scenario requires helper command not documented
+- **Default handling**: Feature mentions "default" selection but no setDefault command
+
+## Output Format
+
+Return a JSON object matching this structure:
+
+```json
+{
+  "check_type": "feature-command-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.