create-mercato-app 0.6.5-develop.5266.2.9acdca82ec → 0.6.5-develop.5296.1.799a610136

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/agentic/shared/ai/skills/om-help/SKILL.md +107 -0
  2. package/agentic/shared/ai/skills/om-help/references/skills-catalog.md +81 -0
  3. package/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +193 -0
  4. package/dist/agentic/shared/ai/skills/om-help/SKILL.md +107 -0
  5. package/dist/agentic/shared/ai/skills/om-help/references/skills-catalog.md +81 -0
  6. package/dist/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +193 -0
  7. package/dist/index.js +12 -0
  8. package/package.json +1 -1
package/agentic/shared/ai/skills/om-help/SKILL.md ADDED
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: om-help
3
+ description: >
4
+ Open Mercato app navigator. Use when a developer asks: "what should I do now?",
5
+ "which skill should I use?", "where do I start?", "next steps?", "I'm lost",
6
+ "what comes after X?", "how do I create/add/build Y?", "how do I extend module Z?",
7
+ "how do I fix this error?", "where does X go?", "what's the sequence for a new module / feature / integration?".
8
+ Covers both orientation (navigation mode) and technical how-to (knowledge mode).
9
+ ---
10
+
11
+ # om-help — App Navigator
12
+
13
+ Two modes: pick the one that matches the question.
14
+
15
+ ---
16
+
17
+ ## Mode 1: Navigation — "What do I do now?"
18
+
19
+ **Triggers:** "what now?", "next steps?", "where do I start?", "which skill?", "I'm lost"
20
+
21
+ ### Step 1 — Read current context
22
+
23
+ ```bash
24
+ git branch --show-current
25
+ git status --short
26
+ ls src/modules/ 2>/dev/null | head -20
27
+ gh pr list --author "@me" --state open --json number,title,labels 2>/dev/null || true
28
+ ```
29
+
30
+ ### Step 2 — Map to a workflow sequence
31
+
32
+ Read `references/workflow-sequences.md`. Match the context:
33
+
34
+ | Signal | Likely sequence |
35
+ |--------|-----------------|
36
+ | No module yet, task described | New Module |
37
+ | Module exists, adding new behavior | New Feature in Existing Module |
38
+ | Modifying a core OM module | Extend an Existing Module (UMES first) |
39
+ | Adding payment / shipping / sync | New Integration Provider |
40
+ | Error, broken build, missing widget | Fix a Bug / Something Is Broken |
41
+ | Code done, no PR | code-review → auto-create-pr |
42
+ | PR open, no review | auto-review-pr |
43
+ | Fresh scaffold with unused modules | Slim Down the App |
44
+ | Version bump needed | Upgrade Open Mercato |
45
+
46
+ ### Step 3 — Recommend
47
+
48
+ ```
49
+ **Where you are:** <one sentence: branch, open PR or active work if any>
50
+
51
+ **Recommended next step:** `/om-<skill-name>`
52
+
53
+ **Why:** <one sentence explaining the match>
54
+
55
+ **After that:** `/om-<next-skill>` → `/om-<skill-after>`
56
+ ```
57
+
58
+ If multiple paths are valid, present at most two options.
59
+
60
+ ---
61
+
62
+ ## Mode 2: Knowledge — "How do I do X?"
63
+
64
+ **Triggers:** "how do I add X?", "how do I build Y?", "where does Z go?", "what import for W?", "how do I extend module Z?"
65
+
66
+ ### Step 1 — Map question to the right skill
67
+
68
+ | Question topic | Load this skill's SKILL.md or references |
69
+ |---------------|------------------------------------------|
70
+ | Create a new module | `om-module-scaffold/SKILL.md` |
71
+ | Design entities, fields, migrations | `om-data-model-design/SKILL.md` |
72
+ | Extend existing module (columns, fields, API) | `om-system-extension/SKILL.md` + `references/extension-contracts.md` |
73
+ | Build admin pages, forms, data tables | `om-backend-ui-design/SKILL.md` + `references/ui-components.md` |
74
+ | Build an integration provider | `om-integration-builder/SKILL.md` |
75
+ | Write a spec | `om-spec-writing/SKILL.md` |
76
+ | Write integration tests | `om-integration-tests/SKILL.md` |
77
+ | Eject and customize core module | `om-eject-and-customize/SKILL.md` |
78
+ | Something is broken | `om-troubleshooter/SKILL.md` |
79
+ | Remove unused modules | `om-trim-unused-modules/SKILL.md` |
80
+ | Code review | `om-code-review/SKILL.md` + `references/review-checklist.md` |
81
+
82
+ ### Step 2 — Load and read the target skill
83
+
84
+ Read the identified `SKILL.md` and any relevant `references/` files. Look for:
85
+ - Step-by-step instructions specific to the task
86
+ - File paths, commands, and code patterns
87
+ - MUST rules and anti-patterns to avoid
88
+
89
+ ### Step 3 — Answer grounded in the skill
90
+
91
+ Provide a specific answer citing:
92
+ - The exact steps or patterns from the skill
93
+ - Relevant commands to run (e.g. `yarn generate`, `yarn db:generate`)
94
+ - Any MUST rules that apply
95
+
96
+ Do not answer from model training data alone — ground every claim in the loaded skill content.
97
+
98
+ ---
99
+
100
+ ## References
101
+
102
+ - **Skill catalog** (all skills, categories, triggers, sequencing): `references/skills-catalog.md`
103
+ - **Workflow sequences** (named workflows with ordered skill lists): `references/workflow-sequences.md`
104
+
105
+ Load `references/skills-catalog.md` when the user asks which skill to use.
106
+ Load `references/workflow-sequences.md` when the user asks about sequencing or "where to start".
107
+ Load both when the user is fully disoriented.
package/agentic/shared/ai/skills/om-help/references/skills-catalog.md ADDED
@@ -0,0 +1,81 @@
1
+ # Skills Catalog — Standalone App
2
+
3
+ > All skills available in a `create-mercato-app` project, organized by category.
4
+ > Load this file when answering "what skill should I use?" or "what comes next?".
5
+
6
+ ## Table of Contents
7
+
8
+ - [Building Your App](#building-your-app)
9
+ - [Extending & Customizing](#extending--customizing)
10
+ - [Troubleshooting & Maintenance](#troubleshooting--maintenance)
11
+ - [PR & Code Quality](#pr--code-quality)
12
+ - [Migration](#migration)
13
+
14
+ ---
15
+
16
+ ## Building Your App
17
+
18
+ Skills for creating new functionality in your standalone Open Mercato application.
19
+
20
+ | Skill | Trigger / When to use | Preceded by | Followed by |
21
+ |-------|----------------------|-------------|-------------|
22
+ | `om-help` | "what now?", "which skill?", "next steps?", "how do I X?", orientation | — | any |
23
+ | `om-data-model-design` | Designing entities, relationships, migrations, encryption maps for PII | — | `om-spec-writing` or `om-module-scaffold` |
24
+ | `om-spec-writing` | Writing a spec before building a non-trivial feature | `om-data-model-design` | `om-module-scaffold` or `om-implement-spec` |
25
+ | `om-module-scaffold` | Creating a new module with entity, routes, pages, ACL, DI | `om-spec-writing` or `om-data-model-design` | `om-integration-tests` |
26
+ | `om-implement-spec` | Implementing an existing spec phase-by-phase | `om-spec-writing` | `om-integration-tests` |
27
+ | `om-backend-ui-design` | Designing admin pages, CRUD forms, data tables | — | `om-implement-spec` or `om-module-scaffold` |
28
+ | `om-integration-builder` | Building a payment, shipping, or data-sync integration provider | `om-spec-writing` | `om-integration-tests` |
29
+ | `om-integration-tests` | Writing or running Playwright integration tests | `om-module-scaffold` or `om-implement-spec` | `om-code-review` |
30
+
31
+ ---
32
+
33
+ ## Extending & Customizing
34
+
35
+ Skills for modifying or extending behavior without touching core module source.
36
+
37
+ | Skill | Trigger / When to use | Preceded by | Followed by |
38
+ |-------|----------------------|-------------|-------------|
39
+ | `om-system-extension` | Add columns/fields/filters to existing tables, enrich API responses, intercept routes, inject menu items, replace UI components | — | `om-code-review` |
40
+ | `om-eject-and-customize` | When UMES extensions aren't enough and you need to modify core module source directly | — | `om-code-review` |
41
+ | `om-trim-unused-modules` | Slim down the app by disabling modules you don't use | — | `om-code-review` |
42
+
43
+ ---
44
+
45
+ ## Troubleshooting & Maintenance
46
+
47
+ | Skill | Trigger / When to use | Preceded by | Followed by |
48
+ |-------|----------------------|-------------|-------------|
49
+ | `om-troubleshooter` | Errors, module not loading, widgets not appearing, migration failures, build errors, "it doesn't work" | — | `om-code-review` (after fix) |
50
+
51
+ ---
52
+
53
+ ## PR & Code Quality
54
+
55
+ | Skill | Trigger / When to use | Preceded by | Followed by |
56
+ |-------|----------------------|-------------|-------------|
57
+ | `om-code-review` | Review before merging — architecture, security, DS, conventions | any impl skill | `om-auto-create-pr` |
58
+ | `om-auto-create-pr` | Ship work as a GitHub PR end-to-end | `om-code-review` | `om-auto-review-pr` |
59
+ | `om-auto-continue-pr` | Resume an in-progress PR started by `om-auto-create-pr` | — | `om-auto-review-pr` |
60
+ | `om-auto-create-pr-loop` | Long multi-step implementation with step-level resumability | — | `om-auto-review-pr` |
61
+ | `om-auto-continue-pr-loop` | Resume a PR started by `om-auto-create-pr-loop` | — | `om-auto-review-pr` |
62
+ | `om-auto-review-pr` | Automated PR review + approve/request-changes | `om-auto-create-pr` | — |
63
+ | `om-auto-fix-github` | Fix a GitHub issue end-to-end | — | `om-auto-create-pr` |
64
+ | `om-prepare-issue` | Capture a feature to build later — write the spec, ship a docs-only spec PR, open a tracking issue | `om-spec-writing` | `om-implement-spec` |
65
+
66
+ ---
67
+
68
+ ## Migration
69
+
70
+ | Skill | Trigger / When to use | Preceded by | Followed by |
71
+ |-------|----------------------|-------------|-------------|
72
+ | `om-auto-upgrade-0.4.10-to-0.5.0` | Upgrade app from Open Mercato 0.4.10 → 0.5.0 | — | `om-code-review` |
73
+
74
+ ---
75
+
76
+ ## Notes
77
+
78
+ - **preceded-by / followed-by** are suggestions, not hard constraints.
79
+ - `om-troubleshooter` is always a valid entry point when something is broken.
80
+ - `om-system-extension` should be tried before `om-eject-and-customize` — ejecting makes upgrades harder.
81
+ - `om-help` is always the right starting point when you're unsure.
package/agentic/shared/ai/skills/om-help/references/workflow-sequences.md ADDED
@@ -0,0 +1,193 @@
1
+ # Workflow Sequences — Standalone App
2
+
3
+ > Common development workflows for a `create-mercato-app` project with the recommended skill sequence.
4
+ > Load this file when the user asks "where do I start?" or "what's the order for X?".
5
+
6
+ ## Table of Contents
7
+
8
+ - [New Module](#1-new-module)
9
+ - [New Feature in Existing Module](#2-new-feature-in-existing-module)
10
+ - [Extend an Existing Module](#3-extend-an-existing-module)
11
+ - [New Integration Provider](#4-new-integration-provider)
12
+ - [Fix a Bug / Something Is Broken](#5-fix-a-bug--something-is-broken)
13
+ - [PR Lifecycle](#6-pr-lifecycle)
14
+ - [Eject and Customize a Core Module](#7-eject-and-customize-a-core-module)
15
+ - [Slim Down the App](#8-slim-down-the-app)
16
+ - [Upgrade Open Mercato](#9-upgrade-open-mercato)
17
+ - [Choosing the Right Sequence](#choosing-the-right-sequence)
18
+
19
+ ---
20
+
21
+ ## 1. New Module
22
+
23
+ **Use when:** Building a brand-new module with its own entity, API routes, and admin pages.
24
+
25
+ ```
26
+ om-data-model-design (design entity, fields, relationships, migrations)
27
+ → om-spec-writing (spec the feature if non-trivial)
28
+ → om-module-scaffold (generate all required files)
29
+ → om-backend-ui-design (design forms and tables if needed)
30
+ → om-implement-spec (fill in business logic)
31
+ → om-integration-tests
32
+ → om-code-review
33
+ → om-auto-create-pr
34
+ ```
35
+
36
+ **Rationale per step:**
37
+ 1. `om-data-model-design` — design entities and migrations before touching code
38
+ 2. `om-spec-writing` — capture requirements, API contracts, phases (skip for simple CRUD)
39
+ 3. `om-module-scaffold` — generates entity, routes, pages, ACL, DI in one pass
40
+ 4. `om-backend-ui-design` — design consistent admin UI before implementing
41
+ 5. `om-implement-spec` — fill in custom logic beyond what scaffold generates
42
+ 6. `om-integration-tests` → `om-code-review` → `om-auto-create-pr`
43
+
44
+ > For simple CRUD modules: skip `om-spec-writing` and go directly to `om-module-scaffold`.
45
+
46
+ ---
47
+
48
+ ## 2. New Feature in Existing Module
49
+
50
+ **Use when:** Adding a field, endpoint, page, or behavior to a module you already have.
51
+
52
+ ```
53
+ om-spec-writing (capture requirements and API changes)
54
+ → om-implement-spec
55
+ → om-integration-tests
56
+ → om-code-review
57
+ → om-auto-create-pr
58
+ ```
59
+
60
+ > For small additions (1–2 files): skip `om-spec-writing` and implement directly.
61
+
62
+ ---
63
+
64
+ ## 3. Extend an Existing Module
65
+
66
+ **Use when:** Adding columns, filters, menu items, API enrichments, or UI changes to a *core* OM module without modifying its source.
67
+
68
+ ```
69
+ om-system-extension (use UMES: enrichers, widgets, interceptors, guards, event subscribers)
70
+ → om-code-review
71
+ → om-auto-create-pr
72
+ ```
73
+
74
+ **Rationale:** Always try `om-system-extension` first. UMES mechanisms cover most extension needs and survive upgrades. Only fall back to `om-eject-and-customize` if UMES cannot solve the problem.
75
+
76
+ **Extension mechanisms by use case:**
77
+
78
+ | What you want to do | UMES mechanism |
79
+ |--------------------|----------------|
80
+ | Add a column to a list table | Field/Column Widget |
81
+ | Add a field to a form | Field Widget |
82
+ | Add a filter to a data table | Filter Widget |
83
+ | Add data to an API response | Response Enricher |
84
+ | Block or validate a mutation | Mutation Guard |
85
+ | Hook before/after an API call | API Interceptor |
86
+ | Replace a UI component | Component Replacement |
87
+ | Add a menu item | Menu Injection Widget |
88
+ | React to a domain event | Event Subscriber |
89
+
90
+ ---
91
+
92
+ ## 4. New Integration Provider
93
+
94
+ **Use when:** Connecting to a payment gateway, shipping carrier, data-sync service, or external API.
95
+
96
+ ```
97
+ om-spec-writing (design adapter contract, credentials, health check)
98
+ → om-integration-builder (scaffold provider package)
99
+ → om-implement-spec (fill in provider logic)
100
+ → om-integration-tests
101
+ → om-code-review
102
+ → om-auto-create-pr
103
+ ```
104
+
105
+ ---
106
+
107
+ ## 5. Fix a Bug / Something Is Broken
108
+
109
+ **Use when:** Module not loading, widget not appearing, migration failing, build error, "it doesn't work".
110
+
111
+ ```
112
+ om-troubleshooter
113
+ → om-code-review (after fix is in place)
114
+ → om-auto-create-pr
115
+ ```
116
+
117
+ **Rationale:** `om-troubleshooter` follows a systematic diagnostic flow. Start there — don't guess. It covers module issues, entity/migration issues, API routes, UI/widgets, build/type errors, and database problems.
118
+
119
+ ---
120
+
121
+ ## 6. PR Lifecycle
122
+
123
+ **Use when:** Shipping work as a GitHub PR.
124
+
125
+ ```
126
+ om-auto-create-pr
127
+ → om-auto-review-pr
128
+ ```
129
+
130
+ Or for long/resumable work:
131
+ ```
132
+ om-auto-create-pr-loop
133
+ → om-auto-continue-pr-loop (if interrupted)
134
+ → om-auto-review-pr
135
+ ```
136
+
137
+ ---
138
+
139
+ ## 7. Eject and Customize a Core Module
140
+
141
+ **Use when:** UMES extensions (see sequence 3) cannot solve the problem and you need to modify core module source directly.
142
+
143
+ ```
144
+ om-eject-and-customize (pre-ejection analysis, identify safe zones, document customizations)
145
+ → om-implement-spec (implement modifications)
146
+ → om-code-review
147
+ → om-auto-create-pr
148
+ ```
149
+
150
+ **Warning:** Ejected modules require manual diff tracking on upgrades. Only eject when necessary.
151
+
152
+ ---
153
+
154
+ ## 8. Slim Down the App
155
+
156
+ **Use when:** Fresh `create-mercato-app` scaffold enables all modules by default; you want to disable unused ones.
157
+
158
+ ```
159
+ om-trim-unused-modules
160
+ → om-code-review
161
+ → om-auto-create-pr
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 9. Upgrade Open Mercato
167
+
168
+ **Use when:** Bumping the framework version in your app.
169
+
170
+ ```
171
+ om-auto-upgrade-0.4.10-to-0.5.0 (for 0.4.10 → 0.5.0)
172
+ → om-code-review
173
+ → om-auto-create-pr
174
+ ```
175
+
176
+ For other version jumps, check the `UPGRADE_NOTES.md` in your project.
177
+
178
+ ---
179
+
180
+ ## Choosing the Right Sequence
181
+
182
+ | Situation | Sequence |
183
+ |-----------|----------|
184
+ | I want to build a new module | [New Module](#1-new-module) |
185
+ | I want to add something to an existing module I own | [New Feature in Existing Module](#2-new-feature-in-existing-module) |
186
+ | I want to customize a core OM module | [Extend an Existing Module](#3-extend-an-existing-module) (try UMES first) |
187
+ | I want to add a payment/shipping/sync integration | [New Integration Provider](#4-new-integration-provider) |
188
+ | Something is broken | [Fix a Bug / Something Is Broken](#5-fix-a-bug--something-is-broken) |
189
+ | I want to open a PR | [PR Lifecycle](#6-pr-lifecycle) |
190
+ | UMES can't solve my extension need | [Eject and Customize](#7-eject-and-customize-a-core-module) |
191
+ | I want to remove unused modules | [Slim Down the App](#8-slim-down-the-app) |
192
+ | I need to upgrade OM version | [Upgrade Open Mercato](#9-upgrade-open-mercato) |
193
+ | I'm not sure what I need | Start with `om-help` |
package/dist/agentic/shared/ai/skills/om-help/SKILL.md ADDED
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: om-help
3
+ description: >
4
+ Open Mercato app navigator. Use when a developer asks: "what should I do now?",
5
+ "which skill should I use?", "where do I start?", "next steps?", "I'm lost",
6
+ "what comes after X?", "how do I create/add/build Y?", "how do I extend module Z?",
7
+ "how do I fix this error?", "where does X go?", "what's the sequence for a new module / feature / integration?".
8
+ Covers both orientation (navigation mode) and technical how-to (knowledge mode).
9
+ ---
10
+
11
+ # om-help — App Navigator
12
+
13
+ Two modes: pick the one that matches the question.
14
+
15
+ ---
16
+
17
+ ## Mode 1: Navigation — "What do I do now?"
18
+
19
+ **Triggers:** "what now?", "next steps?", "where do I start?", "which skill?", "I'm lost"
20
+
21
+ ### Step 1 — Read current context
22
+
23
+ ```bash
24
+ git branch --show-current
25
+ git status --short
26
+ ls src/modules/ 2>/dev/null | head -20
27
+ gh pr list --author "@me" --state open --json number,title,labels 2>/dev/null || true
28
+ ```
29
+
30
+ ### Step 2 — Map to a workflow sequence
31
+
32
+ Read `references/workflow-sequences.md`. Match the context:
33
+
34
+ | Signal | Likely sequence |
35
+ |--------|-----------------|
36
+ | No module yet, task described | New Module |
37
+ | Module exists, adding new behavior | New Feature in Existing Module |
38
+ | Modifying a core OM module | Extend an Existing Module (UMES first) |
39
+ | Adding payment / shipping / sync | New Integration Provider |
40
+ | Error, broken build, missing widget | Fix a Bug / Something Is Broken |
41
+ | Code done, no PR | code-review → auto-create-pr |
42
+ | PR open, no review | auto-review-pr |
43
+ | Fresh scaffold with unused modules | Slim Down the App |
44
+ | Version bump needed | Upgrade Open Mercato |
45
+
46
+ ### Step 3 — Recommend
47
+
48
+ ```
49
+ **Where you are:** <one sentence: branch, open PR or active work if any>
50
+
51
+ **Recommended next step:** `/om-<skill-name>`
52
+
53
+ **Why:** <one sentence explaining the match>
54
+
55
+ **After that:** `/om-<next-skill>` → `/om-<skill-after>`
56
+ ```
57
+
58
+ If multiple paths are valid, present at most two options.
59
+
60
+ ---
61
+
62
+ ## Mode 2: Knowledge — "How do I do X?"
63
+
64
+ **Triggers:** "how do I add X?", "how do I build Y?", "where does Z go?", "what import for W?", "how do I extend module Z?"
65
+
66
+ ### Step 1 — Map question to the right skill
67
+
68
+ | Question topic | Load this skill's SKILL.md or references |
69
+ |---------------|------------------------------------------|
70
+ | Create a new module | `om-module-scaffold/SKILL.md` |
71
+ | Design entities, fields, migrations | `om-data-model-design/SKILL.md` |
72
+ | Extend existing module (columns, fields, API) | `om-system-extension/SKILL.md` + `references/extension-contracts.md` |
73
+ | Build admin pages, forms, data tables | `om-backend-ui-design/SKILL.md` + `references/ui-components.md` |
74
+ | Build an integration provider | `om-integration-builder/SKILL.md` |
75
+ | Write a spec | `om-spec-writing/SKILL.md` |
76
+ | Write integration tests | `om-integration-tests/SKILL.md` |
77
+ | Eject and customize core module | `om-eject-and-customize/SKILL.md` |
78
+ | Something is broken | `om-troubleshooter/SKILL.md` |
79
+ | Remove unused modules | `om-trim-unused-modules/SKILL.md` |
80
+ | Code review | `om-code-review/SKILL.md` + `references/review-checklist.md` |
81
+
82
+ ### Step 2 — Load and read the target skill
83
+
84
+ Read the identified `SKILL.md` and any relevant `references/` files. Look for:
85
+ - Step-by-step instructions specific to the task
86
+ - File paths, commands, and code patterns
87
+ - MUST rules and anti-patterns to avoid
88
+
89
+ ### Step 3 — Answer grounded in the skill
90
+
91
+ Provide a specific answer citing:
92
+ - The exact steps or patterns from the skill
93
+ - Relevant commands to run (e.g. `yarn generate`, `yarn db:generate`)
94
+ - Any MUST rules that apply
95
+
96
+ Do not answer from model training data alone — ground every claim in the loaded skill content.
97
+
98
+ ---
99
+
100
+ ## References
101
+
102
+ - **Skill catalog** (all skills, categories, triggers, sequencing): `references/skills-catalog.md`
103
+ - **Workflow sequences** (named workflows with ordered skill lists): `references/workflow-sequences.md`
104
+
105
+ Load `references/skills-catalog.md` when the user asks which skill to use.
106
+ Load `references/workflow-sequences.md` when the user asks about sequencing or "where to start".
107
+ Load both when the user is fully disoriented.
package/dist/agentic/shared/ai/skills/om-help/references/skills-catalog.md ADDED
@@ -0,0 +1,81 @@
1
+ # Skills Catalog — Standalone App
2
+
3
+ > All skills available in a `create-mercato-app` project, organized by category.
4
+ > Load this file when answering "what skill should I use?" or "what comes next?".
5
+
6
+ ## Table of Contents
7
+
8
+ - [Building Your App](#building-your-app)
9
+ - [Extending & Customizing](#extending--customizing)
10
+ - [Troubleshooting & Maintenance](#troubleshooting--maintenance)
11
+ - [PR & Code Quality](#pr--code-quality)
12
+ - [Migration](#migration)
13
+
14
+ ---
15
+
16
+ ## Building Your App
17
+
18
+ Skills for creating new functionality in your standalone Open Mercato application.
19
+
20
+ | Skill | Trigger / When to use | Preceded by | Followed by |
21
+ |-------|----------------------|-------------|-------------|
22
+ | `om-help` | "what now?", "which skill?", "next steps?", "how do I X?", orientation | — | any |
23
+ | `om-data-model-design` | Designing entities, relationships, migrations, encryption maps for PII | — | `om-spec-writing` or `om-module-scaffold` |
24
+ | `om-spec-writing` | Writing a spec before building a non-trivial feature | `om-data-model-design` | `om-module-scaffold` or `om-implement-spec` |
25
+ | `om-module-scaffold` | Creating a new module with entity, routes, pages, ACL, DI | `om-spec-writing` or `om-data-model-design` | `om-integration-tests` |
26
+ | `om-implement-spec` | Implementing an existing spec phase-by-phase | `om-spec-writing` | `om-integration-tests` |
27
+ | `om-backend-ui-design` | Designing admin pages, CRUD forms, data tables | — | `om-implement-spec` or `om-module-scaffold` |
28
+ | `om-integration-builder` | Building a payment, shipping, or data-sync integration provider | `om-spec-writing` | `om-integration-tests` |
29
+ | `om-integration-tests` | Writing or running Playwright integration tests | `om-module-scaffold` or `om-implement-spec` | `om-code-review` |
30
+
31
+ ---
32
+
33
+ ## Extending & Customizing
34
+
35
+ Skills for modifying or extending behavior without touching core module source.
36
+
37
+ | Skill | Trigger / When to use | Preceded by | Followed by |
38
+ |-------|----------------------|-------------|-------------|
39
+ | `om-system-extension` | Add columns/fields/filters to existing tables, enrich API responses, intercept routes, inject menu items, replace UI components | — | `om-code-review` |
40
+ | `om-eject-and-customize` | When UMES extensions aren't enough and you need to modify core module source directly | — | `om-code-review` |
41
+ | `om-trim-unused-modules` | Slim down the app by disabling modules you don't use | — | `om-code-review` |
42
+
43
+ ---
44
+
45
+ ## Troubleshooting & Maintenance
46
+
47
+ | Skill | Trigger / When to use | Preceded by | Followed by |
48
+ |-------|----------------------|-------------|-------------|
49
+ | `om-troubleshooter` | Errors, module not loading, widgets not appearing, migration failures, build errors, "it doesn't work" | — | `om-code-review` (after fix) |
50
+
51
+ ---
52
+
53
+ ## PR & Code Quality
54
+
55
+ | Skill | Trigger / When to use | Preceded by | Followed by |
56
+ |-------|----------------------|-------------|-------------|
57
+ | `om-code-review` | Review before merging — architecture, security, DS, conventions | any impl skill | `om-auto-create-pr` |
58
+ | `om-auto-create-pr` | Ship work as a GitHub PR end-to-end | `om-code-review` | `om-auto-review-pr` |
59
+ | `om-auto-continue-pr` | Resume an in-progress PR started by `om-auto-create-pr` | — | `om-auto-review-pr` |
60
+ | `om-auto-create-pr-loop` | Long multi-step implementation with step-level resumability | — | `om-auto-review-pr` |
61
+ | `om-auto-continue-pr-loop` | Resume a PR started by `om-auto-create-pr-loop` | — | `om-auto-review-pr` |
62
+ | `om-auto-review-pr` | Automated PR review + approve/request-changes | `om-auto-create-pr` | — |
63
+ | `om-auto-fix-github` | Fix a GitHub issue end-to-end | — | `om-auto-create-pr` |
64
+ | `om-prepare-issue` | Capture a feature to build later — write the spec, ship a docs-only spec PR, open a tracking issue | `om-spec-writing` | `om-implement-spec` |
65
+
66
+ ---
67
+
68
+ ## Migration
69
+
70
+ | Skill | Trigger / When to use | Preceded by | Followed by |
71
+ |-------|----------------------|-------------|-------------|
72
+ | `om-auto-upgrade-0.4.10-to-0.5.0` | Upgrade app from Open Mercato 0.4.10 → 0.5.0 | — | `om-code-review` |
73
+
74
+ ---
75
+
76
+ ## Notes
77
+
78
+ - **preceded-by / followed-by** are suggestions, not hard constraints.
79
+ - `om-troubleshooter` is always a valid entry point when something is broken.
80
+ - `om-system-extension` should be tried before `om-eject-and-customize` — ejecting makes upgrades harder.
81
+ - `om-help` is always the right starting point when you're unsure.
package/dist/agentic/shared/ai/skills/om-help/references/workflow-sequences.md ADDED
@@ -0,0 +1,193 @@
1
+ # Workflow Sequences — Standalone App
2
+
3
+ > Common development workflows for a `create-mercato-app` project with the recommended skill sequence.
4
+ > Load this file when the user asks "where do I start?" or "what's the order for X?".
5
+
6
+ ## Table of Contents
7
+
8
+ - [New Module](#1-new-module)
9
+ - [New Feature in Existing Module](#2-new-feature-in-existing-module)
10
+ - [Extend an Existing Module](#3-extend-an-existing-module)
11
+ - [New Integration Provider](#4-new-integration-provider)
12
+ - [Fix a Bug / Something Is Broken](#5-fix-a-bug--something-is-broken)
13
+ - [PR Lifecycle](#6-pr-lifecycle)
14
+ - [Eject and Customize a Core Module](#7-eject-and-customize-a-core-module)
15
+ - [Slim Down the App](#8-slim-down-the-app)
16
+ - [Upgrade Open Mercato](#9-upgrade-open-mercato)
17
+ - [Choosing the Right Sequence](#choosing-the-right-sequence)
18
+
19
+ ---
20
+
21
+ ## 1. New Module
22
+
23
+ **Use when:** Building a brand-new module with its own entity, API routes, and admin pages.
24
+
25
+ ```
26
+ om-data-model-design (design entity, fields, relationships, migrations)
27
+ → om-spec-writing (spec the feature if non-trivial)
28
+ → om-module-scaffold (generate all required files)
29
+ → om-backend-ui-design (design forms and tables if needed)
30
+ → om-implement-spec (fill in business logic)
31
+ → om-integration-tests
32
+ → om-code-review
33
+ → om-auto-create-pr
34
+ ```
35
+
36
+ **Rationale per step:**
37
+ 1. `om-data-model-design` — design entities and migrations before touching code
38
+ 2. `om-spec-writing` — capture requirements, API contracts, phases (skip for simple CRUD)
39
+ 3. `om-module-scaffold` — generates entity, routes, pages, ACL, DI in one pass
40
+ 4. `om-backend-ui-design` — design consistent admin UI before implementing
41
+ 5. `om-implement-spec` — fill in custom logic beyond what scaffold generates
42
+ 6. `om-integration-tests` → `om-code-review` → `om-auto-create-pr`
43
+
44
+ > For simple CRUD modules: skip `om-spec-writing` and go directly to `om-module-scaffold`.
45
+
46
+ ---
47
+
48
+ ## 2. New Feature in Existing Module
49
+
50
+ **Use when:** Adding a field, endpoint, page, or behavior to a module you already have.
51
+
52
+ ```
53
+ om-spec-writing (capture requirements and API changes)
54
+ → om-implement-spec
55
+ → om-integration-tests
56
+ → om-code-review
57
+ → om-auto-create-pr
58
+ ```
59
+
60
+ > For small additions (1–2 files): skip `om-spec-writing` and implement directly.
61
+
62
+ ---
63
+
64
+ ## 3. Extend an Existing Module
65
+
66
+ **Use when:** Adding columns, filters, menu items, API enrichments, or UI changes to a *core* OM module without modifying its source.
67
+
68
+ ```
69
+ om-system-extension (use UMES: enrichers, widgets, interceptors, guards, event subscribers)
70
+ → om-code-review
71
+ → om-auto-create-pr
72
+ ```
73
+
74
+ **Rationale:** Always try `om-system-extension` first. UMES mechanisms cover most extension needs and survive upgrades. Only fall back to `om-eject-and-customize` if UMES cannot solve the problem.
75
+
76
+ **Extension mechanisms by use case:**
77
+
78
+ | What you want to do | UMES mechanism |
79
+ |--------------------|----------------|
80
+ | Add a column to a list table | Field/Column Widget |
81
+ | Add a field to a form | Field Widget |
82
+ | Add a filter to a data table | Filter Widget |
83
+ | Add data to an API response | Response Enricher |
84
+ | Block or validate a mutation | Mutation Guard |
85
+ | Hook before/after an API call | API Interceptor |
86
+ | Replace a UI component | Component Replacement |
87
+ | Add a menu item | Menu Injection Widget |
88
+ | React to a domain event | Event Subscriber |
89
+
90
+ ---
91
+
92
+ ## 4. New Integration Provider
93
+
94
+ **Use when:** Connecting to a payment gateway, shipping carrier, data-sync service, or external API.
95
+
96
+ ```
97
+ om-spec-writing (design adapter contract, credentials, health check)
98
+ → om-integration-builder (scaffold provider package)
99
+ → om-implement-spec (fill in provider logic)
100
+ → om-integration-tests
101
+ → om-code-review
102
+ → om-auto-create-pr
103
+ ```
104
+
105
+ ---
106
+
107
+ ## 5. Fix a Bug / Something Is Broken
108
+
109
+ **Use when:** Module not loading, widget not appearing, migration failing, build error, "it doesn't work".
110
+
111
+ ```
112
+ om-troubleshooter
113
+ → om-code-review (after fix is in place)
114
+ → om-auto-create-pr
115
+ ```
116
+
117
+ **Rationale:** `om-troubleshooter` follows a systematic diagnostic flow. Start there — don't guess. It covers module issues, entity/migration issues, API routes, UI/widgets, build/type errors, and database problems.
118
+
119
+ ---
120
+
121
+ ## 6. PR Lifecycle
122
+
123
+ **Use when:** Shipping work as a GitHub PR.
124
+
125
+ ```
126
+ om-auto-create-pr
127
+ → om-auto-review-pr
128
+ ```
129
+
130
+ Or for long/resumable work:
131
+ ```
132
+ om-auto-create-pr-loop
133
+ → om-auto-continue-pr-loop (if interrupted)
134
+ → om-auto-review-pr
135
+ ```
136
+
137
+ ---
138
+
139
+ ## 7. Eject and Customize a Core Module
140
+
141
+ **Use when:** UMES extensions (see sequence 3) cannot solve the problem and you need to modify core module source directly.
142
+
143
+ ```
144
+ om-eject-and-customize (pre-ejection analysis, identify safe zones, document customizations)
145
+ → om-implement-spec (implement modifications)
146
+ → om-code-review
147
+ → om-auto-create-pr
148
+ ```
149
+
150
+ **Warning:** Ejected modules require manual diff tracking on upgrades. Only eject when necessary.
151
+
152
+ ---
153
+
154
+ ## 8. Slim Down the App
155
+
156
+ **Use when:** Fresh `create-mercato-app` scaffold enables all modules by default; you want to disable unused ones.
157
+
158
+ ```
159
+ om-trim-unused-modules
160
+ → om-code-review
161
+ → om-auto-create-pr
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 9. Upgrade Open Mercato
167
+
168
+ **Use when:** Bumping the framework version in your app.
169
+
170
+ ```
171
+ om-auto-upgrade-0.4.10-to-0.5.0 (for 0.4.10 → 0.5.0)
172
+ → om-code-review
173
+ → om-auto-create-pr
174
+ ```
175
+
176
+ For other version jumps, check the `UPGRADE_NOTES.md` in your project.
177
+
178
+ ---
179
+
180
+ ## Choosing the Right Sequence
181
+
182
+ | Situation | Sequence |
183
+ |-----------|----------|
184
+ | I want to build a new module | [New Module](#1-new-module) |
185
+ | I want to add something to an existing module I own | [New Feature in Existing Module](#2-new-feature-in-existing-module) |
186
+ | I want to customize a core OM module | [Extend an Existing Module](#3-extend-an-existing-module) (try UMES first) |
187
+ | I want to add a payment/shipping/sync integration | [New Integration Provider](#4-new-integration-provider) |
188
+ | Something is broken | [Fix a Bug / Something Is Broken](#5-fix-a-bug--something-is-broken) |
189
+ | I want to open a PR | [PR Lifecycle](#6-pr-lifecycle) |
190
+ | UMES can't solve my extension need | [Eject and Customize](#7-eject-and-customize-a-core-module) |
191
+ | I want to remove unused modules | [Slim Down the App](#8-slim-down-the-app) |
192
+ | I need to upgrade OM version | [Upgrade Open Mercato](#9-upgrade-open-mercato) |
193
+ | I'm not sure what I need | Start with `om-help` |
package/dist/index.js CHANGED
@@ -561,6 +561,18 @@ function generateShared(config) {
561
561
  "ai/skills/om-integration-tests/SKILL.md",
562
562
  join3(targetDir, ".ai", "skills", "om-integration-tests", "SKILL.md")
563
563
  );
564
+ copyFile(
565
+ "ai/skills/om-help/SKILL.md",
566
+ join3(targetDir, ".ai", "skills", "om-help", "SKILL.md")
567
+ );
568
+ copyFile(
569
+ "ai/skills/om-help/references/skills-catalog.md",
570
+ join3(targetDir, ".ai", "skills", "om-help", "references", "skills-catalog.md")
571
+ );
572
+ copyFile(
573
+ "ai/skills/om-help/references/workflow-sequences.md",
574
+ join3(targetDir, ".ai", "skills", "om-help", "references", "workflow-sequences.md")
575
+ );
564
576
  copyFile(
565
577
  "ai/skills/om-auto-upgrade-0.4.10-to-0.5.0/SKILL.md",
566
578
  join3(targetDir, ".ai", "skills", "om-auto-upgrade-0.4.10-to-0.5.0", "SKILL.md")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-mercato-app",
3
- "version": "0.6.5-develop.5266.2.9acdca82ec",
3
+ "version": "0.6.5-develop.5296.1.799a610136",
4
4
  "type": "module",
5
5
  "description": "Create a new Open Mercato application",
6
6
  "main": "./dist/index.js",