@tailor-platform/erp-kit 0.2.1 → 0.3.0

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

@@ -0,0 +1,89 @@
+# Resolver Extraction
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+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
+4. Return results as a structured markdown report
+
+## Extraction Rules
+
+### Resolver Identification
+
+For each business flow step that modifies data:
+
+1. Identify the operation type (create, update, delete, approve, etc.)
+2. Map to a resolver name using camelCase action-verb convention
+3. Identify the module command the resolver will call
+4. Extract inputs, outputs, and error scenarios
+
+### Operation → Resolver Mapping
+
+See [erp-kit-app-shared/references/resolver-classification.md](../../erp-kit-app-shared/references/resolver-classification.md) for the full operation → resolver mapping table and custom vs built-in classification.
+
+### Module Command Mapping
+
+For each resolver, identify which erp-kit module provides the command:
+
+| Resolver Operation | Typical Module        |
+| ------------------ | --------------------- |
+| User invite/roles  | `user-management`     |
+| Supplier CRUD      | `supplier-management` |
+| Document handling  | `document-management` |
+| Task workflows     | `task-management`     |
+| Item CRUD          | `item-management`     |
+| Unit/currency      | `primitives`          |
+
+### Resolver Content
+
+For each resolver, extract:
+
+- **Name**: camelCase action-verb (e.g., `createSupplierInvitation`)
+- **Type**: Mutation or Query
+- **Module**: which erp-kit module provides the command
+- **Command**: which module command it calls
+- **Inputs**: parameters from the flow step
+- **Outputs**: expected return data
+- **Error scenarios**: what can go wrong
+
+## Naming Convention
+
+- Resolver filename: camelCase matching the operation name
+- Action-focused: `createSupplierInvitation.md`, `updateItem.md`
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Resolvers
+
+For each resolver:
+
+- **Resolver:** `<resolverName>`
+- **Type:** Mutation / Query
+- **Module:** module name
+- **Command:** command name
+- **Flow steps:** which flow steps this resolver supports
+- **Inputs:** bulleted list of input fields
+- **Error scenarios:** bulleted list of error cases
+
+### Built-in Queries
+
+List entities that only need built-in list/get queries (no custom resolver needed).
+
+### Module Dependencies
+
+Table with columns: Module, Required Commands, Status (exists/missing)
+
+### Summary
+
+- Total custom resolvers
+- Total built-in queries
+- Resolvers per module (table)

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

@@ -0,0 +1,74 @@
+# Screen Extraction
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+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. Return results as a structured markdown report
+
+## Extraction Rules
+
+### Screen Identification
+
+For each business flow step that involves UI:
+
+1. Identify what the user sees or interacts with
+2. Classify the screen type
+3. Extract fields, columns, and actions
+
+### Screen Types
+
+| Screen Type   | When to Use                                          |
+| ------------- | ---------------------------------------------------- |
+| ListView      | User browses a list of entities (table with columns) |
+| Form (create) | User fills in fields to create a new entity          |
+| Form (edit)   | User modifies fields of an existing entity           |
+| DetailView    | User views details of a single entity with actions   |
+
+### Screen Content
+
+For each screen, extract:
+
+- **Name**: kebab-case, noun-focused (e.g., `supplier-list`, `supplier-detail`, `supplier-form`)
+- **Type**: ListView / Form / DetailView
+- **Fields/Columns**: what data is displayed or edited
+- **Actions**: navigation actions (create, edit, back) and mutation actions (save, delete, activate)
+- **Stories**: which stories reference this screen
+
+### Deduplication
+
+- Screens can be shared across multiple stories and flows
+- If two flows need the same entity list view, create one screen doc referenced by both
+- Create/edit forms for the same entity are separate screens (different field requirements)
+
+## Naming Convention
+
+- Screen filename: kebab-case, noun-focused
+- Pattern: `<entity>-list.md`, `<entity>-detail.md`, `<entity>-create-form.md`, `<entity>-edit-form.md`
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Screens
+
+For each screen:
+
+- **Screen:** `<screen-name>`
+- **Type:** ListView / Form / DetailView
+- **Fields/Columns:** bulleted list of fields with types
+- **Actions:** bulleted list of actions
+- **Referenced by stories:** which stories use this screen
+- **Referenced by flows:** which business flows need this screen
+
+### Summary
+
+- Total screens extracted
+- Screens by type (table: ListView, Form, DetailView counts)

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

@@ -0,0 +1,86 @@
+# Story Extraction
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+1. Read ALL actor docs at the paths above
+2. Read ALL business flow docs at the paths above
+3. For each business flow, decompose into user stories
+4. Return results as a structured markdown report
+
+## Extraction Rules
+
+### Flow Step → Story Mapping
+
+For each business flow:
+
+1. Identify each numbered step or substep that represents a user action
+2. Map each step to the responsible actor (from "Actors Involved" or sequence diagram)
+3. Group related steps into stories (a story = a cohesive user action completable in one session)
+
+| Flow Element     | Maps To     |
+| ---------------- | ----------- |
+| User action step | Story       |
+| UI requirement   | Screen ref  |
+| Actor in flow    | Story actor |
+
+### Story Granularity
+
+- Aim for 3-8 stories per business flow
+- Each story should be completable in a single user session
+- If a flow step is too large (multiple UI interactions), split into separate stories
+- If a flow step is too small (a single click), merge with related steps
+
+### Story Content
+
+For each story, extract:
+
+- **Actor**: which actor performs this action (from filename convention `<actor>--<name>.md`)
+- **Scenario patterns**: concrete usage scenarios ("Admin creates a new supplier invitation")
+- **Preconditions**: what must be true before this story
+- **Postconditions**: what changes after this story completes
+- **Screen references**: which screens the user interacts with
+- **Resolver needs**: whether this story needs mutations (non-read-only) or is read-only
+
+### Resolver Classification
+
+For each story, determine:
+
+- **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
+
+- Story filename: `<actor>--<story-name>.md` (double-dash separator between actor and story)
+- Story heading: Title Case of the story name portion
+- Actor slug: kebab-case of actor name
+
+## Output Format
+
+Return your findings as a structured markdown report:
+
+### Stories by Business Flow
+
+For each business flow:
+
+#### <flow-name>
+
+For each story:
+
+- **Story:** `<actor>--<story-name>`
+- **Actor:** actor name
+- **Flow steps covered:** which steps this story implements
+- **Scenario patterns:** bulleted list of scenarios
+- **Screen references:** which screens are needed
+- **Resolvers:** `TBD` (needs mutations) or `None` (read-only)
+
+### Summary
+
+- Total stories extracted
+- Stories per flow (table)
+- Stories per actor (table)

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

@@ -0,0 +1,168 @@
+---
+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.
+---
+
+# Documentation Parity Review
+
+Review **documentation consistency** across Tier 2, 3, and 4 documentation.
+
+## When to Use
+
+- After writing Tier 3-4 documentation, check for gaps
+- Before proceeding to implementation (step 5)
+- Quality check during documentation review
+
+## 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`
+- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
+- `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
+- `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+- `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.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/."
+
+## 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.
+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                  |
+
+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
+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:
+
+### Documentation Parity Review Report
+
+**Application:** <APP_NAME>
+
+---
+
+### 1. Business Flow → Story Coverage
+
+| Business Flow | Flow Steps | Required Stories | Documented Stories | Gap |
+| ------------- | ---------- | ---------------- | ------------------ | --- |
+
+(Populated from agent 1 gaps where check is `story_existence`)
+
+---
+
+### 2. Actor Coverage in Stories
+
+| Business Flow | Actor | Referenced in Stories | Status |
+| ------------- | ----- | --------------------- | ------ |
+
+(Populated from agent 1 gaps where check is `actor_coverage`)
+
+---
+
+### 3. Actor → Business Flow Coverage
+
+| Actor | Authorized Flows | Documented Flows | Gap |
+| ----- | ---------------- | ---------------- | --- |
+
+(Populated from agent 2 gaps where check is `flow_existence`)
+
+---
+
+### 4. Story → Screen Coverage
+
+| Story | Referenced Screens | Documented Screens | Gap |
+| ----- | ------------------ | ------------------ | --- |
+
+(Populated from agent 3 gaps where check is `screen_existence`)
+
+---
+
+### 5. Story → Resolver Coverage
+
+| Story | Resolver Status | Required Resolvers | Documented Resolvers | Gap |
+| ----- | --------------- | ------------------ | -------------------- | --- |
+
+(Populated from agent 4 gaps where check is `resolver_existence`)
+
+---
+
+### 6. Orphan Detection
+
+| Type | File | Issue |
+| ---- | ---- | ----- |
+
+(Populated from agent 5 gaps)
+
+---
+
+### 7. Link Validity
+
+| Source | Target | Status |
+| ------ | ------ | ------ |
+
+(Populated from all agents' gaps where check is `link_validity`)
+
+---
+
+### 8. Inconsistencies
+
+| Type | Location | Issue |
+| ---- | -------- | ----- |
+
+(Populated from all agents' `inconsistencies[]`)
+
+---
+
+### 9. Summary
+
+| Aspect                | Status | Details           |
+| --------------------- | ------ | ----------------- |
+| Business Flow → Story |        | X/Y checks passed |
+| Actor → Flow          |        | X/Y checks passed |
+| Story → Screen        |        | X/Y checks passed |
+| Story → Resolver      |        | X/Y checks passed |
+| Orphan Detection      |        | X/Y checks passed |
+
+### 10. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Create missing docs (highest priority)
+2. Fix broken links
+3. Remove or link orphans
+
+## References
+
+- [Link format reference](../erp-kit-app-shared/references/link-format-reference.md)
+- [Parity report format](references/parity-report-format.md)
+- For plan creation, see erp-kit-app-3-plan
+- For implementation, see erp-kit-app-5-impl-backend

package/skills/erp-kit-app-4-plan-review/references/actor-flow-parity.md

@@ -0,0 +1,73 @@
+# Actor → Business Flow Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+
+## Instructions
+
+1. Read ALL actor docs at the paths above
+2. Read ALL business flow docs at the paths above
+3. For each actor, extract the list of authorized/referenced business flows
+4. Run every parity check below against each actor
+5. Return results as JSON per the Output Format section
+
+## Extraction: Actor Docs
+
+From each actor doc, extract:
+
+- Actor name
+- List of authorized or referenced business flows
+- Flow links (format: `../business-flow/<flow>/README.md`)
+
+## Extraction: Business Flow Docs
+
+From each business flow README.md, extract:
+
+- Flow name (from directory name or heading)
+- Actors involved in the flow
+
+## Parity Checks
+
+For each actor's referenced flows:
+
+| Check ID       | Question                                                     |
+| -------------- | ------------------------------------------------------------ |
+| flow_existence | Do all flows listed in the actor's "Authorized Flows" exist? |
+| link_validity  | Do flow links in the actor doc resolve to real files?        |
+
+### How to Check
+
+1. List all flows referenced by each actor doc
+2. Verify a corresponding business flow README exists for each
+3. Validate that all `../business-flow/<flow>/README.md` links resolve to actual files in BUSINESS_FLOW_DOCS
+
+## Link Format Reference
+
+| From  | To            | Format                              |
+| ----- | ------------- | ----------------------------------- |
+| Actor | Business Flow | `../business-flow/<flow>/README.md` |
+
+## Common Gap Patterns
+
+- **Missing flow docs**: Actor references a flow that has no README.md
+- **Broken flow links**: Actor doc links to a flow directory that does not exist
+- **Unlinked actor**: Actor doc exists but references no flows
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "actor-flow-parity",
+  "app": "{{APP_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-app-4-plan-review/references/business-flow-story-parity.md

@@ -0,0 +1,86 @@
+# Business Flow → Story Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
+
+## Instructions
+
+1. Read ALL business flow docs at the paths above
+2. Read ALL story docs at the paths above
+3. For each business flow, extract flow steps and referenced actors
+4. For each story, extract the actor and the flow step it covers
+5. Run every parity check below against each business flow
+6. Return results as JSON per the Output Format section
+
+## Extraction: Business Flow Docs
+
+From each business flow README.md, extract:
+
+### Flow Steps
+
+- Each numbered step or substep in the flow
+- The actor responsible for each step
+- Any story links referenced (format: `./story/<actor>--<name>.md`)
+
+### Actors
+
+- All actors mentioned in the flow
+- Actor doc links (format: `../../actors/<actor>.md`)
+
+## Extraction: Story Docs
+
+From each story doc, extract:
+
+- The actor (from filename pattern `<actor>--<name>.md` or from content)
+- The scenario patterns and user actions described
+- Screen references (format: `../../../screen/<screen>.md`)
+
+## Parity Checks
+
+For each business flow's steps and actors:
+
+| Check ID        | Question                                                 |
+| --------------- | -------------------------------------------------------- |
+| story_existence | Does each flow step have a corresponding story?          |
+| actor_coverage  | Are all actors in the flow represented in stories?       |
+| link_validity   | Do story links in the flow README resolve to real files? |
+
+### How to Check
+
+1. List all flow steps from each business flow README
+2. For each step, verify a story doc exists that covers it
+3. Verify all actors mentioned in the flow appear as story actors
+4. Validate that all `./story/<actor>--<name>.md` links resolve to actual files in STORY_DOCS
+
+## Link Format Reference
+
+| From          | To    | Format                       |
+| ------------- | ----- | ---------------------------- |
+| Business Flow | Story | `./story/<actor>--<name>.md` |
+| Business Flow | Actor | `../../actors/<actor>.md`    |
+
+## Common Gap Patterns
+
+- **Missing stories**: Flow step describes an action but no story doc exists for it
+- **Actor mismatch**: Flow mentions an actor not represented in any story
+- **Broken story links**: Flow README links to a story file that does not exist
+- **Incomplete coverage**: Some flow steps have stories but others are skipped
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "business-flow-story-parity",
+  "app": "{{APP_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-app-4-plan-review/references/orphan-detection.md

@@ -0,0 +1,69 @@
+# Orphan Detection Check
+
+## Context
+
+App: {{APP_NAME}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
+Screen docs: {{SCREEN_DOCS}}
+Actor docs: {{ACTOR_DOCS}}
+Resolver docs: {{RESOLVER_DOCS}}
+
+## Instructions
+
+1. Read ALL docs at the paths above
+2. Build a reference graph: which docs link to which other docs
+3. Run every parity check below to find orphaned documents
+4. Return results as JSON per the Output Format section
+
+## Building the Reference Graph
+
+Scan all docs for outgoing links using these patterns:
+
+| From          | To            | Link Pattern                        |
+| ------------- | ------------- | ----------------------------------- |
+| Business Flow | Story         | `./story/<actor>--<name>.md`        |
+| Business Flow | Actor         | `../../actors/<actor>.md`           |
+| Actor         | Business Flow | `../business-flow/<flow>/README.md` |
+| Story         | Screen        | `../../../screen/<screen>.md`       |
+| Story         | Resolver      | `../../../resolver/<name>.md`       |
+
+For each doc, record all outgoing link targets (resolved to actual file paths).
+
+## Parity Checks
+
+| Check ID         | Question                                             |
+| ---------------- | ---------------------------------------------------- |
+| orphan_stories   | Are there stories not linked from any business flow? |
+| orphan_screens   | Are there screens not referenced by any story?       |
+| orphan_actors    | Are there actors not participating in any flow?      |
+| orphan_resolvers | Are there resolvers not referenced by any story?     |
+
+### How to Check
+
+1. **Orphan stories**: For each file in STORY_DOCS, check if any business flow README links to it. If no flow references it, it is an orphan.
+2. **Orphan screens**: For each file in SCREEN_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
+3. **Orphan actors**: For each file in ACTOR_DOCS, check if any business flow README links to it AND the actor doc links to at least one flow. If neither condition is met, it is an orphan.
+4. **Orphan resolvers**: For each file in RESOLVER_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
+
+## Common Gap Patterns
+
+- **Renamed files**: A doc was renamed but links were not updated, leaving the old target as an orphan
+- **Leftover drafts**: Docs created during planning but never linked into the flow
+- **Incomplete cleanup**: A flow was removed but its stories/screens/resolvers were not deleted
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "orphan-detection",
+  "app": "{{APP_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-app-4-plan-review/references/parity-report-format.md

@@ -0,0 +1,52 @@
+# Parity Report Format
+
+All parity check agents return results in this JSON structure.
+
+## Schema
+
+```json
+{
+  "check_type": "<one of: business-flow-story-parity, actor-flow-parity, story-screen-parity, story-resolver-parity, orphan-detection>",
+  "app": "<app-name>",
+  "gaps": [
+    {
+      "source": "<source doc path>",
+      "target": "<target doc path or 'missing'>",
+      "check": "<check_id from the agent's parity checks table>",
+      "status": "pass | fail | skip",
+      "detail": "<human-readable description of the finding>"
+    }
+  ],
+  "inconsistencies": [
+    {
+      "type": "<inconsistency type, e.g. link_mismatch>",
+      "location": "<source vs target description>",
+      "detail": "<human-readable description>"
+    }
+  ],
+  "summary": {
+    "total_checks": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0
+  }
+}
+```
+
+## Field Reference
+
+### gaps[]
+
+One entry per parity check performed. `status` is:
+
+- `pass`: source and target are consistent
+- `fail`: gap or mismatch found
+- `skip`: target docs missing or empty, check could not run
+
+### inconsistencies[]
+
+Cross-cutting issues found during the check that don't fit a single gap entry (e.g., link format violations, naming mismatches across multiple docs).
+
+### summary
+
+Aggregate counts. `total_checks = passed + failed + skipped`.